# 画面設計書 17-ワークフローエディタ画面

## 概要

本ドキュメントは、Giselle Studio の「ワークフローエディタ画面」に関する画面設計書である。React Flowベースのビジュアルエディタで、AIワークフローのノード・接続を視覚的に編集する画面を定義する。

### 本画面の処理概要

**業務上の目的・背景**：ノーコード/ローコードでAIワークフローを構築できるビジュアルエディタを提供する。テキスト生成、画像生成、トリガー、アクションなど様々なノードを配置し、接続することでワークフローを設計できる。

**画面へのアクセス方法**：ワークスペース一覧画面からワークスペースを選択、または直接URLでアクセス。

**主要な操作・処理内容**：
1. ノードの追加・編集・削除（テキスト生成、画像生成、トリガー、アクション、クエリなど）
2. ノード間の接続の作成・削除
3. ワークスペース名の変更
4. ワークフローの保存
5. トリガーの設定（手動、GitHub連携など）
6. アプリとして公開

**画面遷移**：
- 遷移元：ワークスペース一覧画面（/workspaces）
- 遷移先：プレイグラウンド画面（/playground）、各種設定画面

**権限による表示制御**：ワークスペースが属するチームのメンバーのみアクセス可能。非メンバーの場合は404を返す。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | ワークスペース取得 | 主機能 | 指定されたワークスペースデータの読み込みと表示 |
| 3 | ワークスペース更新 | 主機能 | ノード、接続、UI状態の更新保存処理 |
| 6 | テキスト生成ノード | 補助機能 | AIモデルを使用したテキスト生成ノードの追加・編集 |
| 7 | 画像生成ノード | 補助機能 | AIモデルを使用した画像生成ノードの追加・編集 |
| 8 | トリガーノード | 補助機能 | ワークフローの開始点トリガーノードの追加・編集 |
| 9 | アクションノード | 補助機能 | GitHub API操作などのアクションノードの追加・編集 |
| 10 | クエリノード | 補助機能 | ベクトルストアクエリノードの追加・編集 |
| 11 | データクエリノード | 補助機能 | データストアクエリノードの追加・編集 |
| 12 | アプリエントリーノード | 補助機能 | 公開アプリケーションのエントリーポイントノードの追加・編集 |
| 13 | 終了ノード | 補助機能 | ワークフロー終点ノードの追加・編集 |
| 14 | テキストノード | 補助機能 | テキスト変数ノードの追加・編集 |
| 15 | ファイルノード | 補助機能 | ファイル変数ノードの追加・編集 |
| 16 | GitHubノード | 補助機能 | GitHubリポジトリ関連変数ノードの追加・編集 |
| 17 | ベクトルストアノード | 補助機能 | ベクトルストア参照変数ノードの追加・編集 |
| 18 | Webページノード | 補助機能 | Webページスクレイピング変数ノードの追加・編集 |
| 19 | データストアノード | 補助機能 | データストア参照変数ノードの追加・編集 |
| 33 | トリガー設定 | API連携 | ワークフローのトリガー設定処理 |
| 60 | アプリ保存 | API連携 | ワークフローをアプリとして保存・公開 |
| 63 | ファイルアップロード | API連携 | ワークスペースへのファイルアップロード処理 |
| 67 | シークレット追加 | API連携 | ワークスペースへのシークレット追加処理 |
| 81 | 言語モデルプロバイダ取得 | API連携 | 利用可能な言語モデルプロバイダの一覧取得 |
| 93 | ワークフローデザイナー | 主機能 | React Flowベースのビジュアルワークフロー編集UI |

## 画面種別

エディタ画面

## URL/ルーティング

`/workspaces/[workspaceId]`

- `[workspaceId]`: ワークスペースID（WorkspaceId型、例: `wrks_xxx`）

## 入出力項目

| 項目名 | 項目ID | 入出力 | 必須 | データ型 | 制約・バリデーション |
|--------|--------|--------|------|----------|---------------------|
| ワークスペースID | workspaceId | 入力（URLパラメータ） | 必須 | WorkspaceId | 有効なWorkspaceId形式 |
| ワークスペース名 | name | 入力（編集可能） | 任意 | string | 最大文字数制限なし |
| ノード配列 | nodes | 入出力 | 必須 | Node[] | Zod バリデーション |
| 接続配列 | connections | 入出力 | 必須 | Connection[] | Zod バリデーション |

