# 通知設計書 21-サーバーエラー

## 概要

本ドキュメントは、サーバー側で内部エラーが発生した際にユーザーに表示されるサーバーエラー通知の仕様を定義します。

### 本通知の処理概要

サーバーエラー通知は、アプリケーションの内部処理においてサーバー側で予期せぬエラーが発生した場合にユーザーへ通知を行う機能です。

**業務上の目的・背景**：サーバー内部で発生したエラーをユーザーに適切に伝え、アプリケーションの再起動やGitHubへのバグ報告を促すことで、問題の早期解決とユーザーエクスペリエンスの向上を図ります。予期せぬエラーが発生した場合でも、ユーザーが適切な対処方法を把握できるようにすることが重要です。

**通知の送信タイミング**：サーバーから `server-error` イベントが発行された時点で即座に通知が表示されます。このイベントはサーバー側の処理で例外がキャッチされた際に発行されます。

**通知の受信者**：エラーが発生したセッションのユーザー（現在アプリケーションを使用中のユーザー）に対して通知が表示されます。

**通知内容の概要**：内部エラーが発生したことを伝え、アプリケーションの再起動を推奨するメッセージ、およびGitHubへのバグ報告を促すメッセージが表示されます。

**期待されるアクション**：ユーザーはアプリケーションを再起動し、問題が継続する場合はGitHubにバグレポートを提出することが期待されます。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（イベント駆動） |
| 優先度 | 高 |
| リトライ | なし |

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

サーバーエラーイベントを受信したクライアントに対して、即座に通知を表示します。特定のユーザーロールや権限による制限はありません。

## 通知テンプレート

### アプリ内通知

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

### 本文テンプレート

```
Something internally went wrong. You may want to restart the app if anything looks wrong. Please report this as a new issue on GitHub.
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | 固定メッセージのため変数なし | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| サーバーイベント | server-error | 常時 | サーバー側で内部エラーが発生した際に発行 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | サーバーエラー発生時は常に通知を表示 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[サーバー内部エラー発生] --> B[server-errorイベント発行]
    B --> C[クライアントがイベントをリッスン]
    C --> D[addGenericErrorNotification実行]
    D --> E[通知スライスに通知追加]
    E --> F[UIに通知表示]
    F --> G[ユーザーが確認]
    G --> H[終了]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | データベース参照なし | 固定メッセージのため |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | なし | ログの記録なし |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | エラー通知自体がエラー処理のため | - |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

時間帯制限なし（エラー発生時は即座に通知）

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

- エラーメッセージには内部実装の詳細やスタックトレースを含めない
- ユーザーの個人情報は通知内容に含めない
- GitHubへの報告時はユーザーが自身で情報を選択して報告

## 備考

- 国際化（i18n）対応済み：メッセージは `t()` 関数でラップされており、多言語対応
- この通知は汎用エラー通知として、様々なサーバーエラーに対して共通で使用される

---

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

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

### 推奨読解順序

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

まず、通知のデータ構造と型定義を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | notificationsSlice.ts | `packages/desktop-client/src/notifications/notificationsSlice.ts` | Notification型の定義（9-26行目）を確認。type, message, stickyなどのプロパティを理解する |
| 1-2 | server-events.ts | `packages/loot-core/src/types/server-events.ts` | ServerEvents型でserver-errorイベントの型定義（64行目、79行目）を確認 |

**読解のコツ**: TypeScriptの型定義を先に理解することで、通知オブジェクトがどのようなプロパティを持つか把握できます。

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

処理の起点となるイベントリスナーの登録箇所を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | global-events.ts | `packages/desktop-client/src/global-events.ts` | handleGlobalEvents関数（19行目）がエントリーポイント。server-errorイベントのリスナー登録（20-22行目）を確認 |

**主要処理フロー**:
1. **20行目**: `listen('server-error', ...)` でserver-errorイベントをリッスン
2. **21行目**: イベント受信時に `addGenericErrorNotification()` をディスパッチ

#### Step 3: 通知追加処理を理解する

通知がReduxストアに追加される処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | notificationsSlice.ts | `packages/desktop-client/src/notifications/notificationsSlice.ts` | addGenericErrorNotificationリデューサー（69-79行目）でエラー通知オブジェクトが生成される処理を確認 |

**主要処理フロー**:
- **69-79行目**: 固定のエラーメッセージを持つ通知オブジェクトを生成し、notifications配列に追加

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

```
handleGlobalEvents (global-events.ts:19)
    │
    └─ listen('server-error', callback) (global-events.ts:20)
           │
           └─ store.dispatch(addGenericErrorNotification())
                  │
                  └─ notificationsSlice.reducers.addGenericErrorNotification (notificationsSlice.ts:69)
                         │
                         └─ state.notifications に通知追加
```

### データフロー図

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

サーバーエラー発生 ───▶ server-errorイベント発行 ───▶ クライアントでリッスン
                                                              │
                                                              ▼
                                               addGenericErrorNotification
                                                              │
                                                              ▼
                                               Reduxストアに通知追加
                                                              │
                                                              ▼
                                               UIコンポーネントで表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| global-events.ts | `packages/desktop-client/src/global-events.ts` | ソース | グローバルイベントハンドラーの登録 |
| notificationsSlice.ts | `packages/desktop-client/src/notifications/notificationsSlice.ts` | ソース | 通知の状態管理（Redux Slice） |
| server-events.ts | `packages/loot-core/src/types/server-events.ts` | 型定義 | サーバーイベントの型定義 |
| store.ts | `packages/desktop-client/src/redux/store.ts` | ソース | Reduxストアの設定 |
