# 機能設計書 86-Giselleクライアント

## 概要

本ドキュメントは、Giselleプラットフォームにおけるリアクティブクライアントインターフェースの設計を定義する。GiselleClientは、ReactアプリケーションからGiselle APIを呼び出すための統一されたクライアントインターフェースを提供し、タスク実行、生成操作、ファイル管理、トリガー設定などの機能をクライアント側から利用可能にする。

### 本機能の処理概要

**業務上の目的・背景**：Giselleのフロントエンドアプリケーション（ワークフローエディタ、プレイグラウンド等）からバックエンドAPIを呼び出す際、型安全で一貫性のあるインターフェースが必要となる。GiselleClientは、Giselle（サーバー側）の各メソッドに対応するクライアント側のメソッドを定義し、HTTPリクエストの抽象化とTypeScript型の提供を行う。

**機能の利用シーン**：
- ワークフローエディタでタスクを作成・開始する場合
- プレイグラウンドで生成処理を実行する場合
- ファイルのアップロード・削除を行う場合
- トリガーの設定・取得を行う場合
- シークレットの追加・削除を行う場合

**主要な処理内容**：
1. アプリ管理: getApp、saveApp、deleteApp
2. タスク管理: createTask、startTask、getWorkspaceInprogressTask、getTaskGenerationIndexes、getWorkspaceTasks
3. 生成管理: getGeneration、getNodeGenerations、cancelGeneration、setGeneration、generateImage、startContentGeneration、getGenerationMessageChunks
4. トリガー管理: resolveTrigger、configureTrigger、getTrigger、setTrigger、reconfigureGitHubTrigger
5. ファイル管理: uploadFile、removeFile、copyFile、getFileText、addWebPage
6. シークレット管理: addSecret、deleteSecret、getWorkspaceSecrets

**関連システム・外部連携**：
- Giselle HTTP API
- Next.js App Router

**権限による制御**：各API呼び出しは、バックエンド側の認証・認可に従う。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主機能 | 各種API呼び出しのクライアント実装 |
| 18 | プレイグラウンド画面 | 主機能 | タスク作成・開始のクライアント呼び出し |

## 機能種別

APIクライアントインターフェース

## 入力仕様

### 入力パラメータ

GiselleClientの各メソッドは、対応するGiselleサーバーメソッドのパラメータ型を使用する。

| メソッドカテゴリ | メソッド名 | パラメータ型 | 説明 |
|----------------|-----------|-------------|------|
| apps | getApp | Giselle["getApp"]の入力 | アプリ取得 |
| apps | saveApp | Giselle["saveApp"]の入力 | アプリ保存 |
| apps | deleteApp | Giselle["deleteApp"]の入力 | アプリ削除 |
| tasks | createTask | Giselle["createTask"]の入力 | タスク作成 |
| tasks | startTask | Giselle["startTask"]の入力 | タスク開始 |
| generations | getGeneration | { generationId: GenerationId } | 生成取得 |
| generations | cancelGeneration | { generationId: GenerationId } | 生成キャンセル |
| files | uploadFile | FormData | ファイルアップロード |
| files | removeFile | { workspaceId, fileId } | ファイル削除 |
| secrets | addSecret | Giselle["addSecret"]の入力 | シークレット追加 |

### 入力データソース

- React UIコンポーネントからの呼び出し
- Zustandストアからのアクション

## 出力仕様

### 出力データ

| メソッドカテゴリ | メソッド名 | 戻り値型 | 説明 |
|----------------|-----------|---------|------|
| apps | getApp | { app: App } | アプリ情報 |
| tasks | createTask | Task | 作成されたタスク |
| tasks | getWorkspaceInprogressTask | { task: Task \| undefined } | 進行中タスク |
| generations | getGeneration | Generation | 生成情報 |
| triggers | getTrigger | { trigger: Trigger } | トリガー情報 |

### 出力先

- React UIコンポーネントへの返却
- Zustandストアへの状態更新

## 処理フロー

### 処理シーケンス

