# 通知設計書 12-アップデートエラー通知

## 概要

本ドキュメントは、Oh My Zshのアップデート処理中にエラーが発生した場合にユーザーに表示されるエラー通知の設計を記載する。

### 本通知の処理概要

この通知は、Oh My Zshの更新処理（git pull --rebase）が失敗した場合に、ユーザーにエラーが発生したことを赤色のメッセージで通知する機能である。

**業務上の目的・背景**：ソフトウェアの更新処理は、ネットワーク障害、マージコンフリクト、権限問題など様々な理由で失敗する可能性がある。失敗時に明確なフィードバックを提供することで、ユーザーは問題が発生したことを認識し、後で再試行するか、手動で問題を解決する判断ができる。

**通知の送信タイミング**：`omz update`コマンド実行時、またはバックグラウンド自動更新時に、git pull --rebaseコマンドが非ゼロの終了コードを返した場合に送信される。

**通知の受信者**：ターミナル上でOh My Zshを使用しているユーザー。フォアグラウンド更新の場合は更新コマンドを実行した本人に直接表示され、バックグラウンド更新の場合は次回のprecmdフック実行時に表示される。

**通知内容の概要**：「There was an error updating. Try again later?」というメッセージが赤色で表示される。バックグラウンド更新の場合は、具体的なエラー内容も黄色で併せて表示される。

**期待されるアクション**：ユーザーはエラー発生を認識し、ネットワーク状況を確認した上で後ほど`omz update`コマンドを再実行するか、手動でgit操作を行って問題を解決する。

## 通知種別

ターミナル標準出力（STDOUT）への直接表示

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（フォアグラウンド）/ 非同期（バックグラウンド） |
| 優先度 | 高（エラー通知は重要） |
| リトライ | なし（ターミナル出力のため） |

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

更新処理を実行したターミナルセッションに直接出力する。バックグラウンドモードの場合は、precmdフックにより次のプロンプト表示前に出力される。

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 送信元 | upgrade.sh / check_for_upgrade.sh |
| 表示色 | RED（エラーメッセージ）、YELLOW（詳細エラー内容） |
| 形式 | プレーンテキスト + ANSIエスケープシーケンス |

### 本文テンプレート

#### フォアグラウンド更新時

```
There was an error updating. Try again later?
```

#### バックグラウンド更新時

```
[oh-my-zsh] There was an error updating:
<エラー詳細メッセージ>
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | ターミナル出力のため添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| RED | 赤色エスケープシーケンス | ANSIエスケープシーケンス | Yes |
| RESET | リセットエスケープシーケンス | ANSIエスケープシーケンス | Yes |
| ERROR | エラー詳細メッセージ | git pullのstderr出力 | No（バックグラウンドのみ） |
| EXIT_STATUS | 終了コード | git pullの終了コード | No（バックグラウンドのみ） |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コマンド実行 | `omz update`コマンド実行 | git pull失敗（終了コード≠0） | ユーザーが手動で更新を実行 |
| 自動更新 | バックグラウンド更新失敗 | git pull失敗かつ次回precmd実行時 | background-alphaモードで自動実行 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| git pull成功 | 正常終了時はエラー通知を表示しない |
| verbose_mode=silent（フォアグラウンドのみ） | サイレントモードでも終了コードは返す |

## 処理フロー

### 送信フロー（フォアグラウンド）

```mermaid
flowchart TD
    A[omz update実行] --> B[git pull --rebase実行]
    B -->|失敗| C[ret変数に終了コード保存]
    C --> D[REDカラーでエラーメッセージ出力]
    D --> E[exit $ret で終了]
```

### 送信フロー（バックグラウンド）

```mermaid
flowchart TD
    A[バックグラウンド更新実行] --> B[git pull --rebase実行]
    B -->|失敗| C[.zsh-updateにEXIT_STATUS, ERROR保存]
    C --> D[次回precmd実行]
    D --> E{EXIT_STATUS確認}
    E -->|≠0| F[REDでエラーヘッダ出力]
    F --> G[YELLOWでエラー詳細出力]
    G --> H[.zsh-updateをクリア]
    H --> I[終了]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | - | データベースは使用しない |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | データベースは使用しない |

