# 機能設計書 112-複数アクションの一括実行

## 概要

複数のアクションを1つのコマンドとして順番に実行する機能（MultipleActions アクション）の設計書である。

### 本機能の処理概要

本機能は、settings.json のキーバインド設定やコマンドパレットにおいて、複数のアクションを1つのショートカットキーやコマンドにまとめて定義し、それらを順次実行する仕組みを提供する。

**業務上の目的・背景**：ユーザーが日常的に連続して行う操作（例：ペインを分割してから特定のコマンドを送信する、複数のタブを一度に開くなど）を1つのキーバインドにまとめることで、操作の効率化とカスタマイズ性を向上させる必要がある。

**機能の利用シーン**：settings.json でキーバインドを設定する際に、`"action": "multipleActions"` と `"actions"` 配列を指定して複数のアクションを1回の操作で実行する場面で使用される。例えば、`split-pane` と `sendInput` を組み合わせて、ペインを分割した直後にコマンドを送信するといった利用方法がある。

**主要な処理内容**：
1. MultipleActionsArgs から actions 配列を取得する
2. actions 配列内の各 ActionAndArgs を順番にイテレートする
3. 各アクションに対して _actionDispatch->DoAction を呼び出して実行する
4. すべてのアクションが完了したら Handled = true に設定する

**関連システム・外部連携**：ActionDispatch（アクションディスパッチャー）を通じて各アクションが実行される。各アクションは個別のハンドラに委譲される。

**権限による制御**：特に権限による制御はない。個々のアクションが権限チェックを行う場合はそちらに従う。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleMultipleActionsにより複数アクションを順番に実行 |
| 10 | CommandPalette（コマンドパレット） | 補助画面 | 選択されたコマンドに含まれる複数アクションを実行 |

## 機能種別

コマンド実行処理（メタアクション）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Actions | IVector<ActionAndArgs> | Yes | 順番に実行するアクションのリスト | null でないこと |

### 入力データソース

- settings.json のキーバインド設定（"action": "multipleActions"）
- コマンドパレットのコマンド定義

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Handled | bool | すべてのアクションが正常にディスパッチされたかどうか |

### 出力先

各アクションの結果に応じた出力先（タブ作成、ペイン操作、テキスト送信等）。

## 処理フロー

### 処理シーケンス

```
1. _HandleMultipleActions が呼び出される
   └─ ActionEventArgs から MultipleActionsArgs を取得
2. MultipleActionsArgs の Actions プロパティを取得
   └─ IVector<ActionAndArgs> 型のアクションリスト
3. actions 配列を順次イテレート
   └─ 各アクションに対して _actionDispatch->DoAction を呼び出す
4. すべてのアクション実行後に Handled = true を設定
   └─ 個々のアクションの成否に関わらず Handled される
```

### フローチャート

```mermaid
flowchart TD
    A[_HandleMultipleActions 呼び出し] --> B{args が null でない?}
    B -->|No| Z[終了（未処理）]
    B -->|Yes| C{MultipleActionsArgs 取得成功?}
    C -->|No| Z
    C -->|Yes| D[Actions 配列を取得]
    D --> E[for each action in Actions]
    E --> F[_actionDispatch->DoAction で実行]
    F --> G{次のアクションあり?}
    G -->|Yes| E
    G -->|No| H[Handled = true]
    H --> I[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-112-01 | 順次実行 | Actions 配列内のアクションは定義順に順次実行される | 常時 |
| BR-112-02 | 個別失敗の影響 | 個々のアクションが失敗しても残りのアクションは実行される | アクション失敗時 |
| BR-112-03 | 空配列 | Actions が空の場合でも Handled = true となる | Actions が空の場合 |

### 計算ロジック

特になし。

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

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

本機能自体はデータベース操作を行わない。個々のサブアクションが行う場合がある。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 型変換エラー | ActionArgs が MultipleActionsArgs にキャストできない場合 | try_as が nullptr を返し、処理をスキップ |
| - | null引数 | args が null の場合 | null チェックにより処理をスキップ |

### リトライ仕様

リトライは行わない。

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

トランザクション管理は不要。各アクションは独立して実行され、全体をロールバックする仕組みはない。

## パフォーマンス要件

各アクションは同期的に DoAction で実行されるため、アクション数に比例した実行時間がかかる。

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

- 個々のアクションのセキュリティポリシーに従う
- 悪意のある設定ファイルにより大量のアクションが定義される可能性があるが、ユーザーが自身で設定ファイルを編集するため、リスクは限定的

## 備考

- MultipleActionsArgs は JSON の `actions` キーから ActionAndArgs の配列としてデシリアライズされる
- ネストした MultipleActions（MultipleActions の中に MultipleActions を含む）も技術的には可能

---

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

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

### 推奨読解順序

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

MultipleActionsArgs のデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ActionArgs.h | `src/cascadia/TerminalSettingsModel/ActionArgs.h` | **969-1014行目**: MultipleActionsArgs の C++ 実装。Actions プロパティ（IVector<ActionAndArgs>）を持つ。FromJson で "actions" キーからデシリアライズ |

**読解のコツ**: MultipleActionsArgs は ACTION_ARGS_STRUCT マクロを使用せず、直接構造体として実装されている。これは Actions プロパティが IVector<ActionAndArgs> という複雑な型であり、マクロでは対応できないためである。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | **1239-1254行目**: _HandleMultipleActions メソッド。非常にシンプルで、Actions のイテレーションと DoAction の呼び出しのみ |

**主要処理フロー**:
1. **1242行目**: args の null チェック
2. **1244行目**: MultipleActionsArgs への try_as キャスト
3. **1246行目**: for ループで各アクションをイテレート
4. **1248行目**: _actionDispatch->DoAction(action) で各アクションを実行
5. **1251行目**: Handled = true に設定

#### Step 3: アクションディスパッチを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ActionArgs.h | `src/cascadia/TerminalSettingsModel/ActionArgs.h` | **988-994行目**: FromJson メソッド。JSON の "actions" キーから ActionAndArgs のリストをデシリアライズする |

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

```
TerminalPage::_HandleMultipleActions (AppActionHandlers.cpp:1239)
    |
    +-- MultipleActionsArgs::try_as (型キャスト)
    |
    +-- for (action : realArgs.Actions())
            |
            +-- _actionDispatch->DoAction(action)
                    |
                    +-- 各アクションハンドラ
                        (例: _HandleNewTab, _HandleSplitPane, _HandleSendInput等)
```

### データフロー図

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

settings.json の               MultipleActionsArgs から            各アクションの結果
"actions" 配列   ───>  FromJson でデシリアライズ ───>  （タブ作成、ペイン分割等）
                              |
                              v
                     _HandleMultipleActions
                     各アクションを順次 DoAction ───> 個別ハンドラへ委譲
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ActionArgs.h | `src/cascadia/TerminalSettingsModel/ActionArgs.h` | ソース | MultipleActionsArgs の定義と JSON シリアライズ |
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleMultipleActions ハンドラの実装 |
| AllShortcutActions.h | `src/cascadia/TerminalSettingsModel/AllShortcutActions.h` | ソース | MultipleActions アクションの登録 |
| ActionMap.cpp | `src/cascadia/TerminalSettingsModel/ActionMap.cpp` | ソース | MultipleActions のリソース名マッピング |
