価格API（/prices）および商品API（/products）の定義追加と、Invoice作成時における price_id 指定への修正

[reiroop]

価格API（/prices）および商品API（/products）の定義追加と、Invoice作成時における price_id 指定への修正

解決したい課題

Stripe を用いた決済処理（請求書アイテムの追加など）においては、商品ID（product_id）ではなく価格ID（price_id）を指定してAPIを呼び出す必要があります。

現行 of POST /me/invoices (Invoice 作成 API) は product_id を受け取る設計になっており、Stripe 上で正常に請求書を発行できません。

本修正では、Invoice 作成 API で price_id を受け取るように修正します。また、これに伴ってフロントエンドが有効な Price ID を取得するためのマスタAPI（/prices）を新設し、さらに価格情報から参照される詳細な商品マスタを取得するための商品API（/products）も追加します。

設計意図

1. Invoice 作成 API の修正と価格一覧・商品一覧APIの定義:

   • Stripe 物理仕様において請求対象を指定するパラメータである価格IDを渡せるよう、POST /me/invoices のパラメータを product_id から price_id に変更します。
   • これに伴い、フロントエンドが有効な price_id を取得・選択できるようにするため、価格一覧を提供する GET /prices を新設します。
   • さらに、価格データに関連付けられている詳細な商品情報を取得可能にするため、商品一覧を提供する GET /products も新設します。

2. スキーマの独立性とIDによる分離（設計方針）:

   • Price スキーマと Product スキーマを物理的に独立した別個のデータモデルとして定義します。
   • Price スキーマは商品オブジェクトを内包せず、Stripe の物理仕様に準拠したID参照である product: string (Stripe Product ID) のみを持つようにします。
   • これにより、同一の商品に対して複数の価格（割引価格や周期違いなど）が存在する場合に、同一の商品オブジェクトが何度も重複してレスポンスに含まれ、通信ペイロードが肥大化（ネットワーク負荷）する問題を防止します。
   • フロントエンドが必要に応じて /products から商品情報を取得し、/prices から価格を取得して、IDによってデータ結合する設計とします。

3. ユーザー権限に応じた閲覧制御:

   • ユーザーの役割や権限等によって取得可能な情報を制御するため、GET /prices および GET /products の閲覧制限を行えるようにします。バックエンド側でリクエスト元の権限（認証セッションの種類など）に基づき、現在取得可能なリソースに絞り込んでレスポンスをフィルタリング・返却する設計とします。

4. Stripeメタデータの動的同期:

   • 価格および商品の metadata は、本サービス内におけるユーザー種別の判定ロジックや、特定の決済時期に応じた適用ルールなどを管理するために使用されます。Stripe 上のオブジェクトの状態を同期させるため、/prices/{id} および /products/{id} の PATCH を定義して metadata および active を更新可能とします。

5. スキーマ内のプロパティ構成:

   • 不要な内部メタ属性を排除し、本サービスに必要な以下のプロパティのみに絞り込んで定義します。
   • Price スキーマ: id (Stripe Price ID), active, currency, product (Stripe Product IDへの参照), recurring (継続課金周期情報), type, unit_amount
   • Product スキーマ: id (Stripe Product ID), active, description, metadata, name
   • プロパティの記述順は、Stripe の公式ドキュメント（id 先頭、以降はアルファベット順）に準拠します。

達成したい要件

1. /prices API の追加

• GET /prices:
  • 認証セッション（EmailVerifiedSession または NeoShowcaseAuth）を必須とし、未認証アクセスには 401 Unauthorized を返します。
  • クエリパラメータとして以下をサポートします：
    • active (boolean, デフォルト true): 有効な価格のみを取得するか、無効な価格のみを取得するかを制御するフィルター。
    • product (string, optional): 指定した商品ID (Stripe Product ID) に一致する価格のみをフィルターする。
    • type (string, optional, enum: [one_time, recurring]): 課金タイプ（単発または継続）でフィルターする。
    • limit (integer, デフォルト 10) / starting_after (string) / ending_before (string): カーソルページネーション用。
• PATCH /prices/{id}:
  • 管理者権限（NeoShowcaseAuth かつ CsrfTokenHeader）が必要。
  • リクエストボディに active (boolean) と metadata (object) を含め、価格ステータスと付随するメタデータを動的に更新可能とします。

2. /products API の追加

• GET /products:
  • 認証セッション（EmailVerifiedSession または NeoShowcaseAuth）を必須とします。
  • クエリパラメータとして以下をサポートします：
    • active (boolean, デフォルト true)
    • ids (array of strings, optional): 指定した商品IDリストに一致する商品のみをフィルターする。
    • limit / starting_after / ending_before
• PATCH /products/{id}:
  • 管理者権限（NeoShowcaseAuth かつ CsrfTokenHeader）が必要。
  • リクエストボディに active、description、metadata、name を含め、商品情報を動的に更新可能とします。

3. Invoice 作成 API リクエストスキーマの修正

• PostMeInvoiceRequest のプロパティ product_id を price_id に変更します。