# 機能設計書 5-サンプルワークスペース作成

## 概要

本ドキュメントは、Giselleにおけるサンプルワークスペース作成機能の設計を定義する。デモンストレーション用のサンプルワークスペースをテンプレートから複製し、全てのID（ノード、入出力、接続）を新規生成することで独立したワークスペースを作成する機能である。

### 本機能の処理概要

サンプルワークスペース作成機能は、事前に用意されたテンプレートワークスペースを基に、デモンストレーション用のサンプルワークスペースを生成する機能である。単純なコピーとは異なり、全てのIDを新規生成し、プロンプト内のID参照も更新する。

**業務上の目的・背景**：新規ユーザーがGiselleを使い始める際、空のワークスペースからスタートするよりも、実動するサンプルワークフローから学ぶ方が効果的である。本機能により、事前に設計されたテンプレートワークスペースを複数同時に生成し、ユーザーに即座に試用可能な環境を提供できる。ID参照も完全に更新されるため、テンプレート間での干渉なく独立したサンプルとして機能する。

**機能の利用シーン**：新規ユーザーのオンボーディング時、ロビー画面でのチュートリアル開始時、サンプルアプリからの学習開始時などに利用される。

**主要な処理内容**：
1. 設定されたsampleAppWorkspaceIdsからテンプレートID一覧を取得
2. 各テンプレートに対してcreateSampleWorkspaceFromTemplateを実行
3. ノード、入出力、接続の全IDを新規生成
4. IDマッピングを作成し、プロンプト内のID参照を更新
5. 新しいワークスペースとファイルをストレージに保存
6. 生成結果（ワークスペース、テンプレートID、IDマップ）を返却

**関連システム・外部連携**：GiselleStorageを通じたストレージ操作。GiselleContextのsampleAppWorkspaceIds設定との連携。

**権限による制御**：本機能は新規ユーザー向けの機能であり、チームへの書き込み権限があれば実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | ロビー画面（V2） | 補助機能 | テンプレートアプリの取得と表示（サンプル作成に関連） |

## 機能種別

CRUD操作（Create - テンプレートからの生成）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| context | GiselleContext | Yes | Giselleの実行コンテキスト | sampleAppWorkspaceIdsが必須 |

### 入力データソース

- context.sampleAppWorkspaceIds: テンプレートワークスペースID配列
- ストレージ: 各テンプレートのworkspace.json
- ストレージ: 各テンプレートの関連ファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| workspace | Workspace | 生成されたワークスペースオブジェクト |
| templateWorkspaceId | WorkspaceId | 元のテンプレートワークスペースID |
| idMap | Record<string, string> | 旧ID→新IDのマッピング |

### 出力先

- ストレージ: `workspaces/{newWorkspaceId}/workspace.json` に保存
- ストレージ: `workspaces/{newWorkspaceId}/files/` にファイルコピー
- 戻り値: SampleWorkspaceResult配列

## 処理フロー

### 処理シーケンス

