Secure Push Gateway 最小仕様書 dev

旧オンプレ画面と同じ手順で確認できるよう、AWS版の実装済みAPIと未実装APIを並べて表示しています。

Base URL: http://tegami-mail-dev.ma-cp.com Auth: Microsoft Entra ID (client_credentials) Required Role: push:write QR Public: https://tegami-mail-dev.ma-cp.com

0. 目的

このページは「トークン取得 → テンプレート解析 → AIプレビュー → 一括生成 → Salesforce通知」の旧オンプレ運用手順に合わせて、AWS版で何が使えるかを確認するための画面です。

AWS版の本線は、Salesforceから受け取った差し込みデータでDOCX手紙を生成し、ZIP化してSES経由でメール送信する流れです。手紙に印字するQRコードのスキャン状況もRDSに記録します。
旧オンプレと完全同一ではありません。認証・保存方式・一部APIはAWS移行方針により変更されています。未実装のものは下の一覧とブラウザテスト内で明示しています。

1. 最小API一覧

1. Token旧: /oauth2/token
AWS: Entra IDで取得
2. Analyze/api/analyze-template
実装済み
3. AI Preview/api/ai-preview
実装済み
4. Batch/api/generate-letter-batch
実装済み
5. Salesforce/api/salesforce/letter-batch-response
未実装
6. QR/r/{token}
AWS版で追加
MethodPath状態認証用途
POST/oauth2/token廃止不要AWS版ではアプリ内発行しない。Microsoft Entra IDで取得
GET/api/health実装済みBearer (write)認証込みの稼働確認
POST/api/analyze-template実装済みBearer (write)DOCX差し込み項目抽出
POST/api/ai-preview実装済みBearer (write)AI文章プレビュー
POST/api/generate-letter-batch実装済みBearer (write)一括生成・品質チェック・ZIPメール送信
POST/api/salesforce/letter-batch-response未実装Bearer (write)生成結果をSalesforceへ通知。AWS版MVP外
GET/r/{token}実装済み不要（公開）QRスキャンの記録 + 外部フォームへリダイレクト
GET/healthz実装済み不要ALB ヘルスチェック
旧画面の操作順に近づけるため、廃止・未実装APIも一覧に残しています。ボタンがない/押せないものはAWS版ではまだ呼べません。

2. API詳細

POST/oauth2/tokenAWS版では廃止

旧オンプレ: アプリ自身がclient_credentials tokenを発行。

AWS版: Microsoft Entra ID の token endpoint を直接使います。devのブラウザテストではCORS回避用に /dev/token プロキシを用意していますが、本番クライアントが使うAPIではありません。

GET/healthz

認証: 不要 / ALBターゲットグループのヘルスチェック用

Response 200
{ "status": "ok" }
GET/api/health

認証: Bearer JWT 必須

Response 200
{ "status": "ok", "environment": "dev" }
POST/api/analyze-template

旧オンプレ: DOCXをアップロードして、差し込み項目を抽出。

Request (application/json)
{
  "file_type": "letter",
  "file_name": "template.docx",
  "file_data": "<BASE64_DOCX>"
}

Response 200
{
  "status": "success",
  "data": {
    "file_type": "letter",
    "file_name": "template.docx",
    "placeholders": ["企業名", "AI_TEXT", "QR_CODE"],
    "placeholder_count": 3
  },
  "message": "テンプレート解析が完了しました"
}
POST/api/ai-preview

認証: Bearer JWT 必須（roleに push:write）

Request (application/json)
{
  "prompt": "株式会社サンプル向けにM&A提案文を作成してください",
  "substituted_values": {
    "企業名": "株式会社サンプル",
    "業種": "製造業"
  }
}
POST/api/generate-letter-batch

認証: Bearer JWT 必須（roleに push:write）

Request (application/json)
{
  "request_id": "ma-20260428-001",
  "user": { "name": "宇都宮", "email": "utsunomiya@knowing-lab.com" },
  "mail_to": "letter-gen@ma-cp.com",
  "template_files": {
    "letter": ["<BASE64_LETTER_DOCX>"]
  },
  "generation_types": ["letter"],
  "mappings": {
    "letter": { "企業名": "Name", "QR_CODE": "QR_CODE" }
  },
  "companies": [
    {
      "task_id": "TODO12345",
      "company_data": { "Name": "株式会社テスト" },
      "qr_url": "TODO12345"
    }
  ],
  "has_ai_text": false,
  "has_qr_code": true,
  "output_format": "external_storage"
}

Response 200
{
  "status": "success",
  "data": {
    "file_urls": { "all": "X:\\\\...\\\\宇都宮_20260428_153000.zip" },
    "expiration_date": "2026-05-14T03:00:00Z",
    "generated_count": 1,
    "excluded_count": 0,
    "file_info": { ... },
    "quality_check_results": { ... },
    "total_tokens_used": 97,
    "processing_time_ms": 1234
  },
  "message": "手紙生成と品質チェックが完了しました"
}
POST/api/salesforce/letter-batch-response未実装

旧オンプレ: generate-letter-batch の結果をSalesforceへ通知。

AWS版: 未実装です。現時点では /api/generate-letter-batch のレスポンスを呼び出し元が受け取り、必要に応じてSalesforce側で扱います。

GET/r/{token}

認証: 不要（QRスキャナから公開アクセス）

QRトークンを引いて、qr_scans に記録してから target_url へ 302リダイレクト。未知のtokenは MA_QR_FALLBACK_URL へ302。

3. ブラウザテスト dev only

下のフォームから直接APIを叩けます。本番環境では/dev/tokenプロキシが無効化されているのでトークン取得セクションは動きません。

3-1. トークン取得（旧 /oauth2/token 相当）

旧オンプレの /oauth2/token の代わりに、AWS版ではMicrosoft Entra IDから JWT を取得します。この画面では dev only の /dev/token プロキシを経由します。

未実行

共通: アクセストークン

3-2. /api/health 試行

未実行

3-3. /api/analyze-template 試行

DOCXテンプレート内の差し込み項目を抽出します。

未実行

3-4. /api/ai-preview 試行

プロンプト1個だけ送って Azure OpenAI の応答を確認。手紙生成のフルフローを回さずに AI 単独テストが可能。

未実行

3-5. /api/generate-letter-batch 試行

旧画面と同じく、テンプレートファイルと payload_json を分けて入力します。AWS版APIはJSON/Base64受信のため、送信時にこの画面が添付ファイルをBase64化して template_files へ入れます。

旧画面の multipart 操作感に寄せていますが、AWS版の実送信は application/json です。ファイル未選択時は payload_json 内の template_files をそのまま使います。
未実行

3-6. /api/salesforce/letter-batch-response 試行 未実装

旧オンプレ画面では一括生成レスポンスをSalesforceへ通知するための操作でした。AWS版ではまだ実装していません。

AWS版MVP外: /api/salesforce/letter-batch-response はまだ呼び出せません

3-7. /r/{token} 試行 AWS版追加

注意: ブラウザは302をたどるので最終リダイレクト先が表示されます。「新しいタブで開く」ボタンは新しいタブで開きます。

未実行