# 機能設計書 2-テーブルノード表示

## 概要

本ドキュメントは、Liamシステムにおける「テーブルノード表示」機能の設計を記述したものである。データベースのテーブル情報（テーブル名、カラム、制約、インデックス等）をER図上のノードとして視覚的に表示する機能である。

### 本機能の処理概要

本機能は、スキーマ情報から抽出されたテーブルデータをReact Flowのカスタムノードとして描画する。テーブルヘッダーにはテーブル名とアイコンを表示し、カラム一覧では各カラムの名前、型、制約情報を視覚的に表現する。

**業務上の目的・背景**：ER図においてテーブル情報を適切に可視化することで、開発者がデータベース構造を直感的に把握できるようにする。カラムの型や制約（Primary Key、Foreign Key、Not Null等）を視覚的に区別することで、スキーマの理解を促進する。

**機能の利用シーン**：
- データベーススキーマの構造確認
- テーブル間のリレーションシップの起点・終点の特定
- カラム制約の視覚的確認
- スキーマ差分レビュー時の変更箇所特定

**主要な処理内容**：
1. テーブルヘッダーの描画（テーブル名、アイコン、差分表示）
2. カラム一覧の描画（表示モードに応じたフィルタリング）
3. 各カラムの制約アイコン表示（PK、FK、Not Null等）
4. React Flow Handleの配置（エッジ接続点）
5. ハイライト状態の視覚的反映
6. 詳細情報の展開・折りたたみ

**関連システム・外部連携**：ER図表示機能（No.1）からノードとして呼び出される。リレーションシップエッジ表示機能（No.3）とHandle IDで連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | スキーマ画面 | 主画面 | テーブル情報をノードとして表示 |
| 14 | デザインセッション詳細画面 | 主画面 | 設計中スキーマのテーブルノード表示 |
| 20 | 公開ERD画面 | 主画面 | 公開スキーマのテーブルノード表示 |

## 機能種別

データ表示 / UIコンポーネント

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| data | TableNodeData | Yes | テーブルノードのデータ | - |
| data.table | Table | Yes | テーブル情報（name, columns, constraints等） | - |
| data.isHighlighted | boolean | No | ハイライト状態 | - |
| data.isActiveHighlighted | boolean | No | アクティブ選択状態 | - |
| data.sourceColumnName | string | No | ソースカラム名（FK参照元） | - |
| data.targetColumnCardinalities | Record | No | ターゲットカラムのカーディナリティ | - |
| data.showMode | ShowMode | No | 表示モード（ノード固有設定） | - |

### 入力データソース

- ER図表示機能から渡されるTableNodeData
- ユーザー設定（showMode）
- スキーマストアからの差分操作情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ReactNode | JSX.Element | テーブルノードのDOM要素 |

### 出力先

React Flow Canvas内のノード要素

## 処理フロー

### 処理シーケンス

```
1. TableNode描画開始
   └─ NodePropsからTableNodeDataを受け取る
2. showMode決定
   └─ ノード固有設定 or グローバル設定を適用
3. TableHeader描画
   └─ テーブル名、アイコン、差分表示を描画
4. TableColumnList描画
   ├─ ALL_FIELDS: 全カラムを表示
   ├─ KEY_ONLY: PKとFK関連カラムのみ表示
   └─ TABLE_NAME: カラム非表示
5. 各カラムの描画
   └─ アイコン、名前、型、Handleを配置
```

### フローチャート

