# 画面設計書 27-銀行同期口座編集画面（モバイル）

## 概要

本ドキュメントは、Actual Budgetアプリケーションにおけるモバイル向け銀行同期口座編集画面の設計仕様を定義するものである。

### 本画面の処理概要

モバイルデバイスにおいて、銀行同期が設定された口座の詳細設定を編集するための専用画面である。フィールドマッピング（銀行データと取引フィールドの対応付け）、取引方向の設定、各種インポートオプションを設定できる。また、口座のリンク解除も本画面から行える。

**業務上の目的・背景**：銀行APIから取得する取引データと、Actual Budgetの取引フィールドとの対応付けは、金融機関によって異なる場合がある。本画面は、このマッピングをユーザーがカスタマイズできるようにすることで、より正確な取引データの取り込みを実現する。また、保留中取引のインポート、ノートの自動取り込み、削除済み取引の再インポートなど、詳細なインポート動作を制御できる。

**画面へのアクセス方法**：銀行同期管理画面（モバイル）から特定のリンク済み口座をタップすることで、`/bank-sync/account/:accountId/edit` ルートに遷移する。このルートはナロー画面幅（モバイル）でのみアクセス可能。

**主要な操作・処理内容**：
1. フィールドマッピングの設定（受取/支払の金額方向、各フィールドの対応付け）
2. 取引方向の切り替え（incoming/outgoing）
3. インポートオプションの設定（保留取引、ノート、削除済み取引、取引インポート）
4. 設定の保存
5. 口座のリンク解除

**画面遷移**：
- 遷移元：銀行同期管理画面（モバイル） `/bank-sync`
- 遷移先：銀行同期管理画面（モバイル） `/bank-sync`（保存完了時・キャンセル時・リンク解除時）

**権限による表示制御**：特別な権限制御は設けられていない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 29 | 銀行同期バッチ処理 | 主機能 | モバイルでの同期口座設定編集 |

## 画面種別

編集

## URL/ルーティング

`/bank-sync/account/:accountId/edit`

- `:accountId` - 編集対象の口座ID（UUID形式）
- モバイル（ナロー画面幅）でのみアクセス可能
- ワイド画面幅でアクセスした場合は `/bank-sync` にリダイレクト

## 入出力項目

| 項目名 | 項目ID | データ型 | 入力/出力 | 必須 | 説明 |
|--------|--------|----------|-----------|------|------|
| 口座ID | accountId | string | 入力（URL） | 必須 | 編集対象の口座ID |
| 取引方向 | transactionDirection | 'incoming' / 'outgoing' | 入力 | 必須 | 取引データの方向 |
| 保留取引インポート | importPending | boolean | 入力 | 必須 | 保留中取引のインポート可否 |
| ノートインポート | importNotes | boolean | 入力 | 必須 | ノートの自動インポート可否 |
| 削除済み再インポート | reimportDeleted | boolean | 入力 | 必須 | 削除済み取引の再インポート可否 |
| 取引インポート | importTransactions | boolean | 入力 | 必須 | 取引データのインポート可否 |
| フィールドマッピング | mappings | Map | 入力 | 必須 | 各フィールドのマッピング設定 |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ヘッダータイトル | string | 口座名を表示 |
| 戻るボタン | button | 銀行同期一覧画面に戻る |
| フィールドマッピングセクション | component | フィールドマッピング設定UI |
| オプションセクション | component | 各種チェックボックスオプション |
| リンク解除ボタン | button | 口座のリンク解除 |
| キャンセルボタン | button | 編集キャンセル |
| 保存ボタン | button | 設定保存 |
| 口座未存在メッセージ | text | 口座が見つからない場合のメッセージ |

## イベント仕様

### 1-画面初期表示

URLパラメータの `accountId` を使用して口座データと同期設定を取得する。

**処理フロー**:
1. `useParams()` で `accountId` を取得
2. `useAccount(accountId)` で口座データを取得
3. `useBankSyncAccountSettings(accountId)` で同期設定を取得
4. 口座が見つからない場合、エラーメッセージを表示

### 2-フィールドマッピング変更

フィールドマッピングUIで各フィールドの対応付けを変更する。

**処理フロー**:
1. `FieldMapping` コンポーネントで設定変更を受け付け
2. `setMapping` 関数でマッピングを更新
3. 取引方向（transactionDirection）の切り替えに応じてマッピングを切り替え

### 3-オプション変更

各種インポートオプションのチェックボックスを変更する。

**処理フロー**:
1. `BankSyncCheckboxOptions` コンポーネントで設定変更を受け付け
2. 各setter関数（setImportPending等）でステートを更新

### 4-保存処理

保存ボタン押下時に設定を保存して一覧画面に戻る。

**処理フロー**:
1. `saveSettings()` を呼び出し
2. 設定がサーバーに保存される
3. `navigate('/bank-sync')` で一覧画面に戻る

### 5-キャンセル処理

キャンセルボタン押下時に編集を破棄して一覧画面に戻る。

**処理フロー**:
1. `handleCancel()` を呼び出し
2. `navigate('/bank-sync')` で一覧画面に戻る

### 6-リンク解除処理

リンク解除ボタン押下時に確認ダイアログを表示して口座のリンクを解除する。

**処理フロー**:
1. `handleUnlink()` を呼び出し
2. `pushModal('confirm-unlink-account', ...)` で確認ダイアログを表示
3. 確認後、`unlinkAccount({ id: accountId })` アクションをディスパッチ
4. `navigate('/bank-sync')` で一覧画面に戻る

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存 | accounts (metadata) | UPDATE | 同期設定の更新 |
| リンク解除 | accounts | UPDATE | 同期プロバイダー情報のクリア |

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

