FPシミュレーターを読める、直せる、作れるようになる

0. この資料の使い方

上から順番に読む必要はありません。まず「全体像」をつかみ、 次に自分でコードを開いて、説明と実装を照らし合わせてください。

1. 学習前のセルフチェック

合否を決めるためではなく、どこから読み始めるかを決めるための確認表です。 すべてに答えられなくても問題ありません。答えられない項目を、次に読む節の目印にしてください。

2. まず全体像：このリポジトリは何をするか

FPシミュレーターは、家族・収入・支出・年金・住宅・ローンなどを入力として受け取り、 世帯の将来を月ごとに計算します。結果はWeb画面から見られ、 SQLiteに保存でき、さらにLLMがMCPツールとして参照・計算・更新できます。

このシステムを一文で言うと

「画面が見えること」だけがアプリではありません。入力を正しいデータに変換し、 計算し、保存し、結果を別の入口からも利用できるようにする一連の仕組みがアプリケーションです。

3. 先に覚える基礎用語

用語は単独で暗記せず、「このリポジトリのどこに登場するか」とセットで覚えます。

def net(income, tax, expense):
    return income - tax - expense

result = net(300000, 50000, 180000)
# result は 70000

monthly_amount: int
start_month: int
bonus_months: list[int]

INSERT INTO households
  (id, name, data, created_at, updated_at)
VALUES (?, ?, ?, ?, ?)
ON CONFLICT(id) DO UPDATE ...

4. リポジトリ探検：どのファイルから読むか

ファイル名を全部覚える必要はありません。変更したいものから、入口 → データ → 処理 → 出力の順で探します。

出力側の画面をたどる

入力ウィザードを読んだ後は、main.pyのルートとテンプレートを対応させると、 計算結果がどのように表示されるかを確認できます。

読む順番のテンプレート

1. README.mdで目的、起動方法、構成を確認する。
2. 要件定義書で「正しい動作」の背景と用語を確認する。
3. 引き継ぎ資料で、現在の運用上の注意点と未完了の課題を確認する。
4. 目的に近いテストを先に読み、入力と期待結果を知る。
5. そのテストが呼ぶengine / modelsを読む。
6. 最後にweb / template / dbを読んで、入口と保存をつなげる。

5. Webの流れ：入力フォームから結果画面まで

HTTPからFastAPI、モデル、DB、テンプレートへ進む流れを、1本の処理として見てみましょう。 ここでは「新しい世帯を作る」操作を例にします。

図中の「田中家」や金額は説明用の架空データです。実在する個人情報や家計情報を入力して 公開環境へ送信しないでください。

GETとPOSTを区別する

6. 計算エンジンを理解する：月次キャッシュフロー

このリポジトリの中心は engine/cashflow.py です。 世帯主の基準年月から想定寿命まで、月を1つずつ進めながら収入・税・支出・残高を計算します。

Webの/households/{household_id}/simulate、比較画面、災害シナリオ、 月次結果画面はそれぞれmain.pyからsimulate()を呼びます。 MCPのrun_simulationも同じエンジンを再利用します。入口が違っても計算を共有する設計です。

MonthlyCashflowを読む

@dataclass
class MonthlyCashflow:
    date: datetime.date
    age: int
    salary_income: int = 0
    pension_income: int = 0
    income_tax: int = 0
    living_expense: int = 0
    loan_payment: int = 0
    balance: int = 0

    @property
    def net(self) -> int:
        return self.total_income - self.total_tax_si - self.total_expense

これは完全なコードではなく、読み方を示す抜粋です。 @dataclassはデータをまとめるための仕組み、 @propertyはオブジェクトから計算結果を読むための仕組みです。 netは保存された入力ではなく、他の項目から導く値です。

なぜ月次なのか

7. コードの読み方：モデル・パラメータ・保存

7-1. Pydanticモデルは「データの契約」

engine/models.pyのモデルは、「世帯データはどんな形でなければならないか」という契約です。 画面、DB、計算エンジン、MCPが同じ契約を使うことで、層ごとに別の形へ変換する量を減らせます。

class Income(BaseModel):
    id: str
    member_id: str
    monthly_amount: int
    bonus_months: list[int] = Field(default_factory=list)
    annual_raise_rate: float = 0.0

これは実装の一部を抜き出した例です。完全な定義と他の項目はengine/models.pyを確認してください。

7-2. YAMLパラメータは「変わる制度」と「変わりにくい計算」を分ける

税率や控除額は法改正で変わる可能性があります。 parameters/に適用開始日と出典を保存し、ParameterStoreが計算日から有効な値を選びます。

- path: 所得税.基礎控除.控除額
  description: 基礎控除
  values:
    - from: 2013-01-01
      value: 380000
      source: https://www.nta.go.jp/taxes/shiraberu/taxanswer/shotoku/1199.htm
    - from: 2020-01-01
      value: 480000
      source: https://www.nta.go.jp/taxes/shiraberu/taxanswer/shotoku/1199.htm
    - from: 2025-01-01
      value: 580000
      source: https://www.nta.go.jp/taxes/shiraberu/taxanswer/shotoku/1199.htm

ParameterStoreは、計算日以前のfromのうち最も新しい値を選びます。 まだ適用開始日前なら最古の値を使います。既定のparameters/以外を使う本番設定には FP_PARAMETERS_DIR、テストでストアを作り直すときにはreset_store()を確認します。

7-3. DBはモデルJSONを保存する

このリポジトリでは、世帯全体をPydanticのJSONとしてSQLiteのdata列に保存します。 まずはシンプルな構成で、保存時と取得時に同じモデルへ変換します。

