# 帳票設計書 7-Budget Analysis（予算分析）レポート

## 概要

本ドキュメントは、Actual Budgetアプリケーションにおける「Budget Analysis（予算分析）レポート」の設計仕様を記述したものである。予算と実際の支出を比較分析するレポート機能について詳細に解説する。

### 本帳票の処理概要

Budget Analysis（予算分析）レポートは、予算額と実際の支出額を時系列で比較分析するレポートである。予算額、支出額、超過調整額、残高推移を表示し、棒グラフまたは線グラフでの表示に対応している。機能フラグで有効化が必要な機能である。

**業務上の目的・背景**：予算管理において、設定した予算に対して実際の支出がどのように推移しているかを把握することは重要である。本レポートは、予算と実績の乖離を可視化することで、予算超過の早期発見と対策を支援する。また、ロールオーバー設定を反映した残高推移により、長期的な予算パフォーマンスを追跡できる。

**帳票の利用シーン**：月次の予算レビュー時、予算超過カテゴリの特定時、予算配分の見直し検討時、長期的な予算パフォーマンス分析時など、予算と実績の比較が必要な場面で利用される。

**主要な出力内容**：
1. 予算額・支出額・超過調整額の時系列グラフ
2. 残高推移ライン（オプション表示）
3. 合計予算額・合計支出額・合計超過調整額
4. 最終残高

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

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

## 帳票種別

予算対実績比較レポート

## 利用画面

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

## 出力形式

### 基本仕様

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

### 表示固有設定

| 項目 | 内容 |
|-----|------|
| グラフライブラリ | Recharts |
| グラフタイプ | BarChart / LineChart（切替可能） |
| カラーテーマ | 予算:青系、支出:赤系、残高:緑系 |

## 帳票レイアウト

### レイアウト概要

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

