# 機能設計書 23-タスク実行

## 概要

本ドキュメントは、Giselleシステムにおける「タスク実行」機能の設計仕様を定義する。この機能は、作成されたタスクを最後まで実行し、各シーケンスとステップを順次/並列に処理するコア実行エンジンである。

### 本機能の処理概要

**業務上の目的・背景**：ワークフローの実行において、タスク内の複数のシーケンス（処理ブロック）とステップ（個別ノード処理）を適切な順序で実行し、各ノードの出力を次のノードへ伝播させる必要がある。この機能は、依存関係を考慮した実行順序制御、並列処理による効率化、エラー時の適切なハンドリングを提供する。

**機能の利用シーン**：
- startTask関数から呼び出され、タスク全体を実行する場合
- createAndStartTask関数から呼び出され、作成直後のタスクを実行する場合
- 外部プロセス（QStash等）からタスク実行を再開する場合

**主要な処理内容**：
1. タスクデータを取得し、パッチキューを初期化する
2. executeTask関数でタスクの実行を制御する
3. 各シーケンスを定義順に実行する
4. シーケンス内のステップを並列実行する
5. 各ステップでノードタイプに応じた生成処理を実行する
6. 実行結果をパッチ操作でタスクに反映する
7. コールバックで実行状況を通知する

**関連システム・外部連携**：
- Storage: タスクと生成データの永続化
- AI Provider APIs: テキスト生成、画像生成
- GitHub API: アクション実行
- Vector Store: クエリ実行

**権限による制御**：
- タスク実行は作成されたタスクに対してのみ可能
- 外部連携時は各サービスの認証情報が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主画面 | Runボタン押下後のタスク実行 |
| 18 | プレイグラウンド画面 | 主画面 | アプリ実行テストでのタスク実行 |
| 20 | タスク詳細画面 | 結果表示画面 | タスク実行結果の表示 |

## 機能種別

非同期処理実行 / オーケストレーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| taskId | TaskId | Yes | 実行対象のタスクID | `tsk_`で始まる有効なID形式 |
| callbacks | RunTaskCallbacks | No | シーケンスイベントコールバック | - |
| logger | GiselleLogger | No | カスタムロガー | - |
| metadata | GenerationMetadata | No | 生成メタデータ | - |
| onGenerationComplete | function | No | 生成完了時コールバック | - |
| onGenerationError | function | No | 生成エラー時コールバック | - |

### 入力データソース

- Storage: `tasks/{taskId}.json` からタスクデータを取得
- Storage: 各生成データを `generations/` から取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | void | 戻り値なし（非同期実行、コールバックで通知） |

### 出力先

- Storage: タスクステータス、duration、usage等の更新
- Storage: 各生成データのステータスと結果の更新
- コールバック: sequenceStart/Complete/Fail/Skip、generationComplete/Error

## 処理フロー

### 処理シーケンス

