# 機能設計書 19-DB Agentサブグラフ

## 概要

本ドキュメントは、ReActパターンによる反復的なデータベーススキーマ設計を行う「DB Agentサブグラフ」機能の設計を記述する。

### 本機能の処理概要

**業務上の目的・背景**：データベーススキーマの設計は複雑で反復的なプロセスを必要とする。本機能は、AIがスキーマ設計を行い、ツール呼び出しを通じて実際のスキーマ変更を適用するReActパターンを実装することで、複数ステップにわたるスキーマ構築（例：users -> posts -> comments）を可能にする。

**機能の利用シーン**：
- Deep Modelingワークフローからのサブグラフ呼び出し
- PM Agentで分析された要件に基づくスキーマ設計
- 自然言語での指示に基づくテーブル・カラムの作成・変更

**主要な処理内容**：
1. designSchemaノードでAIによるスキーマ設計と次のアクション決定
2. invokeCreateMigrationToolノードでスキーマ変更の適用
3. ツール実行後はdesignSchemaに戻り反復的に設計を継続
4. AIがツール呼び出しを行わない場合に設計完了

**関連システム・外部連携**：
- OpenAI API（GPT-5-mini）
- マイグレーション操作生成（No.13）
- PostgreSQL DDL生成（No.14）
- PGlite（DDL検証用）

**権限による制御**：デザインセッションへのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | デザインセッション詳細画面 | 主機能 | AIによるスキーマ設計 |

## 機能種別

AIサブグラフ（ReActエージェント）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| messages | BaseMessage[] | Yes | 対話履歴 | 空でないこと |
| schemaData | Schema | Yes | 現在のスキーマ情報 | Schema型に準拠 |
| prompt | string | Yes | 設計指示プロンプト | 空でないこと |
| designSessionId | string | Yes | デザインセッションID | 有効なUUID |
| organizationId | string | Yes | 組織ID | 有効なUUID |
| userId | string | Yes | ユーザーID | 有効なUUID |

### 入力データソース

- 親グラフ（Deep Modelingワークフロー）からの状態引き継ぎ
- PM Agentで分析された要件（prompt経由）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| messages | BaseMessage[] | 更新された対話履歴 |
| schemaData | Schema | 更新されたスキーマ情報 |
| createMigrationSuccessful | boolean | マイグレーション成功フラグ |
| next | string | 次のノード指定（END等） |

### 出力先

- 親グラフへの状態返却
- ストリーミング応答としてフロントエンドに送信
- Supabaseにスキーマバージョンとして永続化

## 処理フロー

### 処理シーケンス

```
1. designSchemaノード実行
   └─ LLMにスキーマ設計を依頼
      └─ 現在のスキーマをYAMLで渡す
      └─ システムプロンプトとユーザー指示を組み合わせ
2. ルーティング判定（routeAfterDesignSchema）
   └─ ツール呼び出しあり → invokeCreateMigrationToolへ
   └─ ツール呼び出しなし → END（設計完了）
3. invokeCreateMigrationToolノード実行
   └─ createMigrationToolを実行
      └─ JSON Patch操作を適用
      └─ DDL生成・検証
      └─ スキーマバージョン作成
4. designSchemaノードに戻る（反復）
   └─ 追加のスキーマ変更が必要か判断
```

### フローチャート

