# 通知設計書 22-Update available

## 概要

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

### 本通知の処理概要

この通知は、OpenCodeの新しいバージョンが利用可能になった場合にユーザーに通知し、更新を促すための持続的トースト通知である。

**業務上の目的・背景**：ソフトウェアの最新バージョンを使用することは、セキュリティ、パフォーマンス、機能面で重要である。本通知は、ユーザーが新しいバージョンの存在を認識し、適切なタイミングでアップデートを実行できるよう支援する。デスクトップアプリケーションにおいて、ユーザーの作業を中断することなく、アップデートの選択肢を提供することが目的である。

**通知の送信タイミング**：アプリケーション起動時のアップデートチェック、および定期的なポーリング（10分間隔）でアップデートが検出された場合にトリガーされる。また、設定画面から手動でアップデートチェックを実行した際にも表示される可能性がある。

**通知の受信者**：OpenCodeデスクトップアプリケーションを使用している全ユーザー。プラットフォームがアップデート機能をサポートしている場合のみ対象。

**通知内容の概要**：新しいバージョン番号を含むタイトルと説明文、および「インストールして再起動」「今はしない」の2つのアクションボタンが表示される。この通知は持続的（persistent）であり、ユーザーが明示的に操作するまで消えない。

**期待されるアクション**：ユーザーは「インストールして再起動」を選択してアップデートを実行するか、「今はしない」を選択して通知を閉じる。アップデートを選択した場合、アプリケーションは自動的に更新をダウンロード・インストールし、再起動する。

## 通知種別

トースト通知（アプリ内通知、持続的）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（UIスレッドで即時表示） |
| 優先度 | 高（持続的通知） |
| リトライ | なし |

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

現在アクティブなアプリケーションウィンドウ内でトースト通知として表示。デスクトッププラットフォームでアップデート機能（`platform.checkUpdate`、`platform.update`、`platform.restart`）が利用可能な場合のみ表示。

## 通知テンプレート

### トースト通知

| 項目 | 内容 |
|-----|------|
| タイトル | `toast.update.title` |
| 説明 | `toast.update.description` |
| アイコン | download |
| バリアント | default |
| 持続性 | persistent: true |

### 本文テンプレート

```
タイトル: Update available
説明: A new version of OpenCode ({{version}}) is now available to install.
アクション1: Install and restart
アクション2: Not yet
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| version | 新しいバージョン番号 | `checkUpdate()`の戻り値 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| スケジュール | アプリ起動時チェック | `settings.updates.startup()`がtrue、かつアップデートあり | 起動時の自動チェック |
| スケジュール | 定期ポーリング（10分間隔） | アップデートあり | バックグラウンドでの定期チェック |
| 画面操作 | 設定画面の「Check now」ボタン | アップデートあり | 手動チェック |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 既に同じ通知が表示中 | toastIdを追跡し、重複表示を防止 |
| アップデートが利用できない | `updateAvailable`がfalseの場合 |
| プラットフォーム非対応 | `platform.checkUpdate`が利用不可の場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[アップデートチェック開始] --> B[platform.checkUpdate実行]
    B -->|updateAvailable=false| C[終了/You're up to date通知]
    B -->|updateAvailable=true| D{既存の通知あり?}
    D -->|はい| E[終了]
    D -->|いいえ| F[showToast呼び出し]
    F --> G[持続的トースト表示]
    G --> H{ユーザーアクション}
    H -->|Install and restart| I[platform.update実行]
    I --> J[platform.restart実行]
    H -->|Not yet| K[通知を閉じる]
    J --> L[終了]
    K --> L
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| チェック失敗 | ネットワークエラー等 | 手動チェック時はエラー通知を表示 |
| アップデート失敗 | ダウンロード/インストールエラー | 別途エラーダイアログで通知 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（定期ポーリングで再チェック） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 1件（重複防止機構あり） |
| 1日あたり上限 | 制限なし |

### 配信時間帯

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

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

- アップデートの取得元は公式サーバーに限定
- バージョン情報は信頼できるソースから取得

## 備考

- 国際化対応（i18n）済み
- 日本語: タイトル「アップデートが利用可能です」、説明「OpenCodeの新しいバージョン ({{version}}) がインストール可能です。」
- Tauri/デスクトップ環境専用機能

---

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

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

### 推奨読解順序

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

持続的トースト通知のオプション構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | toast.tsx | `packages/ui/src/components/toast.tsx` | ToastOptions型のpersistent、actionsプロパティを確認 |

**読解のコツ**: persistentプロパティがtrueの場合、ユーザー操作まで通知が消えない。

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

通知がトリガーされる主要な場所。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | layout.tsx | `packages/app/src/pages/layout.tsx` | useUpdatePolling関数でのアップデートチェックロジック |
| 2-2 | settings-general.tsx | `packages/app/src/components/settings-general.tsx` | check関数での手動チェック実装 |

**主要処理フロー（layout.tsx）**:
1. **行281-332**: useUpdatePolling関数の定義
2. **行288-311**: pollUpdate関数でアップデートチェックと通知表示
3. **行292-310**: showToast呼び出しとアクション定義

**主要処理フロー（settings-general.tsx）**:
1. **行52-104**: check関数でのアップデートチェック
2. **行91-97**: showToast呼び出し

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

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

**主要処理フロー**:
- **en.ts 行432-435**: `toast.update.title`、`toast.update.description`、アクションラベル
- **ja.ts 行387-390**: 日本語翻訳

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

```
Layout (layout.tsx)
    │
    └─ useUpdatePolling
           │
           ├─ onMount
           │      └─ pollUpdate (即時実行)
           │             ├─ platform.checkUpdate()
           │             └─ showToast({persistent: true, actions: [...]})
           │
           └─ setInterval (10分間隔)
                  └─ pollUpdate

SettingsGeneral (settings-general.tsx)
    │
    └─ check (ボタンクリック)
           ├─ platform.checkUpdate()
           └─ showToast({persistent: true, actions: [...]})
```

### データフロー図

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

platform.checkUpdate()
         │
         ▼
  {updateAvailable, version}
         │
         ├──▶ updateAvailable === false ──▶ [You're up to date 通知]
         │
         └──▶ updateAvailable === true
                     │
                     ▼
              showToast({
                persistent: true,
                icon: "download",
                title: "Update available",
                description: `version ${version}`,
                actions: [
                  {Install and restart},
                  {Not yet}
                ]
              })
                     │
                     ▼
              [持続的トースト通知表示]
                     │
         ┌──────────┴──────────┐
         ▼                     ▼
[Install and restart]     [Not yet]
         │                     │
         ▼                     ▼
platform.update()        toaster.dismiss()
         │
         ▼
platform.restart()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| layout.tsx | `packages/app/src/pages/layout.tsx` | ソース | 自動アップデートチェック・通知表示（メイン） |
| settings-general.tsx | `packages/app/src/components/settings-general.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` | 設定 | 日本語メッセージ定義 |
