# 機能設計書 18-Deep Modelingワークフロー

## 概要

本ドキュメントは、LangGraphベースのAIエージェントによるスキーマ分析・設計支援を行う「Deep Modelingワークフロー」機能の設計を記述する。

### 本機能の処理概要

**業務上の目的・背景**：データベーススキーマ設計は専門知識と経験を必要とする複雑なタスクである。本機能は、AIエージェントが複数の専門役割（PM、DB設計、QA）を協調して動作させることで、ユーザーの要件からスキーマ設計、テストケース生成までを一貫してサポートする。

**機能の利用シーン**：
- デザインセッション画面でのAIとの対話形式によるスキーマ設計
- 自然言語による要件からの自動スキーマ生成
- 設計したスキーマの検証とテストケース生成

**主要な処理内容**：
1. ユーザー入力の受付とワークフロー状態の初期化
2. Lead Agentによる次のアクション決定
3. PM Agentによる要件分析と構造化
4. DB Agentによるスキーマ設計とマイグレーション操作生成
5. QA Agentによるテストケース生成と検証
6. ストリーミング応答によるリアルタイムフィードバック

**関連システム・外部連携**：
- OpenAI API（GPT-4等のLLMモデル）
- Supabaseチェックポイント永続化（No.24）
- マイグレーション操作生成（No.13）

**権限による制御**：認証済みユーザーのみがデザインセッションを作成・実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | デザインセッション詳細画面 | 主機能 | LangGraphベースのAIエージェントによるスキーマ分析・設計支援 |

## 機能種別

AIワークフロー制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| messages | BaseMessage[] | Yes | ユーザーとの対話履歴 | 空でないこと |
| schemaData | Schema | No | 既存のスキーマ情報 | Schema型に準拠 |
| designSessionId | string | Yes | デザインセッションID | 有効なUUID |
| recursionLimit | number | No | ワークフローの再帰制限 | デフォルト: 50 |

### 入力データソース

- デザインセッション画面からのユーザー入力
- Supabaseに保存されたセッション状態

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| messages | BaseMessage[] | AIからの応答メッセージ |
| schemaData | Schema | 更新されたスキーマ情報 |
| analyzedRequirements | AnalyzedRequirements | 分析された要件情報 |
| schemaIssues | SchemaIssue[] | 検出されたスキーマの問題 |

### 出力先

- ストリーミング応答としてフロントエンドに送信
- Supabaseにチェックポイントとして永続化

## 処理フロー

### 処理シーケンス