### ファイル更新

| ファイル | 操作 | 概要 |
|---------|------|------|
| .zsh-update | UPDATE | LAST_EPOCH, EXIT_STATUS, ERRORを記録（バックグラウンドのみ） |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ネットワークエラー | リモートサーバーに接続できない | エラーメッセージ表示、再試行を促す |
| マージコンフリクト | ローカル変更とリモート変更が競合 | エラーメッセージ表示、手動解決を促す |
| 権限エラー | $ZSHディレクトリへの書き込み権限がない | エラーメッセージ表示 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限なし | ターミナル出力のため制限不要 |

### 配信時間帯

制限なし

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

- エラーメッセージにはgitコマンドの出力が含まれる可能性があるが、機密情報は通常含まれない
- リモートURLなどが含まれる場合があるが、公開リポジトリのため問題ない

## 備考

- フォアグラウンド更新では終了コードが返されるため、スクリプトでの判定が可能
- バックグラウンド更新では.zsh-updateファイルを介してエラー情報が永続化される
- バックグラウンドエラーは一度表示されると.zsh-updateから削除される

---

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

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

### 推奨読解順序

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

まず、エラー情報の保存形式を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | update_last_updated_file関数（96-109行目）でのファイル形式定義 |

**読解のコツ**: .zsh-updateファイルには`LAST_EPOCH`, `EXIT_STATUS`, `ERROR`の3つの変数がシェル変数形式で保存される。

#### Step 2: エントリーポイントを理解する（フォアグラウンド）

処理の起点となるファイル・関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | upgrade.sh | `tools/upgrade.sh` | git pull実行とエラー処理（245, 280-283行目） |

**主要処理フロー**:
1. **245行目**: `git pull --quiet --rebase`実行
2. **280行目**: elseブロック（git pull失敗時）に入る
3. **281行目**: `ret=$?`で終了コードを保存
4. **282行目**: 赤色でエラーメッセージを出力

#### Step 3: バックグラウンド更新のエラー処理を理解する

バックグラウンド更新でのエラー通知フローを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | update_ohmyzsh関数（111-134行目） |
| 3-2 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | _omz_bg_update_status関数（265-296行目） |

**主要処理フロー**:
- **127-131行目**: silentモードで実行し、エラー時にupdate_last_updated_fileを呼び出し
- **281-284行目**: EXIT_STATUSが非0の場合、赤色でヘッダ、黄色でエラー詳細を出力

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

```
omz update (cli.zsh)
    │
    └─ tools/upgrade.sh
           │
           ├─ git pull --rebase (245行目)
           │      └─ [失敗時] ret=$? (281行目)
           │
           └─ printf (282行目)
                  └─ REDカラーでエラーメッセージ出力

---

background-alpha モード:
    │
    ├─ _omz_bg_update (253-263行目)
    │      └─ handle_update → update_ohmyzsh
    │             └─ upgrade.sh (silent mode)
    │                    └─ [失敗] update_last_updated_file
    │
    └─ _omz_bg_update_status (265-296行目)
           └─ [EXIT_STATUS≠0] print -P でエラー出力
```

### データフロー図

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

git pull結果 ───▶ 終了コード取得 ───▶ printf (フォアグラウンド)
                       │
                       ▼
                 .zsh-update保存
                       │
                       ▼
            precmdフック ───────▶ print -P (バックグラウンド)
                                     │
                                     ├─ RED: ヘッダ
                                     └─ YELLOW: 詳細
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| upgrade.sh | `tools/upgrade.sh` | ソース | アップデート処理のメイン実装（フォアグラウンドエラー出力） |
| check_for_upgrade.sh | `tools/check_for_upgrade.sh` | ソース | 自動更新チェックとバックグラウンドエラー出力 |
| .zsh-update | `$ZSH_CACHE_DIR/.zsh-update` | データ | 更新状態とエラー情報の永続化 |
