設計レビューで判明した会員・会計フローの要求ギャップ

[reiroop]

背景

設計レビューで、現状の issue に明確な担当が無い、または記述が設計意図と食い違う要求を検出した。各関連 issue に反映するか、個別に issue 化する。

ギャップ

• 入部費 price のサーバー決定(過少請求防止): 現状 invoices.create は price をクライアントからの入力のまま受け取っている。期(前期 4000 / 後期 2000)に応じて price をサーバー側で自動的に決定するロジックと、期の境界(日付)を判定する処理が必要。放置すると、前期の入部者が後期の 2000 を指定して過少請求できてしまう。(セッション・管理者依存エンドポイントの契約とバックエンドを実装する #18)
• 支払者情報の付与(enrichment): 一覧に「誰が払ったか」を出す担当が不在。traq_id を Stripe metadata から DB へ移した後、customer_id → DB 逆引きで traq_id / 氏名を entry に付与する必要がある。(入出金一覧に商品情報・支払い参照を含める #20 / 統合台帳 入出金の統合台帳 ledger.list を DB ベースで実装する #21)
• 再入部の未検証 traQ ID の隔離: 凍結アカウント(セッション無し)の再入部では、入力された traQ ID を Customer への保存・参照には使わず、どの凍結アカウントを復旧対象とするかの特定にのみ使う。セッション・管理者依存エンドポイントの契約とバックエンドを実装する #18 の「traq_id を常にセッション由来として DB 紐付け」という前提と矛盾する。認証プリンシパルごとに traq_id の信頼度を分ける必要がある。(セッション・管理者依存エンドポイントの契約とバックエンドを実装する #18)
• webhook の会計通知と会員状態モデル: Stripe webhook(invoice-paid)を実装する #17 の「会員状態の更新」については、そもそも会員状態を表すモデルが未定義。加えて、通知の宛先・手段、凍結時のみ通知する条件、checkout.session.completed 由来の入金の扱いも要検討。(Stripe webhook(invoice-paid)を実装する #17)
• 二重プリンシパルの所有権キー: 新規/再入部はメール検証(認証サブシステム(メール確認・CSRF・セッション)を実装する #16 の isct セッション)、現役は traQ セッションが本人性の根拠であり、所有権キーがプリンシパルによって変わる(mail_hash か traq_id→customer か)。オブジェクト単位認可の前提として整理が必要。(認可・レート制限を導入し、無認証アクセスを塞ぐ #15 / 認証サブシステム(メール確認・CSRF・セッション)を実装する #16)
• Customer 重複回避: 作成前に Stripe を email で検索して既存を再利用し、リトライ時の二重作成を防ぐ(冪等)。(セッション・管理者依存エンドポイントの契約とバックエンドを実装する #18)
• 二重支払い防止: 1 ユーザー・1 期あたり入部費は 1 回。未払いの入部費請求が既にあれば新規発行しないガードが必要(冪等キーは同一リクエストのリトライしか防がない)。(認可・レート制限を導入し、無認証アクセスを塞ぐ #15 / セッション・管理者依存エンドポイントの契約とバックエンドを実装する #18)
• 管理者の付与・剥奪: セッション・管理者依存エンドポイントの契約とバックエンドを実装する #18 は GET /admin(一覧)のみ。管理者権限を付与/剥奪する導線と、初期管理者のブートストラップが必要。(セッション・管理者依存エンドポイントの契約とバックエンドを実装する #18)