# 画面設計書 31-純資産レポート画面

## 概要

本ドキュメントは、Actual Budget アプリケーションの純資産レポート画面の設計仕様を記述したものである。

### 本画面の処理概要

純資産レポート画面は、ユーザーの総資産と総負債の差額である純資産の推移を時系列グラフで可視化する画面である。口座残高の履歴データを集計し、指定期間における純資産の変動を分析できる。

**業務上の目的・背景**：個人の財務状況を把握する上で、純資産（総資産から総負債を差し引いた金額）は最も重要な指標の一つである。この画面では、時間経過に伴う純資産の変化を視覚的に確認でき、長期的な財務健全性の評価や、貯蓄・投資戦略の効果測定が可能となる。資産形成の進捗確認や、負債削減の成果を定量的に把握することで、財務目標達成に向けたモチベーション維持にも寄与する。

**画面へのアクセス方法**：サイドバーの「レポート」メニューをクリック後、レポートダッシュボードから「純資産」カードを選択、または直接 `/reports/net-worth` URLにアクセスする。ダッシュボードウィジェットとして追加されている場合は、ウィジェットIDを含むURL `/reports/net-worth/:id` でアクセスする。

**主要な操作・処理内容**：
1. 期間選択：開始月と終了月をドロップダウンから選択、またはプリセットボタン（1ヶ月、3ヶ月、6ヶ月、1年、年初来、全期間など）で期間を指定
2. 表示間隔の切替：日次、週次、月次、年次の表示間隔を選択
3. グラフモードの切替：トレンドグラフまたは積み上げグラフの表示モードを選択
4. フィルタ適用：口座やカテゴリなどの条件でデータをフィルタリング
5. ウィジェット保存：ダッシュボードウィジェットとして現在の設定を保存

**画面遷移**：レポートダッシュボード画面（`/reports`）から遷移する。モバイル画面幅では戻るボタンでレポートダッシュボードへ戻る。

**権限による表示制御**：特に権限による制御はない。予算ファイルがロードされていることが前提条件となる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 33 | 収支レポート | 主機能 | 純資産推移グラフの表示・分析 |
| 35 | 口座別レポート | 補助機能 | 口座ごとの資産推移表示 |

## 画面種別

詳細・分析画面

## URL/ルーティング

- `/reports/net-worth` - 基本URL
- `/reports/net-worth/:id` - ダッシュボードウィジェットID指定時

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 必須 | 説明 |
|--------|----------|---------|------|------|
| 開始月 | 入力 | string | Yes | 表示期間の開始月（YYYY-MM形式） |
| 終了月 | 入力 | string | Yes | 表示期間の終了月（YYYY-MM形式） |
| 表示モード | 入力 | string | Yes | 'static' または 'sliding-window' |
| 表示間隔 | 入力 | string | Yes | 'Daily', 'Weekly', 'Monthly', 'Yearly' |
| グラフモード | 入力 | string | Yes | 'trend' または 'stacked' |
| フィルタ条件 | 入力 | array | No | RuleConditionEntity配列 |
| フィルタ演算子 | 入力 | string | No | 'and' または 'or' |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| 純資産金額 | number | 現在の純資産総額（フォーマット済み） |
| 変動額 | number | 期間内の純資産変動額 |
| 純資産推移グラフ | chart | 期間内の純資産推移を示す折れ線/積み上げグラフ |
| 口座別内訳 | array | グラフ上でホバー時に表示される口座別の残高内訳 |

## イベント仕様

### 1-期間変更

ユーザーが開始月または終了月のドロップダウンを変更した際、`onChangeDates`関数が呼び出され、`start`, `end`, `mode`の状態が更新される。その後、`netWorthSpreadsheet`が再計算され、グラフデータが更新される。

### 2-表示間隔変更

表示間隔セレクターで間隔を変更すると、`setInterval`により状態が更新され、スプレッドシートが再計算される。間隔によりデータポイントの粒度が変化する。

### 3-グラフモード変更

モードセレクターでトレンド/積み上げを切り替えると、`setGraphMode`により状態が更新され、`NetWorthGraph`コンポーネントの表示が切り替わる。

### 4-フィルタ適用

フィルタボタンからフィルタ条件を追加すると、`onApplyFilter`が呼び出され、条件配列が更新される。スプレッドシートが再計算され、フィルタ条件に合致するデータのみが表示される。

### 5-ウィジェット保存

「Save widget」ボタン押下時、`onSaveWidget`関数が実行され、`send('dashboard-update-widget', {...})`によりサーバーへウィジェット設定が保存される。成功時は通知が表示される。

### 6-ウィジェット名変更

タイトルをクリックして編集モードに入り、新しい名前を入力して確定すると、`onSaveWidgetName`関数が実行され、ウィジェットのメタデータが更新される。

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ウィジェット保存 | dashboard_widgets | UPDATE | ウィジェットのmeta情報を更新 |
| ウィジェット名変更 | dashboard_widgets | UPDATE | ウィジェットのmeta.nameを更新 |
| データ取得 | transactions | SELECT | 取引データを取得して純資産を計算 |
| 口座情報取得 | accounts | SELECT | 口座一覧を取得 |

### テーブル別更新項目詳細

#### dashboard_widgets

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | meta | JSON（conditions, conditionsOp, interval, mode, timeFrame） | ウィジェット保存時 |
| UPDATE | meta.name | string | ウィジェット名変更時 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|---------|
| MSG_WIDGET_SAVED | 成功 | Dashboard widget successfully saved. | ウィジェット保存成功時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ウィジェットが存在しない | 「Save widget」ボタンが表示されない |
| データがない | グラフが空の状態で表示される |
| 取引データ取得失敗 | ローディングインジケータが表示され続ける |

