# 画面設計書 26-銀行同期管理画面（モバイル）

## 概要

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

### 本画面の処理概要

モバイルデバイス向けに最適化された銀行同期管理画面である。デスクトップ版と同様に、GoCardless、SimpleFIN、PluggyAI の銀行同期プロバイダーに対応し、口座の同期状態確認、設定編集、未リンク口座の連携設定を行う。検索機能を備え、多数の口座から目的の口座を素早く見つけることができる。

**業務上の目的・背景**：モバイル環境でも銀行同期設定の確認・調整を可能にすることで、外出先でのトラブルシューティングや設定変更のニーズに応える。銀行連携エラーが発生した場合でも、その場で設定を確認・修正できることで、取引同期の継続性を確保する。

**画面へのアクセス方法**：モバイルナビゲーションの「More」メニューから「Bank Sync」を選択、またはサイドメニューから `/bank-sync` ルートに遷移することでアクセスする。

**主要な操作・処理内容**：
1. 同期プロバイダー別の口座一覧表示
2. 口座名・銀行名での検索フィルタリング
3. 口座タップで同期設定編集画面へ遷移
4. 未リンク口座の銀行連携設定（モーダル）

**画面遷移**：
- 遷移元：モバイルナビゲーション、サイドメニュー
- 遷移先：銀行同期口座編集画面（モバイル） `/bank-sync/account/:accountId/edit`

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | GoCardless連携 | 主機能 | モバイルでの銀行連携管理 |
| 27 | SimpleFIN連携 | 主機能 | モバイルでのSimpleFIN連携管理 |
| 28 | PluggyAI連携 | 主機能 | モバイルでのPluggyAI連携管理 |
| 60 | レスポンシブUI | 補助機能 | モバイル最適化表示 |

## 画面種別

一覧

## URL/ルーティング

`/bank-sync`

- モバイル（ナロー画面幅）では `MobileBankSyncPage` コンポーネント
- デスクトップ（ワイド画面幅）では `BankSync` コンポーネント

## 入出力項目

| 項目名 | 項目ID | データ型 | 入力/出力 | 必須 | 説明 |
|--------|--------|----------|-----------|------|------|
| 検索フィルタ | filter | string | 入力 | 任意 | 口座名・銀行名で検索 |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ヘッダータイトル | string | "Bank Sync" と表示 |
| 検索フィールド | input | 口座検索用入力フィールド |
| プロバイダー名 | string | GoCardless / SimpleFIN / Pluggy.ai / Unlinked |
| 口座一覧 | list | 口座名、銀行名、アクションボタン |
| 空状態メッセージ | text | 口座がない場合のガイダンス |

## イベント仕様

### 1-画面初期表示

画面表示時に口座一覧を取得し、同期プロバイダー別にグループ化して表示する。

**処理フロー**:
1. `useAccounts()` フックで口座一覧を取得
2. `openAccounts` でクローズされた口座をフィルタアウト
3. `groupedAccounts` で同期プロバイダー別にグループ化
4. プロバイダー名でソート（Unlinked は最後）

### 2-口座検索

検索フィールドへの入力で口座をフィルタリングする。

**処理フロー**:
1. `onSearchChange` イベントで `filter` ステートを更新
2. 口座名または銀行名との部分一致（大文字小文字区別なし）でフィルタリング
3. `filteredGroupedAccounts` を再計算

### 3-口座同期設定編集（リンク済み）

リンク済み口座行のタップで同期設定編集画面へ遷移する。

**処理フロー**:
1. `onAction(account, 'edit')` を呼び出し
2. `navigate('/bank-sync/account/${account.id}/edit')` で編集画面へ遷移

### 4-未リンク口座の連携設定

未リンク口座の「Link」ボタン押下時に銀行連携設定を開始する。

