# 帳票設計書 1-Net Worth（純資産）レポート

## 概要

本ドキュメントは、Actual Budgetアプリケーションにおける「Net Worth（純資産）レポート」の設計仕様を記述したものである。全口座の純資産を時系列で表示し、資産と負債の推移を可視化するレポート機能について詳細に解説する。

### 本帳票の処理概要

Net Worth（純資産）レポートは、ユーザーが保有する全ての口座の資産と負債を集計し、純資産（資産合計 - 負債合計）の推移を時系列グラフで可視化するレポートである。

**業務上の目的・背景**：個人の財務状況を総合的に把握することは、将来の資産計画を立てる上で極めて重要である。本レポートは、ユーザーが自身の財務健全性を一目で理解し、資産形成の進捗を追跡できるようにすることで、より良い財務意思決定を支援する。全資産（銀行口座、投資口座等）と全負債（ローン、クレジットカード等）を統合して表示することで、真の財務状況を把握できる。

**帳票の利用シーン**：月次・年次の財務レビュー時、資産運用の効果測定時、ローン返済の進捗確認時、長期的な資産形成目標の達成度確認時など、ユーザーが自身の総合的な財務状況を確認したい場面で利用される。

**主要な出力内容**：
1. 純資産の時系列推移グラフ（トレンドモード/スタックモード切替可能）
2. 現在の純資産額と前回からの変化額
3. 口座別の資産・負債内訳（ホバー時にツールチップ表示）
4. 日次/週次/月次/年次での集計切替

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

**帳票の利用者**：アプリケーションの全ユーザー（個人の家計管理者）

## 帳票種別

集計分析グラフレポート

## 利用画面

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

## 出力形式

### 基本仕様

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

### 表示固有設定

| 項目 | 内容 |
|-----|------|
| グラフライブラリ | Recharts |
| グラフタイプ | AreaChart / StackedAreaChart |
| カラーテーマ | アプリケーションテーマに連動 |

## 帳票レイアウト

### レイアウト概要

レポートは上部のヘッダー部、中央のサマリー部、下部のグラフ表示部の3つのセクションで構成される。

