ログインユーザー専用の請求書作成APIの導入とパラメータの安全化

[reiroop]

解決したい課題

現在、請求書作成用API（POST /invoices）はルート直下に配置されており、クライアント側から customer_id を直接指定して送信する仕様になっています。

これには以下のセキュリティおよび運用保守上の課題があります。

1. 不正な請求書作成リスク（権限昇格）:
   入部手続きや部費の支払手続きにおいて、一般ユーザー自身が本APIを呼び出す際、リクエストボディに任意の customer_id を指定して送信できてしまうため、他人の名義で不正に請求書を作成できてしまうセキュリティ脆弱性があります。
2. 再入部時の紐付け識別不可:
   再入部手続きにおいては、請求書支払時にアカウント復旧対象となる traq_id をWebhook側で検知して自動復旧をトリガーする必要がありますが、現在のリクエストスキーマ（PostInvoiceRequest）にはこのIDを受け渡すためのパラメータが定義されておらず、支払者と復旧対象アカウントの紐付けを識別することができません。
3. キー名の揺らぎによるサイレント障害リスク（保守性の課題）:
   上記IDをフリーフォーマットの汎用メタデータとして受け渡す設計にした場合、フロントエンドの実装におけるフィールド名のタイポや表記の揺らぎ（traqId 等）をスキーマ検証で検知できず、支払完了時にアカウントの復旧処理が実行されないサイレント障害が発生するリスクがあります。

達成したい要件（仕様）

API契約としての型安全性と堅牢性を担保しながら、これらの課題を解決します。

1. 個人コンテキスト用エンドポイントへの移行

• 既存の /invoices (POST) を廃止します。
• 代わりに、ログインユーザー自身の請求書を発行する専用のエンドポイント POST /me/invoices を新設します。
• これにより、クライアント側から customer_id を直接指定する設計を排除し、バックエンドがセッション情報から暗慢的かつ安全に顧客情報を解決するようにします。

2. PostInvoiceRequest スキーマの再定義と厳格化

• 新設する POST /me/invoices のリクエストスキーマ PostInvoiceRequest を以下の通り変更します。
  • customer_id フィールドを削除。
  • product_id（商品ID：必須） フィールドを定義。
  • traq_id（アカウント復旧対象の traQ ID：任意） フィールドをオプショナルとして明示的に定義。
• traq_id をスキーマに明示的に定義しておくことで、フィールド名のタイポや揺らぎをスキーマバリデーションで即座に検知し、かつ再入部時に支払者と復旧対象アカウントの確実な識別を保証します。

3. バックエンドにおける顧客自動作成処理の前提

• 本API呼び出し時、認証されたメールアドレスやアカウントに対応する Customer オブジェクトが未作成の場合、バックエンド側で自動的（透過的）に Customer オブジェクトを作成した上で、該当顧客向けの請求書を発行する動作を前提とします。