# 機能設計書 75-クイックフィックス

## 概要

本ドキュメントは、Windows Terminalにおけるクイックフィックス機能の設計を記述する。シェル統合と連携し、コマンド実行エラー時に修正候補を自動的に検出・表示する機能である。

### 本機能の処理概要

クイックフィックス機能は、シェル統合を通じてコマンドの実行失敗を検出し、修正候補（例: wingetによるパッケージインストール提案）を自動的に生成・キャッシュする。ユーザーはSuggestionsControl経由でこれらの修正候補にアクセスし、ワンクリックで修正コマンドを実行できる。

**業務上の目的・背景**：コマンド実行エラー時に、ユーザーが手動で修正方法を検索する手間を省く。特に「コマンドが見つからない」エラーに対して、wingetパッケージマネージャーを使用したインストールコマンドを自動提案することで、開発環境セットアップの効率化を図る。

**機能の利用シーン**：未インストールのコマンドを実行してエラーになった場合、コマンドのスペルミスを修正したい場合に利用される。Feature_QuickFixフィーチャーフラグにより制御される実験的機能である。

**主要な処理内容**：
1. シェル統合によるコマンド実行エラーの検出
2. SearchMissingCommandコールバックによるパッケージ検索
3. 検出された修正候補のキャッシュ（_cachedQuickFixes）
4. RefreshQuickFixUIイベントによるUI更新通知
5. SuggestionsControlでのクイックフィックス候補表示

**関連システム・外部連携**：シェル統合（OSCシーケンス）、wingetパッケージマネージャーとの連携。

**権限による制御**：Feature_QuickFixフィーチャーフラグにより有効/無効が制御される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | SuggestionsControl（サジェスト） | 主画面 | シェル統合と連携しエラー修正候補を表示 |
| 6 | TermControl（ターミナル表示） | 関連画面 | QuickFixesAvailable状態の管理 |

## 機能種別

自動検出 / コマンド提案

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| missingCommand | hstring | Yes | 見つからなかったコマンド名（シェル統合から自動取得） | 空文字でないこと |
| bufferRow | int | Yes | コマンドが実行されたバッファ行番号 | 有効な行番号であること |

### 入力データソース

シェル統合（OSCシーケンス）によるコマンド実行結果のフィードバック。Terminalコアの SetSearchMissingCommandCallback。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| _cachedQuickFixes | IVector<hstring> | キャッシュされた修正候補コマンド一覧 |
| QuickFixesAvailable | bool | クイックフィックスが利用可能かどうか |
| RefreshQuickFixUI | イベント | UI更新通知イベント |

### 出力先

ControlCore の _cachedQuickFixes キャッシュ、SuggestionsControl UI

## 処理フロー

### 処理シーケンス

```
1. コマンド実行エラー検出
   └─ シェル統合がOSCシーケンスでエラーを通知
2. SetSearchMissingCommandCallback 呼び出し
   └─ Terminal コアからControlCoreへコールバック
3. SearchMissingCommand イベント発行
   └─ ControlCore._terminalSearchMissingCommand
4. パッケージ検索の実行
   └─ 見つからなかったコマンドに対する修正候補の検索
5. UpdateQuickFixes によるキャッシュ更新
   └─ _cachedQuickFixes にコマンド一覧を保存
6. RefreshQuickFixUI イベント発行
   └─ UIに更新を通知
7. ClearQuickFix によるキャッシュクリア
   └─ 新しいコマンド実行時にキャッシュをクリア
```

### フローチャート

