# 通知設計書 21-Failed to load sessions

## 概要

本ドキュメントは、OpenCodeアプリケーションにおける「Failed to load sessions」トースト通知の設計を定義する。

### 本通知の処理概要

この通知は、プロジェクトに関連するセッション一覧の読み込みに失敗した場合にユーザーに表示されるエラー通知である。

**業務上の目的・背景**：セッション一覧の読み込みは、ユーザーがプロジェクトを選択した際に過去の会話履歴を表示するために不可欠な機能である。この機能が失敗した場合、ユーザーは原因を把握し、適切な対処（再試行、ネットワーク確認等）を行う必要がある。本通知は、セッション読み込み失敗という重要なエラーをユーザーに即座に伝達し、トラブルシューティングを支援する。

**通知の送信タイミング**：GlobalSyncコンテキストの`loadSessions`関数において、SDKを通じたセッション一覧取得APIがエラーを返した時点で即座に通知が表示される。具体的には、`globalSDK.client.session.list`の呼び出しがcatchブロックに到達した際にトリガーされる。

**通知の受信者**：現在OpenCodeアプリケーションを操作しているユーザー本人。セッション読み込みを要求した当事者に対してのみ表示される。

**通知内容の概要**：プロジェクト名を含むタイトルメッセージ（「Failed to load sessions for {project}」）と、エラーの詳細内容を含む説明文が表示される。これにより、どのプロジェクトで問題が発生したかが明確になる。

**期待されるアクション**：ユーザーは通知内容を確認し、ネットワーク接続の確認、サーバー状態の確認、または再試行などの対処を行う。通知は一定時間後に自動的に消えるか、ユーザーが手動で閉じることができる。

## 通知種別

トースト通知（アプリ内通知）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（UIスレッドで即時表示） |
| 優先度 | 中 |
| リトライ | なし（通知表示自体にはリトライ不要） |

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

現在アクティブなアプリケーションウィンドウ内でトースト通知として表示。特定のユーザーロールや権限による制限はない。

## 通知テンプレート

### トースト通知

| 項目 | 内容 |
|-----|------|
| タイトル | `toast.session.listFailed.title` |
| 説明 | エラーメッセージ（動的） |
| アイコン | なし（デフォルト） |
| バリアント | default |

### 本文テンプレート

```
タイトル: Failed to load sessions for {{project}}
説明: {{errorMessage}}
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| project | プロジェクト名（ディレクトリ名から抽出） | `getFilename(directory)` | Yes |
| errorMessage | エラーメッセージ | catchブロックのエラーオブジェクト | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | `globalSDK.client.session.list` APIエラー | セッション一覧取得が失敗した場合 | loadSessions関数内のcatchブロックで発火 |

### 送信抑止条件

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

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[loadSessions関数呼び出し] --> B[session.list API実行]
    B -->|成功| C[セッション一覧を更新]
    B -->|失敗| D[エラーをキャッチ]
    D --> E[プロジェクト名を取得]
    E --> F[showToast呼び出し]
    F --> G[トースト通知表示]
    G --> H[終了]
    C --> H
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | なし | クライアントサイド処理のみ |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | なし | 通知表示のみ、DB更新なし |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ネットワークエラー | サーバーとの通信失敗 | エラーメッセージを通知に表示 |
| 認証エラー | セッション取得権限がない | エラーメッセージを通知に表示 |
| サーバーエラー | サーバー内部エラー | エラーメッセージを通知に表示 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（24時間表示可能）

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

- エラーメッセージには内部実装の詳細やセンシティブな情報を含めないよう配慮
- プロジェクトパスの表示はディレクトリ名のみに限定

## 備考

- 国際化対応（i18n）済み：`toast.session.listFailed.title`キーで多言語対応
- 日本語: 「{{project}}のセッション読み込みに失敗しました」

---

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

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

### 推奨読解順序

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

トースト通知のオプション構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | toast.tsx | `packages/ui/src/components/toast.tsx` | ToastOptions型の定義（title, description, icon等のプロパティ）を確認 |

**読解のコツ**: TypeScriptの型定義を確認し、showToast関数がどのようなオプションを受け取るかを把握する。

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

通知がトリガーされる起点となるファイル。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | global-sync.tsx | `packages/app/src/context/global-sync.tsx` | loadSessions関数のcatchブロックでshowToastが呼ばれている箇所を確認 |

**主要処理フロー**:
1. **行206-213**: catchブロック内でエラー処理とトースト表示
2. **行208**: getFilenameでプロジェクト名を抽出
3. **行209-212**: showToast呼び出しで通知表示

#### Step 3: 国際化リソースを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | en.ts | `packages/app/src/i18n/en.ts` | `toast.session.listFailed.title`キーの定義を確認 |
| 3-2 | ja.ts | `packages/app/src/i18n/ja.ts` | 日本語翻訳を確認 |

**主要処理フロー**:
- **en.ts 行430**: `"toast.session.listFailed.title": "Failed to load sessions for {{project}}"`
- **ja.ts 行386**: `"toast.session.listFailed.title": "{{project}}のセッション読み込みに失敗しました"`

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

```
loadSessions (global-sync.tsx)
    │
    ├─ globalSDK.client.session.list (SDK呼び出し)
    │      └─ .catch() (エラーハンドリング)
    │             ├─ getFilename(directory) (プロジェクト名取得)
    │             └─ showToast() (通知表示)
    │                    └─ Toast component (UI描画)
    │
    └─ .then() (成功時の処理)
```

### データフロー図

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

directory ───▶ getFilename() ───▶ project変数
    │
    ├─────▶ session.list() ───▶ エラー発生
    │                               │
    │                               ▼
    └─────────────────────────▶ showToast({
                                   title: i18n(project),
                                   description: error.message
                                 })
                                       │
                                       ▼
                                 [トースト通知表示]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| global-sync.tsx | `packages/app/src/context/global-sync.tsx` | ソース | 通知トリガー元 |
| toast.tsx | `packages/ui/src/components/toast.tsx` | ソース | トースト通知コンポーネント |
| en.ts | `packages/app/src/i18n/en.ts` | 設定 | 英語メッセージ定義 |
| ja.ts | `packages/app/src/i18n/ja.ts` | 設定 | 日本語メッセージ定義 |
