# 画面設計書 11-カテゴリ画面（モバイル）

## 概要

本ドキュメントは、Actual Budgetアプリケーションにおけるモバイル向けカテゴリ別取引一覧画面の設計仕様を定義する。

### 本画面の処理概要

カテゴリ画面（モバイル）は、特定のカテゴリに属する取引を月別にフィルタリングして表示するモバイル専用画面である。ユーザーは選択したカテゴリ内の取引を確認し、新規取引の追加や既存取引の編集を行うことができる。

**業務上の目的・背景**：予算管理において、特定カテゴリの支出状況を把握することは極めて重要である。本画面は、モバイルデバイスからでもカテゴリ別の取引履歴を素早く確認できるようにし、外出先でも予算の消化状況をリアルタイムで把握できるようにすることを目的としている。未分類の取引がある場合は、それらをまとめて表示し、適切なカテゴリへの分類を促進する。

**画面へのアクセス方法**：予算画面（モバイル）のカテゴリ一覧から特定のカテゴリをタップすることでアクセスする。URLパラメータとしてカテゴリIDと対象月が渡される。URLパターンは `/categories/:id?month=YYYY-MM` の形式である。

**主要な操作・処理内容**：
1. カテゴリに属する取引一覧の表示（月別フィルタ適用）
2. 取引の検索・フィルタリング
3. 新規取引の追加（右上の「+」ボタン）
4. 取引詳細画面への遷移（取引タップ）
5. カテゴリ残高・クリア済残高・未クリア残高の表示
6. スケジュール取引のプレビュー表示

**画面遷移**：
- 遷移元：予算画面（モバイル）
- 遷移先：取引編集画面（モバイル）

**権限による表示制御**：特になし。認証済みユーザーであれば全機能を利用可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | カテゴリ作成・編集・削除 | 主機能 | モバイルでのカテゴリ別取引一覧表示 |
| 13 | 取引検索・フィルタ | 補助機能 | カテゴリでフィルタされた取引の表示 |

## 画面種別

一覧

## URL/ルーティング

`/categories/:id?month=YYYY-MM`

- `:id` - カテゴリID（UUIDまたは「uncategorized」）
- `month` - 対象月（YYYY-MM形式、省略時は現在月）

## 入出力項目

| 項目名 | 項目ID | 入力/出力 | 型 | 必須 | 説明 |
|--------|--------|----------|-----|------|------|
| カテゴリID | id | 入力（URL） | string | Yes | 表示対象カテゴリのID |
| 月 | month | 入力（クエリ） | string | No | 対象月（YYYY-MM形式） |
| 検索キーワード | search | 入力 | string | No | 取引検索用キーワード |

## 表示項目

| 項目名 | 説明 | データソース |
|--------|------|-------------|
| カテゴリ名 | 画面タイトルに表示されるカテゴリ名 | categories.name |
| 対象月 | 表示対象の年月（例：January '24） | URLクエリパラメータ |
| 取引一覧 | カテゴリに属する取引のリスト | transactions |
| カテゴリ残高 | 当月のカテゴリ残高 | categoryBalance binding |
| クリア済残高 | クリア済取引の残高合計 | categoryBalanceCleared binding |
| 未クリア残高 | 未クリア取引の残高合計 | categoryBalanceUncleared binding |

## イベント仕様

### 1-戻るボタン押下

ヘッダー左側の戻るボタン（MobileBackButton）を押下すると、前の画面（予算画面）に戻る。

### 2-取引追加ボタン押下

ヘッダー右側の「+」ボタン（AddTransactionButton）を押下すると、取引編集画面（モバイル）に遷移する。カテゴリIDが自動的に新規取引に設定される。

### 3-取引項目タップ

取引一覧の各項目をタップすると、該当取引の編集画面（`/transactions/:transactionId`）に遷移する。プレビュー取引（スケジュールされた未実行取引）はタップしても遷移しない。

### 4-検索実行

検索フィールドにキーワードを入力すると、日付形式に応じた検索が実行され、取引一覧がフィルタリングされる。

### 5-スクロール下端到達

取引一覧をスクロールして下端に到達すると、追加の取引データがロードされる（無限スクロール）。

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

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

本画面は主に参照機能であり、直接的なデータベース更新は行わない。取引の追加・編集は遷移先の取引編集画面で行われる。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | transactions | SELECT | カテゴリ・月でフィルタされた取引を取得 |
| 画面表示 | categories | SELECT | カテゴリ情報を取得 |
| 画面表示 | schedules | SELECT | スケジュールされた取引を取得 |

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

#### transactions

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | category = :categoryId AND date.month = :month | インラインスプリット形式で取得 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| M001 | 情報 | Uncategorized | カテゴリが未指定または見つからない場合のタイトル |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| カテゴリが存在しない | 「Uncategorized」として未分類取引を表示 |
| 取引データなし | 空の一覧を表示（特別なメッセージなし） |
| データ取得エラー | コンソールにエラーログ出力、画面はローディング状態を維持 |

