# 機能設計書 118-デバッガーへのブレーク

## 概要

デバッグビルド時にデバッガーにブレークインする機能（BreakIntoDebugger アクション）の設計書である。

### 本機能の処理概要

本機能は、Windows Terminal のデバッグビルドにおいて、キーバインドやコマンドパレットから意図的にデバッガーにブレークインするための開発者向け機能である。DebugBreak() Win32 API を呼び出してデバッガーを起動または接続中のデバッガーで停止する。

**業務上の目的・背景**：Windows Terminal の開発・デバッグ時に、特定のタイミングでデバッガーを起動してメモリやスタックの状態を調査する必要がある。キーバインドからデバッガーにブレークインできることで、任意のタイミングでの調査が容易になる。

**機能の利用シーン**：Windows Terminal の開発中に、特定の状態を再現した後にデバッガーで調査したい場合に使用される。DebugFeaturesEnabled が有効な場合のみ動作する、完全な開発者向け機能である。

**主要な処理内容**：
1. DebugFeaturesEnabled の設定値を確認する
2. Handled = true に設定する
3. Win32 API の DebugBreak() を呼び出す

**関連システム・外部連携**：Win32 API の DebugBreak() を使用する。Visual Studio 等のデバッガーとの連携。

**権限による制御**：DebugFeaturesEnabled 設定が true の場合のみ動作する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleBreakIntoDebuggerによりデバッガーにブレークイン |

## 機能種別

デバッグ処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| （パラメータなし） | - | - | 本アクションはパラメータを取らない | - |

### 入力データソース

- GlobalSettings の DebugFeaturesEnabled 設定値

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| デバッガーブレーク | - | デバッガーの停止 |

### 出力先

接続中のデバッガー（Visual Studio 等）。デバッガーが接続されていない場合はOSの例外ハンドラが起動する。

## 処理フロー

### 処理シーケンス

```
1. _HandleBreakIntoDebugger が呼び出される
   └─ DebugFeaturesEnabled の確認
2. Handled = true に設定
3. DebugBreak() を呼び出す
   └─ デバッガーにブレークイン
```

### フローチャート

```mermaid
flowchart TD
    A[_HandleBreakIntoDebugger] --> B{DebugFeaturesEnabled?}
    B -->|No| Z[終了（未処理）]
    B -->|Yes| C[Handled = true]
    C --> D[DebugBreak 呼び出し]
    D --> E[デバッガーで停止]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-118-01 | デバッグ制限 | DebugFeaturesEnabled が true の場合のみ動作する | 常時 |
| BR-118-02 | 即座に停止 | DebugBreak() の呼び出しによりプロセスが即座に停止する | デバッガー接続時 |

### 計算ロジック

特になし。

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

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | デバッガー未接続 | デバッガーが接続されていない状態で DebugBreak が呼ばれた場合 | OSの例外ハンドラが起動する（Windows Error Reporting 等） |

### リトライ仕様

リトライは行わない。

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

トランザクション管理は不要。

## パフォーマンス要件

即座にデバッガーにブレークインする。

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

- DebugFeaturesEnabled によるアクセス制御が行われている
- 本番環境では使用されない開発者向け機能
- DebugBreak はプロセスの実行を停止させるため、不正利用のリスクは DebugFeaturesEnabled で制御

## 備考

- 非常にシンプルな実装（3行のコード）
- デバッガーが接続されていない場合、アプリケーションがクラッシュする可能性がある

---

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

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

### 推奨読解順序

#### Step 1: エントリーポイント（唯一の処理）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | **865-873行目**: _HandleBreakIntoDebugger メソッド。DebugFeaturesEnabled チェック後に DebugBreak() を呼び出す。非常にシンプルな実装 |

**主要処理フロー**:
1. **868行目**: _settings.GlobalSettings().DebugFeaturesEnabled() チェック
2. **870行目**: Handled = true に設定
3. **871行目**: DebugBreak() 呼び出し

**読解のコツ**: DebugBreak() は Win32 API で、現在のプロセスにブレークポイント例外を発生させる。デバッガーが接続されている場合はそのデバッガーが制御を取得し、接続されていない場合はOSの例外ハンドラが起動する。

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

```
TerminalPage::_HandleBreakIntoDebugger (AppActionHandlers.cpp:865)
    |
    +-- GlobalSettings().DebugFeaturesEnabled() (チェック)
    |
    +-- DebugBreak() (Win32 API)
```

### データフロー図

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

キーバインド/         DebugFeaturesEnabled     DebugBreak()
コマンドパレット ──>  チェック ──────────────>  デバッガー停止
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleBreakIntoDebugger ハンドラ |
| AllShortcutActions.h | `src/cascadia/TerminalSettingsModel/AllShortcutActions.h` | ソース | BreakIntoDebugger アクション登録 |
