# 通知設計書 28-口座同期エラー

## 概要

本ドキュメントは、銀行口座の同期処理中にエラーが発生した場合にユーザーに表示される通知の仕様を定義します。

### 本通知の処理概要

口座同期エラー通知は、GoCardless、SimpleFin、Pluggy.aiなどの銀行連携サービスを通じた口座同期処理において、何らかのエラーが発生した場合にユーザーにフィードバックする機能です。

**業務上の目的・背景**：銀行口座の自動同期は、取引データを最新の状態に保つための重要な機能です。しかし、銀行側のAPI制限、認証期限切れ、ネットワーク障害などの理由で同期が失敗することがあります。この通知により、ユーザーはエラーの内容を把握し、適切な対処（再認証、再試行など）を行うことができます。

**通知の送信タイミング**：ユーザーが口座同期を実行した際、または自動同期処理中にエラーが発生した時点で通知が表示されます。エラーは各口座の同期処理ごとに個別に発生する可能性があります。

**通知の受信者**：同期処理を実行したユーザー、または自動同期が設定されている予算ファイルのユーザーに対して通知が表示されます。

**通知内容の概要**：エラーの種類（SyncError）と具体的なエラーメッセージが表示されます。内部エラーの場合は追加の技術情報も含まれることがあります。

**期待されるアクション**：エラー内容に応じて、銀行連携の再認証、接続の再試行、またはサポートへの問い合わせを行うことが期待されます。

## 通知種別

アプリ内通知（エラータイプ）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（同期処理完了時） |
| 優先度 | 高 |
| リトライ | なし（通知自体のリトライはない） |

### 送信先決定ロジック

同期処理を実行した/自動同期が設定されている予算ファイルのユーザーに対して通知を表示します。

## 通知テンプレート

### アプリ内通知

| 項目 | 内容 |
|-----|------|
| 通知タイプ | error |
| 件名/タイトル | なし |
| 表示形式 | トースト通知 |

### 本文テンプレート

**SyncErrorの場合：**
```
{エラーメッセージ}
```

