# 機能設計書 13-マイグレーション操作生成

## 概要

本ドキュメントは、2つのスキーマ状態（before/after）を比較し、差分をJSON Patch形式のマイグレーション操作リストとして生成する「マイグレーション操作生成」機能の設計を記述する。

### 本機能の処理概要

**業務上の目的・背景**：AIエージェントによるデータベーススキーマ設計において、ユーザーの要件に基づいてスキーマを段階的に変更する必要がある。この機能により、現在のスキーマと目標スキーマの差分を構造化された形式で取得でき、変更内容の追跡・レビュー・適用が容易になる。

**機能の利用シーン**：
- デザインセッションでAIエージェントがスキーマ変更を提案する際
- スキーマのバージョン間差分を確認する際
- マイグレーションDDLの自動生成の前処理として

**主要な処理内容**：
1. fast-json-patchライブラリを使用して2つのスキーマオブジェクトを比較
2. 生成されたJSON Patch操作をValibotスキーマでフィルタリング
3. 有効なMigrationOperation型の操作のみを抽出して返却

**関連システム・外部連携**：
- DB Agentサブグラフ（No.19）でスキーマ変更の適用に使用
- PostgreSQL DDL生成（No.14）の入力データとして使用

**権限による制御**：本機能は認証・認可を必要としないライブラリ機能である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | デザインセッション詳細画面 | 補助機能 | スキーマ差分からマイグレーション操作リストを生成 |

## 機能種別

データ比較・差分検出処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| before | Schema | Yes | 変更前のスキーマオブジェクト | Schema型に準拠 |
| after | Schema | Yes | 変更後のスキーマオブジェクト | Schema型に準拠 |

### 入力データソース

- メモリ上のSchemaオブジェクト（tables, enums, extensionsを含む）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | MigrationOperation[] | マイグレーション操作の配列 |

### MigrationOperation型のバリエーション

テーブル操作:
- add（テーブル追加）
- remove（テーブル削除）
- replace（テーブル名変更等）

カラム操作:
- add（カラム追加）
- remove（カラム削除）
- replace（カラム属性変更）

インデックス操作:
- add（インデックス追加）
- remove（インデックス削除）

制約操作:
- add（制約追加）
- remove（制約削除）
- replace（制約変更）

ENUM操作:
- add（ENUM追加）
- remove（ENUM削除）
- replace（ENUM値変更）

拡張機能操作:
- add（拡張機能追加）
- remove（拡張機能削除）

### 出力先

関数の戻り値として返却される。

## 処理フロー

### 処理シーケンス

