# 通知設計書 51-Update Failed (download)

## 概要

本ドキュメントは、OpenCodeデスクトップアプリケーションにおけるアップデートダウンロード失敗時のダイアログ通知（Update Failed - download）の設計について記載する。

### 本通知の処理概要

本通知は、OpenCodeデスクトップアプリケーション（Tauri製）において、自動アップデートのダウンロードプロセスが失敗した際にユーザーに対してシステムダイアログを表示し、エラー状況を通知する機能である。

**業務上の目的・背景**：OpenCodeはデスクトップアプリケーションとして継続的なアップデートを提供しており、ユーザーが常に最新機能とセキュリティ修正を利用できるようにすることが重要である。アップデートダウンロードの失敗は、ネットワーク接続の問題、サーバー障害、ディスク容量不足など様々な要因で発生する可能性があり、ユーザーに対して明確にエラー状況を伝えることで、問題解決のための適切な対応を促す必要がある。

**通知の送信タイミング**：Tauriのupdaterプラグインを使用したアップデートダウンロード処理（`update.download()`）が例外をスローした時点で、即座にダイアログが表示される。この処理は、メニューからの手動アップデートチェック（`alertOnFail: true`）時にのみ発動し、自動バックグラウンドチェックでは表示されない。

**通知の受信者**：OpenCodeデスクトップアプリケーションを使用中のユーザー本人。ダイアログはアプリケーションのメインウィンドウに対してモーダルで表示される。

**通知内容の概要**：ダイアログには「Update Failed」というタイトル（i18nキー: `desktop.updater.downloadFailed.title`）と「Failed to download update」というメッセージ（i18nキー: `desktop.updater.downloadFailed.message`）が表示される。多言語対応により、ユーザーの言語設定に応じて適切な言語で表示される。

**期待されるアクション**：ユーザーはダイアログのOKボタンをクリックして閉じた後、ネットワーク接続の確認、時間を置いての再試行、または手動でのアップデート確認などの対応を行うことが期待される。

## 通知種別

デスクトップダイアログ（Tauri Dialog API - `message`関数）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（await） |
| 優先度 | 高 |
| リトライ | なし（ダイアログ表示自体のリトライはなし。アップデートの再試行はユーザー操作による） |

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

- アプリケーションを操作中のユーザーに対して、Tauriのダイアログプラグインを通じてネイティブOSのダイアログとして表示される
- `alertOnFail`パラメータが`true`の場合のみダイアログを表示（手動アップデートチェック時）
- 自動バックグラウンドチェック時（`alertOnFail: false`）はダイアログを表示せず、静かに処理を終了する

## 通知テンプレート

### デスクトップダイアログの場合

| 項目 | 内容 |
|-----|------|
| ダイアログタイプ | message（情報ダイアログ） |
| タイトル | `desktop.updater.downloadFailed.title` |
| メッセージ | `desktop.updater.downloadFailed.message` |
| ボタン | OK（デフォルト） |

### 本文テンプレート

**英語（en）:**
```
Title: Update Failed
Message: Failed to download update
```

**日本語（ja）:**
```
Title: アップデートに失敗しました
Message: アップデートをダウンロードできませんでした
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | 本通知には動的変数なし | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | メニュー「Check for Updates...」選択 | `alertOnFail: true` かつ `update.download()`が例外をスロー | ユーザーが手動でアップデートをチェックし、ダウンロードが失敗した場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `alertOnFail: false` | 自動バックグラウンドチェック時はダイアログを表示しない |
| アップデートチェック成功後の正常ダウンロード | ダウンロードが正常に完了した場合は表示しない |
| アップデートなし | 利用可能なアップデートがない場合はこのダイアログに到達しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[runUpdater関数呼び出し] --> B[i18n初期化]
    B --> C[アップデートチェック check]
    C --> D{アップデート存在?}
    D -->|Yes| E[update.download実行]
    D -->|No| F[No Update Availableダイアログ/終了]
    E --> G{ダウンロード成功?}
    G -->|Yes| H[Update Downloadedダイアログ表示]
    G -->|No - 例外発生| I{alertOnFail?}
    I -->|Yes| J[Update Failedダイアログ表示]
    I -->|No| K[静かに終了]
    J --> K
```

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

### 参照テーブル一覧