```mermaid
flowchart TD
    A[TableNode受信] --> B{showMode判定}
    B -->|TABLE_NAME| C[ヘッダーのみ表示]
    B -->|KEY_ONLY| D[PKとFKカラムのみ表示]
    B -->|ALL_FIELDS| E[全カラム表示]
    C --> F[Handle配置]
    D --> G[カラムフィルタリング]
    E --> H[全カラム描画]
    G --> I[TableColumnList描画]
    H --> I
    I --> J[各カラムにアイコン付与]
    J --> K[Handle配置]
    F --> L[完了]
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | カラムアイコン優先度 | PK > FK > NotNull > Nullable の順でアイコンを決定 | 常時 |
| BR-002 | KEY_ONLYフィルタ | isPrimaryKeyまたはtargetColumnCardinalitiesに含まれるカラムのみ表示 | showMode=KEY_ONLY |
| BR-003 | Handle配置 | isSourceならRightにsource Handle、targetCardinalityならLeftにtarget Handle | カラム描画時 |
| BR-004 | ハイライトカラム | テーブルがハイライト状態かつFK関連カラムの場合、カラムもハイライト | isHighlightedTable=true |

### 計算ロジック

カラム表示可否の判定（shouldDisplayColumn関数）:
- filter=KEY_ONLY: `isPrimaryKey(column.name, table.constraints) || targetColumnCardinalities?.[column.name] !== undefined`
- filter=undefined: 常にtrue

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | 表示エラーはReact Error Boundaryで捕捉 |

### リトライ仕様

なし（コンポーネントの再レンダリングで対応）

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

該当なし（表示専用機能）

## パフォーマンス要件

- 大量カラム（100+）を持つテーブルでもスムーズに描画
- 仮想化は未実装（将来的な改善候補）

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

- テーブル名、カラム名はエスケープして表示
- 機密性の高いカラム情報も表示されるため、アクセス制御は上位機能で担保

## 備考

詳細情報の展開・折りたたみ機能はTableDetailコンポーネントで実装されている。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `frontend/packages/erd-core/src/features/erd/types.ts` | TableNodeData型の構造を把握 |
| 1-2 | schema/index.ts | `frontend/packages/schema/src/schema/index.ts` | Table, Column, Constraint型を確認 |

**読解のコツ**: TableNodeDataはReact Flowノードのdata部分であり、描画に必要な全情報を含む。

#### Step 2: メインコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TableNode.tsx | `frontend/packages/erd-core/src/features/erd/components/ERDContent/components/TableNode/TableNode.tsx` | ノード全体の構成、showModeによる分岐 |

**主要処理フロー**:
1. **20-22行目**: showModeの決定ロジック
2. **40-43行目**: showModeに応じたTableColumnListの条件分岐

#### Step 3: ヘッダー部分を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TableHeader.tsx | `frontend/packages/erd-core/src/features/erd/components/ERDContent/components/TableNode/TableHeader/TableHeader.tsx` | テーブル名表示、差分アイコン、Handle配置 |

**主要処理フロー**:
- **28-29行目**: isTarget/isSourceの判定
- **32-38行目**: 差分状態の計算（showDiff時のみ）
- **104-123行目**: TABLE_NAMEモード時のHandle配置

#### Step 4: カラム一覧を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TableColumnList.tsx | `frontend/packages/erd-core/src/features/erd/components/ERDContent/components/TableNode/TableColumnList/TableColumnList.tsx` | カラムフィルタリング、一覧描画 |
| 4-2 | TableColumn.tsx | `frontend/packages/erd-core/src/features/erd/components/ERDContent/components/TableNode/TableColumnList/TableColumn/TableColumn.tsx` | 個別カラムの描画、アイコン決定 |

**主要処理フロー (TableColumnList.tsx)**:
- **12-25行目**: shouldDisplayColumn関数でフィルタリング
- **41-43行目**: handleId生成とisSource判定

**主要処理フロー (TableColumn.tsx)**:
- **37-90行目**: ColumnIconコンポーネント（PK > FK > NotNull > Nullable）
- **155-171行目**: Handle配置ロジック

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

```
TableNode
    │
    ├─ useUserEditingOrThrow (showMode取得)
    │
    ├─ TableHeader
    │      ├─ useSchemaOrThrow (operations取得)
    │      ├─ getChangeStatus (差分判定)
    │      ├─ DiffIcon
    │      └─ Handle (TABLE_NAMEモード時)
    │
    └─ TableColumnList
           ├─ shouldDisplayColumn (フィルタ)
           └─ TableColumn
                  ├─ ColumnIcon
                  │      └─ isPrimaryKey
                  ├─ getChangeStatus
                  ├─ DiffIcon
                  └─ Handle (source/target)
```

### データフロー図

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

TableNodeData ─────▶ TableNode ──────────────▶ DOM要素
     │                   │
     │                   ├─▶ TableHeader ────▶ ヘッダーDOM
     │                   │
     └─ showMode ────────┴─▶ TableColumnList ▶ カラムリストDOM
                                    │
                                    └─▶ TableColumn ─▶ カラムDOM + Handle
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TableNode.tsx | `frontend/packages/erd-core/src/features/erd/components/ERDContent/components/TableNode/TableNode.tsx` | ソース | メインノードコンポーネント |
| TableHeader.tsx | `frontend/packages/erd-core/src/features/erd/components/ERDContent/components/TableNode/TableHeader/TableHeader.tsx` | ソース | ヘッダー描画 |
| TableColumnList.tsx | `frontend/packages/erd-core/src/features/erd/components/ERDContent/components/TableNode/TableColumnList/TableColumnList.tsx` | ソース | カラム一覧 |
| TableColumn.tsx | `frontend/packages/erd-core/src/features/erd/components/ERDContent/components/TableNode/TableColumnList/TableColumn/TableColumn.tsx` | ソース | 個別カラム描画 |
| types.ts | `frontend/packages/erd-core/src/features/erd/types.ts` | ソース | 型定義 |
| TableNode.module.css | `frontend/packages/erd-core/src/features/erd/components/ERDContent/components/TableNode/TableNode.module.css` | スタイル | ノードスタイル |
| TableHeader.module.css | `frontend/packages/erd-core/src/features/erd/components/ERDContent/components/TableNode/TableHeader/TableHeader.module.css` | スタイル | ヘッダースタイル |
| TableColumn.module.css | `frontend/packages/erd-core/src/features/erd/components/ERDContent/components/TableNode/TableColumnList/TableColumn/TableColumn.module.css` | スタイル | カラムスタイル |
| columnHandleId.ts | `frontend/packages/erd-core/src/features/erd/utils/columnHandleId.ts` | ソース | Handle ID生成 |
