管理者権限による請求書作成（POST /invoices）APIの定義追加

[reiroop]

管理者権限による請求書作成（POST /invoices）APIの定義追加

解決したい課題

一般ユーザー向けのセルフ請求書作成（POST /me/invoices）に加え、管理者が特定の顧客（Stripe Customer ID）に対して個別に商品（Stripe Product）の請求書を発行し、任意のメタデータを付与できるようにするため、管理者向け請求書作成 API を定義する必要があります。

設計意図

1. セキュリティと権限の分離:
   • 一般ユーザー向けの /me/invoices は、セッションから顧客IDをバックエンド側で暗黙的に決定し、任意の金額や商品の指定を制限することで、不正な請求書発行を根本的に防ぐ極めてタイトなセキュリティ設計となっています。
   • 一方で、管理者向けの /invoices は、管理者（NeoShowcaseAuth のみ）に権限を限定した上で、任意の customer_id、product_id、および metadata の組み合わせを許可し、運用の柔軟性を最大化します。
2. メタデータの柔軟性:
   • 管理者が請求書を発行する際、任意の管理用情報やトラッキング用キーを付与できるようにするため、metadata を指定可能とします。
3. スキーマの共通化（DRY）:
   • 発行された請求書IDと決済URLを返すレスポンスを PostInvoiceResponse としてユーザー用（/me/invoices）と管理者用（/invoices）で共通統合し、スキーマの重複を排除します。

達成したい要件

1. POST /invoices の追加: 管理者権限（NeoShowcaseAuth）が必要。customer_id、product_id、および任意の metadata を受け取ります。
2. レスポンスの共通統合:
   • 既存の /me/invoices のレスポンススキーマ PostMeInvoiceResponse を PostInvoiceResponse にリネームして共通化します。
   • 既存の /me/invoices エンドポイントが参照するレスポンススキーマを新共通スキーマに変更します。