該当なし（本機能はデータベースを使用しない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ダウンロード失敗 | ネットワークエラー、サーバーエラー、ディスク容量不足等 | ダイアログ表示後、処理を終了（return） |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし（ユーザー操作起点のため） |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（ユーザーがいつでも操作可能）

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

- ダイアログには具体的なエラー詳細（スタックトレースやシステム情報）を表示せず、ユーザーフレンドリーなメッセージのみを表示
- Tauriのセキュアなダイアログプラグインを使用しており、XSSやインジェクション攻撃のリスクは低い
- 多言語対応のi18n辞書は静的に定義されており、動的なテンプレート展開による脆弱性リスクはない

## 備考

- 本ダイアログはTauri専用機能であり、Web版OpenCodeでは利用不可
- `@tauri-apps/plugin-dialog`の`message`関数を使用してネイティブOSダイアログを表示
- 多言語対応: en, ja, ko, zh, zht, de, fr, es, it, ru, ar, br, bs, da, no, pl

---

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

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

### 推奨読解順序

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

i18n辞書の構造を理解することで、通知メッセージがどのように定義されているかを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | en.ts | `packages/desktop/src/i18n/en.ts` | 英語の基本メッセージ定義。`desktop.updater.downloadFailed.title`と`.message`を確認 |
| 1-2 | ja.ts | `packages/desktop/src/i18n/ja.ts` | 日本語翻訳例。同じキーで翻訳が定義されていることを確認 |

**読解のコツ**: i18nファイルは`dict`オブジェクトとしてkey-value形式で定義されており、キー名は`desktop.updater.downloadFailed.{title|message}`のドット区切り形式で階層構造を表現している。

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

アップデート処理の起点となるファイルを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | updater.ts | `packages/desktop/src/updater.ts` | `runUpdater`関数がエントリーポイント。`alertOnFail`パラメータの役割を理解 |

**主要処理フロー**:
1. **11行目**: `runUpdater`関数定義。`alertOnFail`パラメータでダイアログ表示制御
2. **12行目**: `initI18n()`でi18n初期化
3. **15-16行目**: `check()`でアップデート確認（Tauriプラグイン）
4. **28-29行目**: `update.download()`でダウンロード実行
5. **30-33行目**: catchブロックでダウンロード失敗時の処理、`alertOnFail`チェック後にダイアログ表示

#### Step 3: Tauri Dialog APIを理解する

外部依存ライブラリの使用方法を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | updater.ts | `packages/desktop/src/updater.ts` | `@tauri-apps/plugin-dialog`からの`message`関数インポート（3行目） |

**主要処理フロー**:
- **3行目**: `import { ask, message } from "@tauri-apps/plugin-dialog"`
- **31-32行目**: `message(t("desktop.updater.downloadFailed.message"), { title: t("desktop.updater.downloadFailed.title") })`

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

```
メニュー: Check for Updates...
    │
    └─ runUpdater({ alertOnFail: true })
           │
           ├─ initI18n()
           │
           ├─ check() [Tauri Updater Plugin]
           │
           ├─ update.download() [Tauri Updater Plugin]
           │      │
           │      └─ [例外発生時]
           │             │
           │             └─ message() [Tauri Dialog Plugin]
           │                    │
           │                    └─ t("desktop.updater.downloadFailed.title")
           │                    └─ t("desktop.updater.downloadFailed.message")
           │
           └─ return (処理終了)
```

### データフロー図

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

メニュー操作     ───▶  runUpdater()
                              │
                              ▼
                       check() - アップデート確認
                              │
                              ▼
                       download() - ダウンロード試行
                              │
                              ▼
                       [例外発生]
                              │
                              ▼
                       i18n翻訳取得(t関数)    ───▶  ネイティブOSダイアログ
                              │                         (message関数)
                              ▼
                       処理終了(return)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| updater.ts | `packages/desktop/src/updater.ts` | ソース | アップデート処理のメインロジック |
| en.ts | `packages/desktop/src/i18n/en.ts` | 設定 | 英語メッセージ定義 |
| ja.ts | `packages/desktop/src/i18n/ja.ts` | 設定 | 日本語メッセージ定義 |
| index.ts (i18n) | `packages/desktop/src/i18n/index.ts` | ソース | i18n初期化・翻訳関数(t)の提供 |
| package.json | `packages/desktop/package.json` | 設定 | Tauri依存関係定義 |