```
+------------------------------------------+
|              ページヘッダー                |
|  [タイトル]                    [保存ボタン] |
+------------------------------------------+
|              フィルターヘッダー              |
| [期間選択] [インターバル] [モード] [フィルター] |
+------------------------------------------+
|              サマリー表示                  |
|                     現在の純資産額: ¥XXXX  |
|                         変化額: +¥XXXX   |
+------------------------------------------+
|              グラフ表示部                  |
|                                          |
|  [時系列グラフ]                            |
|                                          |
+------------------------------------------+
|              説明文                       |
+------------------------------------------+
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | タイトル | レポート名（編集可能） | widget.meta.name | テキスト |
| 2 | 期間選択 | 開始月・終了月の選択 | allMonths | ドロップダウン |
| 3 | インターバル | 日次/週次/月次/年次 | ReportOptions.interval | ドロップダウン |
| 4 | 表示モード | トレンド/スタック | graphMode | ボタン切替 |
| 5 | フィルター | 条件フィルター | conditions | フィルターボタン |

### 明細部（グラフ）

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | X軸 | 時間軸（期間） | graphData.x | 日付ラベル |
| 2 | Y軸 | 金額 | graphData.y | 通貨形式 |
| 3 | 純資産ライン | 純資産の推移 | graphData.y | 面グラフ |
| 4 | 口座別内訳 | 各口座の残高 | graphData[accountId] | スタック表示時 |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 説明文 | 純資産の計算方法説明 | 固定テキスト | パラグラフ |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| 期間（開始） | 集計開始月 | Yes |
| 期間（終了） | 集計終了月 | Yes |
| 口座フィルター | 対象口座の絞り込み | No |
| カスタムフィルター | ルール条件によるフィルタリング | No |

### ソート順

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

### 改ページ条件

該当なし（単一画面表示）

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

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| transactions | トランザクションデータ | account.id = transactions.account |
| accounts | 口座マスタ | - |

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

#### transactions

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| date | グラフX軸 | date >= startDate AND date <= endDate | 期間内のみ |
| amount | 残高計算 | - | 整数値（セント単位） |
| account | 口座別集計 | - | 口座IDで紐付け |

#### accounts

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| id | 口座識別 | - | - |
| name | 口座名表示 | - | ツールチップ表示用 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| 開始時残高 | SUM(amount) WHERE date < startDate | なし | 口座別に算出 |
| 期間内残高推移 | 開始時残高 + 累積SUM(amount) | なし | 各期間ポイントで計算 |
| 資産合計 | SUM(残高 >= 0の口座) | なし | 正の残高のみ |
| 負債合計 | SUM(残高 < 0の口座) | なし | 負の残高のみ（絶対値） |
| 純資産 | 資産合計 - 負債合計 | なし | 全口座の残高合計 |
| 変化額 | 終了時純資産 - 開始時純資産 | なし | 期間内の増減 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[レポート画面表示] --> B[パラメータ初期化]
    B --> C[最古/最新トランザクション取得]
    C --> D[期間範囲設定]
    D --> E[スプレッドシート生成]
    E --> F[口座別残高クエリ実行]
    F --> G[開始時残高計算]
    G --> H[期間内残高推移計算]
    H --> I[グラフデータ整形]
    I --> J[グラフ描画]
    J --> K{パラメータ変更?}
    K -->|Yes| E
    K -->|No| L[表示完了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| データなし | トランザクションが存在しない | 該当するデータがありません | 期間やフィルターを変更 |
| ウィジェット未設定 | widget未定義時の保存 | No widget that could be saved. | ウィジェット経由でアクセス |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数千〜数万件のトランザクション |
| 目標出力時間 | 3秒以内 |
| キャッシュ | useMemoによるメモ化 |

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

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

## 備考

- ウィジェットとして保存した場合、フィルター条件・期間・表示モードが永続化される
- モバイル表示時はツールチップが非表示になる

---

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

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

### 推奨読解順序

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

まず、レポートで使用されるデータ型とウィジェット定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.ts | `loot-core/types/models` | NetWorthWidget, TimeFrame型の定義を確認 |
| 1-2 | ReportOptions.ts | `packages/desktop-client/src/components/reports/ReportOptions.ts` | intervalオプションの定義を確認 |

**読解のコツ**: TypeScriptの型定義ファイルから、レポートが扱うデータの形状を把握する。

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

処理の起点となるReactコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | NetWorth.tsx | `packages/desktop-client/src/components/reports/reports/NetWorth.tsx` | メインコンポーネントの構造 |

**主要処理フロー**:
1. **行54-66**: NetWorth関数コンポーネント - ウィジェットデータの読み込みとLoading状態管理
2. **行72-87**: NetWorthInner - 状態変数の初期化（mode, interval, graphMode等）
3. **行131-155**: reportParams - スプレッドシート生成パラメータのメモ化
4. **行156**: useReport - データ取得フック呼び出し
5. **行157-207**: useEffect - 最古/最新トランザクション取得と期間設定
6. **行368-374**: NetWorthGraph - グラフコンポーネントへのデータ渡し

#### Step 3: スプレッドシート（データ集計ロジック）を理解する

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

**主要処理フロー**:
- **行23-33**: createSpreadsheet関数 - スプレッドシート生成のエントリーポイント
- **行38-41**: フィルター条件の生成
- **行64-108**: 口座別のトランザクション集計クエリ
- **行153-166**: recalculate関数 - グラフデータの生成
- **行196-281**: graphData生成 - 各期間ポイントでの資産・負債・純資産計算

#### Step 4: グラフ描画を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | NetWorthGraph.tsx | `packages/desktop-client/src/components/reports/graphs/NetWorthGraph.tsx` | Rechartsによるグラフ描画 |

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

```
NetWorth.tsx
    |
    +-- useWidget<NetWorthWidget>() --> ウィジェットデータ取得
    |
    +-- NetWorthInner
            |
            +-- useRuleConditionFilters() --> フィルター条件管理
            |
            +-- createSpreadsheet() --> net-worth-spreadsheet.ts
            |       |
            |       +-- send('make-filters-from-conditions') --> フィルター生成
            |       |
            |       +-- aqlQuery() --> トランザクション集計
            |       |
            |       +-- recalculate() --> グラフデータ変換
            |
            +-- useReport('net_worth', reportParams) --> データ取得・キャッシュ
            |
            +-- NetWorthGraph --> グラフ描画
```

### データフロー図

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

口座マスタ ──────────+
                    |
トランザクション ────+──> createSpreadsheet ──> recalculate ──> graphData
                    |         |                    |              |
フィルター条件 ──────+         |                    |              v
                              v                    v         [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` | ソース | ヘッダーUI |
| ReportOptions.ts | `packages/desktop-client/src/components/reports/ReportOptions.ts` | ソース | レポートオプション定義 |
| useReport.ts | `packages/desktop-client/src/components/reports/useReport.ts` | ソース | レポートデータ取得フック |
| reportRanges.ts | `packages/desktop-client/src/components/reports/reportRanges.ts` | ソース | 期間計算ユーティリティ |
| months.ts | `loot-core/shared/months.ts` | ソース | 日付操作ユーティリティ |