```mermaid
flowchart TD
    A[START] --> B[designSchemaノード]
    B --> C{ツール呼び出しあり?}
    C -->|Yes| D[invokeCreateMigrationToolノード]
    C -->|No| E[END - 設計完了]
    D --> F{ツール実行成功?}
    F -->|Yes| G[スキーマ更新・バージョン作成]
    F -->|No| H[エラーメッセージ返却]
    G --> B
    H --> B
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ReActパターン | ツール呼び出し後は必ずdesignSchemaに戻る | 常に適用 |
| BR-02 | DDL検証 | スキーマ変更前にDDLを生成・実行して検証 | マイグレーションツール実行時 |
| BR-03 | バージョン管理 | スキーマ変更成功時に新バージョンを作成 | マイグレーション成功時 |
| BR-04 | 自律的設計 | 曖昧な指示でも合理的な仮定で設計を続行 | 常に適用 |

### createMigrationTool仕様

| 操作種別 | JSON Patch操作 | 対象 |
|---------|---------------|------|
| テーブル追加 | add | /tables/{tableName} |
| カラム追加 | add | /tables/{tableName}/columns/{columnName} |
| 制約追加 | add | /tables/{tableName}/constraints/{constraintName} |
| インデックス追加 | add | /tables/{tableName}/indexes/{indexName} |
| テーブル削除 | remove | /tables/{tableName} |
| カラム変更 | replace | /tables/{tableName}/columns/{columnName}/{property} |

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| スキーマ取得 | building_schemas | SELECT | 現在のスキーマ取得 |
| バージョン作成 | schema_versions | INSERT | 新バージョン作成 |
| DDL検証 | PGlite仮想DB | 実行 | DDLの構文・意味検証 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------
| - | WorkflowTerminationError | 設定取得失敗 | エラーをスローしてワークフロー終了 |
| - | DDL生成エラー | スキーマ不正 | エラーメッセージを返却、AIが修正を試行 |
| - | DDL実行エラー | SQL構文エラー | エラーメッセージを返却、AIが修正を試行 |
| - | バージョン作成エラー | DB書き込み失敗 | エラーをスローしてリトライ |

### リトライ仕様

- RETRY_POLICY適用
- initialInterval: 1秒
- backoffFactor: 2
- maxAttempts: 3

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

- DDL検証とバージョン作成は別トランザクション
- DDL検証はPGlite仮想DBで実行（本番DBには影響なし）

## パフォーマンス要件

- 単一ツール呼び出し：5秒以内
- 複数ステップ設計：各ステップ間でストリーミング応答

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

- LLM出力のJSON Patch操作はValibotでスキーマ検証
- DDLはPGlite仮想DBで検証後にバージョン保存
- 組織ID・ユーザーIDによるアクセス制御

## 備考

- GPT-5-miniモデルをreasoningモード（effort: low, summary: detailed）で使用
- tool_choice: autoでAIがツール使用を自律的に判断
- strictモードでツールスキーマを厳格に適用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | dbAgentAnnotation.ts | `frontend/internal-packages/agent/src/db-agent/shared/dbAgentAnnotation.ts` | サブグラフの状態定義 |

**読解のコツ**: Annotation.Root()でサブグラフ固有の状態（schemaData, next, createMigrationSuccessful等）を定義している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | createDbAgentGraph.ts | `frontend/internal-packages/agent/src/db-agent/createDbAgentGraph.ts` | サブグラフの構築 |

**主要処理フロー**:
- **24-26行目**: StateGraphの初期化とdbAgentAnnotationの適用
- **27-33行目**: designSchemaとinvokeCreateMigrationToolノードの追加（リトライポリシー付き）
- **35-42行目**: エッジの定義（START→designSchema、条件付きエッジ、ツール→designSchemaのループ）
- **44-47行目**: checkpointerの有無に応じたコンパイル

#### Step 3: 設計ノードを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | designSchemaNode.ts | `frontend/internal-packages/agent/src/db-agent/nodes/designSchemaNode.ts` | AIによるスキーマ設計 |

**主要処理フロー**:
- **18-26行目**: 設定取得とスキーマのYAML変換
- **30行目**: reasoningフィールドの除去（APIエラー回避）
- **32-42行目**: invokeDesignAgentでLLM呼び出し
- **50-55行目**: レスポンスを状態に追加

#### Step 4: ツール実行ノードを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | invokeCreateMigrationToolNode.ts | `frontend/internal-packages/agent/src/db-agent/nodes/invokeCreateMigrationToolNode.ts` | マイグレーションツールの実行 |

**主要処理フロー**:
- **56-65行目**: ToolNodeの作成とストリーム実行
- **87-98行目**: ツール成功時のスキーマ再取得
- **22-30行目**: wasCreateMigrationToolSuccessful関数でツール成功判定

#### Step 5: マイグレーションツールを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | createMigrationTool.ts | `frontend/internal-packages/agent/src/db-agent/tools/createMigrationTool.ts` | JSON Patch操作の適用とDDL検証 |

**主要処理フロー**:
- **112-186行目**: ツール本体の定義
- **125-134行目**: Valibotによる入力検証
- **146-157行目**: applyPatchOperationsでスキーマ変更
- **159行目**: validateAndExecuteDDLでDDL検証
- **166-179行目**: スキーマバージョン作成

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

```
createDbAgentGraph()
    │
    └─ StateGraph(dbAgentAnnotation)
           │
           ├─ designSchemaNode
           │      │
           │      ├─ getConfigurable(config)
           │      │
           │      ├─ yamlSchemaDeparser(schemaData)
           │      │
           │      └─ invokeDesignAgent(variables, messages, configurable)
           │             │
           │             ├─ contextPromptTemplate.format()
           │             │
           │             ├─ model.stream() [GPT-5-mini]
           │             │      └─ SystemMessage(SYSTEM_PROMPT)
           │             │      └─ HumanMessage(contextPrompt)
           │             │
           │             └─ streamLLMResponse()
           │
           ├─ routeAfterDesignSchema
           │      └─ hasToolCalls() → 'invokeCreateMigrationTool' | END
           │
           └─ invokeCreateMigrationToolNode
                  │
                  ├─ ToolNode([createMigrationTool])
                  │
                  └─ createMigrationTool
                         │
                         ├─ v.safeParse(createMigrationToolSchema, input)
                         │
                         ├─ repositories.schema.getSchema()
                         │
                         ├─ applyPatchOperations()
                         │
                         ├─ validateAndExecuteDDL()
                         │      │
                         │      ├─ postgresqlSchemaDeparser()
                         │      │
                         │      └─ executeQuery() [PGlite]
                         │
                         └─ repositories.schema.createVersion()
