# 機能設計書 26-ワークスペースタスク一覧

## 概要

本ドキュメントは、Giselleシステムにおける「ワークスペースタスク一覧」機能の設計仕様を定義する。この機能は、指定されたワークスペースに関連する全てのタスクの一覧を取得するための機能である。

### 本機能の処理概要

**業務上の目的・背景**：ワークスペース単位でタスクの実行履歴を管理し、過去の実行結果を参照・分析する必要がある。この機能により、特定のワークスペースで実行された全タスクを一覧として取得でき、実行履歴の可視化やタスク管理が可能となる。

**機能の利用シーン**：
- タスク一覧画面でワークスペースに紐づくタスクを表示する場合
- ワークフローエディタで過去の実行履歴を確認する場合
- アプリ詳細画面で実行履歴を参照する場合
- 進行中のタスクを検索する際のベースクエリとして使用する場合

**主要な処理内容**：
1. ワークスペースIDからタスクインデックスパスを生成する
2. タスクインデックスファイルからタスクID一覧を取得する
3. 各タスクIDに対してタスクデータを並列取得する
4. 取得に失敗したタスクはスキップし、警告ログを出力する
5. 正常に取得できたタスクの配列を返却する

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

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | タスク一覧画面 | 補助機能 | ワークスペースに関連するタスクのフィルタリング |

## 機能種別

CRUD操作（Read） / 一覧取得

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| tasks | Task[] | タスクオブジェクトの配列 |

### 出力先

- 呼び出し元: Task配列として返却

## 処理フロー

### 処理シーケンス

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

2. タスク並列取得
   ├─ Promise.allで全タスクIDを並列処理
   │   ├─ taskPath(taskId)でパス生成
   │   └─ storage.getJsonでタスクデータ取得
   │
   └─ エラーハンドリング
       ├─ 取得成功: タスクオブジェクトを返却
       └─ 取得失敗: 警告ログ出力、nullを返却

3. フィルタリング
   └─ null値を除外してTask配列を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[workspaceTaskPath生成]
    B --> C[getWorkspaceIndex]
    C --> D{インデックスあり?}
    D -->|No| E[空配列を返却]
    D -->|Yes| F[Promise.all開始]
    F --> G[各タスクID処理]
    G --> H[taskPath生成]
    H --> I[storage.getJson]
    I --> J{取得成功?}
    J -->|Yes| K[Taskを返却]
    J -->|No| L[警告ログ出力]
    L --> M[nullを返却]
    K --> N{全タスク処理完了?}
    M --> N
    N -->|No| G
    N -->|Yes| O[null値をフィルタ]
    O --> P[Task配列を返却]
    P --> Q[終了]
    E --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-26-01 | インデックスパス | インデックスは`tasks/byWorkspace/{workspaceId}.json`に保存 | 常時 |
| BR-26-02 | 並列取得 | 各タスクはPromise.allで並列取得 | タスク取得時 |
| BR-26-03 | エラー許容 | 取得失敗したタスクはスキップし、他のタスクは返却 | 取得エラー時 |
| BR-26-04 | 警告ログ | 取得失敗時は警告ログを出力 | 取得エラー時 |

### 計算ロジック

特になし（データ取得のみ）

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

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

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

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

#### Storage: tasks/byWorkspace/{workspaceId}.json

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | TaskIndexObject[] | workspaceIdで取得 | インデックス配列 |

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

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | 全フィールド | taskIdで取得 | 並列実行 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| INDEX_NOT_FOUND | NotFoundError | インデックスファイルが存在しない | 空配列を返却 |
| TASK_NOT_FOUND | NotFoundError | 個別タスクが存在しない | 警告ログ出力してスキップ |
| STORAGE_ERROR | StorageError | ストレージアクセスに失敗 | エラーログ出力 |

### リトライ仕様

- 個別タスク取得エラー: 自動リトライなし、スキップして継続

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

- 読み取り専用のため、トランザクション制御は不要
- 並列取得中に他の処理がタスクを更新した場合、取得時点のデータを返却

## パフォーマンス要件

- インデックス取得: 50ms以内
- 全タスク取得: 200ms + (タスク数 × 10ms)程度
- 並列実行による高速化

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

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

## 備考

- TaskIndexObjectはTask型の部分型（id, workspaceIdのみ）
- 削除されたタスクはインデックスに残っている可能性があるため、取得失敗を許容

---

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

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

### 推奨読解順序

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

タスクインデックスとTask型の構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | task.ts | `packages/protocol/src/task/task.ts` | Task型とTaskIndexObject型 |

**読解のコツ**: TaskIndexObjectはTask.pick({ id: true, workspaceId: true })で定義されており、インデックス用の軽量型である。

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

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

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

**主要処理フロー**:
1. **1-5行目**: インポート（WorkspaceId, Task, TaskIndexObject等）
2. **7-10行目**: 関数シグネチャ
3. **11-15行目**: getWorkspaceIndexでインデックス取得
4. **16-38行目**: Promise.allで各タスクを並列取得
5. **19-21行目**: storage.getJsonでタスク取得
6. **22-34行目**: try-catchでエラーハンドリング
7. **38行目**: null値をフィルタして返却

#### Step 3: パス生成とインデックス取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | path.ts | `packages/giselle/src/path.ts` | workspaceTaskPath関数 |
| 3-2 | workspace-index.ts | `packages/giselle/src/utils/workspace-index.ts` | getWorkspaceIndex関数 |

**主要処理フロー**:
- **24-26行目** (path.ts): workspaceTaskPath関数

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

```
getWorkspaceTasks (get-workspace-tasks.ts)
    │
    ├─ workspaceTaskPath (path.ts)
    │      └─ `tasks/byWorkspace/${workspaceId}.json`
    │
    ├─ getWorkspaceIndex (workspace-index.ts)
    │      └─ TaskIndexObject[]取得
    │
    └─ Promise.all
           │
           └─ 各タスクID
                  │
                  ├─ taskPath (path.ts)
                  │
                  └─ storage.getJson
                         │
                         └─ Task型オブジェクト
```

### データフロー図

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

workspaceId ─────────▶ workspaceTaskPath
                           │
                           ▼
                      getWorkspaceIndex
                           │
                           ▼
                      TaskIndexObject[]
                           │
                           ▼
                      Promise.all
                           │
                           ├─▶ taskPath → storage.getJson → Task
                           ├─▶ taskPath → storage.getJson → Task
                           └─▶ taskPath → storage.getJson → Task/null
                                   │
                                   ▼
                              filter(nullを除外)
                                   │
                                   ▼
                              Task[] ────────────────────▶ 呼び出し元
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 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型、TaskIndexObject型 |
| giselle.ts | `packages/giselle/src/giselle.ts` | ソース | Giselleクラス（メソッド公開） |
