ReconciliationとIntegrity Check
制約で予防するだけでなく、保存済みデータを横断して異常を発見する仕組みを学びます。
台帳、振込、KYC、権限、監査、照合をMinibankの実装と結び付ける。
先に学ぶ内容 — Prerequisite: 基礎 / 銀行業務学ぶこと — LEARNING GOALS
このページで学ぶこと
- 予防と検出の違い
- 照合対象
- 正常・異常をどのように記録するか
体験06 · RECONCILIATION（照合）
小さな間違いは、どう見つかるか確かめよう
まずは予想をひと言。本文を読んだ後、管理者向けの検査画面と、その記録を確認します。
- 01まず予想する — PREDICT
まずここだけ：思ったことをひと言書く
銀行のシステムに小さな記録の食い違いがあったとき、誰かが気づく前に自動的に直ると思いますか？
正解でなくて大丈夫です。「〜だと思う」から始めてみましょう。
ヒント1を見る
「間違いを起こさせない仕組み」と「起きた間違いを見つける仕組み」は、同じものでしょうか？
ヒント2を見る
見つかった食い違いは、誰かが確認するまでどうなっていると思いますか？
もっと詳しく：この問いで使う専門用語
- Constraint（制約）は、データベースが不正な状態を最初から作らせない仕組みです。
- Reconciliation（照合）は、保存済みの記録を後から比べて食い違いを探すことです。
- Integrity Check（整合性検査）は、照合の実行そのものです。
- Issue（検出された問題）は、照合で見つかった食い違いの記録です。
日常語で理解する — PLAIN LANGUAGE
まず、ここだけつかむ
照合は、保存済みのデータを複数の角度から再計算し、食い違いや孤立を見つける健康診断です。制約が事故を入口で止めるのに対し、照合は残ってしまった異常を発見します。
台帳残高とcached_balance、業務取引と仕訳、元仕訳と逆仕訳、顧客口座と台帳口座などを比較します。
検出しただけでは直りません。重大度、対象、検出時刻を保存し、通知・調査・安全な是正へつなげる運用が必要です。
順番に理解する — DIFFICULT PARTS, STEP BY STEP
難しいポイントを、順番にほどく
専門用語を覚えることより、「なぜ必要か」「このシステムのどこで使うか」を理解することが目標です。
予防と検出
制約や権限は不正状態を作らせない予防、reconciliationは既にある異常を探す検出です。
未知の不具合、過去version、運用者の強権限操作まで予防だけで完全には覆えません。
DB constraintとRLS/RPCに加え、reconciliation.run_check()を用意しています。
source of truthとcache
正しいとみなす正式記録と、表示を速くする複製値です。
両者がずれた際、どちらを基準に調査・再構築するか決める必要があります。
ledgerを正とし、bank_accounts.cached_balanceとの差を検出します。
orphan
親となる記録を失い、意味を説明できなくなった孤立データです。
仕訳はあるのに口座がない、逆仕訳元がない状態は会計履歴を壊します。
外部キーに加え、検査でmissing ledger accountなどの異常を探します。
Integrity RunとIssue
Runは1回の検査実行、Issueはその中で見つかった個別問題です。
いつ何を検査し、何件見つけ、解決したかを運用で追跡できます。
検査結果をrun単位とissue単位で保存し、管理画面から確認します。
発展 — ADVANCEDもっと詳しく確認する最初の学習では読まなくても問題ありません。仕組みをもっと深く理解したい場合に開いてください。
通常状態と異常状態
| 対象 | 通常 | 検出する異常例 |
|---|---|---|
| 残高 | ledger集計 = cached_balance | BALANCE_MISMATCH |
| 仕訳 | 2行以上、借方 = 貸方 | JOURNAL_LINES_INSUFFICIENT / JOURNAL_NOT_BALANCED |
| 口座 | 対応ledger accountがある | MISSING_LEDGER_ACCOUNT |
| 業務記録 | transfer/operationとjournalが対応 | MISSING_TRANSFER / ORPHAN_TRANSFER / TYPE_MISMATCH |
| 逆仕訳 | 対象・金額・参照が一致し1回だけ | REVERSAL_* / DOUBLE_REVERSAL |
| 管理 | active admin_managerが1人以上、actor分離 | NO_ACTIVE_ADMIN_MANAGER / ACTOR_COLLISION |
検査の流れ
- 01service_roleまたはactive adminがwrapperを呼ぶ
- 02reconciliation.run_check()がカテゴリ別に照合
- 03異常をintegrity_issuesへ追記
- 04件数と状態をintegrity_runsへ記録
- 05管理画面のread APIで履歴を確認
実際のMinibankでは
`full` のほか `balance`、`journal`、`financial_operations`、`reversal` を選べます。検査結果tableも通常運用ではappend-onlyです。既知のテストfixtureはmigration内で明示的に除外されています。
体験学習の続き · LEARNING LOOP
ここまで読めましたか？続けて確認してみましょう
予防と検出の違いを読んだところで、実際の検査画面とその記録を確認し、自分の言葉で説明してみます。
- 02実際に観察する — OBSERVE
同じ仕組みを、動く画面から観察する
この仕組みは管理者向けの検査画面でのみ確認できます。管理者ログインがない場合は、この教材内の図・説明・Source Trail（教材の参照元）で代替学習し、次へ進めます。
管理者ログインがない場合：教材の参照元で確認する ↓ - 03証拠を確認する — EVIDENCE
何を見たか、1つずつ確かめる
Evidence（判断の根拠となる記録）を確認したらチェックします。各項目の「何を見るか」を手がかりにしてください。
画面を開けない項目は、Source Trail（教材の参照元）と教材の説明で確認できます。失敗を実際に起こす必要はありません。
- 04コードの処理経路を追う — CODE TRAIL
コードを書く必要はありません
ここでは「説明されている仕組みが、実際のMini Bankのどこに実装されているか」を確認します。まずは日本語の役割説明を読み、入力した依頼がどこへ渡るかをつかみましょう。コードの全文を読む必要はありません。
基本の順序は、画面 → API Route（依頼を受ける窓口）→ TransferService（処理をつなぐサービス）→ DB / RPC（記録の保存場所と、その処理の呼び出し）です。まず最初の2つを見て、続くサービスは「もっと詳しく」で確認します。
教材の参照元を確認する — Source Trail ↓Migration（DB定義の変更履歴）。残高・仕訳・業務記録・逆仕訳を照合する定義を確認します。
supabase/migrations/20260823120001_add_integrity_check_missing_gaps.sql管理者向けの検査結果画面。検査履歴と問題一覧をどう表示するかを探します。
src/app/admin/(protected)/integrity/page.tsx - 05自分の言葉で説明する — EXPLAIN
LEVEL 1 — やさしい説明（まずここだけ）
制約（constraint）と照合（reconciliation）は、何を防ぎ、何を見つけるという役割の違いがあるでしょうか？ 短い2文を目安に説明してください。
日常語だけで完了できます。専門用語の数や正誤を自動採点するものではありません。
ヒント1を見る
「制約」と「照合」という2つの言葉を使って書いてみましょう。
ヒント2を見る
見つかった食い違いが、自動で直るべきか、人が確認すべきかを考えてみましょう。
もっと詳しく：LEVEL 2 — 専門用語を使った説明（任意）
Constraint、Reconciliation、Integrity Run、Issueの4つを使って、異常が発見されるまでの流れを説明してみましょう。
挑戦する場合は、上の説明欄に追記できます。追加しなくても完了できます。
説明の確認ポイント — Checkpoint- 制約と照合が別の役割であると説明できる
- 検出された問題は自動で直るとは限らないと説明できる
理解を確かめる — CHECK YOUR UNDERSTANDING
3問で理解チェック
答えを頭の中で考えてから、各項目を開いて確認してください。
Q1DB制約があれば照合は不要ですか？
不要ではありません。未知の不具合や過去データ、強権限操作などで残った異常を検出する役割があります。
Q2残高cacheと台帳が違ったらどちらを基準にしますか？
設計上のsource of truthである台帳を基準に原因を調査します。自動修正は承認と監査を伴うべきです。
Q3異常を画面表示するだけで十分ですか？
十分ではありません。通知、担当、調査手順、重大度、是正と再検査まで運用設計が必要です。
完全に暗記する必要はありません。大切な考え方を説明できそうなら押してください。
教材の参照元 — SOURCE TRAIL
根拠と関連教材
CURRENT IMPLEMENTATIONは確認したrepository内の実装です。HISTORICAL IMPLEMENTATIONは導入・修正の履歴で、後続migrationによる再定義があり得ます。RELATED LESSONは教材への案内で、実装の一次Sourceではありません。ASSUMPTIONは仮定、UNKNOWNは未確認を表します。
確認基点: d02eae8914f39cbf06bfe422dc39c71886f82b3e / 2026-09-11。稼働環境への適用確認: UNKNOWN。パス実在の自動検査と、記述した技術的事実の確認は別です。
- 過去の実装 — HISTORICAL IMPLEMENTATION
supabase/migrations/20260821110001_create_reconciliation_schema_and_tables.sqlrunとissueの記録 - 過去の実装 — HISTORICAL IMPLEMENTATION
supabase/migrations/20260823120001_add_integrity_check_missing_gaps.sqlreconciliation.run_check()残高・仕訳・業務記録・逆仕訳の検査 - 過去の実装 — HISTORICAL IMPLEMENTATION
supabase/migrations/20260823160001_enforce_actor_separation.sqlACTOR_COLLISION検出 - 現在の実装 — CURRENT IMPLEMENTATION
src/app/admin/(protected)/integrity/page.tsx管理画面の検査履歴