# 機能設計書 2-ワークスペース取得

## 概要

本ドキュメントは、Giselleにおけるワークスペース取得機能の設計を定義する。指定されたワークスペースIDに基づき、ストレージからワークスペースデータを読み込み、必要な変換処理を施して返却する機能である。

### 本機能の処理概要

ワークスペース取得機能は、永続化ストレージに保存されているワークスペースデータを読み込み、クライアントやサーバー側の処理で利用可能な形式に変換して返却する機能である。

**業務上の目的・背景**：Giselleのワークフローエディタでは、ユーザーが以前作成したワークスペースを開いて編集を継続する必要がある。また、ワークフローの実行時にもワークスペースの構成情報（ノード、接続）が必要となる。本機能により、保存されたワークスペースの状態を復元し、編集や実行に利用できる形で提供する。フィーチャーフラグに応じたノード形式の変換も行い、実験的機能の切り替えにも対応する。

**機能の利用シーン**：ワークフローエディタ画面を開いたとき、タスク実行前のワークスペース情報取得時、ワークスペース一覧画面での詳細表示時、ワークスペースコピーやサンプル作成時の元データ取得など、多くの場面で利用される。

**主要な処理内容**：
1. ワークスペースIDからストレージパスを構築
2. ストレージからJSONデータを読み込み、Zodスキーマでパース
3. 各ノードに対してデータモディファイア（parseAndMod）を適用
4. フィーチャーフラグに基づくノード形式の変換（TextGeneration/ContentGeneration）
5. 変換後のワークスペースオブジェクトを返却

**関連システム・外部連携**：GiselleStorageインターフェースを通じてファイルシステムまたはクラウドストレージと連携する。node-registryパッケージによるノード変換処理も含む。

**権限による制御**：本機能自体にはロールベースの制限はないが、呼び出し元のAPIエンドポイントにおいてワークスペースへのアクセス権限確認が行われる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | ロビー画面 | 主機能 | アプリ検索、ワークスペース一覧の取得と表示 |
| 16 | ワークスペース一覧画面 | 主機能 | チームのワークスペース（エージェント）一覧を取得・表示 |
| 17 | ワークフローエディタ画面 | 主機能 | 指定されたワークスペースデータの読み込みと表示 |

## 機能種別

CRUD操作（Read）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| context | GiselleContext | Yes | Giselleの実行コンテキスト | 型チェック |
| workspaceId | WorkspaceId | Yes | 取得対象のワークスペースID | wrks_プレフィックス形式 |

### 入力データソース

- ストレージ: `workspaces/{workspaceId}/workspace.json` パスから読み込み

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | WorkspaceId | ワークスペースの一意識別子 |
| schemaVersion | string | スキーマバージョン |
| name | string \| undefined | ワークスペース名 |
| nodes | Node[] | ノード配列（変換後） |
| connections | Connection[] | 接続配列 |
| ui | UIState | UI状態 |

### 出力先

- 戻り値: 呼び出し元にWorkspaceオブジェクトを返却

## 処理フロー

### 処理シーケンス

