# 通知設計書 44-Request failed

## 概要

本ドキュメントは、OpenCodeアプリケーションにおける「Request failed」トースト通知の設計を記載する。これはアプリケーション全体で汎用的に使用されるエラー通知であり、APIリクエストが失敗した際のフォールバックメッセージとして機能する。

### 本通知の処理概要

アプリケーション内の各種APIリクエストが失敗した際に、詳細なエラーメッセージが利用できない場合のデフォルトメッセージとして「Request failed」を表示し、ユーザーに処理の失敗を通知する。

**業務上の目的・背景**：OpenCodeでは多数のAPIエンドポイントと通信を行っており、様々な理由でリクエストが失敗する可能性がある。すべてのエラーケースに個別のメッセージを用意することは現実的でないため、汎用的なフォールバックメッセージとして「Request failed」を使用する。これにより、ユーザーは少なくとも処理が失敗したことを認識でき、適切な対応（再試行、サポートへの問い合わせなど）を取ることができる。

**通知の送信タイミング**：以下のような状況でAPIエラーが発生し、より具体的なエラーメッセージが利用できない場合に表示される。
- プロバイダー接続/切断処理の失敗
- フォーク処理の失敗
- セッション関連操作の失敗
- その他各種API操作の失敗

**通知の受信者**：操作を実行したユーザー自身。アプリケーションのアクティブウィンドウにトースト通知が表示される。

**通知内容の概要**：タイトルとして「Request failed」が表示される。より詳細なエラーメッセージがAPIから返却された場合は、そちらが優先して表示される。

**期待されるアクション**：ユーザーは通知を確認後、操作を再試行するか、ネットワーク接続やサーバー状態を確認する。問題が継続する場合はサポートに問い合わせる。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（APIエラー発生時に即時表示） |
| 優先度 | 中 |
| リトライ | 無 |

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

操作を実行したユーザー自身のブラウザ/デスクトップアプリ画面に表示される。送信先の判定は不要（ローカル通知のため）。

## 通知テンプレート

### トースト通知

| 項目 | 内容 |
|-----|------|
| アイコン | なし（デフォルト）またはerrorバリアントのアイコン |
| タイトル | `common.requestFailed`（"Request failed"） |
| 説明 | 操作に応じたエラー詳細（オプション） |
| バリアント | error（場合による） |

### 本文テンプレート

```
タイトル: Request failed
説明: {contextual error message} (オプション)
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| - | 「Request failed」は固定テキスト | i18n | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | プロバイダー接続 | APIエラー時のフォールバック | dialog-connect-provider.tsx |
| 画面操作 | カスタムプロバイダー作成 | APIエラー時のフォールバック | dialog-custom-provider.tsx |
| 画面操作 | フォーク処理 | APIエラー時のフォールバック | dialog-fork.tsx |
| 画面操作 | サーバー選択 | APIエラー時のフォールバック | dialog-select-server.tsx |
| 画面操作 | プロンプト送信 | APIエラー時のフォールバック | submit.ts |
| 画面操作 | 設定変更 | APIエラー時のフォールバック | settings-general.tsx等 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| APIリクエスト成功 | 処理が成功した場合は通知を表示しない |
| より具体的なエラーメッセージがある | APIから詳細メッセージが返却された場合はそちらを使用 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[APIリクエスト実行] --> B{結果}
    B -->|成功| C[通常処理]
    B -->|失敗| D{詳細エラーメッセージあり?}
    D -->|Yes| E[詳細メッセージで通知]
    D -->|No| F[Request failedで通知]
    E --> G[終了]
    F --> G
    C --> G
```

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

### 参照テーブル一覧

本通知はクライアントサイドで完結するため、データベースへの直接参照は行わない。

### 更新テーブル一覧

本通知はクライアントサイドで完結するため、データベースへの更新は行わない。

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| APIエラー | 各種APIの失敗 | 「Request failed」メッセージをトースト通知で表示 |
| ネットワークエラー | 接続不可 | 「Request failed」メッセージをトースト通知で表示 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（通知表示自体はリトライしない） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（エラー発生時に即時表示）

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

