# 帳票設計書 8-Crossover（クロスオーバーポイント）レポート

## 概要

本ドキュメントは、Actual Budgetアプリケーションにおける「Crossover（クロスオーバーポイント）レポート」の設計仕様を記述したものである。リタイアメント計画のためのクロスオーバーポイント分析機能について詳細に解説する。

### 本帳票の処理概要

Crossover（クロスオーバーポイント）レポートは、リタイアメント計画のためのFI（Financial Independence）分析レポートである。投資収入が生活費を上回る時点（クロスオーバーポイント）を予測し、安全引出率、期待リターン、支出調整係数などのパラメータを設定して将来シミュレーションを行う。機能フラグで有効化が必要な機能である。

**業務上の目的・背景**：FIRE（Financial Independence, Retire Early）を目指すユーザーにとって、投資収入が生活費を上回る時点を把握することは重要な目標設定となる。本レポートは、現在の資産状況と支出パターンから将来を予測し、リタイアメントに必要な資産額（ターゲットNest Egg）と目標月収を算出することで、長期的な資産形成計画を支援する。

**帳票の利用シーン**：リタイアメント計画の策定時、FI目標の進捗確認時、支出削減の効果シミュレーション時、投資リターン想定の変更検討時など、長期的な財務計画場面で利用される。

**主要な出力内容**：
1. 投資収入と生活費の推移グラフ（過去実績 + 将来予測）
2. リタイアまでの年数（Years to Retire）
3. 目標月収（Target Monthly Income）
4. 目標資産額（Target Life Savings / Nest Egg）

**帳票の出力タイミング**：ユーザーがレポート画面から「Crossover Point」を選択した際、またはダッシュボードウィジェットとして設定された際にリアルタイムで生成される。機能フラグで有効化が必要。

**帳票の利用者**：アプリケーションの全ユーザー（特にFIRE志向のユーザー）

## 帳票種別

将来予測シミュレーションレポート

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| R-008 | Crossoverレポート | `/reports/crossover` | レポートメニューから選択 |
| R-008-W | Crossoverウィジェット | `/reports/crossover/:id` | ダッシュボードウィジェットクリック |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | HTML（画面表示）/ SVGグラフ |
| 表示形式 | インタラクティブなグラフ表示 |
| レスポンシブ対応 | 有（モバイル/デスクトップ） |
| データ更新 | リアルタイム（パラメータ変更時に再計算） |
| 機能フラグ | 有効化が必要 |

### 表示固有設定

| 項目 | 内容 |
|-----|------|
| グラフライブラリ | Recharts |
| グラフタイプ | AreaChart（投資収入 vs 生活費） |
| カラーテーマ | 投資収入:緑系、生活費:赤系（実績:実線、予測:点線） |

## 帳票レイアウト

### レイアウト概要

レポートは左側のサイドバー部、右側のメインコンテンツ部の2つのセクションで構成される。

```
+------------------------------------------+
|              ページヘッダー                |
|  [タイトル]                    [保存ボタン] |
+------------------------------------------+
|              フィルターヘッダー              |
| [期間選択]                                |
+------------------------------------------+
|         |                                |
| サイド   |  サマリーカード                  |
| バー     |  Years to Retire: X years      |
|         |  Target Monthly Income: ¥XX    |
| 支出     |  Target Life Savings: ¥XX      |
| カテゴリ +--------------------------------|
|         |                                |
| 収入    |  グラフ表示エリア                 |
| 口座    |                                |
|         |  [投資収入 vs 生活費グラフ]       |
| SWR    |                                |
| 投影    |                                |
| タイプ  +--------------------------------|
|         |                                |
| 目標   |  説明文                          |
| 収入    |                                |
|         |                                |
+------------------------------------------+
```

