# 機能設計書 6-スキーマ差分表示

## 概要

本ドキュメントは、Liamシステムにおける「スキーマ差分表示」機能の設計を記述したものである。スキーマの変更差分を視覚的に表示し、追加・変更・削除の状態を色分けで表現する機能である。

### 本機能の処理概要

本機能は、2つのスキーマ（変更前・変更後）を比較し、JSON Patchベースの変更追跡を行う。テーブル、カラム、制約、インデックス等の各要素に対して、追加（緑）、変更（黄）、削除（赤）の状態を判定し、ER図上で色分け表示する。

**業務上の目的・背景**：データベーススキーマの変更をレビューする際、変更箇所を視覚的に把握できることは非常に重要である。本機能により、マイグレーション前後のスキーマ差分を一目で確認でき、レビュー品質と効率を向上させる。

**機能の利用シーン**：
- デザインセッションでのスキーマ変更確認
- マイグレーション影響範囲の把握
- スキーマレビュー
- 変更履歴の追跡

**主要な処理内容**：
1. 変更前後のスキーマからMigrationOperationを生成
2. 各要素のChangeStatus（added/modified/removed）を判定
3. DiffIconコンポーネントで状態アイコンを表示
4. 背景色スタイルの適用

**関連システム・外部連携**：fast-json-patchライブラリを使用してJSON差分を検出。ER図表示機能（No.1）と連携。

**権限による制御**：デザインセッション機能の一部として、認証ユーザーのみ利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | デザインセッション詳細画面 | 主画面 | スキーマの変更差分を視覚的に表示 |
| 15 | 公開デザインセッション詳細画面 | 結果表示画面 | スキーマの変更差分を視覚的に表示 |

## 機能種別

データ表示 / 差分検出 / 視覚的フィードバック

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| before | Schema | Yes | 変更前スキーマ | schemaSchemaによるバリデーション |
| after | Schema | Yes | 変更後スキーマ | schemaSchemaによるバリデーション |
| showDiff | boolean | Yes | 差分表示モード有効/無効 | - |

### 入力データソース

- デザインセッションの元スキーマ（current）
- AIエージェントによる変更後スキーマ（merged）
- ユーザー設定（showDiff）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| operations | MigrationOperation[] | JSON Patch形式の操作リスト |
| changeStatus | ChangeStatus | 各要素の変更状態（added/modified/removed） |

### 出力先

ER図のノード・カラム・制約へのスタイル適用

## 処理フロー

### 処理シーケンス

```
1. スキーマ比較
   └─ getMigrationOperations(before, after)でJSON Patchを生成
2. 操作フィルタリング
   └─ MigrationOperationスキーマでバリデーション
3. ChangeStatus判定
   └─ 各要素に対してgetChangeStatus関数で状態を判定
4. スタイル適用
   └─ useDiffStyleフックで背景色クラスを取得
5. アイコン表示
   └─ DiffIconコンポーネントで状態アイコンを表示
```

### フローチャート

```mermaid
flowchart TD
    A[before/afterスキーマ] --> B[getMigrationOperations]
    B --> C[JSON Patch生成]
    C --> D[MigrationOperationフィルタ]
    D --> E[operations配列]
    E --> F{各要素のレンダリング}
    F --> G[getChangeStatus]
    G --> H{changeStatus?}
    H -->|added| I[緑背景 + アイコン]
    H -->|modified| J[黄背景 + アイコン]
    H -->|removed| K[赤背景 + アイコン]
    H -->|undefined| L[通常表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 追加状態 | pathが新規要素を指す場合はadded | op='add' |
| BR-002 | 削除状態 | pathが削除要素を指す場合はremoved | op='remove' |
| BR-003 | 変更状態 | pathが既存要素の更新を指す場合はmodified | op='replace' |
| BR-004 | showDiff無効時 | showDiff=falseの場合は差分表示しない | showDiff=false |

### 計算ロジック

MigrationOperation生成:
```javascript
const operations = compare(before, after) // fast-json-patch
const filteredOperations = operations.filter(isMigrationOperation)
```

ChangeStatus判定:
```javascript
// getChangeStatus内でoperationsを走査し、該当パスの操作を検出
match(changeStatus)
  .with('added', () => diffStyles.addedBg)
  .with('removed', () => diffStyles.removedBg)
  .with('modified', () => diffStyles.modifiedBg)
  .otherwise(() => undefined)
```

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

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

本機能はデータベースを直接操作しない。表示専用機能。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | バリデーション失敗の操作は除外 |

### リトライ仕様

なし（再レンダリングで対応）

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

該当なし（メモリ内処理）

## パフォーマンス要件

- JSON Patch生成は大規模スキーマでも高速
- ChangeStatus判定はメモ化（useMemo）で最適化

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

- スキーマ情報は認証されたユーザーのセッション内でのみ表示

## 備考

fast-json-patchライブラリ（RFC 6902準拠）を使用してJSON差分を検出する。

---

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

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

### 推奨読解順序

#### Step 1: 差分検出を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | getMigrationOperations.ts | `frontend/packages/schema/src/migrationOperation/utils/getMigrationOperations.ts` | JSON Patchベースの差分検出 |

**主要処理フロー**:
1. **17-25行目**: compareで差分生成、フィルタリング

#### Step 2: 変更状態判定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | getTableChangeStatus.ts | `frontend/packages/schema/src/migrationOperation/utils/tables/getTableChangeStatus.ts` | テーブルレベルの状態判定 |
| 2-2 | getColumnChangeStatus系 | `frontend/packages/schema/src/migrationOperation/utils/columns/` | カラムレベルの状態判定 |

#### Step 3: スタイル適用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | useDiffStyle.ts | `frontend/packages/erd-core/src/features/diff/hooks/useDiffStyle.ts` | CSS背景色クラスの取得 |
| 3-2 | DiffIcon.tsx | `frontend/packages/erd-core/src/features/diff/components/DiffIcon/DiffIcon.tsx` | 状態アイコンの表示 |

**主要処理フロー (useDiffStyle.ts)**:
- **6-18行目**: showDiffとchangeStatusに応じた背景色クラスを返却

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

```
ERDRenderer
    │
    └─ useSchemaOrThrow (operations取得)
           │
           └─ getMigrationOperations
                  └─ compare (fast-json-patch)

TableHeader / TableColumn / etc.
    │
    ├─ getChangeStatus (状態判定)
    │
    ├─ useDiffStyle (背景色)
    │
    └─ DiffIcon (アイコン表示)
```

### データフロー図

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

before/afterスキーマ ▶ compare() ─────────────▶ Operation[]
                           │
                           ▼
                    isMigrationOperation ────▶ MigrationOperation[]
                           │
                           ▼
tableId/columnId ──▶ getChangeStatus ────────▶ ChangeStatus
                           │
                           ▼
                    useDiffStyle ────────────▶ CSSクラス
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| getMigrationOperations.ts | `frontend/packages/schema/src/migrationOperation/utils/getMigrationOperations.ts` | ソース | 差分検出 |
| useDiffStyle.ts | `frontend/packages/erd-core/src/features/diff/hooks/useDiffStyle.ts` | ソース | スタイル取得 |
| DiffIcon.tsx | `frontend/packages/erd-core/src/features/diff/components/DiffIcon/DiffIcon.tsx` | ソース | アイコン表示 |
| Diff.module.css | `frontend/packages/erd-core/src/features/diff/styles/Diff.module.css` | スタイル | 差分スタイル定義 |
| getTableChangeStatus.ts | `frontend/packages/schema/src/migrationOperation/utils/tables/getTableChangeStatus.ts` | ソース | テーブル状態判定 |
