# 通知設計書 19-同期エラー（不明）

## 概要

本ドキュメントは、Actualアプリケーションにおける「同期エラー（不明）」エラー通知の設計仕様を定義する。この通知は、同期処理中に既知のカテゴリに分類されないエラーが発生した場合に表示され、バグ報告を促す。

### 本通知の処理概要

この通知は、同期処理中に発生したエラーが既知のサブタイプ（out-of-sync, invalid-schema, encrypt-failure等）に該当しない場合のフォールバックとして発行される。これは予期しないエラーが発生したことを意味し、開発チームへのバグ報告が必要なケースである。

**業務上の目的・背景**：同期システムは複雑であり、すべてのエラーケースを網羅的に処理することは困難である。この通知は、未知のエラーをキャッチし、ユーザーに問題を報告してもらうことで、開発チームがエッジケースを発見し、システムの堅牢性を向上させる目的がある。

**通知の送信タイミング**：同期処理（listenForSyncEvent）でsync-eventのtype: 'error'を受信し、subtypeがswitch文のどのcaseにも該当しない場合（default節）に発行される。

**通知の受信者**：現在アプリケーションを操作しているユーザー。通知はアプリ内のUIに直接表示されるため、ログイン中のユーザーが受信者となる。

**通知内容の概要**：同期に問題が発生したことを伝え、GitHubでのバグ報告を促す。

**期待されるアクション**：ユーザーはメッセージ内のGitHubリンクをクリックして、新しいissueを作成しバグを報告することが期待される。エラーの発生状況や操作内容を報告することで、開発チームが問題を特定できる。

## 通知種別

アプリ内通知（In-App Notification）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（イベントリスナー経由） |
| 優先度 | 高（error） |
| リトライ | 無し |

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

通知は現在アクティブなブラウザ/アプリウィンドウに表示される。特定のユーザー選定ロジックは存在せず、同期エラーが発生したセッションに対して直接通知が発行される。

## 通知テンプレート

### アプリ内通知の場合

| 項目 | 内容 |
|-----|------|
| 通知タイプ | error |
| タイトル | なし（messageのみ） |
| sticky | false（自動消去） |
| 識別ID | なし（自動生成） |

### 本文テンプレート

```
We had problems syncing your changes. Please report this as a bug by
[opening a GitHub issue](https://github.com/actualbudget/actual/issues/new?assignees=&labels=bug&template=bug-report.yml&title=%5BBug%5D%3A+).
```

### ボタン

ボタンなし（メッセージ内リンクのみ）

### メッセージ内リンク

| リンクテキスト | URL |
|--------------|-----|
| opening a GitHub issue | https://github.com/actualbudget/actual/issues/new?assignees=&labels=bug&template=bug-report.yml&title=%5BBug%5D%3A+ |

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| githubIssueLink | GitHubのissue作成URL | ハードコード | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| イベント | sync-event (type: error, subtype: 不明) | 未知のエラー | 既知のサブタイプに該当しない |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 予算ファイル未読み込み | prefs.local.idが未設定の場合、通知は発行されない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[同期処理中にエラー発生] --> B[sync-event エミット]
    B --> C[listenForSyncEvent がキャッチ]
    C --> D{subtype判定}
    D -->|out-of-sync| E[No.7/No.8 通知]
    D -->|file-old-version| F[No.9 通知]
    D -->|file-key-mismatch| G[No.10 通知]
    D -->|file-not-found| H[No.11 通知]
    D -->|その他既知| I[対応する通知]
    D -->|default 不明| J[console.trace でログ出力]
    J --> K[通知オブジェクト作成]
    K --> L[addNotification ディスパッチ]
    L --> M[UI に通知表示]
    M --> N[ユーザーがGitHubリンクをクリック]
    N --> O[GitHub issue作成ページへ遷移]
