# 機能設計書 5-ハイライト機能

## 概要

本ドキュメントは、Liamシステムにおける「ハイライト機能」の設計を記述したものである。選択したテーブルに関連するノードとエッジを強調表示し、リレーションシップの把握を支援する機能である。

### 本機能の処理概要

本機能は、ユーザーがテーブルノードをクリックまたはホバーした際に、そのテーブルと直接関連するテーブル（外部キーで接続されているテーブル）およびエッジをハイライト表示する。これにより、複雑なスキーマ内でのリレーションシップを視覚的に追跡できる。

**業務上の目的・背景**：大規模なデータベーススキーマでは、特定のテーブルに関連するテーブルを見つけることが困難である。ハイライト機能により、選択したテーブルの参照関係を即座に視覚化し、スキーマ理解を促進する。

**機能の利用シーン**：
- 特定テーブルの参照先・参照元の確認
- 外部キー関係の追跡
- スキーマ設計時の影響範囲分析
- データモデルの説明・プレゼンテーション

**主要な処理内容**：
1. ノードクリック/ホバーイベントの検知
2. エッジマップの構築（関連テーブルの特定）
3. 関連ノードのハイライト状態更新
4. 関連エッジのハイライト状態更新
5. 非関連要素の非ハイライト処理

**関連システム・外部連携**：ER図表示機能（No.1）から呼び出される。テーブルノード表示（No.2）、リレーションシップエッジ表示（No.3）のスタイルに影響。

**権限による制御**：表示のみの機能のため、認証ユーザーであればアクセス可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | スキーマ画面 | 主画面 | 選択したテーブルに関連するノードとエッジを強調 |
| 14 | デザインセッション詳細画面 | 主画面 | 設計中スキーマでのハイライト表示 |
| 20 | 公開ERD画面 | 主画面 | 公開スキーマでのハイライト表示 |

## 機能種別

UI操作 / 視覚的フィードバック

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| nodes | Node[] | Yes | 現在のノード配列 | - |
| edges | Edge[] | Yes | 現在のエッジ配列 | - |
| trigger.activeTableName | string | No | クリック選択されたテーブル名 | - |
| trigger.hoverTableName | string | No | ホバー中のテーブル名 | - |

### 入力データソース

- React Flowのノード・エッジ状態
- ユーザー操作イベント（クリック、ホバー）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| nodes | Node[] | ハイライト状態が更新されたノード配列 |
| edges | Edge[] | ハイライト状態が更新されたエッジ配列 |

### 出力先

React Flowコンポーネントのノード・エッジ状態

## 処理フロー

### 処理シーケンス

```
1. トリガー受信
   └─ activeTableNameまたはhoverTableName
2. エッジマップ構築
   └─ 各エッジのsource/targetから関連テーブルマップを生成
3. ノード更新
   ├─ アクティブノード: isActiveHighlighted = true
   ├─ 関連ノード: isHighlighted = true
   └─ その他: 両方false
4. エッジ更新
   ├─ 関連エッジ: isHighlighted = true, zIndex = edgeHighlighted
   └─ その他: isHighlighted = false, zIndex = edgeDefault
5. 更新済み配列を返却
```

### フローチャート

