# 機能設計書 6-口座残高管理

## 概要

本ドキュメントは、Actual Budget における口座残高の確認・更新機能の設計を記述する。特定日時点での残高取得も可能である。

### 本機能の処理概要

**業務上の目的・背景**：口座残高は財務状況を把握する上で最も基本的な情報である。本機能は、各口座の現在残高をリアルタイムで表示し、特定日時点での残高も取得可能にする。また、残高の突き合わせ（照合）機能により、銀行明細との整合性を確認できる。

**機能の利用シーン**：
- 口座一覧で各口座の現在残高を確認する
- 銀行明細と照合して残高の正確性を確認する
- 特定日時点での残高を取得して過去の状況を把握する
- 全口座の総残高（純資産）を確認する

**主要な処理内容**：
1. 口座残高の計算（取引合計）
2. 口座残高の表示
3. 特定日時点での残高取得（cutoff パラメータ）
4. 残高照合（Reconciliation）機能

**関連システム・外部連携**：取引管理機能、スプレッドシートエンジン

**権限による制御**：特別な権限制御なし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | 口座一覧画面（デスクトップ） | 主画面 | 口座残高の表示・更新処理 |
| 13 | 口座一覧画面（モバイル） | 主画面 | モバイルでの口座残高表示 |

## 機能種別

計算処理 / データ表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| id | string | Yes | 口座ID | 存在する口座ID |
| cutoff | Date | No | 残高計算の基準日 | 有効な日付 |

### 入力データソース

- API経由：`api/account-balance` ハンドラー

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| balance | number | 口座残高（セント単位） |

### 出力先

- 画面表示：口座一覧、口座詳細画面

## 処理フロー

### 処理シーケンス

```
1. 残高取得リクエスト
   └─ getAccountBalance(id, cutoff) を呼び出し

2. api/account-balance メッセージ送信
   └─ id と cutoff パラメータを渡す

3. サーバーで残高計算
   └─ SELECT SUM(amount) FROM transactions WHERE account = id
   └─ cutoff がある場合は日付条件を追加

4. 残高を返却
   └─ 整数（セント単位）で返す
```

### フローチャート

```mermaid
flowchart TD
    A[残高取得リクエスト] --> B{cutoff 指定あり?}
    B -->|No| C[全取引の合計を計算]
    B -->|Yes| D[cutoff以前の取引の合計を計算]
    C --> E[残高を返却]
    D --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 残高計算 | 口座の全取引金額の合計 | 常時 |
| BR-002 | cutoff 指定時 | 指定日以前の取引のみを計算対象 | cutoff パラメータ指定時 |
| BR-003 | 分割取引 | 親取引ではなく子取引の金額を集計 | 分割取引がある場合 |

### 計算ロジック

```sql
-- 基本残高計算
SELECT SUM(amount) as balance
FROM transactions
WHERE account = :accountId
  AND tombstone = 0
  AND is_parent = 0

-- cutoff 指定時
SELECT SUM(amount) as balance
FROM transactions
WHERE account = :accountId
  AND tombstone = 0
  AND is_parent = 0
  AND date <= :cutoff
```

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 残高取得 | transactions | SELECT | 取引金額の集計 |

### テーブル別操作詳細

#### transactions

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | amount | SUM集計 | |
| WHERE | account | 指定口座ID | |
| WHERE | tombstone | 0 | 削除されていない取引 |
| WHERE | is_parent | 0 | 親取引を除外 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ACCOUNT_NOT_FOUND | データ不整合 | 存在しない口座ID | エラーを返す |

### リトライ仕様

- 特になし（読み取り専用操作）

## トランザクション仕様

- 読み取り専用のため特になし

## パフォーマンス要件

- 残高取得は即座に返す（50ms以内）

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

- 残高情報はローカルデータのみ参照

## 備考

- 残高計算はスプレッドシートエンジンでもキャッシュされる

---

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

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

### 推奨読解順序

#### Step 1: API層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | methods.ts | `packages/api/methods.ts` | getAccountBalance 関数の定義 |

**主要処理フロー**:
- **206-208行目**: `getAccountBalance` 関数が `api/account-balance` を呼び出し
- id と cutoff パラメータを受け取る

#### Step 2: 画面表示を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Balance.tsx | `packages/desktop-client/src/components/accounts/Balance.tsx` | 残高表示コンポーネント |

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

```
Account.tsx
    │
    └─ AccountHeader
           │
           └─ Balance コンポーネント
                  │
                  └─ CellValue (balanceQuery binding)
                         │
                         └─ スプレッドシートエンジン
                                │
                                └─ SUM(transactions.amount)

API
    │
    └─ getAccountBalance(id, cutoff)
           │
           └─ send('api/account-balance', { id, cutoff })
                  │
                  └─ サーバー側で SUM 計算
```

### データフロー図

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

口座ID          ───▶    api/account-balance
(+ cutoff)                    │
                              ▼
                         transactions SELECT      ───▶  残高計算
                         WHERE account = id
                              │
                              ▼
                         SUM(amount)              ───▶  balance 値
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| methods.ts | `packages/api/methods.ts` | ソース | getAccountBalance API |
| Balance.tsx | `packages/desktop-client/src/components/accounts/Balance.tsx` | ソース | 残高表示コンポーネント |
| Reconcile.tsx | `packages/desktop-client/src/components/accounts/Reconcile.tsx` | ソース | 残高照合機能 |
| Account.tsx | `packages/desktop-client/src/components/accounts/Account.tsx` | ソース | 口座画面 |