```
1. Reactコンポーネントからメソッド呼び出し
   └─ 例: client.createTask({ ... })
2. HTTPリクエスト構築
   └─ パラメータをJSON化してPOSTリクエスト作成
3. APIエンドポイントへリクエスト送信
   └─ /api/giselle/{メソッド名}
4. レスポンス受信
   └─ JSONレスポンスをパース
5. 結果返却
   └─ 型安全なオブジェクトとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[Reactコンポーネント] --> B[GiselleClientメソッド呼び出し]
    B --> C[パラメータ変換]
    C --> D[HTTPリクエスト送信]
    D --> E[/api/giselle/endpoint]
    E --> F[Giselleサーバー処理]
    F --> G[JSONレスポンス]
    G --> H[型変換]
    H --> I[結果返却]
    I --> A
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-86-01 | 型整合性 | クライアントメソッドの型はサーバーメソッドの型と整合すること | 常時 |
| BR-86-02 | 非同期処理 | すべてのメソッドはPromiseを返却 | 常時 |
| BR-86-03 | ファイルアップロード | uploadFileはFormDataを使用 | ファイルアップロード時 |

### 計算ロジック

特になし。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | クライアント側ではデータベース操作なし |

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

クライアント側ではデータベースアクセスは発生しない。実際のデータベース操作はサーバー側で行われる。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 400 | Bad Request | リクエストパラメータ不正 | パラメータを確認して再送信 |
| 401 | Unauthorized | 認証エラー | 再ログインを促す |
| 500 | Internal Server Error | サーバーエラー | エラーログを確認 |

### リトライ仕様

リトライは呼び出し元で実装する（クライアント自体にはリトライ機能なし）。

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

クライアント側ではトランザクション管理は不要。

## パフォーマンス要件

- メソッド呼び出しオーバーヘッド: < 1ms
- ネットワークレイテンシは環境依存

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

- すべてのAPI呼び出しは認証が必要
- シークレット値はHTTPS経由で送信
- クライアント側でシークレット値をログに出力しない

## 備考

- GiselleClientはインターフェースのみを定義し、実装はアプリケーション側で行う
- Giselleサーバーの各メソッドに対応するクライアントメソッドを提供

---

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

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

### 推奨読解順序

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

GiselleClientインターフェースの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | giselle-client.ts | `packages/react/src/giselle-client.ts` | GiselleClientインターフェース全体の構造 |

**読解のコツ**: 各メソッドの引数型にGiselle["メソッド名"]のParameters型を使用し、サーバー側との型整合性を保っている。

#### Step 2: カテゴリ別のメソッドを理解する

各カテゴリのメソッドを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | giselle-client.ts | `packages/react/src/giselle-client.ts` | apps関連メソッド（17-22行目） |
| 2-2 | giselle-client.ts | `packages/react/src/giselle-client.ts` | tasks関連メソッド（24-35行目） |
| 2-3 | giselle-client.ts | `packages/react/src/giselle-client.ts` | generations関連メソッド（37-60行目） |
| 2-4 | giselle-client.ts | `packages/react/src/giselle-client.ts` | triggers関連メソッド（62-87行目） |
| 2-5 | giselle-client.ts | `packages/react/src/giselle-client.ts` | files関連メソッド（89-105行目） |
| 2-6 | giselle-client.ts | `packages/react/src/giselle-client.ts` | secrets関連メソッド（107-114行目） |

**主要処理フロー**:
- **17-22行目**: アプリ管理（getApp、saveApp、deleteApp）
- **24-35行目**: タスク管理（createTask、startTask、getWorkspaceInprogressTask等）
- **37-60行目**: 生成管理（getGeneration、cancelGeneration、generateImage等）
- **62-87行目**: トリガー管理（resolveTrigger、configureTrigger、getTrigger等）
- **89-105行目**: ファイル管理（uploadFile、removeFile、copyFile等）
- **107-114行目**: シークレット管理（addSecret、deleteSecret、getWorkspaceSecrets）

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

```
React Component
    │
    ├─ GiselleClient.createTask()
    │      │
    │      └─ HTTP POST /api/giselle/createTask
    │             │
    │             └─ jsonRoutes.createTask (router.ts)
    │                    │
    │                    └─ giselle.createTask()
    │
    └─ GiselleClient.getGeneration()
           │
           └─ HTTP POST /api/giselle/getGeneration
                  │
                  └─ jsonRoutes.getGeneration (router.ts)
                         │
                         └─ giselle.getGeneration()
```

### データフロー図

```
[クライアント]                [サーバー]

React Component
       │
       ▼
GiselleClient
       │
       ▼
HTTP Request ─────────────▶ NextGiselle (httpHandler)
                                  │
                                  ▼
                            jsonRoutes
                                  │
                                  ▼
                            Giselle API
                                  │
                                  ▼
HTTP Response ◀───────────── JSON Response
       │
       ▼
Zustand Store / UI Update
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| giselle-client.ts | `packages/react/src/giselle-client.ts` | ソース | GiselleClientインターフェース定義 |
| giselle.ts | `packages/giselle/src/giselle.ts` | ソース | サーバー側Giselle実装 |
| router.ts | `packages/http/src/router.ts` | ソース | HTTPルーティング定義 |
| next-giselle-engine.ts | `packages/nextjs/src/next-giselle-engine.ts` | ソース | Next.js統合HTTPハンドラー |
