本人確認の申請から、審査結果まで
申請した事実と承認された事実を分け、二重クリックや同時審査にも備える。
本文の説明・図・掲載コードだけで読み進められます。出典リンクは、権限のある人向け（非公開GitHub）です。GitHubで閲覧権限がある方だけ開けます。
この記事でわかること
- 顧客が申請してから、銀行担当者が審査する
- pending の再送は新しい申請を増やさない
- KYC 状態の変更も全体の書込停止に従う
この記事の目次
登録と本人確認は、別の一歩
架空の山田さんが会員登録を済ませても、それだけで振込を許してよいとは限りません。登録はログインする人と顧客情報を結び付ける段階であり、本人確認はその後に審査状態を持つ段階です。MiniBank では、この違いを not_started、pending、verified、rejected という状態で表します。
この仕組みは、本人確認の受付と判断の流れを学ぶシミュレーションです。実際の身分証の真正性、外部の本人確認会社との連携、法令上の審査を完了するサービスではありません。「verified」という文字は、このアプリ内の状態を表すもので、現実の本人確認能力を証明する印ではありません。まず何を模型にしているかを押さえてから操作の流れを読みます。
申請する本人を、入力欄で選ばせない
山田さんが申請するとき、顧客 ID を自由入力させて「この人を申請したい」と受け取る必要はありません。申請関数はログイン中の本人を使って、自分の顧客レコードを見つけます。他人の ID を送るだけで、その人の審査を始める経路を作らないためです。対象が見つからない場合は、先に顧客情報の登録が必要です。
not_started または rejected から、本人の申請で pending へ進みます。否認後の再申請は認めますが、すでに verified の人を同じ入口から pending へ戻しません。状態はただのラベルではなく、次に誰が何をしてよいかを決める条件です。すべての状態から同じボタンで上書きできると、審査の意味が消えてしまいます。
二度押しても、申請は一回のまま
申請ボタンを押した直後に通信が切れ、山田さんがもう一度押したとします。最初の申請が DB では終わっていた場合、二回目は pending の現在の記録を返します。もう一度更新したり、同じ申請イベントを増やしたりしません。これが、この申請で使う自然な冪等性です。「同じお願いなら、同じ状態を返す」と考えると分かりやすくなります。
すべての処理に同じ方式を当てはめるわけではありません。顧客自身の申請は状態を手掛かりにできる一方、銀行担当者が他人のデータへ行う承認や否認は操作キーで再送を識別します。誰の責任で、何を何回行ったかを追えるよう、顧客の申請と管理側の操作記録を分ける設計です。
実装を読む：申請の再送
申請関数の意味を短くした説明用の擬似コードです。
ログイン中の本人の顧客行をロックする
pending なら現在の行を返す
verified なら状態変更を断る
not_started または rejected なら pending にする
申請イベントを一度記録する審査は、申請済みのものだけにする
銀行担当の鈴木さんは、pending の申請を承認または否認します。以前の定義では未申請からも審査できましたが、申請機能が加わった後の変更で、pending だけが審査対象になりました。順序を DB でも守ることで、画面外からの呼出しでも「本人がまだ申請していないのに承認された」という食い違いを避けます。
API は対象 ID、操作キー、同じサイトからの要求、ログインの有無を確かめます。さらに DB が有効な管理担当者かを確認し、対象行をロックして審査します。二人が同時に承認と否認を送っても、両方が古い pending を見て勝手に上書きする構造にはしません。同じ操作者・同じ審査操作で操作キーを再利用し、対象の顧客だけを変えた場合は、キーの衝突として拒否します。
ここで審査担当者の確認と顧客の追加認証を混ぜないことも大切です。山田さんが自分の申請を出せることは、山田さんが自分を承認できることではありません。また、管理画面へログインできることも、いま有効な審査担当者である証明の代わりにはなりません。API の入口で要求の形を確かめ、DB の中で現在の権限と対象状態を確かめるのは、両方の失敗を別の場所で捕まえるためです。承認ボタンを押せない場合に画面だけを作り直して通そうとするのではなく、どの条件で断られたのかを読むべきです。審査後の履歴には以前の状態と業務イベントが残るため、後から「申請した後に誰が判断したか」をたどれます。現在の結果だけでなく、その結果に至る順序が審査の説明を支えます。
承認は、何でもできる許可証ではない
verified になると本人確認という条件は満たしますが、振込にはほかの条件もあります。本人の口座であること、口座が利用可能なこと、残高や上限が足りること、必要な追加認証があることは別に確認します。審査を一度通した事実で、その後のすべての安全確認を省略しない点が重要です。
また、銀行全体が復旧中なら、v20 の停止境界は KYC 状態の変更も止めます。お金が直接動かなくても、承認が将来の取引資格を変えるからです。一覧を読むことと、申請・承認・否認で状態を変えることは区別されます。画面が開くのに操作できない場合は、担当権限だけでなく、全体の停止状態も調べる観点になります。
困ったときは、現在の状態から読む
山田さんの申請が進まない場面では、まず自分の顧客情報が存在するか、現在は未申請・審査待ち・承認・否認のどれかを見ます。審査待ちなら、申請を何度も増やす作業ではありません。銀行側では、対象が pending か、操作した担当者が現在も有効か、同じ操作キーで何を行ったかを確認します。
本ガイドは、申請と審査のコード上の契約を追ったものです。実際の顧客を登録したり、審査状態を変えたりして確認したものではありません。現実の本人確認資料や秘密情報を教材へ入力する必要もありません。画面の名称だけで判断せず、対象者、現在の状態、操作の履歴という三つをそろえると、失敗の理由を説明しやすくなります。
出典と、確認できた範囲
以下のリンクは非公開GitHubへの出典で、閲覧権限が必要です。本文はリンク先を開かなくても読める構成です。固定コード・設計資料を参照していますが、今回、この読み物のために銀行の取引やDB操作、本番試験は実行していません。実装や資料にある検査と、こちらで実施した検証を混同しないようにしています。
- KYC の申請関数 ↗（非公開GitHub・要権限）
本人の申請・再申請・pending 再送の扱い - KYC の審査状態 ↗（非公開GitHub・要権限）
審査を pending に限定する追加変更 - KYC 承認 API ↗（非公開GitHub・要権限）
入力・同一オリジン・セッション・操作キーの確認 - 管理操作の権限とロック ↗（非公開GitHub・要権限）
口座凍結・KYC・管理者変更の権限再確認 - v2 の認可・整合性強化 ↗（非公開GitHub・要権限）
所有者・本人確認・口座状態を確認する歴史的な強化点 - 停止境界の強化コード ↗（非公開GitHub・要権限）
業務変更の停止と診断・無効化の例外
MiniBankは学習・検証用の銀行アプリです。架空の金額や人物は、仕組みを説明するための例です。
つながる読み物
ここまで読んだ記録を、ひとつ。
自分のペースで。あとから取り消すこともできます。