# 通知設計書 59-RefreshQuickFixUI

## 概要

本ドキュメントは、Windows Terminal における RefreshQuickFixUI イベント通知の設計仕様を記述する。クイックフィックス（Quick Fix）UIの更新が必要な際に ControlCore から発火し、TermControl のクイックフィックスメニューの表示/非表示を更新するためのアクション通知である。

### 本通知の処理概要

RefreshQuickFixUI は、クイックフィックスのキャッシュがクリアされた際に ControlCore から発火するイベントである。TermControl はこのイベントを受信して RefreshQuickFixMenu メソッドを呼び出し、クイックフィックスボタンの表示/非表示とメニュー内容を更新する。クイックフィックスはターミナル出力に含まれるエラーメッセージやコマンドの修正候補を提示する機能である。

**業務上の目的・背景**：ターミナルでコマンド実行時にエラーが発生した場合、クイックフィックス機能はエラーに対する修正候補をユーザーに提示する。RefreshQuickFixUI イベントは、クイックフィックスの状態が変化した際（候補がクリアされた場合等）にUIを最新の状態に同期させるための仕組みである。Feature_QuickFix フィーチャーフラグにより機能全体が制御される。

**通知の送信タイミング**：ControlCore::ClearQuickFix メソッドが呼び出された際に発火する。このメソッドはキャッシュされたクイックフィックス候補をクリアし、その後 RefreshQuickFixUI イベントを発火する。

**通知の受信者**：TermControl が ControlCore の RefreshQuickFixUI イベントをラムダ式で受信し、RefreshQuickFixMenu メソッドを呼び出す。

**通知内容の概要**：引数なし（nullptr）のシンプルなイベント通知。クイックフィックスUIの更新が必要であることのみを伝達する。

**期待されるアクション**：TermControl::RefreshQuickFixMenu が呼び出され、QuickFixesAvailable プロパティに基づいてクイックフィックスボタンの表示/非表示が更新される。また、スクロール位置の変更やフォントサイズの変更時にも RefreshQuickFixMenu が直接呼び出される。

## 通知種別

アプリ内イベント通知（WinRT TypedEventHandler）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（バックグラウンドスレッドから呼ばれ得る） |
| 優先度 | 低 |
| リトライ | 無 |

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

TermControl が ControlCore の RefreshQuickFixUI イベントにラムダ式ハンドラを登録（TermControl.cpp L336-338）。

## 通知テンプレート

### イベント引数

| 項目 | 内容 |
|-----|------|
| イベント型 | `TypedEventHandler<Object, Object>` |
| 定義元 | `ControlCore.idl` L200 |
| プロパティ | なし（sender, nullptr） |

### イベントデータ構造

```cpp
// ControlCore.idl
event Windows.Foundation.TypedEventHandler<Object, Object> RefreshQuickFixUI;
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| （なし） | イベント引数を持たない | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | ControlCore::ClearQuickFix | メソッド呼び出し時 | ControlCore.cpp L1688-1692: キャッシュクリア後にイベント発火 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| Feature_QuickFix 無効 | RefreshQuickFixMenu 内で Feature_QuickFix::IsEnabled() をチェックし、無効の場合は処理をスキップ |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ClearQuickFix 呼び出し] --> B[_cachedQuickFixes = nullptr]
    B --> C[RefreshQuickFixUI.raise]
    C --> D[TermControl: ラムダ式ハンドラ]
    D --> E[RefreshQuickFixMenu]
    E --> F{Feature_QuickFix 有効?}
    F -->|有効| G{QuickFixesAvailable?}
    F -->|無効| H[return]
    G -->|利用可能| I[QuickFixButton 表示]
    G -->|利用不可| J[QuickFixButton 非表示]
    I --> K[ボタン位置更新]
```

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

### 参照テーブル一覧

該当なし（データベースは使用しない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| UI要素未初期化 | TermControl の XAML 要素が未ロード | QuickFixButton() の null チェック |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし

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

- クイックフィックスの候補はターミナル出力の解析から生成されるため、悪意ある出力による偽の修正候補の提示リスクがある
- Feature_QuickFix フィーチャーフラグにより機能全体を無効化できる

## 備考

