# 帳票設計書 6-Summary（サマリー）レポート

## 概要

本ドキュメントは、Actual Budgetアプリケーションにおける「Summary（サマリー）レポート」の設計仕様を記述したものである。トランザクションの合計、平均、割合を計算し、数式ベースで表示するレポート機能について詳細に解説する。

### 本帳票の処理概要

Summary（サマリー）レポートは、トランザクションの集計結果を様々な形式で表示するレポートである。合計（Sum）、月平均（Average per month）、年平均（Average per year）、トランザクション平均（Average per transaction）、パーセンテージ（Percentage）の5つの計算モードに対応し、フィルター条件を設定して特定のトランザクションを対象にできる。

**業務上の目的・背景**：家計管理において、単純な合計だけでなく、平均値や割合を把握することで、より深い分析が可能になる。本レポートは、「特定カテゴリの月平均支出は？」「食費が全体支出に占める割合は？」といった疑問に答えることで、支出構造の理解を促進し、予算配分の最適化を支援する。

**帳票の利用シーン**：カテゴリ別の月平均支出分析、収入に対する支出割合の確認、トランザクション平均金額の把握、特定条件の支出比率分析など、数値的な分析が必要な場面で利用される。

**主要な出力内容**：
1. 計算式のビジュアル表示（分数形式）
2. 分子（フィルター条件に合致するトランザクション合計）
3. 分母（期間/トランザクション数/比較対象）
4. 計算結果（色分け表示）

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

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

## 帳票種別

数式計算レポート

## 利用画面

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

## 出力形式

### 基本仕様

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

### 表示固有設定

| 項目 | 内容 |
|-----|------|
| 数式表示 | Σ（シグマ）記号を使用した分数形式 |
| 結果色分け | 正:緑、負:赤、ゼロ:ニュートラル |

## 帳票レイアウト

### レイアウト概要

レポートは上部のヘッダー部、中央のコントロール部、下部の数式表示部の3つのセクションで構成される。