- エラーメッセージには機密情報が含まれないよう、APIからの詳細なスタックトレースは表示しない
- 汎用メッセージ「Request failed」は意図的に詳細を隠している

## 備考

- 「Request failed」は多くの箇所で使用される汎用メッセージ
- `errorMessage`ヘルパー関数（submit.ts L64-71）でAPIエラーから詳細メッセージを抽出し、なければこのメッセージを使用
- 多言語対応済み（`common.requestFailed` i18nキー）

---

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

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

### 推奨読解順序

#### Step 1: メッセージ定義を理解する

i18n定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | en.ts | `packages/app/src/i18n/en.ts` | L565の`common.requestFailed`定義 |

**読解のコツ**: `common.requestFailed`がどのキーで定義されているかを確認する。

#### Step 2: 使用箇所を理解する

汎用エラーメッセージの使用パターンを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | submit.ts | `packages/app/src/components/prompt-input/submit.ts` | L64-71のerrorMessage関数 |
| 2-2 | dialog-connect-provider.tsx | `packages/app/src/components/dialog-connect-provider.tsx` | API失敗時の通知 |
| 2-3 | dialog-fork.tsx | `packages/app/src/components/dialog-fork.tsx` | フォーク失敗時の通知 |

**主要処理フロー**:
1. **submit.ts L64-71**: `errorMessage`関数でAPIエラーから詳細を抽出、なければ`common.requestFailed`
2. **各コンポーネント**: catch句でerrorMessageを呼び出しshowToastに渡す

#### Step 3: エラーメッセージ抽出ロジックを理解する

フォールバックメッセージとして使用されるロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | submit.ts | `packages/app/src/components/prompt-input/submit.ts` | L64-71のerrorMessage関数の詳細 |

**主要処理フロー**:
- **L65-68**: APIエラーの`data.message`を抽出
- **L69**: Errorインスタンスの`message`を抽出
- **L70**: フォールバックとして`common.requestFailed`を返す

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

```
各コンポーネント/フック
    │
    ├─ API呼び出し
    │      └─ Promise.catch()
    │
    └─ エラー処理
           ├─ errorMessage(err)
           │      ├─ err.data?.message
           │      ├─ err.message
           │      └─ language.t("common.requestFailed")
           │
           └─ showToast({ title, description })
```

### データフロー図

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

APIエラー ───▶ errorMessage() ───▶ トースト通知表示
                    │                    │
                    ▼                    └─ "Request failed"
             エラー詳細抽出                   またはAPIエラー詳細
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| en.ts | `packages/app/src/i18n/en.ts` | 設定 | 英語メッセージ定義（L565） |
| ja.ts | `packages/app/src/i18n/ja.ts` | 設定 | 日本語メッセージ定義 |
| submit.ts | `packages/app/src/components/prompt-input/submit.ts` | ソース | errorMessage関数（L64-71） |
| dialog-connect-provider.tsx | `packages/app/src/components/dialog-connect-provider.tsx` | ソース | プロバイダー接続での使用 |
| dialog-custom-provider.tsx | `packages/app/src/components/dialog-custom-provider.tsx` | ソース | カスタムプロバイダー作成での使用 |
| dialog-fork.tsx | `packages/app/src/components/dialog-fork.tsx` | ソース | フォーク処理での使用 |
| dialog-select-server.tsx | `packages/app/src/components/dialog-select-server.tsx` | ソース | サーバー選択での使用 |
| settings-general.tsx | `packages/app/src/components/settings-general.tsx` | ソース | 設定変更での使用 |
| settings-providers.tsx | `packages/app/src/components/settings-providers.tsx` | ソース | プロバイダー設定での使用 |
| status-popover.tsx | `packages/app/src/components/status-popover.tsx` | ソース | ステータスポップオーバーでの使用 |