**処理フロー**:
1. `onAction(account, 'link')` を呼び出し
2. `pushModal('add-account', { upgradingAccountId: account.id })` でモーダルを表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| なし | - | - | この画面からの直接的なDB更新なし（遷移先で更新） |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| MSG-001 | ガイダンス | "To use the bank syncing features, you must first add an account." | 口座が存在しない場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 口座が存在しない | ガイダンスメッセージを表示 |

## 備考

- デスクトップ版との主な違いは、編集がモーダルではなく別画面で行われる点
- 検索機能がデフォルトで表示される（デスクトップ版にはない）
- モバイルナビゲーションタブが表示される

---

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

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

### 推奨読解順序

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

デスクトップ版と共通の型定義を確認する。

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

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

モバイル用画面コンポーネントの構造を把握する。

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

**主要処理フロー**:
1. **25-36行目**: useSyncSourceReadable関数
2. **38-44行目**: コンポーネント定義とフック初期化
3. **46-49行目**: openAccounts計算（クローズ口座除外）
4. **51-75行目**: groupedAccounts計算
5. **77-98行目**: filteredGroupedAccounts計算（検索フィルタ適用）
6. **100-121行目**: onAction関数（edit/link処理）
7. **127-184行目**: JSXレンダリング

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

モバイル用口座一覧の表示を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | BankSyncAccountsList.tsx | `packages/desktop-client/src/components/mobile/banksync/BankSyncAccountsList.tsx` | モバイル用口座一覧 |

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

```
MobileBankSyncPage
    │
    ├─ useAccounts()
    │      └─ Redux store から口座一覧取得
    │
    ├─ useSyncSourceReadable()
    │      └─ プロバイダー名の表示変換
    │
    ├─ openAccounts (useMemo)
    │      └─ filter(a => !a.closed)
    │
    ├─ groupedAccounts (useMemo)
    │      ├─ reduce by account_sync_source
    │      └─ sort (unlinked は最後)
    │
    ├─ filteredGroupedAccounts (useMemo)
    │      └─ filter by name/bankName
    │
    ├─ Search コンポーネント
    │
    ├─ BankSyncAccountsList
    │      └─ 各口座行の表示
    │
    └─ onAction()
           ├─ 'edit': navigate('/bank-sync/account/:id/edit')
           └─ 'link': pushModal('add-account')
```

### データフロー図

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

Redux Store ─────────▶ useAccounts() ────────────────────▶ accounts
                             │
                             ▼
                     filter(closed)
                             │
                             ▼
                     groupBy(sync_source) ───────────────▶ groupedAccounts
                             │
filter入力 ──────────▶ filter by name/bankName ──────────▶ filteredGroupedAccounts
                             │
                             ▼
                     BankSyncAccountsList
                             │
口座行タップ ────────▶ onAction('edit') ──────────────────▶ 編集画面へ遷移
                             │
Linkボタン ──────────▶ onAction('link') ──────────────────▶ add-account モーダル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MobileBankSyncPage.tsx | `packages/desktop-client/src/components/mobile/banksync/MobileBankSyncPage.tsx` | ソース | メインコンポーネント |
| BankSyncAccountsList.tsx | `packages/desktop-client/src/components/mobile/banksync/BankSyncAccountsList.tsx` | ソース | 口座一覧コンポーネント |
| Search.tsx | `packages/desktop-client/src/components/common/Search.tsx` | ソース | 検索入力コンポーネント |
| useAccounts.ts | `packages/desktop-client/src/hooks/useAccounts.ts` | ソース | 口座取得フック |
| useNavigate.ts | `packages/desktop-client/src/hooks/useNavigate.ts` | ソース | 画面遷移フック |
| Page.tsx | `packages/desktop-client/src/components/Page.tsx` | ソース | ページレイアウトコンポーネント |
| FinancesApp.tsx | `packages/desktop-client/src/components/FinancesApp.tsx` | ソース | ルーティング定義（299行目） |
| MobileNavTabs.tsx | `packages/desktop-client/src/components/mobile/MobileNavTabs.tsx` | ソース | モバイルナビゲーション |
