Fintech Engineering Handbook – Money‑Critical システム構築の包括的ガイド

Fintech Engineering Handbook – Money‑Critical システム構築の包括的ガイド

TL;DR

Fintech Engineering Handbook は、金銭が主要データモデルであるソフトウェアを構築するために必要な不変・監査可能・信頼不要なパターンを体系化したものです。 金銭表現から台帳設計、外部連携、アクセス制御、テストまでを、3 つの指針に結び付けて解説します。

このハンドブックを使うべき人は？

  • 新規 fintech 採用者 – ドメイン固有のパターンと用語を短時間で習得できる入門コース。
  • 経験豊富な fintech エンジニア – 具体的な課題解決のリファレンスとなり、チーム間の共通言語を提供。
  • fintech 以外のエンジニア – 金銭システムが一般的な Web アプリと何が違うかを学ぶ入門書。

貢献は歓迎します；本ドキュメントは継続的に進化することを想定しています。

コア原則

原則 何を強制するか 典型的なメカニズム
データの捏造禁止 金銭は任意に出現・消滅できない。 Idempotency キー、重複排除、複式簿記、予約。
データの喪失禁止 すべての金銭イベントは永続化され、追跡可能である。 高精度型、少なくとも一回の配信、イベントソーシング、不変の監査トレイル。
信頼不要 外部プロバイダーも内部コンポーネントも信頼できる前提を置かない。 Webhook 署名、スキーマ検証、クロスソース照合、明示的な失敗処理。

金銭の表現

精度の取り扱い

  • 浮動小数点は避ける – 非決定的な丸めが発生します。
  • 整数のマイナー単位 を法定通貨で使用（例: €12.34 を 1234 として保存）。暗号資産はトークンの小数点が最大 18 桁になることがあるため、任意幅整数が必要になることがあります。
  • 任意精度ライブラリ（BigDecimal など）は、FX や価格算出といった中間計算に最適です。
  • 有理数 は精度損失をゼロにしますが、速度が遅くシリアライズが難しいです。

重要ルール: 金額は最小単位の整数で保存し、高精度型で計算する。シリアライズは文字列または整数で行い、JSON の数値としては出さない。

丸め戦略

  1. 明示的に丸める – すべての除算、変換、手数料、精度変更は丸めステップを呼び出す。
  2. ビジネス主導の方向 – 過剰支出を防ぐために切り捨て、統計的公平性のために偶数丸め（half‑even）など、選択は税務・法務に影響する。
  3. できるだけ遅く丸める – 永続化またはユーザー表示までフル精度を保つ。
  4. 残余金の管理 – 金額を分割する際、丸め残りを追跡しバランスドリフトを防ぐ。

重要ルール: 丸めは金銭を創出したり消滅させたりしてはならない。残余は専用口座に入れる。

通貨の取り扱い

  • 金額と通貨は Money 型で一体化する。
  • 異なる通貨間の演算は禁止し、変換は明示的に制御されたレートで行う。
  • システム境界では通貨コードを厳選リストで検証する。
  • 暗号資産は ISO 4217 ではなく (network, contract address) で資産を特定する。

為替レート

  • レートは 方向性がある – EUR/USD ≠ USD/EUR。Bid/Ask スプレッドにより逆数は単純な逆数ではない。
  • タイムスタンプが重要 – リアルタイム評価には現在時点のレート、税務・報告用にはバリューデートレートを使用。
  • 取引レート（実際の換算に基づく）と 参照レート（ミッドマーケットや中央銀行レート）を区別する。
  • 正式な単一ソースは存在しないため、監査可能性のために常にソース識別子を保存する。

金銭の記録: 台帳

複式簿記

  • すべてのエントリは同額を クレジット 口座から デビット 口座へ移動させ、帳簿が常に均衡することを保証する。
  • 残高は導出 され、直接保存しない。
  • 勘定科目（資産、負債、資本、収益、費用）は会計等式 assets = liabilities + equity を強制する。
  • 修正は相殺エントリを投稿して行い、元の行は不変のまま残す。

時間的次元

  • 価値時点 – 経済イベントが発生した時。
  • 記帳時点 – システムにイベントが記録された時。
  • 決済時点 – 実際の資金移動が行われた時（通常は T+X で表現）。
  • 3 つのタイムスタンプすべてを記録する。統合すると再構築性が失われる。

監査と監査トレイル

  • すべての変更について 何を、いつ、誰/何が、なぜ を捕捉する – 残高更新だけでなく、設定変更、権限更新、ルール評価も対象。
  • イベントソーシング はイベントログを真実のソースとし、監査トレイルを一次情報にする。
  • 不変性 – 追記専用ストレージ、ランタイムチェック、ハッシュチェーンによる改ざん防止。
  • 取消し vs. 修正 – 取消しは元エントリを打ち消す。修正は差分を投稿し履歴を保持する。

金銭フローの実行

不変条件

  • 構築時（型安全コンストラクタ、DB 制約）・実行時（アサーション、プロパティベーステスト）・事後（照合ジョブ）で重要な性質を強制する。

資金予約

  • 外部サービス呼び出し前に資金を予約し、総額 と 利用可能額 を区別する（available = total – reserved）。
  • 予約は 線形化可能 で、常に解放または決済されるようにし、デッドロック資金を防ぐ。

