# 通知設計書 8-アップデート成功通知

## 概要

本ドキュメントは、Oh My Zshのアップデート機能におけるバックグラウンド更新成功時の通知について、その設計仕様を定義するものである。

### 本通知の処理概要

Oh My Zshは、バックグラウンド更新モード（background-alpha）で更新が成功した場合に、次回のプロンプト表示時に緑色の成功メッセージを表示する機能を提供する。

**業務上の目的・背景**：バックグラウンド更新モードは、シェル起動時にユーザーの操作を待たずに自動的に更新を実行する実験的な機能である。更新がバックグラウンドで完了した場合、ユーザーは更新が行われたことを認識する必要があるため、次回のプロンプト表示時に成功メッセージを表示する。これにより、ユーザーは自分のOh My Zsh環境が最新であることを確認できる。

**通知の送信タイミング**：バックグラウンド更新が成功した後、次回のprecmdフック（プロンプト表示直前）で_omz_bg_update_status関数が呼び出され、.zsh-updateファイルのEXIT_STATUS=0を検出した時点で通知が表示される。

**通知の受信者**：シェルを使用しているユーザー自身。ターミナル上に緑色のテキストメッセージとして表示される。

**通知内容の概要**：「[oh-my-zsh] Update successful.」という緑色のメッセージがターミナルに表示される。

**期待されるアクション**：受信者は更新が完了したことを認識し、通常の作業を継続する。必要に応じて `omz changelog` コマンドで変更内容を確認する。

## 通知種別

ターミナルテキスト出力（カラー付き）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（print -P によるテキスト出力） |
| 優先度 | 低 |
| リトライ | 無し |

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

現在のシェルセッションの標準出力に対してメッセージを出力する。

## 通知テンプレート

### ターミナル出力の場合

| 項目 | 内容 |
|-----|------|
| プレフィックス | `[oh-my-zsh]` |
| メッセージ | `Update successful.` |
| 色 | 緑色（%F{green}...%f） |

### 本文テンプレート

```
[oh-my-zsh] Update successful.
```

（実際の表示は緑色）

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | - | - | 添付ファイルなし |

## テンプレート変数

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

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| シェルフック | precmd（_omz_bg_update_status） | EXIT_STATUS=0 かつ update_mode=background-alpha | バックグラウンド更新成功時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| update_mode != background-alpha | バックグラウンド更新モードでない場合 |
| EXIT_STATUS != 0 | 更新が失敗した場合（失敗通知に遷移） |
| EXIT_STATUS/ERRORが未設定 | 更新結果がまだ.zsh-updateに書き込まれていない場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[precmd フック] --> B[_omz_bg_update_status呼び出し]
    B --> C{.zsh-updateファイル存在?}
    C -->|No| D[return 1]
    C -->|Yes| E[ファイル読み込み]
    E --> F{EXIT_STATUS/ERROR設定済み?}
    F -->|No| D
    F -->|Yes| G{EXIT_STATUS = 0?}
    G -->|Yes| H[成功メッセージ表示]
    G -->|No| I[エラーメッセージ表示]
    H --> J[update_last_updated_file]
    I --> J
    J --> K[フック解除]
    K --> L[終了]
    D --> L
```

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

### 参照テーブル一覧

本通知はデータベースを使用しない。ファイルとシェル変数で状態管理を行う。

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| N/A | - | データベース不使用 |

### 参照ファイル一覧

| ファイル | パス | 用途 |
|---------|------|------|
| .zsh-update | `$ZSH_CACHE_DIR/.zsh-update` | EXIT_STATUS、ERROR、LAST_EPOCHを保存 |

### ファイル内容形式

```
LAST_EPOCH=<日数>
EXIT_STATUS=0
ERROR='Update successful'
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ファイル未存在 | .zsh-updateが存在しない | return 1で終了 |
| フィールド未設定 | EXIT_STATUS/ERRORが空 | return 1で終了（次回再試行） |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 毎precmdで再試行（結果が書き込まれるまで） |
| リトライ間隔 | プロンプト表示ごと |
| リトライ対象エラー | EXIT_STATUS/ERROR未設定 |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 表示頻度 | 更新成功時に1回のみ（表示後にフック解除） |

