お金の記録アーキテクチャ(台帳の正本性・不変性・金額表現・状態網羅)を決める

横断前提の追加(#39): 台帳は決済プロバイダ非依存で設計する。内部状態集合はドメイン語彙で定義し(プロバイダの状態機械は参考にしつつ値・遷移は内部で持つ)、入金は webhook で受けた外部イベントを内部台帳に記録する。プロバイダ固有の金額・状態表現に直接依存しない。

背景

現状はハンドラが Stripe を直接叩くだけ(packages/api/src/invoices.ts / checkout.ts)で、入出金の内部記録は無い。#21 が DB ベースの台帳を実装しようとしているが、その台帳をどういう性質のデータとして持つかが未確定。

なぜ今決めるか

金銭記録と監査証跡は「後から復元できない」代表例で、データが積もった後の型・単位・記録方式の変更は事実上不可逆。台帳を正本にするか派生ビューにするか、金額をどう表現するか、どの状態まで表現できるかを先に決めないと、記録の正しさと監査可能性を後から作れない。

論点・選択肢

• 台帳の正本性: 内部台帳を book of record(正本)にするか、Stripe を都度参照する派生ビューに留めるか。
• 不変性: append-only にし、返金・失敗・取消・チャージバックは元エントリの書換ではなく符号付きの新規エントリで表現するか。行更新を許すと残高の再現性と監査が失われる。
• 金額表現: 整数の最小通貨単位 + 明示的な通貨コードに固定し、浮動小数点は一切使わない(丸め誤差が会計残高に恒久的に残るため)。JPY 固定でも通貨カラムは持っておくと後の拡張が安い。
• 状態網羅: open→paid→refunded/partially_refunded、open→void/uncollectible、paid→disputed、payment_failed を初日から direction × status で一貫表現できるか。表現できないと該当 webhook を捨てるしかなく、後から遡れない。
• スナップショット: 請求時点の金額・期・商品名を台帳に固定し、可変な Stripe price/product を参照で持たない(価格改定で過去の履歴が遡って変わるのを防ぐ)。

受け入れ条件

• 台帳の正本性・不変性・金額表現・状態集合・スナップショット方針が決まり、#21 のスキーマ設計の前提として文書化されている。

関連

#20(商品情報・支払い参照)・#21(台帳の DB 実装)・#17(webhook 受信)の設計前提(親)。webhook 信頼性の決定、ドメインモデルの決定と接続する。

Start by reading packages/api/src/invoices.ts and packages/api/src/checkout.ts to understand the current Stripe integration, then review the linked design issues #17, #20, #21, and #39. Compare the proposed ledger properties, amount representation, status coverage, and snapshots with the existing design. Done means these policies are decided and documented as prerequisites for #21’s schema design.