### サイドバー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Expenses categories | 生活費カテゴリ選択 | selectedExpenseCategories | ツリー選択 |
| 2 | Income accounts | 収入口座選択 | selectedIncomeAccountIds | チェックリスト |
| 3 | Safe withdrawal rate | 安全引出率（%） | swr | 数値入力 |
| 4 | Expense Projection Type | 支出予測タイプ | projectionType | ドロップダウン |
| 5 | Target Income | 目標収入（支出比率） | expenseAdjustmentFactor | 数値入力 |
| 6 | Use custom growth | カスタム成長率使用 | useCustomGrowth | チェックボックス |
| 7 | Expected return | 期待リターン（年率） | estimatedReturn | 数値入力 |
| 8 | Expected monthly contribution | 月額積立額 | expectedContribution | 数値入力 |

### サマリー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Years to Retire | リタイアまでの年数 | yearsToRetire | 数値 + "years" |
| 2 | Target Monthly Income | 目標月収 | targetMonthlyIncome | 通貨形式 |
| 3 | Target Life Savings | 目標資産額 | targetNestEgg | 通貨形式 |

### グラフ部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | X軸 | 月（過去〜将来） | graphData.x | 日付ラベル |
| 2 | 投資収入ライン | 安全引出率による月収 | investmentIncome | 緑色エリア |
| 3 | 生活費ライン | 予測生活費 | expenses | 赤色エリア |
| 4 | Nest Eggライン | 資産残高 | nestEgg | 青色ライン |
| 5 | 調整後生活費 | 目標収入考慮後 | adjustedExpenses | 赤色点線 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| 期間（開始） | 分析開始月 | Yes |
| 期間（終了） | 分析終了月（予測開始点） | Yes |
| 支出カテゴリ | リタイア後も継続する支出 | No（デフォルト全て） |
| 収入口座 | リタイア資金となる口座 | No（デフォルト全て） |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | 月 | 昇順 |

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| transactions | トランザクションデータ | - |
| accounts | 口座マスタ | account.id |
| categories | カテゴリマスタ | category.id |
| category_groups | カテゴリグループ | - |

### テーブル別参照項目詳細

#### transactions

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| date | 月別集計 | start <= date <= end | - |
| amount | 支出/収入 | - | 支出:負、残高変動:全て |
| category | 支出カテゴリ | selectedExpenseCategories | - |
| account | 口座残高 | selectedIncomeAccountIds | - |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| 月別支出 | SUM(amount) WHERE category IN selectedExpenseCategories | なし | 支出カテゴリのみ |
| 口座残高 | 口座別の月末残高 | なし | 収入口座のみ |
| 予測支出 | Hampel/Median/Meanで算出 | なし | projectionTypeによる |
| 投資収入 | 口座残高 * SWR / 12 | なし | 月額換算 |
| 将来残高 | (前月残高 + 積立) * (1 + リターン/12) | なし | 複利計算 |
| Target Nest Egg | 目標月収 * 12 / SWR | なし | - |
| Years to Retire | クロスオーバー月 / 12 | 小数1位 | - |

### 支出予測タイプ