### 配信時間帯

制限なし（precmd実行時）

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

- メッセージは固定文字列であり、機密情報は含まれない
- ローカル出力のみであり、ネットワーク経由での送信は行われない

## 備考

- print -P でzshのプロンプト展開を使用して色付きテキストを表示
- %F{green}は前景色を緑に設定、%fはリセット
- 成功メッセージ表示後、update_last_updated_fileでEXIT_STATUS/ERRORをクリア
- _omz_bg_update_statusフックは表示後に自動的に解除される
- background-alphaモードは実験的機能

---

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

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

### 推奨読解順序

#### Step 1: バックグラウンド更新モードを理解する

background-alphaモードの設定と動作を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | 249-299行目のbackground-alphaモード処理を確認 |

**読解のコツ**: case文でupdate_mode=background-alphaの場合の処理を追う。

#### Step 2: 更新結果の保存を理解する

バックグラウンド更新の結果がどのように保存されるかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | 96-109行目のupdate_last_updated_file関数を確認 |

**主要処理フロー**:
- **100行目**: LAST_EPOCH書き込み
- **104-108行目**: EXIT_STATUS、ERROR書き込み

#### Step 3: 結果表示関数を理解する

_omz_bg_update_status関数の動作を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | 265-296行目の_omz_bg_update_status関数を確認 |

**主要処理フロー**:
- **268-270行目**: .zsh-updateファイル存在チェック
- **273-276行目**: EXIT_STATUS/ERROR設定チェック
- **278-279行目**: `print -P "\n%F{green}[oh-my-zsh] Update successful.%f"` - 成功メッセージ表示
- **287-289行目**: update_last_updated_file呼び出しとフック解除

#### Step 4: 更新実行関数を理解する

update_ohmyzsh関数でのbackground-alpha処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | 111-134行目のupdate_ohmyzsh関数を確認 |

**主要処理フロー**:
- **127行目**: silentモードでupgrade.sh実行
- **128行目**: 成功時にupdate_last_updated_file 0 "Update successful"呼び出し

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

```
[シェル起動]
    │
    ├─ check_for_upgrade.sh 読み込み
    │      │
    │      └─ [update_mode=background-alpha]
    │             │
    │             ├─ add-zsh-hook precmd _omz_bg_update (298行目)
    │             │
    │             └─ _omz_bg_update (253-263行目)
    │                    │
    │                    ├─ (handle_update) &| サブシェルで実行
    │                    │      │
    │                    │      └─ update_ohmyzsh
    │                    │             │
    │                    │             └─ upgrade.sh 実行
    │                    │                    │
    │                    │                    └─ update_last_updated_file 0 "Update successful"
    │                    │
    │                    └─ add-zsh-hook precmd _omz_bg_update_status
    │
[次回 precmd]
    │
    └─ _omz_bg_update_status (265-296行目)
           │
           ├─ .zsh-update ファイル読み込み
           │
           ├─ [EXIT_STATUS=0?]
           │      │
           │      └─ Yes ──▶ print -P "%F{green}[oh-my-zsh] Update successful.%f"
           │
           ├─ update_last_updated_file (クリア)
           │
           └─ add-zsh-hook -d precmd _omz_bg_update_status (フック解除)
```

### データフロー図

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

upgrade.sh 実行結果 ────────▶ update_last_updated_file
(EXIT_STATUS=0)                    │
                                   ▼
                            .zsh-update ファイル
                            LAST_EPOCH=xxx
                            EXIT_STATUS=0
                            ERROR='Update successful'
                                   │
                                   ▼
                            _omz_bg_update_status
                                   │
                                   └─ 成功メッセージ表示 ──▶ stdout
                                                            │
                                                            ▼
                                                      "\n%F{green}[oh-my-zsh] Update successful.%f"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| check_for_upgrade.sh | `tools/check_for_upgrade.sh` | ソース | バックグラウンド更新と結果表示のロジック |
| upgrade.sh | `tools/upgrade.sh` | ソース | 実際の更新処理を実行 |
| .zsh-update | `$ZSH_CACHE_DIR/.zsh-update` | データ | 更新結果（EXIT_STATUS、ERROR）を保存 |