```
1. ワークフロー状態の初期化
   └─ setupWorkflowState()で初期状態を構築
2. 初期スキーマの検証（オプション）
   └─ isEmptySchema()でスキーマ有無を確認
3. Lead Agentによる分岐決定
   └─ ユーザー入力を分析して次のエージェントを決定
4. PM Agentによる要件分析
   └─ ユーザー要件を構造化して保存
5. DB Agentによるスキーマ設計
   └─ 要件に基づいてスキーマを設計・更新
6. QA Agentによる検証
   └─ スキーマの妥当性確認とテストケース生成
7. Lead Agentへの戻りと終了判定
   └─ 追加処理の要否を判定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ワークフロー状態初期化]
    B --> C{初期スキーマあり?}
    C -->|Yes| D[validateInitialSchema]
    C -->|No| E[leadAgent]
    D --> E
    E --> F{次のアクション}
    F -->|pmAgent| G[PM Agent: 要件分析]
    F -->|dbAgent| H[DB Agent: スキーマ設計]
    F -->|END| I[終了]
    G --> H
    H --> J[QA Agent: 検証]
    J --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 初期スキーマ検証 | 既存スキーマがある場合は最初に検証を実行 | schemaDataが空でない場合 |
| BR-02 | エージェント順序 | PM → DB → QA の順序で処理 | pmAgentから開始した場合 |
| BR-03 | 再帰制限 | デフォルト50回の再帰制限を適用 | 常に適用 |
| BR-04 | QA再帰制限 | QA Agentには別途高い再帰制限を適用 | QA Agent実行時 |

### エージェント間状態共有

| 状態項目 | 共有範囲 | 説明 |
|---------|---------|------|
| messages | 全エージェント | 対話履歴 |
| schemaData | 全エージェント | 現在のスキーマ |
| analyzedRequirements | PM → DB | 分析された要件 |
| schemaIssues | QA → DB | 検出された問題 |

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| チェックポイント保存 | checkpoints | INSERT/UPDATE | ワークフロー状態の永続化 |
| チェックポイント読み込み | checkpoints | SELECT | ワークフロー状態の復元 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | GraphRecursionError | 再帰制限超過 | エラーメッセージを返却 |
| - | WorkflowTerminationError | ノード処理失敗 | エラーをキャッチしてログ出力 |
| - | LLM APIエラー | OpenAI API呼び出し失敗 | リトライポリシーに従い再試行 |

### リトライ仕様

- LLMノードには自動リトライポリシーを適用
- initialInterval: 1秒、backoffFactor: 2、maxAttempts: 3

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

- チェックポイント保存は各ノード完了時に自動実行
- ワークフロー全体のトランザクションは実装されていない

## パフォーマンス要件

- 初回応答：5秒以内にストリーミング開始
- 全体処理：複雑な要件でも60秒以内に完了

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

- APIキーはサーバーサイドで管理
- ユーザー入力はLLMに直接渡されるため、プロンプトインジェクション対策が必要
- セッションIDによるアクセス制御

## 備考

- LangGraph.jsのStateGraphを使用してワークフローを構築
- 各エージェントはサブグラフとして実装
- ストリーミング応答にはstreamEvents APIを使用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | workflowAnnotation.ts | `frontend/internal-packages/agent/src/workflowAnnotation.ts` | ワークフロー状態の定義 |
| 1-2 | types.ts | `frontend/internal-packages/agent/src/types.ts` | AgentWorkflowParams, WorkflowConfigurable等の型定義 |

**読解のコツ**: LangGraphのAnnotation.Root()でワークフロー状態を定義している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | deepModeling.ts | `frontend/internal-packages/agent/src/deepModeling.ts` | deepModeling関数のエントリーポイント |

**主要処理フロー**:
- **16-30行目**: deepModeling関数 - ワークフローのエントリーポイント
- **23-25行目**: createGraphでグラフを作成
- **27-29行目**: setupWorkflowStateとexecuteWorkflowWithTrackingで実行

#### Step 3: グラフ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | createGraph.ts | `frontend/internal-packages/agent/src/createGraph.ts` | メインワークフローグラフの構築 |

**主要処理フロー**:
- **21-26行目**: サブグラフの作成（leadAgent, pmAgent, dbAgent, qaAgent）
- **27-42行目**: callDbAgent関数 - DB Agentの呼び出しラッパー
- **44-52行目**: callQaAgent関数 - QA Agentの呼び出しラッパー
- **54-67行目**: callPmAgent関数 - PM Agentの呼び出しラッパー
- **69-106行目**: StateGraphの構築とノード・エッジの追加
- **76-95行目**: 条件付きエッジの定義

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

```
deepModeling(params, config)
    │
    ├─ createGraph(checkpointer)
    │      │
    │      ├─ createLeadAgentGraph()
    │      ├─ createPmAgentGraph()
    │      ├─ createDbAgentGraph()
    │      └─ createQaAgentGraph()
    │
    └─ setupWorkflowState(params, config)
           │
           └─ executeWorkflowWithTracking(compiled, setupResult, recursionLimit)
                  │
                  └─ graph.streamEvents(...)
                         │
                         ├─ validateInitialSchema [条件付き]
                         ├─ leadAgent
                         │      └─ 次のエージェントを決定
                         ├─ pmAgent [callPmAgent]
                         │      └─ 要件分析
                         ├─ dbAgent [callDbAgent]
                         │      └─ スキーマ設計
                         └─ qaAgent [callQaAgent]
                                └─ 検証・テスト生成
```

### データフロー図

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

ユーザーメッセージ ──▶ leadAgent ──▶ 次のエージェント決定
         │                              │
         │                    ┌─────────┴─────────┐
         │                    ▼                   ▼
         │              pmAgent                dbAgent
         │                │                       │
         │                ▼                       ▼
         │         analyzedRequirements     schemaData更新
         │                │                       │
         │                └───────────┬───────────┘
         │                            ▼
         │                        qaAgent
         │                            │
         │                            ▼
         └────────────────────▶ ストリーミング応答 ──▶ フロントエンド
                                      │
                                      ▼
                              Supabaseチェックポイント
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| deepModeling.ts | `frontend/internal-packages/agent/src/deepModeling.ts` | ソース | ワークフローエントリーポイント |
| createGraph.ts | `frontend/internal-packages/agent/src/createGraph.ts` | ソース | グラフ構築 |
| workflowAnnotation.ts | `frontend/internal-packages/agent/src/workflowAnnotation.ts` | ソース | ワークフロー状態定義 |
| types.ts | `frontend/internal-packages/agent/src/types.ts` | ソース | 型定義 |
| constants.ts | `frontend/internal-packages/agent/src/constants.ts` | ソース | 定数定義 |
| workflowSetup.ts | `frontend/internal-packages/agent/src/utils/workflowSetup.ts` | ソース | ワークフロー初期化 |
| validateInitialSchemaNode.ts | `frontend/internal-packages/agent/src/workflow/nodes/validateInitialSchemaNode.ts` | ソース | 初期スキーマ検証 |