```
+------------------------------------------+
|              ページヘッダー                |
|  [タイトル]                    [保存ボタン] |
+------------------------------------------+
|              フィルターヘッダー              |
| [期間選択] [グラフ切替] [残高表示] [フィルター]|
+------------------------------------------+
|              サマリー表示（右寄せ）          |
|                       Budgeted: ¥XXXX    |
|                          Spent: ¥XXXX    |
|                 Overspending adj: ¥XXXX  |
|                  Ending balance: ¥XXXX   |
+------------------------------------------+
|              グラフ表示部                  |
|  [棒グラフ または 線グラフ]                  |
+------------------------------------------+
|              説明文                       |
+------------------------------------------+
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | タイトル | レポート名（編集可能） | widget.meta.name | テキスト |
| 2 | 期間選択 | 開始月・終了月の選択 | allMonths | ドロップダウン |
| 3 | グラフ切替 | 棒グラフ/線グラフ | graphType | アイコンボタン |
| 4 | 残高表示 | 残高ラインの表示/非表示 | showBalance | ボタン |
| 5 | フィルター | カテゴリフィルター | conditions | フィルターボタン |

### 明細部（サマリー）

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Budgeted | 合計予算額 | totalBudgeted | 通貨形式 |
| 2 | Spent | 合計支出額 | totalSpent | 通貨形式 |
| 3 | Overspending adj | 超過調整額合計 | totalOverspendingAdjustment | 通貨形式 |
| 4 | Ending balance | 最終残高 | endingBalance | 通貨形式（色分け） |

### グラフ部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | X軸 | 月（日次/月次） | intervalData[].interval | 日付ラベル |
| 2 | 予算バー/ライン | 予算額 | intervalData[].budgeted | 青系 |
| 3 | 支出バー/ライン | 支出額 | intervalData[].spent | 赤系 |
| 4 | 超過調整 | 超過調整額 | intervalData[].overspendingAdjustment | オレンジ系 |
| 5 | 残高ライン | 累積残高 | intervalData[].balance | 緑系 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| 期間（開始） | 集計開始月 | Yes |
| 期間（終了） | 集計終了月 | Yes |
| カテゴリフィルター | 対象カテゴリ | No |

### フィルター除外項目

| 除外項目 |
|---------|
| date |
| account |
| payee |
| notes |
| amount |
| cleared |
| reconciled |
| transfer |

### ソート順

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

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

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| transactions | トランザクションデータ | - |
| categories | カテゴリマスタ | category.id |
| budget_data | 予算データ | category.id, month |

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

#### transactions

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| date | 月別集計 | startDate <= date <= endDate | - |
| amount | 支出額 | amount < 0 | 負の値のみ |
| category | カテゴリ別集計 | フィルター条件 | - |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| 月別予算 | 予算データから取得 | なし | カテゴリ別予算の合計 |
| 月別支出 | SUM(amount) WHERE amount < 0 | なし | - |
| 超過調整 | ロールオーバー無しカテゴリの超過分 | なし | 繰越設定により変動 |
| 月別残高 | 前月残高 + 予算 + 支出 + 超過調整 | なし | 累積計算 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[レポート画面表示] --> B[パラメータ初期化]
    B --> C[最古/最新トランザクション取得]
    C --> D[期間設定]
    D --> E[createBudgetAnalysisSpreadsheet]
    E --> F[予算データ取得]
    E --> G[支出データ取得]
    F --> H[月別集計]
    G --> H
    H --> I[超過調整計算]
    I --> J[残高計算]
    J --> K[グラフデータ生成]
    K --> L[BudgetAnalysisGraph描画]
    L --> M{パラメータ変更?}
    M -->|Yes| E
    M -->|No| N[表示完了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| データなし | 予算/支出データなし | LoadingIndicator継続 | 予算を設定 |
| ウィジェット未設定 | widget未定義時の保存 | No widget that could be saved. | ウィジェット経由でアクセス |

## パフォーマンス要件

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

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

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

## 備考

- 機能フラグで有効化が必要
- フィルターは主にカテゴリに限定（他項目は除外）
- 残高計算はカテゴリのロールオーバー設定を反映
- 93日超の期間では自動的に月次（concise）表示

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.ts | `loot-core/types/models` | BudgetAnalysisWidget, TimeFrame型 |

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

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

**主要処理フロー**:
1. **行50-62**: BudgetAnalysis関数 - ウィジェットデータ読み込み
2. **行68-84**: BudgetAnalysisInternal - フィルター条件初期化
3. **行94-96**: graphType - 棒グラフ/線グラフ切替
4. **行183-192**: getGraphData - スプレッドシートパラメータ
5. **行194**: useReport - データ取得
6. **行467-473**: BudgetAnalysisGraph - グラフ描画

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

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

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

```
BudgetAnalysis.tsx
    |
    +-- useWidget<BudgetAnalysisWidget>() --> ウィジェットデータ取得
    |
    +-- BudgetAnalysisInternal
            |
            +-- useRuleConditionFilters() --> フィルター条件管理
            |
            +-- createBudgetAnalysisSpreadsheet() --> budget-analysis-spreadsheet.ts
            |       |
            |       +-- 予算データ取得
            |       +-- 支出データ取得
            |       +-- 超過調整計算
            |       +-- 残高計算
            |
            +-- useReport('default', getGraphData) --> データ取得
            |
            +-- BudgetAnalysisGraph --> グラフ描画
```

### データフロー図

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

budget_data ────────+
                    |
transactions ───────+──> createBudgetAnalysisSpreadsheet ──> intervalData
                    |         |                               |
期間設定 ───────────+         |                               v
                    |         v                          totalBudgeted
カテゴリフィルター ──+    月別集計                         totalSpent
                              |                          totalOverspendingAdj
                              v                          endingBalance
                         超過調整計算                          |
                              |                               v
                              v                    [BudgetAnalysisGraph]
                         残高累積計算                         |
                              |                               v
                              v                     棒グラフ/線グラフ
                         intervalData[]              + 残高ライン
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| BudgetAnalysis.tsx | `packages/desktop-client/src/components/reports/reports/BudgetAnalysis.tsx` | ソース | メインコンポーネント |
| budget-analysis-spreadsheet.ts | `packages/desktop-client/src/components/reports/spreadsheets/budget-analysis-spreadsheet.ts` | ソース | 計算ロジック |
| BudgetAnalysisGraph.tsx | `packages/desktop-client/src/components/reports/graphs/BudgetAnalysisGraph.tsx` | ソース | グラフ描画 |
| Header.tsx | `packages/desktop-client/src/components/reports/Header.tsx` | ソース | ヘッダーUI |
| Change.tsx | `packages/desktop-client/src/components/reports/Change.tsx` | ソース | 変化額表示 |