**その他のエラーの場合：**
```
{エラーメッセージ}

（internal情報がある場合は追加表示）
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| message | エラーメッセージ | error.message | Yes |
| internal | 内部エラー情報 | error.internal | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | 口座同期ボタン押下 | 同期エラー発生時 | 手動同期時のエラー |
| 自動処理 | 自動同期処理 | 同期エラー発生時 | スケジュール同期時のエラー |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | エラー発生時は常に通知 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ユーザーが口座同期を実行] --> B[syncAccounts dispatch]
    B --> C[accounts-bank-sync API呼び出し]
    C --> D[銀行API通信]
    D --> E{同期成功?}
    E -->|No| F[SyncResponse.errorsに追加]
    F --> G[handleSyncResponse実行]
    G --> H{エラーはSyncError?}
    H -->|Yes| I[markAccountFailed dispatch]
    I --> J[addNotification dispatch type=error]
    H -->|No| K[addNotification dispatch with internal]
    J --> L[UIに通知表示]
    K --> L
    E -->|Yes| M[markAccountSuccess dispatch]
    M --> N[正常終了]
    L --> N
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| accounts | 同期対象口座の特定 | bank, closed, tombstoneでフィルタ |

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

#### accounts

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| id | 口座識別 | - |
| bank | 銀行連携ID | NULL以外 |
| account_sync_source | 同期ソース（goCardless/simpleFin/pluggyAi） | - |
| closed | 閉鎖状態 | false |
| tombstone | 削除状態 | false |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし（ステート管理） | - | Reduxストアでfailed状態を管理 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| SyncError | 銀行同期固有のエラー（認証切れ、レート制限等） | エラーメッセージを表示、口座をfailed状態にマーク |
| その他のエラー | ネットワークエラー、内部エラー等 | エラーメッセージと内部情報を表示 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 通知のリトライはなし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

時間帯制限なし

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

- エラーメッセージにはユーザーの銀行口座情報を含めない
- internal情報は開発者向けのデバッグ情報として扱う
- 銀行APIの認証情報はエラーメッセージに露出させない

## 備考

- SyncError型のエラーの場合、対象口座はfailed状態としてマークされ、UIにエラーインジケータが表示される
- 口座のfailed状態は、次回の同期成功時にクリアされる
- 複数口座を同時に同期する場合、各口座のエラーは個別の通知として表示される

---

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

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

### 推奨読解順序

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

エラーレスポンスの型定義を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | accountsSlice.ts | `packages/desktop-client/src/accounts/accountsSlice.ts` | AccountState型（25-35行目）、failedAccountsプロパティ |
| 1-2 | errors.ts | `packages/loot-core/src/shared/errors.ts` | getBankSyncError関数（123-125行目） |

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

クライアント側からの呼び出しフローを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | accountsSlice.ts | `packages/desktop-client/src/accounts/accountsSlice.ts` | syncAccounts thunk（382-506行目） |

**主要処理フロー**:
1. **382行目**: `syncAccounts` thunk開始
2. **399-424行目**: 同期対象口座のフィルタリング
3. **469-490行目**: 各口座に対して `accounts-bank-sync` APIを呼び出し
4. **477-484行目**: `handleSyncResponse` でエラー処理

#### Step 3: エラーハンドリングを理解する

エラー発生時の通知処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | accountsSlice.ts | `packages/desktop-client/src/accounts/accountsSlice.ts` | handleSyncResponse関数（316-376行目） |

**主要処理フロー**:
- **316行目**: `handleSyncResponse` 関数開始
- **328-343行目**: SyncErrorの場合、`markAccountFailed` をディスパッチ
- **346-366行目**: 各エラーに対して `addNotification` をディスパッチ
- **348-355行目**: SyncError型の場合はシンプルなエラーメッセージ
- **357-364行目**: その他のエラーはinternal情報も含む

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

```
syncAccounts (accountsSlice.ts:382)
    │
    ├─ 口座フィルタリング (399-424)
    │
    ├─ SimpleFin batch sync (444-466)
    │      │
    │      └─ handleSyncResponse (316) ─────────────────┐
    │                                                   │
    └─ GoCardless/PluggyAi individual sync (469-490)    │
           │                                            │
           └─ accounts-bank-sync API (473)              │
                  │                                     │
                  └─ handleSyncResponse (316) ──────────┤
                                                        │
                         ┌──────────────────────────────┘
                         │
                         ▼
           handleSyncResponse (accountsSlice.ts:316)
                         │
                         ├─ エラー判定 (328)
                         │      │
                         │      ├─ SyncError → markAccountFailed (334)
                         │      │
                         │      └─ 成功 → markAccountSuccess (342)
                         │
                         └─ エラー通知 (346-366)
                                │
                                ├─ SyncError → addNotification (349)
                                │
                                └─ Other → addNotification with internal (357)
```

### データフロー図

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

同期ボタン押下 ───▶ syncAccounts thunk ───▶ accounts-bank-sync API
                                                     │
                                                     ▼
                                            銀行API通信
                                            (GoCardless/SimpleFin/PluggyAi)
                                                     │
                                          ┌──────────┴──────────┐
                                          ▼                     ▼
                                      成功                   エラー
                                          │                     │
                                          ▼                     ▼
                              markAccountSuccess      markAccountFailed
                                                              │
                                                              ▼
                                                      addNotification
                                                      (type: error)
                                                              │
                                                              ▼
                                                         UI表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| accountsSlice.ts | `packages/desktop-client/src/accounts/accountsSlice.ts` | ソース | 口座同期処理とエラーハンドリング |
| sync.ts | `packages/loot-core/src/server/accounts/sync.ts` | ソース | サーバー側の同期処理 |
| errors.ts | `packages/loot-core/src/shared/errors.ts` | ソース | エラーメッセージ生成 |
| AccountSyncCheck.tsx | `packages/desktop-client/src/components/accounts/AccountSyncCheck.tsx` | ソース | 同期エラー表示UI |
| notificationsSlice.ts | `packages/desktop-client/src/notifications/notificationsSlice.ts` | ソース | 通知の状態管理 |
