# 機能設計書 27-進行中タスク取得

## 概要

本ドキュメントは、Giselleシステムにおける「進行中タスク取得」機能の設計仕様を定義する。この機能は、指定されたワークスペースで現在実行中（inProgress）のタスクを取得するための機能である。

### 本機能の処理概要

**業務上の目的・背景**：ワークフロー実行中に、同一ワークスペースで既に実行中のタスクがあるかどうかを確認する必要がある。この機能により、現在アクティブなタスクの存在確認や、実行中タスクへの再接続が可能となる。複数タスクが同時に実行中の場合は警告を出力し、最新のタスクを返却する。

**機能の利用シーン**：
- ワークフローエディタでRunボタン押下前に実行中タスクを確認する場合
- ストリーム再接続時に実行中タスクを特定する場合
- 同一ワークスペースでの重複実行を防止する場合

**主要な処理内容**：
1. ワークスペースIDからタスクインデックスを取得する
2. 各タスクIDに対してタスクデータを並列取得する
3. 取得したタスクをcreatedAt降順（最新順）でソートする
4. status === "inProgress"のタスクをフィルタリングする
5. 複数の実行中タスクがある場合は警告ログを出力する
6. 最新の実行中タスクを返却する（存在しない場合はundefined）

**関連システム・外部連携**：
- Storage: タスクインデックスとタスクデータの永続化

**権限による制御**：
- ワークスペースへのアクセス権限は呼び出し側で制御

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面機能マッピングに直接の関連なし（内部API） |

## 機能種別

CRUD操作（Read） / 状態検索

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| workspaceId | WorkspaceId | Yes | 対象ワークスペースID | `wks_`で始まる有効なID形式 |
| context | GiselleContext | Yes | Giselleコンテキスト | 有効なコンテキストオブジェクト |

### 入力データソース

- Storage: `tasks/byWorkspace/{workspaceId}.json` からインデックス取得
- Storage: `tasks/{taskId}.json` から各タスクデータ取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| task | Task \| undefined | 進行中のタスク、または存在しない場合はundefined |

### 出力先

- 呼び出し元: Taskオブジェクトまたはundefinedとして返却

## 処理フロー

### 処理シーケンス

```
1. インデックス取得
   ├─ workspaceTaskPath(workspaceId)でパス生成
   └─ getWorkspaceIndexでタスクインデックス配列を取得

2. タスク並列取得
   ├─ Promise.allで全タスクIDを並列処理
   └─ エラーハンドリング（失敗時はnull、警告ログ出力）

3. フィルタリングとソート
   ├─ null値を除外
   ├─ createdAt降順でソート
   └─ status === "inProgress"でフィルタ

4. 結果検証と返却
   ├─ 進行中タスクなし: undefinedを返却
   ├─ 複数の進行中タスク: 警告ログ出力
   └─ 最新の進行中タスクを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[workspaceTaskPath生成]
    B --> C[getWorkspaceIndex]
    C --> D[Promise.allでタスク取得]
    D --> E[null値フィルタ]
    E --> F[createdAt降順ソート]
    F --> G[inProgressフィルタ]
    G --> H{進行中タスクあり?}
    H -->|No| I[undefinedを返却]
    H -->|Yes| J{複数タスク?}
    J -->|Yes| K[警告ログ出力]
    J -->|No| L[最新タスクを返却]
    K --> L
    I --> M[終了]
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-27-01 | ソート順 | createdAt降順（最新が先頭） | タスクソート時 |
| BR-27-02 | ステータスフィルタ | status === "inProgress"のみ抽出 | フィルタリング時 |
| BR-27-03 | 複数警告 | 2つ以上の進行中タスクがある場合は警告 | 結果検証時 |
| BR-27-04 | 単一返却 | 常に0個または1個のタスクを返却 | 結果返却時 |

### 計算ロジック

**ソートロジック**：
```typescript
tasks.sort((a, b) => b.createdAt - a.createdAt)
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| インデックス取得 | Storage (tasks/byWorkspace/{workspaceId}.json) | SELECT | タスクIDインデックスの読み取り |
| タスク取得 | Storage (tasks/{taskId}.json) | SELECT | 各タスクデータの読み取り |

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

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

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | 全フィールド | taskIdで取得 | 並列実行、status="inProgress"をメモリ上でフィルタ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| INDEX_NOT_FOUND | NotFoundError | インデックスファイルが存在しない | undefinedを返却 |
| TASK_NOT_FOUND | NotFoundError | 個別タスクが存在しない | 警告ログ出力してスキップ |