## 備考

- 純資産の計算は、全口座の残高合計から負債口座の残高を差し引いて算出される
- グラフはRechartsライブラリを使用してレンダリングされる
- プライバシーフィルタが有効な場合、金額表示がマスクされる
- モバイル画面幅ではツールチップが無効化される

---

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

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

### 推奨読解順序

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

まず、純資産レポートで使用されるデータ構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.ts | `loot-core/types/models` | `NetWorthWidget`, `TimeFrame`型の定義を確認 |
| 1-2 | net-worth-spreadsheet.ts | `packages/desktop-client/src/components/reports/spreadsheets/net-worth-spreadsheet.ts` | 純資産データの集計ロジックと戻り値の構造を理解 |

**読解のコツ**: TypeScript型定義を先に確認することで、コンポーネントが扱うデータの形状が明確になる。

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

処理の起点となるメインコンポーネントを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | NetWorth.tsx | `packages/desktop-client/src/components/reports/reports/NetWorth.tsx` | `NetWorth`関数コンポーネントがエントリーポイント。URLパラメータからウィジェットIDを取得し、ウィジェットデータをロード |

**主要処理フロー**:
1. **54-66行**: `NetWorth`関数 - URLパラメータからIDを取得し、`useWidget`フックでウィジェットデータを取得
2. **72-395行**: `NetWorthInner`関数 - メインのレンダリングロジックを含む内部コンポーネント
3. **131-155行**: `reportParams`のuseMemo - スプレッドシートパラメータの生成
4. **156行**: `useReport`フック呼び出し - データ取得の実行

#### Step 3: データ取得層を理解する

スプレッドシート計算とデータ取得の流れを追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | net-worth-spreadsheet.ts | `packages/desktop-client/src/components/reports/spreadsheets/net-worth-spreadsheet.ts` | `createSpreadsheet`関数の実装。口座残高の集計ロジック |
| 3-2 | useReport.ts | `packages/desktop-client/src/components/reports/useReport.ts` | レポートデータ取得のカスタムフック |

**主要処理フロー**:
- スプレッドシート関数が取引データをクエリし、期間ごとの残高を計算
- `useReport`フックがスプレッドシート関数を実行し、結果をキャッシュ

#### Step 4: UIコンポーネントを理解する

グラフ表示とヘッダーコントロールの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Header.tsx | `packages/desktop-client/src/components/reports/Header.tsx` | 期間選択、フィルタボタン等の共通ヘッダーコンポーネント |
| 4-2 | NetWorthGraph.tsx | `packages/desktop-client/src/components/reports/graphs/NetWorthGraph.tsx` | Rechartsを使用した純資産グラフのレンダリング |

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

```
NetWorth (エントリーポイント)
    │
    ├─ useWidget (ウィジェットデータ取得)
    │      └─ send('dashboard-get-widget')
    │
    └─ NetWorthInner (メインコンポーネント)
           │
           ├─ useRuleConditionFilters (フィルタ管理)
           │
           ├─ netWorthSpreadsheet (データ計算)
           │      └─ useReport (データ取得フック)
           │
           ├─ Header (期間・フィルタUI)
           │      ├─ Select (期間選択)
           │      └─ FilterButton (フィルタUI)
           │
           ├─ IntervalSelector (間隔選択)
           │
           ├─ ModeSelector (グラフモード選択)
           │
           └─ NetWorthGraph (グラフ描画)
                  └─ Recharts (グラフライブラリ)
```

### データフロー図

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

URLパラメータ ─────────▶ useWidget ─────────────────▶ ウィジェットメタデータ
                              │
期間選択 ──────────────▶ state (start, end, mode)
                              │
間隔選択 ──────────────▶ state (interval)
                              │
グラフモード ─────────▶ state (graphMode)
                              │
フィルタ ──────────────▶ useRuleConditionFilters
                              │
                              ▼
                    netWorthSpreadsheet
                              │
                              ▼
                       useReport
                              │
                              ▼
取引データ(DB) ──────▶ データ集計処理 ─────────────▶ グラフデータ
                                                         │
                                                         ▼
                                               NetWorthGraph
                                                         │
                                                         ▼
                                                  画面表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| NetWorth.tsx | `packages/desktop-client/src/components/reports/reports/NetWorth.tsx` | ソース | メインコンポーネント |
| net-worth-spreadsheet.ts | `packages/desktop-client/src/components/reports/spreadsheets/net-worth-spreadsheet.ts` | ソース | データ集計ロジック |
| NetWorthGraph.tsx | `packages/desktop-client/src/components/reports/graphs/NetWorthGraph.tsx` | ソース | グラフ描画コンポーネント |
| Header.tsx | `packages/desktop-client/src/components/reports/Header.tsx` | ソース | 共通ヘッダーコンポーネント |
| useReport.ts | `packages/desktop-client/src/components/reports/useReport.ts` | ソース | レポートデータ取得フック |
| useWidget.ts | `packages/desktop-client/src/hooks/useWidget.ts` | ソース | ウィジェットデータ取得フック |
| reportRanges.ts | `packages/desktop-client/src/components/reports/reportRanges.ts` | ソース | 期間計算ユーティリティ |
| ReportOptions.ts | `packages/desktop-client/src/components/reports/ReportOptions.ts` | ソース | レポートオプション定義 |
| Change.tsx | `packages/desktop-client/src/components/reports/Change.tsx` | ソース | 変動額表示コンポーネント |
| LoadingIndicator.tsx | `packages/desktop-client/src/components/reports/LoadingIndicator.tsx` | ソース | ローディング表示 |