```
1. sampleAppWorkspaceIdsの存在確認
   └─ 未設定または空の場合はエラー

2. 各テンプレートに対してPromise.allで並列処理
   └─ createSampleWorkspaceFromTemplateを呼び出し

3. テンプレートワークスペースを取得
   └─ getWorkspace()で元データを読み込み

4. IDマッピングの作成と新規ID生成
   └─ 各ノードに対して新NodeId生成
   └─ 各入力に対して新InputId生成
   └─ 各出力に対して新OutputId生成
   └─ idMapに旧ID→新IDを記録

5. 接続の新規ID生成
   └─ 新ConnectionId生成
   └─ idMapを使って参照先を更新

6. UI状態のノードID参照を更新
   └─ nodeStateのキーを新IDに置換

7. プロンプト内のID参照を更新
   └─ TextGenerationノードのプロンプト文字列内のIDを置換

8. 新ワークスペースID生成と保存
   └─ WorkspaceId.generate()
   └─ 並列でsetWorkspaceとcopyFiles

9. 結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{sampleAppWorkspaceIds設定あり?}
    B -->|No| C[エラー終了]
    B -->|Yes| D[各テンプレートに対してPromise.all]
    D --> E[テンプレート取得]
    E --> F[ノードのID再生成]
    F --> G[入出力のID再生成]
    G --> H[接続のID再生成]
    H --> I[UI状態のID更新]
    I --> J[プロンプト内ID更新]
    J --> K[新ワークスペースID生成]
    K --> L[並列: ストレージ保存 & ファイルコピー]
    L --> M[SampleWorkspaceResult返却]
    M --> N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 全ID再生成 | ノード、入出力、接続の全IDを新規生成 | 常に適用 |
| BR-002 | ID参照更新 | プロンプト内のID参照もidMapで置換 | TextGenerationノードがある場合 |
| BR-003 | 並列実行 | 複数テンプレートは並列で処理 | 常に適用 |
| BR-004 | 必須設定 | sampleAppWorkspaceIdsが必須 | 常に適用 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| テンプレート取得 | ストレージ | SELECT | 各テンプレートのworkspace.json |
| ワークスペース保存 | ストレージ | INSERT | 新しいworkspace.json |
| ファイルコピー | ストレージ | INSERT | 関連ファイルをコピー |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| CONFIG_ERROR | 設定エラー | sampleAppWorkspaceIdsが未設定または空 | 設定の確認 |
| NOT_FOUND | テンプレート未存在 | 指定テンプレートが存在しない | テンプレートIDの確認 |
| INVALID_CONNECTION | 接続不整合 | 接続のID参照が解決できない | テンプレートデータの修復 |

### リトライ仕様

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

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

Promise.allによる並列処理のため、部分的な失敗が発生する可能性がある。全体のロールバック機構は備えていない。

## パフォーマンス要件

- レスポンス時間: テンプレート数×ファイル数に依存
- 並列処理: 複数テンプレートの同時処理で効率化

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

- テンプレートワークスペースは公開されている必要がある
- 生成されたワークスペースは呼び出し元のチームに所属

## 備考

- copyWorkspaceと異なり、トリガー設定は複製しない（サンプルはトリガー未設定状態）
- idMapを返却することで、呼び出し元でID変換の追跡が可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | base.ts | `packages/protocol/src/node/base.ts` | NodeId, InputId, OutputIdの生成 |
| 1-2 | connection.ts | `packages/protocol/src/connection.ts` | ConnectionIdとConnection構造 |

**読解のコツ**: createIdGeneratorによる各種ID生成パターンを理解する。

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

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

**主要処理フロー**:
1. **159-169行目**: createSampleWorkspaces関数（エクスポートされるメイン関数）
2. **162-168行目**: sampleAppWorkspaceIdsの存在確認
3. **171-178行目**: Promise.allで各テンプレートを並列処理

#### Step 3: テンプレート複製処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | create-sample-workspace.ts | `packages/giselle/src/workspaces/create-sample-workspace.ts` | createSampleWorkspaceFromTemplate関数（17-151行目） |

**主要処理フロー**:
- **21-24行目**: テンプレートワークスペース取得
- **25行目**: idMapの初期化
- **26-54行目**: ノード・入出力のID再生成
- **55-83行目**: 接続のID再生成
- **85-97行目**: UI状態のノードID更新
- **98行目**: 新ワークスペースID生成
- **100-122行目**: プロンプト内のID参照更新
- **124-145行目**: ワークスペース構築と保存

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

```
createSampleWorkspaces (create-sample-workspace.ts)
    │
    └─ Promise.all
           │
           └─ createSampleWorkspaceFromTemplate
                  │
                  ├─ getWorkspace (utils.ts)
                  │
                  ├─ NodeId.generate
                  ├─ InputId.generate
                  ├─ OutputId.generate
                  ├─ ConnectionId.generate
                  ├─ WorkspaceId.generate
                  │
                  ├─ setWorkspace (utils.ts)
                  │
                  └─ copyFiles (utils.ts)
```

### データフロー図

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

sampleAppWorkspaceIds
        │
        ▼
    Promise.all ───▶ 各テンプレート処理
        │
        ├─────────────────────────────────────────────┐
        ▼                                             │
    getWorkspace ───▶ templateWorkspace               │
        │                                             │
        ▼                                             │
    ID再生成処理                                      │
    ┌──────────┐                                      │
    │ idMap    │ ◀── 旧ID → 新ID マッピング          │
    └──────────┘                                      │
        │                                             │
        ▼                                             │
    接続・UI・プロンプト更新                          │
        │                                             │
        ▼                                             │
    ┌───────────────────┐                             │
    │ 並列実行           │                             │
    │ - setWorkspace    │                             │
    │ - copyFiles       │                             │
    └───────────────────┘                             │
        │                                             │
        └─────────────────────────────────────────────┘
        │
        ▼
    SampleWorkspaceResult[]
    - workspace
    - templateWorkspaceId
    - idMap
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| create-sample-workspace.ts | `packages/giselle/src/workspaces/create-sample-workspace.ts` | ソース | メイン機能実装 |
| utils.ts | `packages/giselle/src/workspaces/utils.ts` | ソース | getWorkspace, setWorkspace, copyFiles |
| base.ts | `packages/protocol/src/node/base.ts` | ソース | NodeId, InputId, OutputId生成 |
| connection.ts | `packages/protocol/src/connection.ts` | ソース | ConnectionId生成 |
| index.ts | `packages/protocol/src/workspace/index.ts` | ソース | WorkspaceId生成 |
