この銀行システムの仕組み

金融更新を戻す範囲と、失敗後に残す記録

金融更新の仕訳・transfers・残高cache・成功audit（TRANSFER_COMPLETEDと内側の変更trigger）は、confirm_transfer_otpの内側の例外blockでまとめてrollbackします。先に保存済みのrequestは消えません。transfer_auth.consumeによる認可済みintentの消費（consumed_at）、request=failed、TRANSFER_FAILEDは内側のrollbackの対象外で、外側のDB transactionがcommitすると残ります。

TOTPコードの正誤はDBではなくSupabase Authが判定します。DBはNext.jsのtransfer_mfa_broker経由で検証前に試行を予約し、その時点でintentのattemptsを加算します（累積5回まで、間隔30秒以上）。認証に失敗しても変わるのはintentとAuth側の状態だけで、requestはpending_otpのまま、金融データも変わりません。新しい認可がないままconfirmすると、transfer_auth.consumeが42501で拒否し、その呼出し全体がrollbackします。request=failedは金融更新の例外を捕捉した経路です。未捕捉例外・deferred constraint・commit自体の失敗なら、その呼出し全体の変更がrollbackするため、失敗記録の永続化を無条件には保証しません。

振込intentに束縛した認証アプリTOTPと、再試行・上限契約

v7（migration 20260920074653と20260920083426）の振込認可は、Supabase Authの認証アプリTOTPを振込intentへ束縛する方式です。request_transferは確認コードを生成・返却せず（otp_plaintext列は応答互換のため残り、常にnull）、reissue_transfer_otpは常に42501で拒否します。prepare_transfer_mfaは所有者・Auth session・送金元・送金先・金額・memo・依頼人名・idempotency key・期限のhashをintentへ固定します。ブラウザはコードをSupabase Authへ直接送り、Next.jsとDBはコードも、そのhashも受け取らず保存もしません。DBはAuth所有のchallenge検証時刻、AAL2 session、同じsessionのTOTP AMRを読んで認可し、confirmは60秒以内の認可を1回だけ消費します。DEMO_OTP_DISPLAY_ENABLEDでDBのコード生成は復活しません。TOTPは時刻ごとの値で、振込先や金額への署名ではなく、フィッシング耐性も主張しません。稼働DBへの適用はこの教材ではUNKNOWNです。

1. 安全な振込 — お金は10段階のチェックを通る

「振込」ボタンを押してから残高が動くまで、実はこのシステムは10個の関門を順番に通しています。どれか1つでも引っかかれば、お金は動きません。

1. 01入力：振込先口座番号と金額を入力する
2. 02本人確認状態チェック：本人確認（KYC）が済んでいるか確認する
3. 03口座状態チェック：振込元・振込先の口座が凍結されていないか確認する
4. 04残高確認：振込元の残高が足りているか確認する
5. 05振込上限チェック：不正な大口送金を防ぐための上限（仕組み自体は準備段階）
6. 06TOTP認可：認証アプリの6桁コードをSupabase Authで検証し、この振込に束縛した認可をDBが1回だけ消費する
7. 07Idempotency確認：同じ依頼を二重に送っても、二重に振込しない仕組み
8. 08Ledger記帳：振込元をマイナス、振込先をプラスとして、同時に記録する
9. 09Audit Log：「誰が・いつ・何をしたか」を消せない形で記録する
10. 10Integrity Check：あとから帳簿の合計が合っているかを機械的に検査する

2. Ledger（台帳）と会計 — 残高は「数字」ではなく「記録の積み上げ」

多くの人は「残高」をデータベースの1つの数字だと思いがちですが、この銀行システムでは違います。残高は「これまでのすべての取引記録を積み上げた結果」であり、数字そのものを直接書き換えることはできません。

• 複式記帳：1回の振込は「振込元の口座がマイナス」「振込先の口座がプラス」という2つの記録を必ずセットで作ります。
• 借方＝貸方：この2つの記録の金額は必ず一致します。片方だけ記録される、ということはシステム上できません。
• Append-only（追記専用）：一度記録した取引は、あとから書き換えたり削除したりできません。訂正が必要な場合は「反対の取引（Reversal）」を新しく追加します。
• Reversal（組戻し）：間違った取引を消すのではなく、打ち消す記録を追加することで帳簿の履歴をすべて残します。
• 残高整合性：表示上の残高（cached_balance）は、あくまで台帳の記録を集計した「キャッシュ」。本当の正解は台帳の記録そのものです。

3. Security（セキュリティ） — 1つの鍵ではなく、何重にも守る

この銀行システムは「本人確認さえ通れば何でもできる」という作りにはなっていません。何段階もの独立したチェックを重ねています。

4. Operations（運用） — システムは作って終わりではない

安全な仕組みを作るだけでなく、「その仕組みがちゃんと機能し続けているか」を見張る運用の仕組みも用意しています。

• Audit Log：誰が・いつ・何をしたかを、すべての重要な操作について記録します。
• Integrity Check：台帳の合計と口座残高がズレていないかを機械的に検査します。
• Reconciliation（照合）：帳簿同士を突き合わせ、矛盾がないかを確認する仕組みです。
• Observability（可観測性）：システムの中で何が起きているかを、後から追跡・確認できるようにする考え方です。
• Admin Console：管理者が本人確認の審査、口座の凍結・解除、監視状況の確認などを行う専用の画面です。

5. Testing（テスト） — 「たぶん動く」ではなく「毎回確認して動く」

見た目が完成していることと、実際に安全に動くことは別問題です。このシステムでは、コードを変更するたびに自動テストがすべて通ることを確認しています。現時点の総テスト件数は 407件 です。