```
1. fast-json-patchのcompare関数を呼び出し
   └─ before/afterスキーマを比較してJSON Patch操作を生成
2. 各操作のバリデーション
   └─ Valibotスキーマで各操作がMigrationOperation型かを検証
3. 有効な操作のフィルタリング
   └─ バリデーションに通過した操作のみを抽出
4. 結果の返却
   └─ MigrationOperation[]として返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[compare関数でJSON Patch生成]
    B --> C[操作リストを取得]
    C --> D{各操作をチェック}
    D --> E[Valibotスキーマでバリデーション]
    E --> F{バリデーション成功?}
    F -->|Yes| G[結果配列に追加]
    F -->|No| H[スキップ]
    G --> I{次の操作あり?}
    H --> I
    I -->|Yes| D
    I -->|No| J[結果配列を返却]
    J --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | JSON Patchベース差分検出 | RFC 6902準拠のJSON Patch形式で差分を表現 | 常に適用 |
| BR-02 | スキーマ固有操作フィルタ | データベーススキーマに関係のないパス変更は除外 | 常に適用 |
| BR-03 | 操作の原子性 | 各MigrationOperationは単一の変更を表す | 常に適用 |

### 計算ロジック

JSON Patchパスの構造:
- `/tables/{tableName}` - テーブル操作
- `/tables/{tableName}/columns/{columnName}` - カラム操作
- `/tables/{tableName}/indexes/{indexName}` - インデックス操作
- `/tables/{tableName}/constraints/{constraintName}` - 制約操作
- `/enums/{enumName}` - ENUM操作
- `/extensions/{extensionName}` - 拡張機能操作

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

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

本機能はデータベースを操作しない（メモリ上でのスキーマ比較のみ）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 型エラー | before/afterがSchema型でない | TypeScriptの型チェックで防止 |

### リトライ仕様

リトライ不要（同期的な比較処理のため）

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

該当なし（データベース操作を行わない）

## パフォーマンス要件

- 処理時間：100テーブル規模のスキーマ比較で100ミリ秒以内

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

- 特になし（メモリ上の純粋な比較処理）

## 備考

- fast-json-patchライブラリのESM対応の問題により、特殊なインポート方法を使用
- 将来的にはより詳細なスキーマ差分表示機能への拡張を想定

---

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

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

### 推奨読解順序

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

まず、MigrationOperation型の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `frontend/packages/schema/src/migrationOperation/schema/index.ts` | MigrationOperation型とChangeStatus型の定義 |
| 1-2 | table.ts | `frontend/packages/schema/src/migrationOperation/schema/table.ts` | テーブル操作のスキーマ定義 |
| 1-3 | column.ts | `frontend/packages/schema/src/migrationOperation/schema/column.ts` | カラム操作のスキーマ定義 |
| 1-4 | constraint.ts | `frontend/packages/schema/src/migrationOperation/schema/constraint.ts` | 制約操作のスキーマ定義 |

**読解のコツ**: `v.union()`で複数のスキーマを結合し、様々な操作タイプを表現している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `frontend/packages/schema/src/migrationOperation/index.ts` | getMigrationOperations関数のエクスポート |

#### Step 3: 差分検出ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | getMigrationOperations.ts | `frontend/packages/schema/src/migrationOperation/utils/getMigrationOperations.ts` | メインの差分検出ロジック |

**主要処理フロー**:
- **1-3行目**: fast-json-patchからcompare関数をインポート（ESM互換性対応）
- **12-15行目**: isMigrationOperation関数 - Valibotでの型検証
- **17-25行目**: getMigrationOperations関数 - メインロジック
- **21行目**: compare(before, after)でJSON Patch操作を生成
- **22行目**: filter(isMigrationOperation)で有効な操作のみ抽出

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

```
getMigrationOperations(before, after)
    │
    ├─ compare(before, after) [fast-json-patch]
    │      └─ JSON Patch操作配列を生成
    │
    └─ operations.filter(isMigrationOperation)
           │
           └─ safeParse(migrationOperationSchema, op)
                  └─ Valibotでの型検証
```

### データフロー図

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

before: Schema ──┐
                 ├──▶ compare() ──▶ Operation[] ──▶ filter() ──▶ MigrationOperation[]
after: Schema  ──┘
                      [fast-json-patch]   [Valibot検証]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| getMigrationOperations.ts | `frontend/packages/schema/src/migrationOperation/utils/getMigrationOperations.ts` | ソース | 差分検出メインロジック |
| index.ts | `frontend/packages/schema/src/migrationOperation/schema/index.ts` | ソース | MigrationOperation型定義 |
| table.ts | `frontend/packages/schema/src/migrationOperation/schema/table.ts` | ソース | テーブル操作スキーマ |
| column.ts | `frontend/packages/schema/src/migrationOperation/schema/column.ts` | ソース | カラム操作スキーマ |
| constraint.ts | `frontend/packages/schema/src/migrationOperation/schema/constraint.ts` | ソース | 制約操作スキーマ |
| indexMigrationOperations.ts | `frontend/packages/schema/src/migrationOperation/schema/indexMigrationOperations.ts` | ソース | インデックス操作スキーマ |
| enum.ts | `frontend/packages/schema/src/migrationOperation/schema/enum.ts` | ソース | ENUM操作スキーマ |
| extension.ts | `frontend/packages/schema/src/migrationOperation/schema/extension.ts` | ソース | 拡張機能操作スキーマ |
| applyPatchOperations.ts | `frontend/packages/schema/src/migrationOperation/utils/applyPatchOperations.ts` | ソース | 操作適用ユーティリティ |
| applyPatchOperations.test.ts | `frontend/packages/schema/src/migrationOperation/__tests__/applyPatchOperations.test.ts` | テスト | 操作適用のテスト |