```
1. 初期化
   ├─ getTaskでタスクデータを取得
   └─ createPatchQueueでパッチキューを初期化

2. タスク実行（executeTask）
   ├─ タスクステータスを"inProgress"に更新
   │
   ├─ シーケンスループ（順次実行）
   │   ├─ 前シーケンスでエラーがあれば後続をスキップ
   │   │
   │   ├─ シーケンス開始処理
   │   │   ├─ シーケンスステータスを"running"に更新
   │   │   └─ onSequenceStartコールバック
   │   │
   │   ├─ ステップ並列実行
   │   │   ├─ getGenerationで生成データ取得
   │   │   ├─ executeStepで生成処理実行
   │   │   │   ├─ action → executeAction
   │   │   │   ├─ imageGeneration → generateImage
   │   │   │   ├─ textGeneration/contentGeneration → startContentGeneration
   │   │   │   ├─ trigger → resolveTrigger
   │   │   │   ├─ query → executeQuery
   │   │   │   └─ dataQuery → executeDataQuery
   │   │   └─ 完了/失敗コールバック
   │   │
   │   └─ シーケンス完了処理
   │       ├─ シーケンスステータスを"completed"/"failed"に更新
   │       └─ onSequenceComplete/Errorコールバック
   │
   └─ タスク完了処理
       ├─ タスクステータスを"completed"/"failed"に更新
       └─ パッチキューをフラッシュ

3. クリーンアップ
   └─ patchQueue.cleanup()
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[getTask]
    B --> C[createPatchQueue]
    C --> D[executeTask開始]
    D --> E[status = inProgress]
    E --> F{シーケンスあり?}
    F -->|No| G[タスク完了]
    F -->|Yes| H{前シーケンスエラー?}
    H -->|Yes| I[残シーケンスをスキップ]
    I --> G
    H -->|No| J[シーケンス開始]
    J --> K[ステップ並列実行]
    K --> L{全ステップ完了?}
    L -->|実行中| M[executeStep]
    M --> N{ノードタイプ}
    N -->|textGeneration| O[generateContent]
    N -->|imageGeneration| P[generateImage]
    N -->|action| Q[executeAction]
    N -->|query| R[executeQuery]
    N -->|trigger| S[resolveTrigger]
    O --> L
    P --> L
    Q --> L
    R --> L
    S --> L
    L -->|完了| T{エラーあり?}
    T -->|Yes| U[シーケンス失敗]
    T -->|No| V[シーケンス完了]
    U --> F
    V --> F
    G --> W[patchQueue.flush]
    W --> X[cleanup]
    X --> Y[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-23-01 | シーケンス順次実行 | シーケンスは配列インデックス順に実行 | タスク実行時 |
| BR-23-02 | ステップ並列実行 | 同一シーケンス内のステップはPromise.allで並列実行 | シーケンス実行時 |
| BR-23-03 | エラー伝播 | シーケンスでエラー発生時、後続シーケンスはキャンセル | エラー発生時 |
| BR-23-04 | ステータス遷移 | created→queued→running→completed/failed/cancelled | ステップ実行時 |
| BR-23-05 | 統計更新 | 実行中にsteps統計を更新（queued→inProgress→completed/failed） | ステップ遷移時 |

### 計算ロジック

**Duration計算**：
- `wallClock`: 開始から終了までの経過時間（Date.now() - startTime）
- `totalTask`: 全ステップのdurationの合計

**Usage集計**：
- `inputTokens`: 全生成のinputTokensの合計
- `outputTokens`: 全生成のoutputTokensの合計
- `totalTokens`: inputTokens + outputTokens

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| タスク取得 | Storage (tasks/{taskId}.json) | SELECT | タスクデータの読み取り |
| 生成取得 | Storage (generations/) | SELECT | 生成データの読み取り |
| タスク更新 | Storage (tasks/{taskId}.json) | UPDATE | ステータス、統計、シーケンス情報の更新 |
| 生成更新 | Storage (generations/) | UPDATE | 生成結果、ステータスの更新 |

### テーブル別操作詳細

#### Storage: tasks/{taskId}.json

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | status | "inProgress" → "completed"/"failed" | パッチ操作 |
| UPDATE | steps.queued | デクリメント | ステップ開始時 |
| UPDATE | steps.inProgress | インクリメント/デクリメント | ステップ開始/終了時 |
| UPDATE | steps.completed | インクリメント | ステップ成功時 |
| UPDATE | steps.failed | インクリメント | ステップ失敗時 |
| UPDATE | steps.cancelled | インクリメント | スキップ時 |
| UPDATE | duration.wallClock | 経過時間 | タスク完了時 |
| UPDATE | duration.totalTask | 合計時間 | ステップ完了ごと |
| UPDATE | sequences[i].status | "running"/"completed"/"failed" | シーケンス遷移時 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| TASK_NOT_FOUND | NotFoundError | タスクが存在しない | 有効なタスクIDを指定 |
| GENERATION_NOT_FOUND | NotFoundError | 生成データが存在しない | タスク作成を確認 |
| AI_PROVIDER_ERROR | ExternalError | AI API呼び出し失敗 | プロバイダ状態を確認 |
| EXECUTION_ERROR | RuntimeError | ステップ実行中のエラー | ログを確認し原因を特定 |

### リトライ仕様

- 個別ステップのエラーは自動リトライなし
- タスク全体のリトライは呼び出し側で制御

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

- パッチ操作はキューに蓄積され、バッチでフラッシュ
- 部分的な成功は許容（一部ステップ失敗でもタスクは失敗として記録）
- タスク完了時にpatchQueue.flush()で全パッチを適用

## パフォーマンス要件

- シーケンス開始処理: 50ms以内
- パッチ適用: 100ms以内（バッチ）
- タスク全体: ノード数とAIモデルレスポンス時間に依存

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

- 各外部サービス（AI API、GitHub）の認証情報は暗号化して管理
- 生成結果のログ出力時は機密情報をマスク
- エラーダンプには詳細情報を含めない（本番環境）

## 備考

- executeStep関数内でノードタイプごとの処理を分岐
- appEntryとendノードは実質的に何も処理しない（パススルー）
- waitUntilGenerationFinishes関数で生成完了をポーリング（1秒間隔）

---

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

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

### 推奨読解順序

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

タスクの実行状態と生成のステータス遷移を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | task.ts | `packages/protocol/src/task/task.ts` | Task, Sequence, Step型の構造 |
| 1-2 | index.ts | `packages/protocol/src/generation/index.ts` | Generation型とステータス遷移 |

**読解のコツ**: GenerationStatusは6種類（created, queued, running, completed, failed, cancelled）あり、それぞれ異なるフィールドを持つ。

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

runTask関数の全体構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | run-task.ts | `packages/giselle/src/tasks/run-task.ts` | runTask関数のシグネチャと処理フロー |

**主要処理フロー**:
1. **28-52行目**: waitUntilGenerationFinishes関数（生成完了ポーリング）
2. **54-59行目**: RunTaskCallbacksインターフェース
3. **61-129行目**: executeStep関数（ノードタイプ別の処理分岐）
4. **131-137行目**: RunTaskInputsスキーマ
5. **139-145行目**: runTask関数シグネチャ
6. **146行目**: getTaskでタスク取得
7. **148-150行目**: パッチキューの初期化
8. **154-212行目**: executeTask呼び出しとコールバック設定
9. **217行目**: patchQueue.cleanup()

#### Step 3: タスク実行ユーティリティを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | task-execution-utils.ts | `packages/giselle/src/tasks/shared/task-execution-utils.ts` | executeTask, executeSequence関数 |

**主要処理フロー**:
- **14-20行目**: VALID_ACT_TRANSITIONS（タスクの有効なステータス遷移）
- **23-33行目**: VALID_GENERATION_TRANSITIONS（生成の有効なステータス遷移）
- **73-147行目**: executeSequence関数（シーケンス内のステップ並列実行）
- **210-331行目**: executeTask関数（シーケンスの順次実行とエラーハンドリング）

#### Step 4: パッチ操作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | patch-queue.ts | `packages/giselle/src/tasks/patch-queue.ts` | パッチキューの実装 |
| 4-2 | patch-creators.ts | `packages/giselle/src/tasks/object/patch-creators.ts` | パッチオブジェクト生成ヘルパー |

#### Step 5: 各ノードタイプの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | generate-content.ts | `packages/giselle/src/generations/generate-content.ts` | テキスト生成処理 |
| 5-2 | generate-image.ts | `packages/giselle/src/generations/generate-image.ts` | 画像生成処理 |
| 5-3 | execute-action.ts | `packages/giselle/src/operations/execute-action.ts` | アクション実行処理 |
| 5-4 | execute-query.ts | `packages/giselle/src/operations/execute-query.ts` | クエリ実行処理 |

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

```
runTask (run-task.ts)
    │
    ├─ getTask (get-task.ts)
    │
    ├─ createPatchQueue (patch-queue.ts)
    │      └─ createApplyPatches
    │
    └─ executeTask (task-execution-utils.ts)
           │
           ├─ applyPatches [status = inProgress]
           │
           ├─ executeSequence (各シーケンス)
           │      │
           │      ├─ onSequenceStart
           │      │
           │      ├─ Promise.all (ステップ並列)
           │      │      │
           │      │      └─ startGeneration (各ステップ)
           │      │             │
           │      │             ├─ getGeneration
           │      │             │
           │      │             └─ executeStep
           │      │                    │
           │      │                    ├─ executeAction
           │      │                    ├─ generateImage
           │      │                    ├─ startContentGeneration
           │      │                    │      └─ waitUntilGenerationFinishes
           │      │                    ├─ resolveTrigger
           │      │                    ├─ executeQuery
           │      │                    └─ executeDataQuery
           │      │
           │      ├─ onStepComplete / onStepError
           │      │
           │      └─ onSequenceComplete / onSequenceError
           │
           ├─ applyPatches [status = completed/failed]
           │
           └─ onTaskComplete
                  │
                  └─ patchQueue.flush
