# 機能設計書 88-生成ストア

## 概要

本ドキュメントは、Giselleプラットフォームにおける生成結果の状態管理ストアの設計を定義する。生成ストアは、Zustandを使用したReact向けのグローバル状態管理ストアであり、AIモデルによる生成結果（Generation）とそのメッセージの状態を管理する。

### 本機能の処理概要

**業務上の目的・背景**：ワークフロー実行中、複数のノードで生成処理が実行され、それぞれの結果と進行状況をリアルタイムにUI上で表示する必要がある。生成ストアは、各生成の状態（作成済み、キュー済み、実行中、完了、失敗）とストリーミングメッセージを管理し、ワークフローエディタやプレイグラウンドで生成結果を表示するための状態を提供する。

**機能の利用シーン**：
- テキスト生成ノードの実行結果をリアルタイム表示する場合
- 生成中のストリーミングメッセージを逐次表示する場合
- 複数の生成処理の進行状況を追跡する場合
- 生成結果の履歴を表示する場合

**主要な処理内容**：
1. generations: 生成オブジェクトの配列を保持
2. setGenerations: 生成配列全体を設定
3. addGenerationRunner: 新しい生成を追加（重複IDは上書き）
4. updateGeneration: 既存の生成を更新
5. updateMessages: 生成のメッセージ配列を更新
6. upsertMessage: 単一メッセージを挿入または更新

**関連システム・外部連携**：
- Zustand（状態管理ライブラリ）
- @giselles-ai/protocol（Generation型、GenerationId型）
- Vercel AI SDK（UIMessage型）

**権限による制御**：権限制御なし（クライアント側の状態管理のみ）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主機能 | 生成結果の表示 |
| 18 | プレイグラウンド画面 | 主機能 | リアルタイム生成表示 |
| 20 | タスク詳細画面 | 参照画面 | 生成履歴の表示 |

## 機能種別

状態管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| generations | Generation[] | No | 設定する生成配列 | - |
| generation | Generation | No | 追加/更新する生成 | - |
| id | GenerationId | No | 対象の生成ID | - |
| messages | UIMessage[] | No | 更新するメッセージ配列 | - |
| message | UIMessage | No | 挿入/更新するメッセージ | - |

### 入力データソース

- Reactコンポーネントからのアクション呼び出し
- GiselleClientからの生成結果

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| generations | Generation[] | 全生成結果の配列 |
| setGenerations | function | 生成配列全体を設定 |
| addGenerationRunner | function | 新しい生成を追加 |
| updateGeneration | function | 既存の生成を更新 |
| updateMessages | function | メッセージ配列を更新 |
| upsertMessage | function | 単一メッセージを挿入/更新 |

### 出力先

- Reactコンポーネントへの状態提供

## 処理フロー

### 処理シーケンス

```
1. ストア初期化
   └─ generations: []
2. 生成開始
   └─ addGenerationRunner(generation)
3. ストリーミング受信
   └─ upsertMessage(id, message) 繰り返し
4. 生成完了
   └─ updateGeneration(completedGeneration)
5. メッセージ更新
   └─ updateMessages(id, messages)
```

### フローチャート

```mermaid
flowchart TD
    A[初期状態: generations = []] --> B{生成開始?}
    B -->|Yes| C[addGenerationRunner]
    C --> D[generations配列に追加]
    D --> E{ストリーミング?}
    E -->|Yes| F[upsertMessage]
    F --> G[メッセージ追加/更新]
    G --> E
    E -->|No| H{生成完了?}
    H -->|Yes| I[updateGeneration]
    I --> J[生成状態更新]
    J --> A
    H -->|No| E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-88-01 | ID重複排除 | addGenerationRunnerは既存IDを上書き | 生成追加時 |
| BR-88-02 | 実行中チェック | upsertMessageは実行中の生成のみ更新 | メッセージ挿入時 |
| BR-88-03 | 初期値 | generationsは空配列で初期化 | ストア初期化時 |

### 計算ロジック

特になし。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | クライアント側メモリ管理のみ |

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

データベースアクセスは発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | - | 実行中でない生成へのupsertMessage | 状態を変更せず返却 |

### リトライ仕様

リトライ不要（同期的な状態更新のみ）

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

トランザクション管理は不要（クライアント側メモリ管理のみ）

## パフォーマンス要件

- 状態更新: < 1ms
- ストリーミング更新: 高頻度更新に対応
- Zustandのセレクタによる再レンダリング最適化

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

- 生成データにはセンシティブな情報が含まれる可能性があるため、適切なデータハンドリングが必要
- クライアント側でのデータ永続化は行わない

## 備考

- isRunningGeneration関数で実行中かどうかを判定
- UIMessage型はVercel AI SDKの型を使用
- メッセージのIDによる重複チェックを実装

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | store.ts | `packages/react/src/generations/store.ts` | GenerationStoreインターフェース定義（9-16行目） |

**読解のコツ**: Zustandストアのパターン。Generation配列と5つのアクションメソッドを定義。

#### Step 2: 各アクションの実装を理解する

各アクションメソッドの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | store.ts | `packages/react/src/generations/store.ts` | setGenerations（20-23行目） |
| 2-2 | store.ts | `packages/react/src/generations/store.ts` | addGenerationRunner（24-34行目） |
| 2-3 | store.ts | `packages/react/src/generations/store.ts` | updateGeneration（35-40行目） |
| 2-4 | store.ts | `packages/react/src/generations/store.ts` | updateMessages（41-52行目） |
| 2-5 | store.ts | `packages/react/src/generations/store.ts` | upsertMessage（54-78行目） |

**主要処理フロー**:
- **20-23行目**: setGenerations - 生成配列全体を置換
- **24-34行目**: addGenerationRunner - 既存IDをフィルタして新規追加
- **35-40行目**: updateGeneration - IDマッチする生成を更新
- **41-52行目**: updateMessages - IDマッチする生成のメッセージを更新
- **54-78行目**: upsertMessage - メッセージIDでマッチして挿入または更新

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

```
React Component
    │
    └─ useGenerationStore()
           │
           ├─ generations (状態参照)
           │
           ├─ setGenerations() (状態更新)
           │
           ├─ addGenerationRunner() (生成追加)
           │
           ├─ updateGeneration() (生成更新)
           │
           ├─ updateMessages() (メッセージ更新)
           │
           └─ upsertMessage() (メッセージ挿入/更新)
```

### データフロー図

```
[コンポーネント]              [GenerationStore]

生成開始
       │
       ▼
addGenerationRunner(gen) ────▶ generations: [...existing, gen]
       │
       ▼
ストリーミング受信 ×N
       │
       ▼
upsertMessage(id, msg) ──────▶ generations[id].messages.push(msg)
       │
       ▼
生成完了
       │
       ▼
updateGeneration(gen) ───────▶ generations[id] = completedGen
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| store.ts | `packages/react/src/generations/store.ts` | ソース | GenerationStore定義と実装 |
| index.ts | `packages/react/src/generations/index.ts` | ソース | エクスポート |