- RefreshQuickFixUI イベントは ControlCore.idl のコメントで「These events are called from some background thread」に分類されている（L190）
- RefreshQuickFixMenu は RefreshQuickFixUI イベント経由以外にも、以下の場面で直接呼び出される：
  - UpdateControlSettings 後（TermControl.cpp L999）
  - スクロール位置変更時（TermControl.cpp L2511）
  - フォントサイズ変更時（TermControl.cpp L3639）
- QuickFixButton は XAML で定義されたボタン要素であり、クイックフィックス候補が存在する場合のみ表示される
- TermControl.idl L165 に RefreshQuickFixMenu と ClearQuickFix が公開メソッドとして宣言されている

---

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

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

### 推奨読解順序

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

RefreshQuickFixUI は引数なしのイベント。関連するデータ構造として CommandHistoryContext を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ControlCore.idl | `src/cascadia/TerminalControl/ControlCore.idl` | L80-85: CommandHistoryContext。QuickFixes プロパティを含む |
| 1-2 | ControlCore.idl | `src/cascadia/TerminalControl/ControlCore.idl` | L174: QuickFixesAvailable プロパティ |
| 1-3 | ControlCore.idl | `src/cascadia/TerminalControl/ControlCore.idl` | L200: RefreshQuickFixUI イベント宣言 |

**読解のコツ**: QuickFix 機能は Feature_QuickFix フィーチャーフラグにより制御される。IsEnabled() チェックが各所に存在する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | L1688-1692: ClearQuickFix メソッド。_cachedQuickFixes をクリアし RefreshQuickFixUI.raise を呼ぶ |

**主要処理フロー**:
1. **L1690**: `_cachedQuickFixes = nullptr` でキャッシュクリア
2. **L1691**: `RefreshQuickFixUI.raise(*this, nullptr)` でイベント発火

#### Step 3: 受信・UI更新層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | L336-338: RefreshQuickFixUI ハンドラ登録（ラムダ式で RefreshQuickFixMenu を呼び出す） |
| 3-2 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | L3987-3997: RefreshQuickFixMenu の実装。Feature_QuickFix チェック、QuickFixesAvailable チェック、ボタン表示/非表示 |

**主要処理フロー**:
- **L3989-3991**: `Feature_QuickFix::IsEnabled()` チェック
- **L3995-3997**: `_core.QuickFixesAvailable()` で候補有無チェック、ボタン Visibility 設定

#### Step 4: その他の呼び出し箇所を把握する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | L999: UpdateControlSettings 後の呼び出し |
| 4-2 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | L2511: スクロール位置変更時の呼び出し |
| 4-3 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | L3639: フォントサイズ変更時の呼び出し |

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

```
ControlCore::ClearQuickFix
    |
    +-- _cachedQuickFixes = nullptr
    +-- RefreshQuickFixUI.raise(*this, nullptr)
            |
            v
TermControl (ラムダハンドラ)
    |
    +-- RefreshQuickFixMenu()
            |
            +-- Feature_QuickFix::IsEnabled() チェック
            +-- _core.QuickFixesAvailable() チェック
            +-- QuickFixButton().Visibility 設定
            +-- ボタン位置更新

--- 直接呼び出し ---

TermControl::UpdateControlSettings --> RefreshQuickFixMenu()
TermControl (スクロール変更) --> RefreshQuickFixMenu()
TermControl (フォントサイズ変更) --> RefreshQuickFixMenu()
```

### データフロー図

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

ClearQuickFix呼び出し -> ControlCore                  QuickFixButton
                         (キャッシュクリア)            表示/非表示更新
                              |
                              v
                         RefreshQuickFixUI.raise
                              |
                              v
                         TermControl
                         ::RefreshQuickFixMenu
                              |
                              v
                         QuickFixButton.Visibility
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ControlCore.idl | `src/cascadia/TerminalControl/ControlCore.idl` | IDL定義 | RefreshQuickFixUI イベント宣言 |
| ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | ソース | ClearQuickFix / イベント発火 |
| ControlCore.h | `src/cascadia/TerminalControl/ControlCore.h` | ヘッダ | ControlCore クラス宣言 |
| TermControl.idl | `src/cascadia/TerminalControl/TermControl.idl` | IDL定義 | RefreshQuickFixMenu / ClearQuickFix 公開メソッド |
| TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | ソース | イベント受信・UI更新処理 |
| TermControl.h | `src/cascadia/TerminalControl/TermControl.h` | ヘッダ | TermControl クラス宣言 |
