# 通知設計書 6-アップデート確認リマインダー

## 概要

本ドキュメントは、Oh My Zshのアップデート確認機能におけるリマインダー通知について、その設計仕様を定義するものである。

### 本通知の処理概要

Oh My Zshは、定期的に更新の確認を行い、更新が利用可能な場合にユーザーにリマインダーメッセージを表示する機能を提供する。この通知は、更新モードが「reminder」に設定されている場合、またはユーザーが入力中の場合に表示される。

**業務上の目的・背景**：Oh My Zshはオープンソースプロジェクトとして継続的に改善されており、新機能追加やバグ修正が定期的に行われている。しかし、自動更新は予期しない変更をもたらす可能性があるため、一部のユーザーは手動更新を好む。リマインダー通知は、自動更新を望まないユーザーに対して、更新の存在を知らせつつ、更新タイミングを自分でコントロールできるようにする。

**通知の送信タイミング**：シェル起動時にhandle_update関数が実行され、以下の条件を満たす場合にリマインダーが表示される：(1) 前回の更新確認から指定日数（デフォルト13日）が経過、(2) 更新が利用可能、(3) 更新モードが「reminder」、またはユーザーが既に入力を開始している。

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

**通知内容の概要**：「[oh-my-zsh] It's time to update! You can do that by running `omz update`」というメッセージがターミナルに表示される。

**期待されるアクション**：受信者は都合の良いタイミングで `omz update` コマンドを実行してOh My Zshを更新する。

## 通知種別

ターミナルテキスト出力

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| プレフィックス | `[oh-my-zsh]` |
| メッセージ | `It's time to update! You can do that by running \`omz update\`` |

### 本文テンプレート

```
[oh-my-zsh] It's time to update! You can do that by running `omz update`
```

### 添付ファイル

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

## テンプレート変数

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

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| シェル起動 | handle_update関数実行 | update_mode=reminder または has_typed_input=true | 更新利用可能時にリマインダー表示 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| update_mode=disabled | 自動更新が無効化されている場合 |
| 更新確認間隔未満 | 前回確認から指定日数が経過していない場合 |
| 更新なし | リモートとローカルのHEADが一致する場合 |
| update_mode=auto/background-alpha | 自動更新モードの場合（リマインダーではなく自動更新） |
| update_mode=prompt かつ 入力なし | 確認プロンプト表示に遷移 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[シェル起動] --> B[handle_update呼び出し]
    B --> C{更新確認間隔経過?}
    C -->|No| D[終了]
    C -->|Yes| E{更新利用可能?}
    E -->|No| F[LAST_EPOCH更新]
    F --> D
    E -->|Yes| G{update_mode=reminder OR 入力あり?}
    G -->|Yes| H[リマインダー表示]
    G -->|No| I{update_mode=auto/background?}
    I -->|Yes| J[自動更新実行]
    I -->|No| K[確認プロンプト表示]
    H --> D
    J --> D
    K --> D
```

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

### 参照テーブル一覧

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

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

### 参照ファイル一覧

| ファイル | パス | 用途 |
|---------|------|------|
| .zsh-update | `$ZSH_CACHE_DIR/.zsh-update` | 最終更新確認日時（LAST_EPOCH）を保存 |

### シェル変数・zstyle一覧

| 設定名 | 用途 | デフォルト値 |
|--------|------|-------------|
| :omz:update mode | 更新モード | prompt |
| :omz:update frequency | 更新確認間隔（日数） | 13 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| Git未インストール | gitコマンドが存在しない | 更新確認をスキップ |
| ネットワークエラー | GitHubへの接続失敗 | 更新確認をスキップ（次回起動時に再試行） |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし、次回起動時に再試行） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 表示頻度 | 更新確認間隔（デフォルト13日）ごとに1回 |

### 配信時間帯

制限なし（シェル起動時）

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

- メッセージは固定文字列であり、機密情報は含まれない
- ローカル出力のみであり、ネットワーク経由での送信は行われない
- 更新確認自体はGitHub APIへのHTTPSリクエストを行う

## 備考

- 更新モードはzstyle ':omz:update' modeで設定可能（prompt/auto/reminder/background-alpha/disabled）
- 古い設定方式（DISABLE_UPDATE_PROMPT/DISABLE_AUTO_UPDATE）もサポートされている
- リマインダー表示前にカーソル位置がリセットされる（printf '\r\e[0K'）

---

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

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

### 推奨読解順序

#### Step 1: 更新モード設定を理解する

更新モードの取得方法と種類を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | 14-20行目のzstyleによる更新モード取得を確認 |

**読解のコツ**: zstyle -s で設定値を変数に読み込む。設定がない場合はデフォルト値が使用される。

#### Step 2: 更新確認ロジックを理解する

handle_update関数の全体フローを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | 161-247行目のhandle_update関数で更新確認の全体フローを理解 |

**主要処理フロー**:
- **196-199行目**: .zsh-updateファイルの読み込みとLAST_EPOCHチェック
- **202-206行目**: 更新間隔のチェック
- **214-218行目**: is_update_available関数で更新確認
- **221-225行目**: リマインダーモードまたは入力中の場合のリマインダー表示

#### Step 3: リマインダー表示処理を理解する

リマインダーメッセージの出力処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | 221-225行目のリマインダー表示条件と出力を確認 |

**主要処理フロー**:
- **221行目**: `[[ "$update_mode" = reminder ]] || { [[ "$update_mode" != background-alpha ]] && has_typed_input }` - 表示条件
- **222行目**: `printf '\r\e[0K'` - カーソル位置リセットと行クリア
- **223行目**: `echo "[oh-my-zsh] It's time to update! ..."` - リマインダーメッセージ表示

#### Step 4: 入力検出を理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | check_for_upgrade.sh | `tools/check_for_upgrade.sh` | 136-159行目のhas_typed_input関数でユーザー入力検出方法を理解 |

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

```
[シェル起動]
    │
    ├─ check_for_upgrade.sh 読み込み
    │      │
    │      └─ handle_update 呼び出し (300-302行目)
    │             │
    │             ├─ .zsh-update ファイル読み込み
    │             │
    │             ├─ 更新間隔チェック
    │             │
    │             ├─ is_update_available
    │             │      └─ GitHub API で最新コミット確認
    │             │
    │             └─ [update_mode=reminder OR has_typed_input?]
    │                    │
    │                    ├─ Yes ──▶ printf '\r\e[0K'
    │                    │          echo "[oh-my-zsh] It's time to update!..."
    │                    │
    │                    └─ No ──▶ 他のモードへ分岐
    │
    └─ シェルプロンプト表示
```

### データフロー図

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

$ZSH_CACHE_DIR/.zsh-update ─▶ handle_update
(LAST_EPOCH)                       │
                                   │
zstyle :omz:update mode ──────────▶├─ 更新モード判定
                                   │
zstyle :omz:update frequency ─────▶├─ 間隔チェック
                                   │
GitHub API ───────────────────────▶├─ is_update_available
                                   │
stdin (has_typed_input) ──────────▶├─ 入力検出
                                   │
                                   └─ リマインダー表示 ──▶ stdout
                                                          │
                                                          ▼
                                                    "[oh-my-zsh] It's time..."
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| check_for_upgrade.sh | `tools/check_for_upgrade.sh` | ソース | 更新確認とリマインダー表示のメインロジック |
| .zsh-update | `$ZSH_CACHE_DIR/.zsh-update` | データ | 最終更新確認日時を保存 |
