# 機能設計書 116-作業ディレクトリを開く

## 概要

ファイルエクスプローラーで現在の作業ディレクトリを開く機能（OpenCWD アクション）の設計書である。

### 本機能の処理概要

本機能は、アクティブなターミナルセッションの現在の作業ディレクトリ（CWD）を Windows ファイルエクスプローラーで開く。シェル統合機能によって追跡されている作業ディレクトリ情報を使用する。

**業務上の目的・背景**：ターミナルで作業中のディレクトリに格納されたファイルをGUIで操作したい場面が頻繁にある。ターミナルから直接ファイルエクスプローラーを開くことで、コマンドラインとGUIの両方のワークフローをシームレスに切り替えることができる。

**機能の利用シーン**：ターミナルでの作業中に、作業ディレクトリ内のファイルをファイルエクスプローラーで確認・操作したい場合に使用される。キーバインドやコマンドパレットから実行する。

**主要な処理内容**：
1. アクティブなターミナルコントロールを取得する
2. TermControl の OpenCWD メソッドを呼び出す
3. ControlCore の OpenCWD で WorkingDirectory を取得する
4. ShellExecute で explorer を起動し、作業ディレクトリを開く

**関連システム・外部連携**：Windows ShellExecute API を使用して explorer.exe を起動する。シェル統合機能で追跡された作業ディレクトリ情報を読み取る。

**権限による制御**：特に権限による制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleOpenCWDによりファイルエクスプローラーで作業ディレクトリを開く |
| 20 | CouldNotOpenUriDialog（URI エラー） | 補助画面 | URIを開けなかった場合のエラー表示 |

## 機能種別

外部アプリケーション起動処理

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- アクティブターミナルセッションの作業ディレクトリ情報（シェル統合経由）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| explorer.exe 起動 | プロセス | 作業ディレクトリを開いた状態の Windows ファイルエクスプローラー |

### 出力先

Windows ファイルエクスプローラー（外部プロセス）。

## 処理フロー

### 処理シーケンス

```
1. _HandleOpenCWD が呼び出される
   └─ アクティブなターミナルコントロールを取得
2. TermControl::OpenCWD を呼び出す
   └─ ControlCore::OpenCWD に委譲
3. ControlCore で WorkingDirectory を取得
   └─ シェル統合で追跡された作業ディレクトリ
4. ShellExecute で explorer を起動
   └─ ShellExecute(nullptr, nullptr, L"explorer", workingDirectory.c_str(), nullptr, SW_SHOW)
5. Handled = true に設定
```

### フローチャート

```mermaid
flowchart TD
    A[_HandleOpenCWD] --> B{アクティブコントロール取得成功?}
    B -->|No| Z[終了（未処理）]
    B -->|Yes| C[control.OpenCWD 呼び出し]
    C --> D[ControlCore::OpenCWD]
    D --> E[WorkingDirectory 取得]
    E --> F[ShellExecute で explorer 起動]
    F --> G[Handled = true]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-116-01 | アクティブコントロール必須 | アクティブなターミナルコントロールが存在する場合のみ動作する | 常時 |
| BR-116-02 | explorer使用 | ShellExecute を使用して Windows ファイルエクスプローラーを起動する | 常時 |

### 計算ロジック

特になし。

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コントロール不在 | アクティブなターミナルコントロールが存在しない場合 | 処理をスキップ |
| - | 作業ディレクトリ未設定 | シェル統合が動作していない場合 | WorkingDirectory が空の文字列になる可能性がある |

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

ShellExecute はOSに委譲されるため、ターミナル側の応答性には影響しない。

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

- ShellExecute を使用して外部プロセスを起動するが、explorer のみが対象
- 作業ディレクトリはシェルプロセスから報告された値をそのまま使用する

## 備考

- 作業ディレクトリの追跡にはシェル統合（OSCシーケンス）が正しく設定されている必要がある
- シェル統合が未設定の場合、WorkingDirectory は空または初期ディレクトリとなる可能性がある

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | **1137-1145行目**: _HandleOpenCWD。アクティブコントロールを取得して OpenCWD を呼び出す |

**主要処理フロー**:
1. **1140行目**: _GetActiveControl() でアクティブコントロール取得
2. **1142行目**: control.OpenCWD() 呼び出し
3. **1143行目**: Handled = true

#### Step 2: TermControl の委譲処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | **2614-2617行目**: TermControl::OpenCWD。_core.OpenCWD() に委譲するだけの薄いラッパー |

#### Step 3: 実際の処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | **1682-1686行目**: ControlCore::OpenCWD。WorkingDirectory() を取得し、ShellExecute で explorer を起動する |

**主要処理フロー**:
- **1684行目**: WorkingDirectory() で作業ディレクトリを取得
- **1685行目**: ShellExecute(nullptr, nullptr, L"explorer", workingDirectory.c_str(), nullptr, SW_SHOW)

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

```
TerminalPage::_HandleOpenCWD (AppActionHandlers.cpp:1137)
    |
    +-- _GetActiveControl() (アクティブコントロール取得)
    |
    +-- TermControl::OpenCWD (TermControl.cpp:2614)
            |
            +-- ControlCore::OpenCWD (ControlCore.cpp:1682)
                    |
                    +-- ControlCore::WorkingDirectory() (CWD取得)
                    |
                    +-- ShellExecute (explorer起動)
```

### データフロー図

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

シェル統合で追跡された    ControlCore::WorkingDirectory    ShellExecute
作業ディレクトリ ──────>  で CWD を取得 ──────────────>  explorer.exe 起動
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleOpenCWD ハンドラ |
| TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | ソース | TermControl::OpenCWD（ControlCore への委譲） |
| ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | ソース | ControlCore::OpenCWD（実際の ShellExecute 呼び出し） |