### リトライ仕様

- 自動リトライなし（呼び出し側で制御）

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

- 読み取り専用のため、トランザクション制御は不要

## パフォーマンス要件

- 全タスク取得とフィルタリング: 300ms以内
- 大量タスク時も並列取得で高速化

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

- ワークスペースIDに紐づくタスクのみ検索対象
- アクセス権限チェックは呼び出し側で実施

## 備考

- 通常、ワークスペースで進行中のタスクは1つのみであることが期待される
- 複数の進行中タスクが存在する場合は、何らかの異常状態の可能性がある

---

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

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

### 推奨読解順序

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

Task型とステータスの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | task.ts | `packages/protocol/src/task/task.ts` | Task型、statusの取りうる値 |

**読解のコツ**: statusは"created" | "inProgress" | "completed" | "failed" | "cancelled"の5種類。

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

getWorkspaceInprogressTask関数の実装を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | get-workspace-inprogress-task.ts | `packages/giselle/src/tasks/get-workspace-inprogress-task.ts` | 関数の実装全体 |

**主要処理フロー**:
1. **7-12行目**: 関数シグネチャ
2. **14行目**: デバッグログ出力
3. **15-19行目**: getWorkspaceIndexでインデックス取得
4. **24-46行目**: Promise.allで各タスクを並列取得（エラー時はnull）
5. **48-50行目**: createdAt降順ソート、inProgressフィルタ
6. **52-54行目**: 進行中タスクなしの場合undefinedを返却
7. **56-59行目**: 複数タスク時の警告ログ
8. **61-62行目**: 最新の進行中タスクを返却

#### Step 3: 類似機能との比較

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | get-workspace-tasks.ts | `packages/giselle/src/tasks/get-workspace-tasks.ts` | 全タスク取得との共通部分 |

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

```
getWorkspaceInprogressTask (get-workspace-inprogress-task.ts)
    │
    ├─ workspaceTaskPath (path.ts)
    │
    ├─ getWorkspaceIndex (workspace-index.ts)
    │      └─ TaskIndexObject[]取得
    │
    ├─ Promise.all
    │      │
    │      └─ 各タスクID
    │             │
    │             └─ storage.getJson → Task/null
    │
    ├─ filter (null除外)
    │
    ├─ sort (createdAt降順)
    │
    └─ filter (inProgressのみ)
           │
           └─ inprogressTasks[0] または undefined
```

### データフロー図

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

workspaceId ─────────▶ getWorkspaceIndex
                           │
                           ▼
                      TaskIndexObject[]
                           │
                           ▼
                      Promise.all → Task[]
                           │
                           ▼
                      filter(null除外)
                           │
                           ▼
                      sort(createdAt DESC)
                           │
                           ▼
                      filter(inProgress)
                           │
                           ▼
                      inprogressTasks
                           │
                           ├─▶ 0件: undefined
                           ├─▶ 1件: Task
                           └─▶ 2件以上: 警告 + Task[0]
                                   │
                                   ▼
                              Task | undefined ──────────▶ 呼び出し元
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| get-workspace-inprogress-task.ts | `packages/giselle/src/tasks/get-workspace-inprogress-task.ts` | ソース | メイン実装 |
| get-workspace-tasks.ts | `packages/giselle/src/tasks/get-workspace-tasks.ts` | ソース | 類似機能（参考） |
| path.ts | `packages/giselle/src/path.ts` | ソース | パス生成 |
| workspace-index.ts | `packages/giselle/src/utils/workspace-index.ts` | ソース | インデックス取得 |
| task.ts | `packages/protocol/src/task/task.ts` | ソース | Task型定義 |
| giselle.ts | `packages/giselle/src/giselle.ts` | ソース | Giselleクラス（メソッド公開） |
