# 機能設計書 25-タスク取得

## 概要

本ドキュメントは、Giselleシステムにおける「タスク取得」機能の設計仕様を定義する。この機能は、指定されたIDのタスクデータをストレージから取得するための基本的なデータアクセス機能である。

### 本機能の処理概要

**業務上の目的・背景**：タスクの状態確認、実行結果の参照、進捗監視など、様々な場面でタスクデータへのアクセスが必要となる。この機能は、タスクIDをキーとしてストレージからタスクの完全なデータを取得し、型安全な形式で返却するシンプルかつ重要な機能である。

**機能の利用シーン**：
- タスク一覧画面で個別のタスク詳細を表示する場合
- タスク詳細画面で実行結果を表示する場合
- タスク実行中にステータスを確認する場合
- ストリーム配信でタスクデータをポーリング取得する場合
- タスク開始時に現在のステータスを検証する場合

**主要な処理内容**：
1. タスクIDからストレージパスを生成する
2. ストレージからJSONデータを読み込む
3. Zodスキーマでデータを検証・パースする
4. 型安全なTaskオブジェクトとして返却する

**関連システム・外部連携**：
- Storage: JSONファイルとしてのタスクデータ永続化

**権限による制御**：
- タスクへのアクセス権限は呼び出し側で制御
- 直接的な権限チェックは本機能では行わない

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | タスク一覧画面 | 主画面 | 実行されたタスクの一覧取得と表示 |
| 20 | タスク詳細画面 | 主画面 | タスクの実行結果詳細データの取得と表示 |
| 21 | タスク一覧画面（非推奨） | 主画面 | 旧バージョンのタスク一覧取得処理 |

## 機能種別

CRUD操作（Read）

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- 呼び出し元: 各種タスク関連機能（startTask, runTask, streamTask等）
- 画面操作: タスク一覧、タスク詳細画面からのデータ取得リクエスト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| task | Task | タスクオブジェクト |

### Taskオブジェクトの構造

| フィールド | 型 | 説明 |
|-----------|-----|------|
| id | TaskId | タスクの一意識別子 |
| starter | TaskStarter | タスク開始元情報 |
| workspaceId | WorkspaceId | 所属ワークスペースID |
| name | string | タスク名 |
| status | string | ステータス（created/inProgress/completed/failed/cancelled） |
| steps | object | ステップ統計（queued/inProgress/completed/warning/cancelled/failed） |
| trigger | string | トリガー情報 |
| duration | object | 実行時間（wallClock/totalTask） |
| usage | object | トークン使用量（inputTokens/outputTokens/totalTokens） |
| createdAt | number | 作成日時（ミリ秒） |
| updatedAt | number | 更新日時（ミリ秒） |
| annotations | array | 注釈情報 |
| sequences | Sequence[] | シーケンス配列 |
| nodeIdsConnectedToEnd | NodeId[] | 終了ノードに接続されたノードID（オプション） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. パス生成
   └─ taskPath(taskId)で`tasks/{taskId}.json`パスを生成

2. データ取得
   └─ storage.getJsonでJSONファイルを読み込み

3. スキーマ検証
   └─ Task Zodスキーマでデータを検証・パース

4. 結果返却
   └─ 型安全なTaskオブジェクトを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[taskPath生成]
    B --> C[storage.getJson]
    C --> D{データ存在?}
    D -->|No| E[エラースロー]
    D -->|Yes| F[Taskスキーマ検証]
    F --> G{検証成功?}
    G -->|No| H[パースエラー]
    G -->|Yes| I[Task返却]
    I --> J[終了]
    E --> K[例外]
    H --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-25-01 | パス形式 | タスクは`tasks/{taskId}.json`パスに保存 | 常時 |
| BR-25-02 | スキーマ検証 | 取得データはTaskスキーマで検証 | データ取得後 |
| BR-25-03 | 存在チェック | 存在しないタスクIDはエラー | データ取得時 |

### 計算ロジック

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

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

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

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

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

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

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | 全フィールド | taskIdで取得 | JSONファイル全体を読み込み |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| TASK_NOT_FOUND | NotFoundError | 指定タスクIDのファイルが存在しない | 有効なタスクIDを指定 |
| PARSE_ERROR | ValidationError | JSONデータがTaskスキーマに適合しない | データの整合性を確認 |
| STORAGE_ERROR | StorageError | ストレージアクセスに失敗 | システム管理者に連絡 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- タスク取得: 100ms以内
- ファイルサイズ: 一般的に数KB〜数十KB

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

- タスクIDは推測困難なランダムID形式
- アクセス権限チェックは呼び出し側で実施

## 備考

- storage.getJsonはZodスキーマを受け取り、パース結果を型付きで返却
- 内部的にJSONファイルの読み込みとパースを行う

---

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

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

### 推奨読解順序

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

Taskの型定義を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | task.ts | `packages/protocol/src/task/task.ts` | Task Zodスキーマと型定義 |
| 1-2 | task-id.ts | `packages/protocol/src/task/task-id.ts` | TaskIdの生成規則 |

**読解のコツ**: `z.object({...})`で定義されたスキーマと、`z.infer<typeof Task>`で導出される型の関係を理解する。

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

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

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

**主要処理フロー**:
1. **1-2行目**: インポート（TaskId, Task型）
2. **3行目**: taskPathのインポート
3. **4行目**: GiselleContext型のインポート
4. **6-9行目**: 関数シグネチャ（taskIdとcontextを受け取る）
5. **10-13行目**: storage.getJsonの呼び出し
6. **14行目**: taskを返却

#### Step 3: パス生成ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | path.ts | `packages/giselle/src/path.ts` | taskPath関数の実装 |

**主要処理フロー**:
- **20-22行目**: taskPath関数（`tasks/${taskId}.json`を返却）

#### Step 4: ストレージ操作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | types.ts | `packages/giselle/src/types.ts` | GiselleContextとstorageインターフェース |

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

```
getTask (get-task.ts)
    │
    ├─ taskPath (path.ts)
    │      └─ `tasks/${taskId}.json`
    │
    └─ context.storage.getJson
           │
           ├─ ファイル読み込み
           │
           └─ Task.parse（Zodスキーマ検証）
                  │
                  └─ Task型オブジェクト返却
```

### データフロー図

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

taskId ──────────────▶ taskPath
                           │
                           ▼
                      "tasks/{taskId}.json"
                           │
                           ▼
                      storage.getJson
                           │
                           ├─▶ ファイル読み込み
                           │
                           ├─▶ JSON.parse
                           │
                           └─▶ Task.parse (Zod)
                                   │
                                   ▼
                              Task ──────────────────────▶ 呼び出し元
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| get-task.ts | `packages/giselle/src/tasks/get-task.ts` | ソース | タスク取得のメイン実装 |
| path.ts | `packages/giselle/src/path.ts` | ソース | ストレージパス生成 |
| task.ts | `packages/protocol/src/task/task.ts` | ソース | Task Zodスキーマと型定義 |
| task-id.ts | `packages/protocol/src/task/task-id.ts` | ソース | TaskId生成規則 |
| giselle.ts | `packages/giselle/src/giselle.ts` | ソース | Giselleクラス（メソッド公開） |
| index.ts | `packages/giselle/src/tasks/index.ts` | ソース | モジュールエクスポート |
