商品一覧の取得（GET /products）およびメタデータ等の更新（PATCH /products/:id）APIの定義追加

[reiroop]

登録されている商品一覧の取得（GET /products）およびメタデータ等の更新（PATCH /products/:id）APIの定義追加

解決したい課題

サークル管理アプリケーションにおいて、登録されている商品（Stripe Products）の一覧を取得し、かつ外部システムから商品の属性（metadata 等）を安全かつ動的に更新できるようにするため、商品管理に関するAPIエンドポイントを追加する必要があります。

設計意図

1. フロントエンドの選択肢提示:
   • ユーザーや管理者が請求書を発行する際（POST /me/invoices および POST /invoices）、有効な product_id を画面上で選択可能にする必要があります。その選択肢（商品一覧）をフロントエンドへ安全に提供するために GET /products を定義します。
2. ユーザー権限に応じた閲覧制御:
   • ユーザーの役割や権限等によって取得可能な商品を制御・フィルタリングする想定であるため、GET /products の閲覧制限を行えるようにします。バックエンド側でリクエスト元の権限（認証セッションの種類など）に基づき、現在取得可能な商品に絞り込んでレスポンスをフィルタリング・返却する設計とします。
3. キュレーションモデル:
   • Stripe の Product オブジェクトのプロパティのうち、アプリケーションで使用するもののみに絞って定義します。これにより、スキーマの複雑性を低減しメンテナンス性を向上させます。
4. ネスト構造:
   • Stripe では Product と Price が別オブジェクトとして管理されていますが、クライアント側での表示や処理の便宜性を考慮し、価格情報を商品情報（Product）にネストした Price オブジェクトとして含めます。Price に由来する属性（unit_amount, currency, recurring, type）を Price オブジェクトとして独立させることで、Stripe のデータ構造との対応関係を明確に維持します。
5. プロパティ選定:
   • currency: Stripe 上に日本円（jpy）以外の価格設定が追加された際、UIと実データの齟齬を防ぐために含めます。
   • type / recurring: UI 側で「年額 / 月額 / 単発」などの周期表記をハードコーディングせず、実データに基づいて動的に表示分けできるようにするために定義します。
   • Stripe の公式ドキュメント（id 先頭、以降はアルファベット順）に厳密に準拠したフィールド順を採用し、デベロッパーの認知負荷を最小化します。
6. 外部システム連携と動的更新:
   • 本サービス内において、商品の metadata はユーザーの種別や時期ごとのデフォルト設定等を管理するために使用されます。サービス側の処理と Stripe 上の商品のメタデータを柔軟に連携させるため、本 API から metadata を更新可能とします。

達成したい要件

1. GET /products の追加: 認証セッション（EmailVerifiedSession または NeoShowcaseAuth）を必須とし、未認証アクセスには 401 Unauthorized を返します。Stripe 互換の active, ending_before/starting_after, limit, および特定の商品を絞り込んで一括取得できる ids クエリパラメータをサポートします。
2. PATCH /products/{id} の追加: 管理者権限（NeoShowcaseAuth）が必要。外部サービスからのメタデータ同期や設定更新のため、リクエストボディに metadata フィールドを含めます。