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

[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)

[reiroop]

会員・会計機能の追加で、ここに挙がっているギャップのいくつかが埋まりました。8 つを 1 つずつ突き合わせた結果を記録します。2026-09-18 に feat/merge-auth-collection の d8feaca で確かめたものです。

埋まったもの（4 つ）。

• 入部費 price のサーバー決定: packages/api/src/billing/pricing.ts の selectPriceId が費目（新規入部費か継続部費か）・期（前期か後期か）・区分（標準か特別か）から price id を選びます。期の判定は packages/api/src/billing/term.ts の computeTerm と computeActivityYear です。packages/api/src/membership/router.ts は入力から price を受け取らないので、クライアントが安い price を指定する経路がありません。
• 二重プリンシパルの所有権キー: packages/api/src/auth/session.ts の SessionIdentity が traqId・userId・mailHash・isAdmin を別の項目として持ち、どれが本人性の根拠かをプリンシパルごとに分けています。
• Customer 重複回避: packages/api/src/stripe/customers.ts の getOrCreateCustomer。
• 二重支払い防止: packages/db/src/schema.ts の membership_slots に (user_id, activity_year, half) の unique 制約（membership_slots_user_year_half_uq）があり、packages/api/src/ledger/store.ts の reserveSlots がこの制約で競合を解決します。アプリ側の読んで確かめて書く方式ではありません。

部分的なもの（2 つ）。

• 再入部の未検証 traQ ID の隔離: packages/api/src/membership/router.ts は、セッションの traq_id を Customer の metadata に使うのを、連結の結果が「連結済み」か「既存」のときだけに限り、衝突時はその user に既に連結された id へ落とします。未検証の traQ ID を利用者の入力として受ける経路自体は現在ありません。
• webhook の会計通知と会員状態モデル: 会員状態は membership_slots（open と paid の 2 値）として定義されました。通知は packages/api/src/notify/notifier.ts が担い、apps/web/server/routes/webhook/invoice-paid.post.ts が invoice.paid で呼びます。ただし checkout.session.completed は購読していません（このルートは invoice.paid 以外のイベントを承認して無視します）。凍結時のみ通知する条件も入っていません。

残っているもの（2 つ）。

• 支払者情報の付与: 会計の一覧が出す支払者名は、packages/api/src/payments/normalize.ts の readCustomer が Stripe の展開済み customer から読んだものです。stripe_customer_id から DB を逆引きして traq_id や氏名を付ける経路はありません。
• 管理者の付与・剥奪: 会計かどうかの判定は環境変数の許可リストです。apps/web/server/routes/login/callback.get.ts が isAccountant を呼び、結果を sessions.is_admin に書きます。付与・剥奪の導線も、初期管理者のブートストラップもありません。