## 表示項目

| 項目名 | 説明 | データソース |
|--------|------|-------------|
| ワークフローキャンバス | ノードと接続を表示するReact Flowキャンバス | Workspace.nodes, Workspace.connections |
| ノードパレット | 追加可能なノードタイプの一覧 | 固定リスト |
| ワークスペース名 | 編集可能なワークスペース名 | Workspace.name |
| チーム情報 | チーム名とアバター | workspaceTeam |
| トリガー設定パネル | トリガーの設定UI | Trigger関連データ |
| プロパティパネル | 選択中ノードのプロパティ編集UI | 選択ノードデータ |

## イベント仕様

### 1-ノード追加

**トリガー**: ノードパレットからドラッグ&ドロップ、またはクリック

**処理フロー**:
1. 選択されたノードタイプのインスタンスを作成
2. キャンバス上の指定位置にノードを配置
3. ローカルステートを更新
4. 自動保存（デバウンス付き）

### 2-ノード接続

**トリガー**: ノードのアウトプットポートからインプットポートへドラッグ

**処理フロー**:
1. 接続の妥当性を検証
2. Connection オブジェクトを作成
3. ローカルステートを更新
4. 自動保存

### 3-ワークスペース保存

**トリガー**: 編集操作後の自動保存、または明示的な保存操作

**処理フロー**:
1. workspaceSaveAction Server Action を呼び出し
2. assertWorkspaceAccess でアクセス権検証
3. giselle.updateWorkspace でワークスペースを更新

### 4-ワークスペース名変更

**トリガー**: ワークスペース名フィールドの編集

**処理フロー**:
1. workspaceNameUpdateAction Server Action を呼び出し
2. assertWorkspaceAccess でアクセス権検証
3. agents テーブルと workspaces テーブルの name を更新

### 5-トリガー設定

**トリガー**: トリガーノードの設定変更

**処理フロー**:
1. triggerUpdateAction Server Action を呼び出し
2. flowTriggers テーブルへ挿入または更新

### 6-GitHub連携状態更新

**トリガー**: 連携状態リフレッシュ要求

**処理フロー**:
1. integrationRefreshAction Server Action を呼び出し
2. getGitHubIntegrationState でGitHub連携状態を取得
3. UIに反映

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ワークスペース保存 | workspaces | UPDATE | SDK経由でワークスペースデータ更新 |
| 名前変更 | agents | UPDATE | エージェント名更新 |
| 名前変更 | workspaces | UPDATE | ワークスペース名更新 |
| トリガー設定 | flowTriggers | INSERT/UPDATE | トリガー設定の保存 |

### テーブル別更新項目詳細

#### agents

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | name | 入力されたワークスペース名 | WHERE workspaceId = 対象ID |

#### workspaces

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | name | 入力されたワークスペース名 | WHERE id = 対象ID |

#### flowTriggers

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | teamDbId | ワークスペースのチームID | - |
| INSERT/UPDATE | sdkFlowTriggerId | トリガーID | - |
| INSERT/UPDATE | sdkWorkspaceId | ワークスペースID | - |
| INSERT/UPDATE | staged | manualトリガーの場合のstaged値 | - |

## メッセージ仕様

| 種別 | メッセージID | メッセージ内容 | 表示条件 |
|------|-------------|---------------|----------|
| エラー | workspace_mismatch | Workspace ID mismatch | 保存時にIDが一致しない場合 |

## 例外処理

| 例外状況 | 処理内容 | ユーザーへの通知 |
|---------|---------|----------------|
| 無効なワークスペースID | notFound() | 404ページ表示 |
| エージェント未発見 | notFound() | 404ページ表示 |
| チームメンバーでない | notFound() | 404ページ表示 |
| ワークスペースID不一致 | エラーをスロー | エラー表示 |

## 備考

- React Flow ベースのビジュアルエディタを内部パッケージ（@giselle-internal/workflow-designer-ui）で実装
- Zustand を使用したステート管理（EditorStore）
- 機能フラグにより利用可能な機能を制御（webSearchAction, generateContentNode, structuredOutput など）
- 使用量制限（usageLimits）に基づく機能制限
- generationTimeout は 3600000ms（1時間）に設定

---

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

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

### 推奨読解順序

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

ワークスペースとノードのデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | protocol | `packages/protocol/src/workspace/` | Workspace, Node, Connection の型定義 |
| 1-2 | data-loader.ts | `apps/studio.giselles.ai/app/workspaces/[workspaceId]/data-loader.ts` | LoaderData 型の構造（32-147行目） |

**読解のコツ**: dataLoader関数は複数のデータソースから情報を集約し、クライアントに必要なすべてのデータを返す。

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

Server Componentとサーバーアクションの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | page.tsx | `apps/studio.giselles.ai/app/workspaces/[workspaceId]/page.tsx` | パラメータ検証（30-36行目）、Server Actions定義（47-114行目） |

**主要処理フロー**:
1. **30-36行目**: WorkspaceId.safeParse でパラメータ検証
2. **38-41行目**: generateContentNodeFlag で機能フラグ確認
3. **47-59行目**: integrationRefreshAction でGitHub連携状態取得
4. **60-92行目**: triggerUpdateAction でトリガー設定保存
5. **93-105行目**: workspaceNameUpdateAction で名前更新
6. **106-114行目**: workspaceSaveAction でワークスペース保存

#### Step 3: クライアントコンポーネントを理解する

エディタUIの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | page.client.tsx | `apps/studio.giselles.ai/app/workspaces/[workspaceId]/page.client.tsx` | プロバイダ構成（34-98行目） |

**主要処理フロー**:
- **30-32行目**: dataLoaderからデータ取得、GiselleClient作成
- **35行目**: GiselleClientProvider でAPI クライアント提供
- **36-41行目**: AppDesignerProvider で保存機能・初期データ提供
- **42-88行目**: WorkspaceProvider で各種設定・状態を提供
- **89-95行目**: Editor コンポーネントをレンダリング

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

```
page.tsx (Server Component)
    │
    ├─ WorkspaceId.safeParse() ─── パラメータ検証
    │
    ├─ generateContentNodeFlag() ─── 機能フラグ
    │
    └─ Page (Client Component) ─── page.client.tsx
           │
           ├─ dataLoader() ─── data-loader.ts
           │      │
           │      ├─ db.query.agents.findFirst()
           │      ├─ fetchCurrentUser()
           │      ├─ isMemberOfTeam()
           │      ├─ getGitHubIntegrationState()
           │      ├─ fetchWorkspaceTeam()
           │      ├─ getUsageLimitsForTeam()
           │      ├─ giselle.getWorkspace()
           │      ├─ getGitHubRepositoryIndexes()
           │      ├─ getDocumentVectorStores()
           │      └─ getTeamDataStores()
           │
           ├─ GiselleClientProvider
           │
           ├─ AppDesignerProvider
           │      └─ workspaceSaveAction()
           │
           ├─ WorkspaceProvider
           │      │
           │      ├─ integration
           │      ├─ vectorStore
           │      ├─ usageLimits
           │      ├─ dataStore
           │      ├─ telemetry
           │      ├─ featureFlag
           │      └─ trigger
           │
           └─ Editor ─── @giselle-internal/workflow-designer-ui
```

### データフロー図

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

workspaceId(URL) ───────▶ dataLoader() ─────────────▶ LoaderData
                               │
                               ├─ workspace
                               ├─ agent
                               ├─ integrations
                               ├─ vectorStores
                               ├─ dataStores
                               ├─ llmProviders
                               └─ featureFlags
                                      │
                                      ▼
                               WorkspaceProvider
                                      │
ユーザー編集 ────────────▶ EditorStore(Zustand) ────▶ ローカル状態
                                      │
                                      ▼
                          workspaceSaveAction() ────▶ DB更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `apps/studio.giselles.ai/app/workspaces/[workspaceId]/page.tsx` | ソース | ページエントリーポイント（Server Component） |
| page.client.tsx | `apps/studio.giselles.ai/app/workspaces/[workspaceId]/page.client.tsx` | ソース | クライアントコンポーネント |
| data-loader.ts | `apps/studio.giselles.ai/app/workspaces/[workspaceId]/data-loader.ts` | ソース | データローダー |
| Editor | `internal-packages/workflow-designer-ui/src/editor/` | ソース | ワークフローエディタUI |
| WorkspaceProvider | `packages/react/src/workspace/provider.tsx` | ソース | ワークスペースコンテキストプロバイダ |
| AppDesignerProvider | `internal-packages/workflow-designer-ui/src/app-designer/` | ソース | アプリデザイナーコンテキスト |