## 備考

- 数値フォーマット（numberFormat）または小数表示設定（hideFraction）が変更された場合、画面全体が再レンダリングされる
- スケジュール取引のプレビューは検索実行中は表示されない
- sync-eventをリッスンしており、transactions/category_mapping/payee_mappingテーブルに変更があった場合は自動的に再読み込みされる

---

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

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

### 推奨読解順序

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

まず、カテゴリと取引のデータ構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models/index.d.ts | `packages/loot-core/types/models/` | CategoryEntityとTransactionEntityの型定義 |

**読解のコツ**: TypeScriptの型定義ファイルでエンティティの構造を把握する。特にcategory, date, amountフィールドに注目。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CategoryPage.tsx | `packages/desktop-client/src/components/mobile/budget/CategoryPage.tsx` | 画面のメインコンポーネント、URLパラメータの取得ロジック |

**主要処理フロー**:
1. **行20-30**: useParams/useSearchParamsでURL情報を取得
2. **行29-30**: useCategoriesフックでカテゴリ一覧を取得し、該当カテゴリを特定
3. **行32-65**: MobilePageHeaderとCategoryTransactions/UncategorizedTransactionsを条件分岐でレンダリング

#### Step 3: 取引一覧コンポーネントを理解する

カテゴリ別取引表示の実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CategoryTransactions.tsx | `packages/desktop-client/src/components/mobile/budget/CategoryTransactions.tsx` | 取引クエリの構築とプレビュー取引の統合 |

**主要処理フロー**:
- **行51-58**: baseTransactionsQueryでカテゴリ・月フィルタを適用したクエリを構築
- **行90-94**: useTransactionsSearchで検索機能を提供
- **行113-118**: useCategoryPreviewTransactionsでスケジュール取引を取得
- **行119-121**: 検索中でなければプレビュー取引を先頭に結合

#### Step 4: スプレッドシートバインディングを理解する

残高計算のバインディングを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | bindings.ts | `packages/desktop-client/src/spreadsheet/bindings.ts` | categoryBalance, categoryBalanceCleared, categoryBalanceUnclearedの定義 |

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

```
CategoryPage (エントリーポイント)
    |
    +-- MobilePageHeader
    |       +-- MobileBackButton
    |       +-- AddTransactionButton
    |
    +-- CategoryTransactions / UncategorizedTransactions
            |
            +-- SchedulesProvider
            |       +-- useCachedSchedules
            |
            +-- TransactionListWithPreviews
                    |
                    +-- useTransactions (取引データ取得)
                    +-- useCategoryPreviewTransactions (プレビュー取引取得)
                    +-- useTransactionsSearch (検索機能)
                    |
                    +-- TransactionListWithBalances
                            +-- 取引一覧表示
                            +-- 残高表示
```

### データフロー図

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

URL params        --->  CategoryPage               --->  画面タイトル
(categoryId,            (パラメータ解析)                  (カテゴリ名+月)
 month)

categories        --->  useCategories              --->  category object
(Redux store)           (カテゴリ検索)

transactions DB   --->  useTransactions            --->  取引一覧
                        (AQLクエリ実行)

schedules DB      --->  useCategoryPreviewTransactions --> プレビュー取引
                        (スケジュール取得)

spreadsheet       --->  bindings.categoryBalance   --->  残高表示
bindings                (残高計算)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CategoryPage.tsx | `packages/desktop-client/src/components/mobile/budget/CategoryPage.tsx` | ソース | メインコンポーネント |
| CategoryTransactions.tsx | `packages/desktop-client/src/components/mobile/budget/CategoryTransactions.tsx` | ソース | カテゴリ取引一覧 |
| UncategorizedTransactions.tsx | `packages/desktop-client/src/components/mobile/budget/UncategorizedTransactions.tsx` | ソース | 未分類取引一覧 |
| TransactionListWithBalances.tsx | `packages/desktop-client/src/components/mobile/transactions/TransactionListWithBalances.tsx` | ソース | 残高付き取引リスト |
| MobileBackButton.tsx | `packages/desktop-client/src/components/mobile/MobileBackButton.tsx` | ソース | 戻るボタン |
| AddTransactionButton.tsx | `packages/desktop-client/src/components/mobile/transactions/AddTransactionButton.tsx` | ソース | 取引追加ボタン |
| useCategoryPreviewTransactions.ts | `packages/desktop-client/src/hooks/useCategoryPreviewTransactions.ts` | ソース | プレビュー取引フック |
| useTransactions.ts | `packages/desktop-client/src/hooks/useTransactions.ts` | ソース | 取引データフック |
| bindings.ts | `packages/desktop-client/src/spreadsheet/bindings.ts` | ソース | スプレッドシートバインディング |