#### accounts

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | account_sync_source | null（リンク解除時） | WHERE id = :accountId |
| UPDATE | bank_id | null（リンク解除時） | WHERE id = :accountId |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| MSG-001 | エラー | "Account not found" | 口座が見つからない場合 |
| MSG-002 | 確認 | リンク解除確認ダイアログ | リンク解除ボタン押下時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 口座が存在しない | エラーメッセージを表示、戻るボタンで一覧へ |

## 備考

- 本画面はモバイル専用であり、デスクトップ版ではモーダルダイアログが使用される
- フィールドマッピングは取引方向（incoming/outgoing）ごとに別々に管理
- `useBankSyncAccountSettings` フックが設定の読み込み・保存を担当

---

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

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

### 推奨読解順序

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

口座同期設定の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models/index.d.ts | `packages/loot-core/src/types/models/index.d.ts` | AccountEntity型の同期関連フィールド |

**読解のコツ**: `account_sync_source`, `bankId`, `bankName` 等の同期関連フィールドを確認。

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

画面コンポーネントの全体構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | MobileBankSyncAccountEditPage.tsx | `packages/desktop-client/src/components/mobile/banksync/MobileBankSyncAccountEditPage.tsx` | メインコンポーネント |

**主要処理フロー**:
1. **22-27行目**: コンポーネント定義とフック初期化
2. **29-44行目**: useBankSyncAccountSettingsから設定取得
3. **46-53行目**: イベントハンドラ（handleCancel, handleSave, handleUnlink）
4. **75-100行目**: 口座未存在時のUI
5. **105-186行目**: メインUIのJSXレンダリング

#### Step 3: 設定管理フックを理解する

同期設定の読み込み・保存ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | useBankSyncAccountSettings.ts | `packages/desktop-client/src/components/banksync/useBankSyncAccountSettings.ts` | 設定管理フック |

#### Step 4: サブコンポーネントを理解する

フィールドマッピングとオプション設定UIを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | FieldMapping.tsx | `packages/desktop-client/src/components/banksync/FieldMapping.tsx` | フィールドマッピングUI |
| 4-2 | BankSyncCheckboxOptions.tsx | `packages/desktop-client/src/components/banksync/BankSyncCheckboxOptions.tsx` | オプションチェックボックス |

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

```
MobileBankSyncAccountEditPage
    │
    ├─ useParams()
    │      └─ accountId 取得
    │
    ├─ useAccount(accountId)
    │      └─ 口座データ取得
    │
    ├─ useBankSyncAccountSettings(accountId)
    │      ├─ transactionDirection / setTransactionDirection
    │      ├─ importPending / setImportPending
    │      ├─ importNotes / setImportNotes
    │      ├─ reimportDeleted / setReimportDeleted
    │      ├─ importTransactions / setImportTransactions
    │      ├─ mappings / setMapping
    │      ├─ fields
    │      └─ saveSettings()
    │
    ├─ FieldMapping
    │      └─ フィールドマッピング設定UI
    │
    ├─ BankSyncCheckboxOptions
    │      └─ オプションチェックボックスUI
    │
    ├─ handleSave()
    │      ├─ saveSettings()
    │      └─ navigate('/bank-sync')
    │
    └─ handleUnlink()
           ├─ pushModal('confirm-unlink-account')
           └─ unlinkAccount({ id })
```

### データフロー図

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

URL param ───────────▶ useParams() ──────────────────────▶ accountId
                             │
Redux Store ─────────▶ useAccount() ─────────────────────▶ account data
                             │
localStorage ────────▶ useBankSyncAccountSettings() ─────▶ 設定ステート
(+ server)                   │
                             ▼
                     FieldMapping / BankSyncCheckboxOptions
                             │
ユーザー編集 ────────▶ setXxx() 関数群 ───────────────────▶ ステート更新
                             │
Save押下 ────────────▶ saveSettings() ───────────────────▶ 設定保存
                             │
                             └─▶ navigate('/bank-sync') ──▶ 一覧へ遷移

Unlink押下 ──────────▶ unlinkAccount() ──────────────────▶ DB更新
                             │
                             └─▶ navigate('/bank-sync') ──▶ 一覧へ遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MobileBankSyncAccountEditPage.tsx | `packages/desktop-client/src/components/mobile/banksync/MobileBankSyncAccountEditPage.tsx` | ソース | メインコンポーネント |
| useBankSyncAccountSettings.ts | `packages/desktop-client/src/components/banksync/useBankSyncAccountSettings.ts` | ソース | 設定管理フック |
| FieldMapping.tsx | `packages/desktop-client/src/components/banksync/FieldMapping.tsx` | ソース | フィールドマッピングUI |
| BankSyncCheckboxOptions.tsx | `packages/desktop-client/src/components/banksync/BankSyncCheckboxOptions.tsx` | ソース | オプションチェックボックスUI |
| accountsSlice.ts | `packages/desktop-client/src/accounts/accountsSlice.ts` | ソース | unlinkAccountアクション |
| useAccount.ts | `packages/desktop-client/src/hooks/useAccount.ts` | ソース | 口座取得フック |
| MobileBackButton.tsx | `packages/desktop-client/src/components/mobile/MobileBackButton.tsx` | ソース | 戻るボタンコンポーネント |
| Page.tsx | `packages/desktop-client/src/components/Page.tsx` | ソース | ページレイアウトコンポーネント |
| FinancesApp.tsx | `packages/desktop-client/src/components/FinancesApp.tsx` | ソース | ルーティング定義（303-307行目） |