```
1. workspacePath()でストレージパスを構築
   └─ パス形式: workspaces/{workspaceId}/workspace.json

2. context.storage.getJson()でJSONデータを取得
   └─ Workspaceスキーマでパース

3. 各ノードに対してparseAndMod()を適用
   └─ データモディファイアによる変換処理

4. フィーチャーフラグに基づくノード変換
   └─ experimental_contentGenerationNodeフラグを確認
   └─ TextGenerationNode ⇔ ContentGenerationNode の変換

5. 変換後のワークスペースオブジェクトを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ストレージパス構築]
    B --> C[JSONデータ取得]
    C --> D{データ存在?}
    D -->|No| E[エラー終了]
    D -->|Yes| F[各ノードにparseAndMod適用]
    F --> G{experimental_contentGenerationNode?}
    G -->|Yes & TextGenNode| H[ContentGenerationNodeに変換]
    G -->|No & ContentGenNode| I[TextGenerationNodeに変換]
    G -->|その他| J[変換なし]
    H --> K[Workspaceオブジェクト構築]
    I --> K
    J --> K
    K --> L[返却]
    L --> M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パス形式 | ストレージパスは`workspaces/{workspaceId}/workspace.json`形式 | 常に適用 |
| BR-002 | ノード変換 | experimental_contentGenerationNodeフラグに応じてノード形式を変換 | フィーチャーフラグ有効時 |
| BR-003 | スキーマ検証 | 取得データはZodスキーマでバリデーション | 常に適用 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ワークスペース取得 | ストレージ（Blob/ファイル） | SELECT | workspace.jsonを読み込み |

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

本機能はファイルベースのストレージを使用するため、RDBテーブル操作は発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NOT_FOUND | データ未存在 | 指定IDのワークスペースが存在しない | IDの確認、ワークスペース作成 |
| VALIDATION_ERROR | バリデーションエラー | 保存データがスキーマに不適合 | データ修復、再作成 |
| STORAGE_ERROR | ストレージエラー | ストレージ読み込み失敗 | 接続確認、リトライ |

### リトライ仕様

ストレージ読み込み失敗時は呼び出し元でリトライを検討する。

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

読み取り専用のため、トランザクション管理は不要。

## パフォーマンス要件

- レスポンス時間: 200ms以内（ストレージ読み込み含む）
- キャッシュ: コメントアウトされているが、bypassingCacheオプションで制御可能

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

- ワークスペースIDによるアクセス制御
- 認証・認可は呼び出し元のAPIレイヤーで実施

## 備考

- parseAndMod関数により、スキーマ変更時のマイグレーション処理が可能
- フィーチャーフラグによるノード形式切り替えは実験的機能のため、将来変更の可能性あり

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/protocol/src/workspace/index.ts` | Workspaceスキーマの構造 |
| 1-2 | node.ts | `packages/protocol/src/node/node.ts` | Node型（OperationNode, VariableNodeの合成） |

**読解のコツ**: `z.discriminatedUnion`によるノード種別の判別方法を理解する。

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

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

**主要処理フロー**:
1. **5-8行目**: 入力パラメータの型定義（context, workspaceId）
2. **9-12行目**: utils.tsのgetWorkspace関数を呼び出し

#### Step 3: 内部処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | utils.ts | `packages/giselle/src/workspaces/utils.ts` | getWorkspace関数（35-68行目） |

**主要処理フロー**:
- **42-46行目**: ストレージからJSONを取得、Workspaceスキーマでパース
- **47-48行目**: 各ノードにparseAndModを適用
- **49-62行目**: フィーチャーフラグに基づくノード変換処理
- **64-67行目**: 変換後のワークスペースを返却

#### Step 4: ノード変換処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | data-mod.ts | `packages/giselle/src/data-mod.ts` | parseAndMod関数（スキーマ変換） |

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

```
getWorkspace (get-workspace.ts)
    │
    └─ getWorkspaceInternal (utils.ts)
           │
           ├─ workspacePath (utils.ts)
           │
           ├─ context.storage.getJson (GiselleStorage)
           │
           ├─ parseAndMod (data-mod.ts)
           │      └─ Node.parse
           │
           └─ convertTextGenerationToContentGeneration (node-registry)
              convertContentGenerationToTextGeneration (node-registry)
```

### データフロー図

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

WorkspaceId ───▶ workspacePath ───▶ Storage Path
                         │
                         ▼
              context.storage.getJson
                         │
                         ▼
                   Raw JSON Data
                         │
                         ▼
            Workspace.parse (Zod validation)
                         │
                         ▼
            parseAndMod (各ノード)
                         │
                         ▼
            FeatureFlag判定 & ノード変換
                         │
                         ▼
              Workspace Object ───▶ 呼び出し元
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| get-workspace.ts | `packages/giselle/src/workspaces/get-workspace.ts` | ソース | メイン機能実装（エクスポート） |
| utils.ts | `packages/giselle/src/workspaces/utils.ts` | ソース | 実際の取得処理実装 |
| data-mod.ts | `packages/giselle/src/data-mod.ts` | ソース | データモディファイア |
| index.ts | `packages/protocol/src/workspace/index.ts` | ソース | Workspaceスキーマ定義 |
| node.ts | `packages/protocol/src/node/node.ts` | ソース | Node型定義 |
| operation-node.ts | `packages/protocol/src/node/operations/operation-node.ts` | ソース | OperationNode型、ノード判定関数 |