当座貸越の取扱い

  • 意図的 な当座貸越（クレジット商品）と 非意図的 な外部不整合によるものを区別する。
  • “残高 ≥ 0” をハード型制約にしないで、不変条件として実装し、違反時は明示的に処理する。

冪等性

  • 操作とクライアントにスコープされた 明示的冪等性キー を使用する。
  • 重複配信は単一の論理効果として扱い、リトライは 1 回の結果に収束させる。
  • 冪等性はシステムの 入力側 と 出力側 の両方で適用する。

完全な再開可能性

  • 長時間実行フローは 耐久的ステートマシン としてモデル化し、各ステップ後に進捗を永続化する。
  • 外部ドライバは未完了フローを検知し再開できるようにする。
  • すべてのステップは 冪等 である必要がある。外部効果は回復不能なので、前方リトライまたは補償アクション（サガパターン）を選択する。

外部世界との連携

API の利用

  • 応答を徹底的に検証 し、スキーマ変更があれば大きく失敗させる。
  • すべての呼び出しは失敗することを想定 – リトライ、タイムアウト、指数バックオフを実装する。
  • リクエストとレスポンスをすべて永続化 – 監査トレイルの一部となり、再処理が可能になる。
  • 重要パスでは プロバイダー冗長化 を検討するが、複雑性が増すことに留意する。

Webhook の取扱い

  • 順序、妥当性、配信保証は信頼しない。
  • 生ペイロードを保存 し、署名（HMAC または非対称）を検証する。
  • Webhook は トリガー として扱い、プロバイダー API で権威ある状態を取得する。
  • 速やかに 2xx で応答し、非同期で処理。冪等性を確保する。

信頼できる通知（Outbox / CDC）

  • 状態変更と同時に トランザクション的にイベントを発行（outbox テーブル）するか、変更データキャプチャ（CDC）で確定行をストリームする。
  • 配信は 少なくとも一回 で、コンシューマは安定したイベント ID で重複排除する必要がある。

照合

  • 定期的に内部レコードと外部ソースを比較（毎時、日次など）。
  • プロバイダー生成 ID でマッチングし、無い場合は 金額＋タイムスタンプ などのヒューリスティックを使用する。
  • 不整合は 修正エントリ または再処理で解決し、履歴データを上書きしない。

コントロールとアクセス

職務分離 & 四眼原則

  • 資金移動や誤表記につながる操作（大口出金、台帳修正、手数料スケジュール変更）には必ず第二承認者を必要とする。
  • 誰が要求し、誰が承認したか を記録し、承認は別人物で行う。

アクセス制御

  • 最小権限 をロールベースアクセス制御（RBAC）で実装する。
  • すべての付与/剥奪を金銭イベントと同様の監査トレイル項目で記録する。
  • 定期的な再認証 を実施し、古くなった権限を検出する。

変更トレイル（SDLC）

  • ソース管理履歴 をコード変更の権威ある記録とみなす。
  • 必須のコードレビュー、保護ブランチ、署名コミットを強制する。
  • デプロイは 誰が、いつ、どのバージョン を実行したか追跡可能にし、インシデントを責任ある変更に結び付ける。

金銭クリティカルシステムのテスト

  • プロパティベーステスト – 任意入力に対して不変条件（例: 総デビット = 総クレジット）を主張する。
  • 各ステップ後の不変チェック – 生成された操作シーケンス全体で簿記規則を自動検証する。
  • 冪等性の生成テスト – 各操作を繰り返し、二重カウントが起きないことを確認する。
  • クラッシュ＆リジューム注入 – ステップ間で障害をシミュレートし、再開可能性を検証する。
  • ラウンドトリップテスト – 金銭型のシリアライズ/デシリアライズで精度損失がないことを確認する。
  • ゴールデンテスト – 複雑な計算（手数料、ステートメント）を固定し、リグレッションを検出する。
  • 後方互換テスト – 現行コードが過去のイベントフォーマットを読めることを検証する。
  • 本番テスト – カナリアまたは合成トランザクションを実際の金銭で実行し、後で取り消すためにタグ付けする。決して台帳をバイパスしない。

付録

付録 A – ドメイン用語集

台帳、IOU、マイナー単位、Bid/Ask スプレッド、T+X などの必須 fintech 用語を簡潔に一覧化し、ハンドブック該当セクションへのリンクを付す。

付録 B – エンドツーエンドフロー例

  1. 暗号資産出金 – 冪等性、予約、コンプライアンスチェック、オンチェーン放送、確定待ち、台帳記録、照合を示す。
  2. カード入金 – Webhook 処理、クリアリング口座、決済遅延、チャージバック取消しを示す。
  3. アプリ内換算＋キャッシュバック – 通貨分離、精度保持、境界での丸め、スプレッド収益とプロモーション費用の複式記帳をハイライト。

結論

Fintech Engineering Handbook は、金銭が捏造も喪失もできず、暗黙の信頼も置けないシステムを構築するための 自己完結型・原則駆動の設計図 を提供します。ここで示したパターン（正確な表現、不変の複式台帳、明示的な不変条件、堅牢な外部連携、厳格なアクセス制御、徹底的なテスト）に従うことで、監査・規制審査・分散システムの必然的な障害に耐える信頼できる金融プロダクトをエンジニアは提供できるようになります。

Sources