# 保存
data = household.model_dump_json()
await db.execute(
    """INSERT INTO households (id, name, data, created_at, updated_at)
       VALUES (?, ?, ?, ?, ?)
       ON CONFLICT(id) DO UPDATE SET
         name=excluded.name, data=excluded.data, updated_at=excluded.updated_at""",
    (household.id, household.name, data, now, now),
)

# 取得
household = Household.model_validate_json(row[0])

ON CONFLICT(id) DO UPDATEは、IDが未登録ならINSERT、登録済みならUPDATEに切り替える UPSERTです。保存関数を読むときは、新規作成だけでなく既存世帯の更新時にどの列が変わるかも確認します。

これは実装を短くした抜粋です。一般的な大規模システムでは、検索しやすいように項目を別テーブルへ分解する設計もあります。 ここでは「ドメインモデルをそのまま保存する」というシンプルさとのトレードオフを学べます。

8. テストを読む・書く：仕様を実行可能にする

テストは、実装を理解するための入口でもあります。 「何を入力し、何を期待しているか」が短く書かれているため、巨大な実装を読む前に仕様を把握できます。

テストの基本形（Arrange / Act / Assert）

import datetime

from fp_simulator.engine.cashflow import MonthlyCashflow


def test_net_is_income_minus_tax_and_expense():
    # Arrange（準備）
    monthly = MonthlyCashflow(
        date=datetime.date(2026, 1, 1),
        age=40,
        salary_income=300000,
        income_tax=50000,
        living_expense=180000,
    )

    # Act（実行）
    result = monthly.net

    # Assert（確認）
    assert result == 70000

必須項目のdateとageを含めた、実際に実行できる最小例です。

1. 再現条件を小さくする：家族全員ではなく、最小の世帯・1つの収入・1つの支出にする。
2. 期待値を決める：手計算できる値、または要件・制度資料から正しい値を決める。
3. 失敗を確認する：修正前にテストが失敗すると、不具合の再現に成功したことになる。
4. 修正する：最小の変更を入れ、同じテストが通ることを確認する。
5. 全体を確認する：関連テストを実行してデグレがないか見る。

9. 不具合修正の手順：入力から出力までを追う

「入力が関数に渡り、意図した出力になるか処理の流れを追う」という考え方を、 再現・観測・修正・回帰確認のループにします。

例：「給与を入力したのに収入が0円」

1. 画面で再現：最小の世帯、1人のメンバー、1件の給与、対象月を決める。
2. POSTを確認：フォームのnameとincomes_addの引数名・型を照合する。
3. モデルを確認：Income.member_idが存在するメンバーを指しているか、月額が数値になっているか確認する。
4. 計算を確認：cashflow.pyで対象月・開始年齢・終了年齢の条件に入っているか確認する。
5. 中間値を観測：必要ならログで給与モデル、対象日、計算されたsalary_incomeを出す。
6. 再現テストを追加：同じ入力をテストデータにし、修正前に失敗、修正後に成功することを確認する。

10. MCPを理解する：LLM用の別の入口

MCP（Model Context Protocol）は、 LLMアプリケーションが外部の機能を「ツール」として呼び出すための共通の接続方法です。 このリポジトリでは、Web画面とは別に、世帯の参照・シミュレーション・金額の説明・更新を提供します。

図には代表的なツールを載せています。実際の定義は mcp_server/server.pyにあり、世帯・税制パラメータの参照系と、 シミュレーション・明細・根拠説明・更新系に分かれています。

実装されているMCPツール

11. 新しいWebアプリを最初から作る設計テンプレート

目標は「このリポジトリを暗記すること」ではなく、同じ考え方を別の題材に移せることです。 たとえば読書記録、家計簿、学習進捗、料理レシピ管理にも応用できます。

設計時に自分へ問いかける質問

12. 学習ロードマップ

順番にチェックし、各項目で小さな成果物を残してください。 チェック状態はこのブラウザに保存されます（別の端末とは共有されません）。

フェーズA：Pythonの基礎

• 変数、文字列、整数、真偽値、リスト、辞書を説明できる。
• 関数に引数を渡し、戻り値を受け取る小さなプログラムを書ける。
• クラスとインスタンスを、入力データの設計図として説明できる。
• 不正な入力を受け付けないための条件（バリデーション）を1つ書ける。

フェーズB：このリポジトリを動かす

• pip install -e ".[dev]"の意味を調べ、依存パッケージをインストールできる。
• pytestを実行し、成功・失敗の表示を読める。
• Uvicornでサーバーを起動し、ブラウザからトップ画面を開ける。
• 目的に応じてREADME、テスト、engine、web、dbの順にファイルを探せる。

フェーズC：小さな変更をテスト付きで行う

• モデルに小さな入力項目を追加し、必須/任意と型を決められる。
• 計算エンジンに1つのルールを追加し、境界値を含むテストを書ける。
• フォーム、FastAPIのPOST、保存、表示を1本の流れとして変更できる。
• 不具合を再現するテストを先に作り、修正後に通ることを確認できる。

フェーズD：新規プロジェクト

• 解決したい課題、利用者、MVPの範囲を1ページに書ける。
• 主要なデータモデルと入力制約を図または表にできる。
• 1つの登録・1つの計算・1つの表示を縦につないだ最小機能を作れる。
• 正常系・境界値・エラー系のテストを用意できる。

進捗を計算中…

13. 確認クイズ：自分の言葉で説明する

答えを先に見ず、紙やメモに書いてから開いてください。 正答率よりも、どこが曖昧かを見つけることが目的です。

14. 用語集