```

### データフロー図

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

taskId ──────────────▶ getTask
                           │
                           ▼
                      Task取得
                           │
                           ▼
                      executeTask
                           │
                           ├─▶ Sequence 1
                           │       │
                           │       ├─▶ Step 1 ─▶ executeStep ─▶ Generation結果
                           │       │
                           │       └─▶ Step 2 ─▶ executeStep ─▶ Generation結果
                           │       （並列実行）
                           │
                           ├─▶ Sequence 2
                           │       │
                           │       └─▶ Step 3 ─▶ executeStep ─▶ Generation結果
                           │
                           ▼
                      パッチ適用 ─────────────────────────────▶ Task更新
                           │
                           └─▶ コールバック
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| run-task.ts | `packages/giselle/src/tasks/run-task.ts` | ソース | エントリーポイント |
| task-execution-utils.ts | `packages/giselle/src/tasks/shared/task-execution-utils.ts` | ソース | 実行ユーティリティ |
| patch-queue.ts | `packages/giselle/src/tasks/patch-queue.ts` | ソース | パッチキュー管理 |
| patch-creators.ts | `packages/giselle/src/tasks/object/patch-creators.ts` | ソース | パッチ生成ヘルパー |
| get-task.ts | `packages/giselle/src/tasks/get-task.ts` | ソース | タスク取得 |
| generate-content.ts | `packages/giselle/src/generations/generate-content.ts` | ソース | テキスト生成 |
| generate-image.ts | `packages/giselle/src/generations/generate-image.ts` | ソース | 画像生成 |
| task.ts | `packages/protocol/src/task/task.ts` | ソース | Task型定義 |
| index.ts | `packages/protocol/src/generation/index.ts` | ソース | Generation型定義 |