```mermaid
flowchart TD
    A[イベント受信] --> B{クリック or ホバー?}
    B -->|クリック| C[activeTableName設定]
    B -->|ホバー| D[hoverTableName設定]
    C --> E[エッジマップ構築]
    D --> E
    E --> F[各ノードをループ]
    F --> G{アクティブノード?}
    G -->|Yes| H[activeHighlight]
    G -->|No| I{関連ノード?}
    I -->|Yes| J[highlight]
    I -->|No| K[unhighlight]
    H --> L[各エッジをループ]
    J --> L
    K --> L
    L --> M{関連エッジ?}
    M -->|Yes| N[highlightEdge]
    M -->|No| O[unhighlightEdge]
    N --> P[結果返却]
    O --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | アクティブハイライト | クリック選択されたテーブルはisActiveHighlighted=true | activeTableNameと一致 |
| BR-002 | 関連ハイライト | 関連テーブルまたはホバーテーブルはisHighlighted=true | エッジで接続 or ホバー中 |
| BR-003 | エッジハイライト | 関連エッジはzIndexを上げてisHighlighted=true | source/targetが対象テーブル |
| BR-004 | 双方向関連 | source/targetの両方向から関連を判定 | エッジマップ構築時 |

### 計算ロジック

エッジマップの構築:
```javascript
for (const edge of edges) {
  edgeMap.get(sourceTableName)?.add(targetTableName)
  edgeMap.get(targetTableName)?.add(sourceTableName)
}
```

関連ノード判定:
```javascript
isRelatedNodeToTarget(targetTableName, edgeMap, node) {
  return edgeMap.get(targetTableName)?.has(node.data.table.name) ?? false
}
```

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | 状態更新エラーはReactで捕捉 |

### リトライ仕様

なし（状態更新の再実行で対応）

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

該当なし（メモリ内状態更新）

## パフォーマンス要件

- 即座の視覚的フィードバック（16ms以内）
- 大量ノード・エッジでも処理遅延なし

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

- 表示のみの機能のため、特別なセキュリティ考慮は不要

## 備考

zIndex定数はconstants.tsで定義されており、ハイライト時にエッジを前面に表示する。

---

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

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

### 推奨読解順序

#### Step 1: メイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | highlightNodesAndEdges.ts | `frontend/packages/erd-core/src/features/erd/utils/highlightNodesAndEdges.ts` | ハイライト処理のメインロジック |

**主要処理フロー**:
1. **84-91行目**: メイン関数のシグネチャとtriggerパラメータ
2. **93-105行目**: エッジマップの構築（双方向関連）
3. **107-125行目**: ノードの更新ループ
4. **127-136行目**: エッジの更新ループ

#### Step 2: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | highlightNodesAndEdges.ts | `frontend/packages/erd-core/src/features/erd/utils/highlightNodesAndEdges.ts` | 各種判定・更新関数 |

**主要処理フロー**:
- **10-15行目**: isActiveNode - アクティブノード判定
- **17-27行目**: isRelatedNodeToTarget - 関連ノード判定
- **29-34行目**: isHoveredNode - ホバーノード判定
- **36-41行目**: isRelatedEdgeToTarget - 関連エッジ判定
- **43-67行目**: ハイライト/非ハイライト更新関数群
- **68-82行目**: エッジのハイライト/非ハイライト更新関数群

#### Step 3: 呼び出し元を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ErdContent.tsx | `frontend/packages/erd-core/src/features/erd/components/ERDContent/ErdContent.tsx` | イベントハンドラからの呼び出し |

**主要処理フロー**:
- **101-113行目**: handleMouseEnterNode - ホバー開始時
- **115-127行目**: handleMouseLeaveNode - ホバー終了時
- **78-95行目**: handleNodeClick - クリック時（selectTable経由）

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

```
ERDContent
    │
    ├─ onNodeClick
    │      └─ selectTable
    │             └─ highlightNodesAndEdges (activeTableName)
    │
    ├─ onNodeMouseEnter
    │      └─ handleMouseEnterNode
    │             └─ highlightNodesAndEdges (hoverTableName)
    │
    └─ onNodeMouseLeave
           └─ handleMouseLeaveNode
                  └─ highlightNodesAndEdges (hoverTableName: undefined)
```

### データフロー図

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

クリック/ホバー ───▶ trigger設定 ────────────▶ activeTableName/hoverTableName
                           │
                           ▼
edges[] ───────────▶ エッジマップ構築 ────────▶ EdgeMap
                           │
                           ▼
nodes[] + EdgeMap ─▶ ノード更新ループ ────────▶ 更新済みnodes[]
     │                   │
     │                   ├─▶ isActiveNode → activeHighlightNode
     │                   ├─▶ isRelatedNode → highlightNode
     │                   └─▶ その他 → unhighlightNode
     │
edges[] ───────────▶ エッジ更新ループ ────────▶ 更新済みedges[]
                         │
                         ├─▶ isRelatedEdge → highlightEdge
                         └─▶ その他 → unhighlightEdge
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| highlightNodesAndEdges.ts | `frontend/packages/erd-core/src/features/erd/utils/highlightNodesAndEdges.ts` | ソース | メインハイライト処理 |
| highlightNodesAndEdges.test.ts | `frontend/packages/erd-core/src/features/erd/utils/highlightNodesAndEdges.test.ts` | テスト | ユニットテスト |
| ErdContent.tsx | `frontend/packages/erd-core/src/features/erd/components/ERDContent/ErdContent.tsx` | ソース | イベントハンドラ |
| types.ts | `frontend/packages/erd-core/src/features/erd/types.ts` | ソース | TableNodeData型（isHighlighted等） |
| constants.ts | `frontend/packages/erd-core/src/features/erd/constants.ts` | ソース | zIndex定数 |
