# 機能設計書 78-終了確認

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける終了確認機能の設計について記載する。この機能は、プロセスが実行中のウィンドウ、タブ、またはスプリットを閉じる際に確認ダイアログを表示し、誤操作によるデータ損失を防止する。

### 本機能の処理概要

**業務上の目的・背景**：
ターミナルでは、長時間実行されるコマンドやインタラクティブなアプリケーションが動作している場合がある。これらのプロセスを誤って終了してしまうと、作業内容の喪失やデータ破損につながる可能性がある。終了確認機能は、サーフェス（ウィンドウ/タブ/スプリット）を閉じる前にユーザーに確認を求めることで、このリスクを軽減する。

**機能の利用シーン**：
- 実行中のコンパイルやビルドプロセスがある状態でウィンドウを閉じようとした場合
- SSH接続中のターミナルを閉じようとした場合
- viやemacsなどのエディタが開いている状態でタブを閉じようとした場合
- 読み取り専用モード中のサーフェス終了時

**主要な処理内容**：
1. サーフェスクローズ要求の受付
2. プロセス実行状態の確認（シェル統合情報を使用）
3. 確認ダイアログの表示判定
4. ユーザー応答に基づくクローズ処理の続行または中断

**関連システム・外部連携**：
- シェル統合（プロセス実行状態の検出）
- プラットフォーム固有のダイアログAPI

**権限による制御**：
- `confirm-close-surface`設定で動作を制御

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | 閉じる確認ダイアログ | 主画面 | アプリ/ウィンドウ/タブ/スプリット閉じる前の確認 |
| 1 | メインターミナルウィンドウ | 参照画面 | 終了確認のトリガー元 |

## 機能種別

確認処理 / ユーザーインターフェース

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| confirm-close-surface | ConfirmCloseSurface | Yes | false/true/always | enum値 |

### 入力データソース

- 設定ファイル（`confirm-close-surface`設定）
- シェル統合からのプロセス状態情報
- 読み取り専用モード状態

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 確認ダイアログ | GUI | ユーザーへの確認ダイアログ |
| 確認結果 | bool | 続行するか中断するか |

### 出力先

- ネイティブダイアログ（macOS / GTK）

## 処理フロー

### 処理シーケンス

```
1. サーフェスクローズ要求受付
   └─ close_surface / close_tab / close_window等
2. 確認必要性チェック
   └─ confirm-close-surface設定値を確認
3. プロセス状態チェック
   └─ シェル統合情報でプロセス実行中か確認
4. 読み取り専用モードチェック
   └─ readonly状態の場合は常に確認
5. ダイアログ表示判定
   └─ 上記条件に基づいて判定
6. 確認ダイアログ表示
   └─ ユーザーに確認を求める
7. ユーザー応答処理
   └─ 続行または中断
```

### フローチャート

```mermaid
flowchart TD
    A[サーフェスクローズ要求] --> B{readonly?}
    B -->|Yes| C[確認ダイアログ表示]
    B -->|No| D{confirm-close-surface?}
    D -->|false| E[即座にクローズ]
    D -->|always| C
    D -->|true| F{プロセス実行中?}
    F -->|Yes| C
    F -->|No| E
    C --> G{ユーザー応答}
    G -->|続行| E
    G -->|キャンセル| H[クローズ中断]
    E --> I[サーフェスクローズ]
    H --> J[終了]
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-78-1 | false設定 | 確認なしで即座にクローズ | confirm-close-surface = false |
| BR-78-2 | true設定 | プロセス実行中のみ確認 | confirm-close-surface = true |
| BR-78-3 | always設定 | 常に確認ダイアログを表示 | confirm-close-surface = always |
| BR-78-4 | readonly優先 | 読み取り専用モードでは設定に関係なく確認 | readonly = true |
| BR-78-5 | child_exited | 子プロセス終了後は確認不要 | child_exited = true |

### 計算ロジック

該当なし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ダイアログ表示失敗 | システムリソース不足等 | クローズを続行（安全側に倒さない） |

### リトライ仕様

リトライは行わない。

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

該当なし

## パフォーマンス要件

- 確認ダイアログはモーダルで即座に表示
- プロセス状態チェックは軽量（シェル統合情報を参照）

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

- 重要な作業中の誤操作防止
- 読み取り専用モードでは常に確認（データ保護観点）

## 備考

- デフォルト値は`true`（プロセス実行中のみ確認）
- シェル統合が無効な場合、プロセス状態は不明として扱われる可能性がある

---

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

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

### 推奨読解順序

#### Step 1: 設定定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Config.zig | `src/config/Config.zig` | confirm-close-surface設定（2475行目） |
| 1-2 | Config.zig | `src/config/Config.zig` | ConfirmCloseSurface enum（5169-5172行目） |

**読解のコツ**: ConfirmCloseSurfaceは`false`/`true`/`always`の3値を持つenum。`c_int`バッキングはC ABI互換のため。

#### Step 2: Surface状態を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Surface.zig | `src/Surface.zig` | DerivedConfig内のconfirm_close_surface（306行目） |
| 2-2 | Surface.zig | `src/Surface.zig` | child_exitedフィールド（142行目） |
| 2-3 | Surface.zig | `src/Surface.zig` | readonlyフィールド（156行目） |

**主要処理フロー**:
- 設定値、プロセス状態、読み取り専用状態を組み合わせて判定

#### Step 3: 画面マッピングを確認

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | 画面機能マッピング.csv | `docs/code-to-docs/画面機能マッピング/` | 閉じる確認ダイアログとの関連 |

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

```
close_surface / close_tab / close_window アクション
    │
    └─ Surface / apprt による処理
           │
           ├─ config.confirm_close_surface チェック
           │
           ├─ child_exited チェック
           │
           ├─ readonly チェック
           │
           └─ 確認ダイアログ表示判定
                  │
                  ├─ [確認不要] → 即座にクローズ
                  │
                  └─ [確認必要] → ダイアログ表示
                         │
                         ├─ [続行] → クローズ
                         └─ [キャンセル] → 中断
```

### データフロー図

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

クローズ要求 ───▶ 確認必要性判定
                        │
設定値 ─────────────────┤
                        │
プロセス状態 ───────────┤
                        │
readonly状態 ───────────┘
                        │
                        ▼
              ┌─────────┴─────────┐
              │                   │
        [確認不要]           [確認必要]
              │                   │
              ▼                   ▼
         即座にクローズ     確認ダイアログ
                                  │
                          ┌───────┴───────┐
                          │               │
                       [続行]         [キャンセル]
                          │               │
                          ▼               ▼
                      クローズ          中断
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Config.zig | `src/config/Config.zig` | ソース | confirm-close-surface設定定義 |
| Surface.zig | `src/Surface.zig` | ソース | DerivedConfig、状態フィールド |
| config.zig | `src/config.zig` | ソース | ConfirmCloseSurface re-export |
| Binding.zig | `src/input/Binding.zig` | ソース | close_surface等アクション |