```

### データフロー図

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

schemaData ──▶ yamlSchemaDeparser() ──▶ schemaText
     │                                      │
     │                    ┌─────────────────┘
     │                    ▼
prompt ───────▶ contextPromptTemplate ──▶ contextPrompt
     │                                      │
     │                    ┌─────────────────┘
     │                    ▼
     │         invokeDesignAgent() ──▶ AIMessage
     │                │                    │
     │                │         ┌──────────┴──────────┐
     │                │         │                     │
     │                │    ツール呼び出しなし      ツール呼び出しあり
     │                │         │                     │
     │                │         ▼                     ▼
     │                │       END           invokeCreateMigrationTool
     │                │                              │
     │                │                              ▼
     │                │                    createMigrationTool
     │                │                              │
     │                │                    ┌─────────┴─────────┐
     │                │                    ▼                   ▼
     │                │           applyPatchOperations   validateAndExecuteDDL
     │                │                    │                   │
     │                │                    └─────────┬─────────┘
     │                │                              ▼
     └────────────────│──────────────────▶ 更新されたschemaData
                      │                              │
                      └──────────────────────────────┘
                                    (反復)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| createDbAgentGraph.ts | `frontend/internal-packages/agent/src/db-agent/createDbAgentGraph.ts` | ソース | サブグラフ構築 |
| dbAgentAnnotation.ts | `frontend/internal-packages/agent/src/db-agent/shared/dbAgentAnnotation.ts` | ソース | 状態定義 |
| designSchemaNode.ts | `frontend/internal-packages/agent/src/db-agent/nodes/designSchemaNode.ts` | ソース | 設計ノード |
| invokeCreateMigrationToolNode.ts | `frontend/internal-packages/agent/src/db-agent/nodes/invokeCreateMigrationToolNode.ts` | ソース | ツール実行ノード |
| createMigrationTool.ts | `frontend/internal-packages/agent/src/db-agent/tools/createMigrationTool.ts` | ソース | マイグレーションツール |
| routeAfterDesignSchema.ts | `frontend/internal-packages/agent/src/db-agent/routing/routeAfterDesignSchema.ts` | ソース | ルーティング |
| invokeDesignAgent.ts | `frontend/internal-packages/agent/src/db-agent/invokeDesignAgent.ts` | ソース | LLM呼び出し |
| prompt.ts | `frontend/internal-packages/agent/src/db-agent/prompt.ts` | ソース | プロンプトテンプレート |
| getToolConfigurable.ts | `frontend/internal-packages/agent/src/db-agent/getToolConfigurable.ts` | ソース | ツール設定取得 |
| convertAnalyzedRequirementsToPrompt.ts | `frontend/internal-packages/agent/src/db-agent/utils/convertAnalyzedRequirementsToPrompt.ts` | ソース | 要件変換 |
| createDbAgentGraph.test.ts | `frontend/internal-packages/agent/src/db-agent/createDbAgentGraph.test.ts` | テスト | ユニットテスト |
| createDbAgentGraph.integration.test.ts | `frontend/internal-packages/agent/src/db-agent/createDbAgentGraph.integration.test.ts` | テスト | 統合テスト |