```
+------------------------------------------+
|              ページヘッダー                |
|  [タイトル]                    [保存ボタン] |
+------------------------------------------+
|              フィルターヘッダー              |
| [期間選択]                                |
+------------------------------------------+
|              コントロール部                |
| Show as [Sum ▼]                          |
| [  ] All time divisor (Percentage時)     |
+------------------------------------------+
|              数式表示部                    |
|                                          |
|      Σ (フィルター条件)                    |
|     ─────────────────  =  結果            |
|      分母（期間/数/条件）                   |
|                                          |
+------------------------------------------+
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | タイトル | レポート名（編集可能） | widget.meta.name | テキスト |
| 2 | 期間選択 | 開始日・終了日の選択 | allMonths | ドロップダウン |

### コントロール部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Show as | 計算タイプ選択 | content.type | ドロップダウン |
| 2 | All time divisor | 分母を全期間にする | content.divisorAllTimeDateRange | チェックボックス |

### 数式表示部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Σ記号 | シグマ記号（期間表示付き） | SvgSum | SVGアイコン |
| 2 | 分子フィルター | 分子のフィルター条件 | dividendFilters | AppliedFilters |
| 3 | 分母 | 期間数/件数/フィルター条件 | 計算タイプによる | テキスト/AppliedFilters |
| 4 | 分子値 | 分子の計算結果 | data.dividend | 通貨形式 |
| 5 | 分母値 | 分母の計算結果 | data.divisor | 数値/通貨形式 |
| 6 | 結果 | 最終計算結果 | data.total | 通貨/パーセント |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| 期間（開始） | 集計開始日 | Yes |
| 期間（終了） | 集計終了日 | Yes |
| 計算タイプ | sum/avgPerMonth/avgPerYear/avgPerTransact/percentage | Yes |
| 分子フィルター | 分子対象のフィルター条件 | No |
| 分母フィルター | 分母対象のフィルター条件（percentage時） | No |

### ソート順

該当なし（単一値計算）

### 改ページ条件

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

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

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| transactions | トランザクションデータ | - |

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

#### transactions

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| date | 期間フィルター | start <= date <= end | - |
| amount | 合計計算 | - | SUM対象 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| dividend | SUM(amount) WHERE dividendFilters | なし | 分子 |
| divisor(avgPerMonth) | 期間の月数 | なし | - |
| divisor(avgPerYear) | 期間の年数 | なし | - |
| divisor(avgPerTransact) | トランザクション件数 | なし | - |
| divisor(percentage) | SUM(amount) WHERE divisorFilters | なし | 分母 |
| total | dividend / divisor * 100 (percentage) | なし | 結果 |

### 計算タイプ対応

| タイプ | 分母 | 結果形式 |
|-------|------|---------|
| sum | なし（分母不要） | 通貨形式 |
| avgPerMonth | 期間の月数 | 通貨形式 |
| avgPerYear | 期間の年数 | 通貨形式 |
| avgPerTransact | トランザクション件数 | 通貨形式 |
| percentage | 分母フィルター条件の合計 | パーセント形式 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[レポート画面表示] --> B[パラメータ初期化]
    B --> C[最古/最新トランザクション取得]
    C --> D[期間設定]
    D --> E[summarySpreadsheet呼び出し]
    E --> F{計算タイプ?}
    F -->|sum| G[合計のみ計算]
    F -->|avgPerMonth| H[月数で割る]
    F -->|avgPerYear| I[年数で割る]
    F -->|avgPerTransact| J[件数で割る]
    F -->|percentage| K[分母フィルター合計で割る]
    G --> L[結果表示]
    H --> L
    I --> L
    J --> L
    K --> L
    L --> M{パラメータ変更?}
    M -->|Yes| E
    M -->|No| N[表示完了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| ウィジェット未設定 | widget未定義時の保存 | Cannot save: No widget available. | ウィジェット経由でアクセス |
| 分母ゼロ | 分母が0の場合 | 0または空表示 | フィルター条件を変更 |

## パフォーマンス要件

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

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

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

## 備考

- percentageモードでは分子・分母それぞれにフィルター条件を設定可能
- All time divisorをチェックすると、分母は全期間のデータを使用
- content設定はJSON形式でwidget.meta.contentに保存

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: SummaryContentが計算タイプと分母条件を保持する。

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

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

**主要処理フロー**:
1. **行54-66**: Summary関数 - ウィジェットデータ読み込み
2. **行74-118**: SummaryInner - 状態初期化、content解析
3. **行113-118**: divisorFilters - 分母用フィルター
4. **行120-138**: params - スプレッドシートパラメータ
5. **行140**: useReport - データ取得
6. **行302-312**: getDivisorFormatted - 分母のフォーマット
7. **行530-589**: Operator - 数式表示コンポーネント
8. **行597-650**: SumWithRange - Σ記号付き数式部品

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

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

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

```
Summary.tsx
    |
    +-- useWidget<SummaryWidget>() --> ウィジェットデータ取得
    |
    +-- SummaryInner
            |
            +-- useRuleConditionFilters() --> 分子フィルター
            +-- useRuleConditionFilters() --> 分母フィルター
            |
            +-- summarySpreadsheet() --> summary-spreadsheet.ts
            |       |
            |       +-- 計算タイプに応じた集計
            |
            +-- useReport('summary', params) --> データ取得
            |
            +-- Operator --> 数式表示
                    |
                    +-- SumWithRange --> Σ記号付き数式
                            |
                            +-- AppliedFilters --> フィルター条件表示
                            +-- FilterButton --> フィルター追加
```

### データフロー図

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

トランザクション ────+
                    |
期間設定 ───────────+──> summarySpreadsheet ──> data
                    |         |                   |
dividendFilters ────+         |                   v
                    |         v              dividend/divisor
divisorFilters ─────+    計算タイプ分岐         /total
                    |         |                   |
content.type ───────+         |                   v
                              v              [Operator]
                         計算実行                 |
                              |                   v
                              v              数式ビジュアル
                         結果生成            + 計算結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Summary.tsx | `packages/desktop-client/src/components/reports/reports/Summary.tsx` | ソース | メインコンポーネント |
| summary-spreadsheet.ts | `packages/desktop-client/src/components/reports/spreadsheets/summary-spreadsheet.ts` | ソース | 計算ロジック |
| Header.tsx | `packages/desktop-client/src/components/reports/Header.tsx` | ソース | ヘッダーUI |
| AppliedFilters.tsx | `packages/desktop-client/src/components/filters/AppliedFilters.tsx` | ソース | フィルター条件表示 |
| FilterButton.tsx | `packages/desktop-client/src/components/filters/FiltersMenu.tsx` | ソース | フィルター追加ボタン |
| FieldSelect.tsx | `packages/desktop-client/src/components/rules/RuleEditor.tsx` | ソース | 計算タイプ選択 |
