中級者編：設計を説明する
中級者の目標は、コードを読めることだけではありません。業務要件をデータ・状態・権限・トランザクションへ翻訳し、その設計理由を他者へ説明できることです。
境界、transaction、並行制御、脅威、テスト、障害対応をFailure Firstで学ぶ。
Prerequisite: FOUNDATION / BANKING SYSTEMLEARNING GOALS
このページで学ぶこと
- 入門から中級へ上がるための能力差
- 設計レビューで使う5つの視点
- Minibankを使った中級演習の進め方
PLAIN LANGUAGE
まず、ここだけつかむ
中級者は、動く仕組みを説明するだけでなく、なぜその境界・状態・制約にしたかを説明します。
要件をtableへ直訳せず、System of Record、状態遷移、不変条件、失敗時の結果へ分解します。
設計の主張は、migration・query・test・監視で確かめられる言葉にします。
DIFFICULT PARTS, STEP BY STEP
難しいポイントを、順番にほどく
専門用語を覚えることより、「なぜ必要か」「このシステムのどこで使うか」を理解することが目標です。
設計理由
構造を選んだ目的・制約・捨てた案です。
形だけをまねると、前提が違う変更で安全装置を壊すからです。
Ledgerを正としcached_balanceを派生値にする理由を不変条件から説明します。
検証可能な要件
testやqueryで真偽を判断できる条件です。
『安全』『高速』のような曖昧語では完成を判定できません。
同じrequest identityではjournalが1件だけ、とrecord数で検証します。
責任境界
どの層・componentが何を必ず守るかの分担です。
全員が誰かの確認を期待すると、実際には誰も守らない穴ができます。
UIは入力支援、DBは認可・lock・会計不変条件を担当します。
入門者と中級者の違い
| 観点 | 入門でできる | 中級でできる |
|---|---|---|
| 業務 | 振込の流れを説明する | 例外・取消・再送を含む状態遷移を定義する |
| データ | tableの役割を知る | 正となる記録、派生値、一意性、履歴を設計する |
| API | requestとresponseを追う | UI・API・DBの責任と信頼境界を分ける |
| 会計 | 借方と貸方を読む | 業務eventからrule・仕訳・照合まで追跡する |
| 運用 | testが必要だと分かる | 監視・復旧・手作業・証拠をrelease前に設計する |
中級者が設計前に答える5問
- 01何がSystem of Recordか
- 02許可される状態と遷移は何か
- 03絶対に破れない不変条件は何か
- 04同時実行・再送・途中失敗でどうなるか
- 05本番で異常をどう検知し復旧するか
推奨する学習順
| 順番 | 教材 | 成果物 |
|---|---|---|
| 1 | 業務をデータモデルへ翻訳する | aggregate・状態機械・不変条件表 |
| 2 | トランザクション境界を設計する | 成功・rollback・冪等性の処理図 |
| 3 | APIとDBの責任境界 | 信頼境界と認可責任表 |
| 4 | 運用できる設計へ仕上げる | SLI・alert・runbook・release checklist |
| 5 | 既存の振込・会計・security教材を再読 | Minibankの実装を根拠にした設計レビュー |
中級修了課題：振込変更をレビューする
『振込手数料を時間帯で変える』という変更を想定し、仕様だけでなく、保存すべき金額snapshot、Accounting Rule、idempotency fingerprint、同時実行、公開error、audit、照合、移行、rollbackまで挙げてください。
正解を暗記する課題ではありません。影響先を漏れなく地図へ置き、どの証拠で安全を確認するか説明できれば中級の入口に立っています。
- 事実・仮定・未決定事項を分ける
- 正常系だけでなく再送・競合・途中失敗を書く
- DB制約で守るものと運用で検知するものを分ける
- 利用者向けmessageと内部診断情報を分ける
実際のMinibankでは
transfer_requests、OTP、transfers、journal、cached_balance、auditが、1件の振込を異なる責任で表します。中級編ではtable名を覚えるのではなく、なぜ分かれ、どれがどの時点の事実を表すのかを読みます。
この教材の説明は実装を読む入口です。コードにない保証を推測せず、migration、RPC、service、回帰testを順番に照合してください。
CHECK YOUR UNDERSTANDING
3問で理解チェック
答えを頭の中で考えてから、各項目を開いて確認してください。
Q1中級者の成果はコード量ですか？
いいえ。業務要件を状態・データ・権限・失敗へ分解し、設計理由と証拠を説明できることです。
Q2『二重処理しない』をどう検証可能にしますか？
同じrequest identityを複数回・並行送信し、業務recordとjournalが1件だけであることを確認します。
Q3既存教材を読み終えたら中級修了ですか？
読むだけではなく、変更課題に対して影響範囲・不変条件・test・運用を自分で作る必要があります。
完全に暗記する必要はありません。大切な考え方を説明できそうなら押してください。
SOURCE TRAIL
根拠と関連教材
CURRENT IMPLEMENTATIONは確認したrepository内の実装です。HISTORICAL IMPLEMENTATIONは導入・修正の履歴で、後続migrationによる再定義があり得ます。RELATED LESSONは教材への案内で、実装の一次Sourceではありません。ASSUMPTIONは仮定、UNKNOWNは未確認を表します。
確認基点: d02eae8914f39cbf06bfe422dc39c71886f82b3e / 2026-09-11。稼働環境への適用確認: UNKNOWN。パス実在の自動検査と、記述した技術的事実の確認は別です。
- RELATED LESSON/docs/architecture関連教材の入口。既存の入門・業務・会計教材
- HISTORICAL IMPLEMENTATION
supabase/migrations/DB設計判断を順番に残すmigration - CURRENT IMPLEMENTATION
scripts/regression/設計上の契約を検証する回帰test