```

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

### 参照テーブル一覧

このエラーは未知のエラーをキャッチするため、特定のテーブル参照はない。

### 更新テーブル一覧

このエラーでは更新は行われない。

## エラー処理

### エラーケース一覧

このエラー通知自体がフォールバック処理のため、特定のエラーケースは定義されない。

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 自動リトライなし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

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

### 配信時間帯

時間帯制限なし（イベント発生時に即座に表示）

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

- 未知のエラーの詳細情報はconsole.traceでログ出力される（開発者向け）
- GitHubリンクにはバグテンプレートが設定されている
- ユーザーの個人データはissueに含まれない（ユーザーが手動で追加しない限り）

## 備考

- この通知はstickyではないため、デフォルトの6.5秒後に自動消去される
- default節で処理されるため、新しいエラータイプが追加された場合に発生する可能性がある
- console.trace('unknown error', event)でデバッグ情報が出力される
- GitHubへの報告が強く推奨される

---

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

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

### 推奨読解順序

#### Step 1: default節の位置を理解する

switch文のdefault節がどこで処理されるかを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sync-events.ts | `packages/desktop-client/src/sync-events.ts` | switch文全体（96-369行目）、default節（361-368行目） |

**読解のコツ**: switch文のすべてのcaseを把握し、default節がどのような場合に実行されるかを理解する。

#### Step 2: エラーイベントの構造を理解する

sync-eventのerrorタイプの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | server-events.ts | `packages/loot-core/src/types/server-events.ts` | SyncEvent型（20-44行目）、SyncSubtype型（4-18行目） |

**主要処理フロー**:
1. **4-18行目**: SyncSubtypeとして定義されているサブタイプ一覧
2. **35-37行目**: type: 'error'の場合、subtypeはオプショナル

#### Step 3: default節の処理を理解する

default節で実行される処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sync-events.ts | `packages/desktop-client/src/sync-events.ts` | default節（361-368行目） |

**主要処理フロー**:
- **361行目**: default:
- **362行目**: console.trace('unknown error', event)
- **363-367行目**: 通知オブジェクト作成（GitHubリンク付き）

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

```
同期処理中のエラー発生
    │
    ▼
app.events.emit('sync', {type: 'error', subtype: ???})
    │
    ▼

listenForSyncEvent (sync-events.ts:23)
    │
    └─ listen('sync-event') (sync-events.ts:42)
           │
           └─ event.type === 'error' (sync-events.ts:90)
                  │
                  └─ switch (event.subtype) {
                         case 'out-of-sync': ...
                         case 'file-old-version': ...
                         case 'file-key-mismatch': ...
                         case 'file-not-found': ...
                         case 'file-needs-upload': ...
                         case 'file-has-reset': ...
                         case 'file-has-new-key': ...
                         case 'encrypt-failure': ...
                         case 'decrypt-failure': ...
                         case 'invalid-schema': ...
                         case 'apply-failure': ...
                         case 'network': ...
                         case 'token-expired': ...
                         default: ★ここで処理
                             console.trace('unknown error', event)
                             notif = {...}
                     }
```

### データフロー図

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

同期処理エラー           sync/index.ts                   sync-event
(未知のサブタイプ) ───▶ app.events.emit ───▶ (type: 'error', subtype: ???)
                              │
                              ▼
                       sync-events.ts
                              │
                              └─ switch (event.subtype)
                                    │
                                    └─ default:
                                          │
                                          ├─ console.trace (デバッグ用)
                                          │
                                          └─ addNotification ───▶ UI表示
                                                                     │
                                                                     ▼
                                                             ユーザーがGitHubリンククリック
                                                                     │
                                                                     ▼
                                                             GitHub issue作成ページ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sync-events.ts | `packages/desktop-client/src/sync-events.ts` | ソース | 同期イベントリスナー、通知発行、default節処理 |
| index.ts | `packages/loot-core/src/server/sync/index.ts` | ソース | fullSync、エラーイベント発火 |
| notificationsSlice.ts | `packages/desktop-client/src/notifications/notificationsSlice.ts` | ソース | 通知状態管理 |
| server-events.ts | `packages/loot-core/src/types/server-events.ts` | 型定義 | SyncSubtype定義、SyncEvent型 |