```mermaid
flowchart TD
    A[コマンド実行エラー] --> B[OSCシーケンスで通知]
    B --> C[SetSearchMissingCommandCallback]
    C --> D[SearchMissingCommand イベント]
    D --> E[修正候補の検索]
    E --> F{候補が見つかった?}
    F -->|Yes| G[UpdateQuickFixes でキャッシュ]
    F -->|No| H[何もしない]
    G --> I[RefreshQuickFixUI イベント]
    I --> J[SuggestionsControl に表示可能]
    J --> K{ユーザーがSuggestions呼び出し?}
    K -->|Yes| L[QuickFixesソースから候補取得]
    K -->|No| M[待機]
    L --> N[コマンド実行]
    N --> O[ClearQuickFix でキャッシュクリア]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-75-01 | フィーチャーフラグ制御 | Feature_QuickFixが有効な場合のみ動作 | features.xml の Feature_QuickFix |
| BR-75-02 | キャッシュクリア | 新しいコマンド実行時に前回のクイックフィックスキャッシュをクリア | ClearQuickFix コールバック |
| BR-75-03 | wingetテレメトリ | wingetコマンドが提案・使用された場合にテレメトリを送信 | QuickFixSuggestionUsed |
| BR-75-04 | QuickFixes利用可能判定 | _cachedQuickFixes が null でなく、Size > 0 の場合に利用可能 | QuickFixesAvailable() |

### 計算ロジック

特になし。

## データベース操作仕様

### 操作別データベース影響一覧

本機能にデータベース操作はない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パッケージ検索失敗 | ネットワークエラーやwinget未インストール | 候補なしとして処理（キャッシュは空のまま） |
| - | キャッシュnull | QuickFixesが一度も設定されていない場合 | QuickFixesAvailable()がfalseを返す |

### リトライ仕様

リトライは不要。次回のコマンドエラー時に再検索される。

## トランザクション仕様

本機能にトランザクション処理はない。

## パフォーマンス要件

パッケージ検索はバックグラウンドで非同期実行される。検索結果のキャッシュにより、同一コマンドに対する再検索を回避する。

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

クイックフィックスが提案するコマンドは自動実行されない。ユーザーの明示的な選択が必要。

## 備考

- クイックフィックスはSuggestions機能（No.74）のQuickFixesソースとして統合されている
- wingetコマンドの提案利用時にはテレメトリが送信される（QuickFixSuggestionUsed）
- Feature_QuickFix フィーチャーフラグで制御される実験的機能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ControlCore.h | `src/cascadia/TerminalControl/ControlCore.h` | _cachedQuickFixesメンバー、QuickFixesAvailable()、UpdateQuickFixes()、ClearQuickFix() |
| 1-2 | ControlCore.idl | `src/cascadia/TerminalControl/ControlCore.idl` | SearchMissingCommandイベント、RefreshQuickFixUIイベント定義 |

**読解のコツ**: QuickFixesのキャッシュ管理は ControlCore 内で行われ、外部からは UpdateQuickFixes/ClearQuickFix で操作する。CommandHistoryContext.QuickFixes で候補を取得できる。

#### Step 2: コールバック登録を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | コールバック登録（133-137行目）: SetSearchMissingCommandCallback, SetClearQuickFixCallback |

**主要処理フロー**:
1. **133-134行目**: pfnSearchMissingCommand コールバック登録
2. **136-137行目**: pfnClearQuickFix コールバック登録
3. **1688-1692行目**: ClearQuickFix() - キャッシュクリアとUI更新イベント発行
4. **2419-2427行目**: QuickFixesAvailable(), UpdateQuickFixes() - キャッシュ管理

#### Step 3: Suggestions統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | CommandHistory()内でのQuickFixes取得（2410行目） |
| 3-2 | SuggestionsControl.cpp | `src/cascadia/TerminalApp/SuggestionsControl.cpp` | QuickFixSuggestionUsedテレメトリ（736-745行目） |

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

```
Terminal::SetSearchMissingCommandCallback
    │
    └─ ControlCore::_terminalSearchMissingCommand (ControlCore.cpp:1679)
           │
           └─ SearchMissingCommand イベント
                  │
                  └─ [上位層] UpdateQuickFixes(quickFixes)
                         │
                         └─ _cachedQuickFixes = quickFixes (ControlCore.cpp:2426)

Terminal::SetClearQuickFixCallback
    │
    └─ ControlCore::ClearQuickFix (ControlCore.cpp:1688)
           │
           ├─ _cachedQuickFixes = nullptr
           └─ RefreshQuickFixUI イベント

ControlCore::CommandHistory (ControlCore.cpp:2400付近)
    │
    └─ context->QuickFixes(_cachedQuickFixes) (ControlCore.cpp:2410)
```

### データフロー図

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

コマンド実行エラー ──────▶ Terminal コア
(OSCシーケンス)              │
                             ▼
                     SearchMissingCommand
                             │
                             ▼
パッケージ検索結果 ──────▶ UpdateQuickFixes ──────▶ _cachedQuickFixes
                                                        │
                                                        ▼
Suggestionsアクション ──▶ CommandHistory() ──────▶ QuickFixes候補
                             │
                             ▼
                       SuggestionsControl ──────▶ UI表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | ソース | QuickFixesキャッシュ管理、コールバック登録 |
| ControlCore.h | `src/cascadia/TerminalControl/ControlCore.h` | ヘッダー | _cachedQuickFixes宣言 |
| ControlCore.idl | `src/cascadia/TerminalControl/ControlCore.idl` | IDL | SearchMissingCommand、RefreshQuickFixUIイベント定義 |
| SuggestionsControl.cpp | `src/cascadia/TerminalApp/SuggestionsControl.cpp` | ソース | QuickFix候補の表示とテレメトリ |
| Terminal.hpp | `src/cascadia/TerminalCore/Terminal.hpp` | ヘッダー | SetSearchMissingCommandCallback定義 |
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | Suggestionsアクション内でのQuickFixes取得 |