| タイプ | 説明 |
|-------|------|
| hampel | Hampelフィルター後の中央値（外れ値除去） |
| median | 単純な中央値 |
| mean | 平均値 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[レポート画面表示] --> B[パラメータ初期化]
    B --> C[最古トランザクション取得]
    C --> D[期間設定]
    D --> E[createCrossoverSpreadsheet]
    E --> F[過去データ集計]
    F --> G[支出予測計算]
    G --> H[将来シミュレーション]
    H --> I[クロスオーバーポイント検出]
    I --> J[グラフデータ生成]
    J --> K[CrossoverGraph描画]
    K --> L{パラメータ変更?}
    L -->|Yes| E
    L -->|No| M[表示完了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| データなし | 口座/カテゴリ未選択 | LoadingIndicator継続 | 選択を追加 |
| 保存失敗 | widget未定義 | Save failed: No widget found to save. | ウィジェット経由でアクセス |
| クロスオーバー未達 | 予測期間内に達成しない | yearsToRetire = N/A | パラメータ調整 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数千件のトランザクション |
| 目標出力時間 | 5秒以内（将来予測含む） |
| キャッシュ | useCallbackによるメモ化 |

## セキュリティ考慮事項

- プライバシーフィルター（PrivacyFilter）による金額のマスキング機能
- ローカルデータストレージ（サーバーへのデータ送信なし）

## 備考

- 機能フラグで有効化が必要
- 現在月は分析から除外（過去データのみ使用）
- カスタム成長率を使用しない場合、過去の口座パフォーマンスから自動計算
- 隠しカテゴリの表示/非表示切替可能

---

## コードリーディングガイド

本帳票を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.ts | `loot-core/types/models` | CrossoverWidget型 |
| 1-2 | Crossover.tsx | 行55-76 | CrossoverData型定義 |

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Crossover.tsx | `packages/desktop-client/src/components/reports/reports/Crossover.tsx` | メインコンポーネント（1164行） |

**主要処理フロー**:
1. **行84-96**: Crossover関数 - ウィジェットデータ読み込み
2. **行100-186**: CrossoverInner - 状態初期化、カテゴリ/口座選択
3. **行130-139**: パラメータ状態（SWR、リターン、積立等）
4. **行331-376**: params - スプレッドシートパラメータ（useCallback）
5. **行378**: useReport - データ取得
6. **行1128-1131**: CrossoverGraph - グラフ描画

#### Step 3: スプレッドシートを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | crossover-spreadsheet.ts | `packages/desktop-client/src/components/reports/spreadsheets/crossover-spreadsheet.ts` | 計算ロジック |

### プログラム呼び出し階層図

```
Crossover.tsx
    |
    +-- useWidget<CrossoverWidget>() --> ウィジェットデータ取得
    |
    +-- CrossoverInner
            |
            +-- useAccounts() --> 口座リスト
            +-- useCategories() --> カテゴリリスト
            |
            +-- CategorySelector --> 支出カテゴリ選択UI
            +-- AccountSelector --> 収入口座選択UI
            |
            +-- createCrossoverSpreadsheet() --> crossover-spreadsheet.ts
            |       |
            |       +-- 過去支出集計
            |       +-- 口座残高集計
            |       +-- 支出予測（Hampel/Median/Mean）
            |       +-- 将来シミュレーション
            |       +-- クロスオーバー検出
            |
            +-- useReport<CrossoverData>('crossover', params)
            |
            +-- CrossoverGraph --> グラフ描画
```

### データフロー図

```
[入力]                         [処理]                          [出力]

過去トランザクション ───+
                      |
支出カテゴリ選択 ──────+──> createCrossoverSpreadsheet
                      |         |
収入口座選択 ─────────+         v
                      |    過去支出/残高集計
                      |         |
SWR ──────────────────+         v
                      |    支出予測計算
estimatedReturn ──────+    (projectionType)
                      |         |
expectedContribution ─+         v
                      |    将来シミュレーション
expenseAdjustmentFactor+   (複利計算)
                              |
                              v
                       クロスオーバー検出
                              |
                              v
                        graphData
                         yearsToRetire
                         targetMonthlyIncome
                         targetNestEgg
                              |
                              v
                       [CrossoverGraph]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Crossover.tsx | `packages/desktop-client/src/components/reports/reports/Crossover.tsx` | ソース | メインコンポーネント |
| crossover-spreadsheet.ts | `packages/desktop-client/src/components/reports/spreadsheets/crossover-spreadsheet.ts` | ソース | 計算ロジック |
| CrossoverGraph.tsx | `packages/desktop-client/src/components/reports/graphs/CrossoverGraph.tsx` | ソース | グラフ描画 |
| CategorySelector.tsx | `packages/desktop-client/src/components/reports/CategorySelector.tsx` | ソース | カテゴリ選択UI |
| AccountSelector.tsx | `packages/desktop-client/src/components/reports/AccountSelector.tsx` | ソース | 口座選択UI |
| Header.tsx | `packages/desktop-client/src/components/reports/Header.tsx` | ソース | ヘッダーUI |
