# 機能設計書 17-erd buildコマンド

## 概要

本ドキュメントは、スキーマファイルからERD HTMLアセットを生成する`@liam-hq/cli erd build`コマンドの設計を記述する。

### 本機能の処理概要

**業務上の目的・背景**：データベーススキーマファイルから静的なERDビューアを生成することで、スキーマの可視化をウェブサーバーでホスティングしたり、チームで共有したりすることを可能にする。CI/CDパイプラインに組み込むことで、スキーマ変更時に自動的にERDを更新できる。

**機能の利用シーン**：
- GitHub ActionsでERDを自動生成してGitHub Pagesにデプロイ
- ローカル環境でスキーマを可視化して確認
- ドキュメントサイトにERDを埋め込む

**主要な処理内容**：
1. 入力スキーマファイルの読み込み
2. フォーマット自動検出（オプション未指定時）
3. スキーマのパースとJSON変換
4. schema.jsonの出力
5. HTMLアセットの生成・コピー

**関連システム・外部連携**：
- スキーマパーサー（No.7-11）
- フォーマット自動検出（No.12）

**権限による制御**：ファイルシステムへの読み書き権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLI専用機能（画面なし） |

## 機能種別

ビルド処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --input, -i | string | Yes | 入力スキーマファイルのパス | ファイルが存在すること |
| --format | SupportedFormat | No | スキーマ形式（省略時は自動検出） | schemarb, postgres, prisma, drizzle, tbls |
| --out | string | No | 出力ディレクトリ（デフォルト: ./dist） | ディレクトリパス |

### 入力データソース

- ファイルシステム：スキーマファイル
- URL：外部URLからのスキーマファイル取得も可能

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| dist/schema.json | ファイル | パースされたスキーマのJSON表現 |
| dist/index.html | ファイル | ERDビューアのHTMLファイル |
| dist/assets/* | ファイル | CSS, JavaScript等のアセット |

### 出力先

指定された出力ディレクトリ（デフォルト: ./dist）

## 処理フロー

### 処理シーケンス

```
1. 入力ファイルの読み込み
   └─ getInputContent()でファイルまたはURLから内容を取得
2. フォーマット検出
   └─ format未指定時はdetectFormat()で自動検出
3. スキーマパース
   └─ parse(input, format)でスキーマをパース
4. schema.json出力
   └─ JSON.stringifyでファイルに書き込み
5. HTMLアセットコピー
   └─ CLIパッケージ内のHTMLテンプレートをコピー
6. 完了メッセージ表示
   └─ 成功時は起動方法を案内
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[入力ファイル読み込み]
    B --> C{読み込み成功?}
    C -->|No| D[エラー返却]
    C -->|Yes| E{format指定あり?}
    E -->|No| F[フォーマット自動検出]
    E -->|Yes| G[指定フォーマット使用]
    F --> H{検出成功?}
    H -->|No| I[フォーマットエラー]
    H -->|Yes| G
    G --> J[スキーマパース]
    J --> K{パース成功?}
    K -->|No| L[パースエラー]
    K -->|Yes| M[schema.json出力]
    M --> N[HTMLアセットコピー]
    N --> O{コピー成功?}
    O -->|No| P[ファイルシステムエラー]
    O -->|Yes| Q[完了メッセージ表示]
    D --> R[終了]
    I --> R
    L --> R
    P --> R
    Q --> R
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | フォーマット自動検出 | --format未指定時はファイル名から自動検出 | 常に適用 |
| BR-02 | 出力ディレクトリ作成 | 存在しない場合は再帰的に作成 | 常に適用 |
| BR-03 | エラー時処理継続 | 軽微なエラーでも処理を継続（将来的な方針） | 適用予定 |

### エラータイプ

| エラー種別 | 説明 |
|-----------|------|
| ArgumentError | 引数の不正（ファイルパス、フォーマット等） |
| FileSystemError | ファイル読み書きエラー |
| WarningProcessingError | パース処理中の警告 |

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

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

本機能はデータベースを操作しない（ファイル操作のみ）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ArgumentError | 入力ファイルが存在しない | エラーメッセージを表示 |
| - | ArgumentError | フォーマットが不正または検出不可 | エラーメッセージを表示 |
| - | WarningProcessingError | スキーマパースエラー | エラーメッセージを表示 |
| - | FileSystemError | 出力ディレクトリ作成失敗 | エラーメッセージを表示 |
| - | FileSystemError | ファイル書き込み失敗 | エラーメッセージを表示 |

### リトライ仕様

リトライなし（バッチ処理）

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

該当なし

## パフォーマンス要件

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

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

- 入力ファイルのサイズ制限なし（大きなスキーマの処理に注意）
- 出力ディレクトリのパーミッションはシステムデフォルト

## 備考

- 生成されたdist/はHTTPサーバーで配信する必要がある（file://では動作しない）
- HTMLアセットはCLIパッケージにバンドルされている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `frontend/packages/cli/src/cli/erdCommand/index.ts` | erdコマンドの登録とbuildサブコマンドの定義 |

#### Step 2: ビルドコマンドの実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `frontend/packages/cli/src/cli/erdCommand/buildCommand/index.ts` | buildCommandメイン関数 |

**主要処理フロー**:
- **9-13行目**: buildCommand関数の引数定義
- **17-21行目**: runPreprocessでスキーマパースとJSON出力
- **29-40行目**: HTMLアセットのコピー処理
- **42-46行目**: 出力ディレクトリのcpSync
- **51-66行目**: 成功メッセージの表示

#### Step 3: 前処理ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | runPreprocess.ts | `frontend/packages/cli/src/cli/erdCommand/runPreprocess.ts` | スキーマパースとJSON出力 |

**主要処理フロー**:
- **23-34行目**: getInputContentで入力ファイル読み込み
- **36-42行目**: フォーマット自動検出
- **44-66行目**: フォーマットバリデーション
- **68-79行目**: parse関数でスキーマパース
- **81-100行目**: schema.jsonの書き込み

#### Step 4: 入力コンテンツ取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | getInputContent.ts | `frontend/packages/cli/src/cli/erdCommand/getInputContent.ts` | ファイル/URL読み込み |

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

```
erd build --input <path> --format <format> --out <dir>
    │
    └─ buildCommand(inputPath, outDir, format)
           │
           ├─ runPreprocess(inputPath, resolvedOutDir, format)
           │      │
           │      ├─ getInputContent(inputPath)
           │      │      └─ ファイル or URL読み込み
           │      │
           │      ├─ detectFormat(inputPath) [format未指定時]
           │      │
           │      ├─ parse(input, format)
           │      │      └─ スキーマパーサー呼び出し
           │      │
           │      └─ fs.writeFileSync(schema.json)
           │
           └─ cpSync(cliHtmlPath, resolvedOutDir)
                  └─ HTMLアセットコピー
```

### データフロー図

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

スキーマファイル ──▶ getInputContent() ──▶ 文字列
      │                                      │
      │                ┌─────────────────────┘
      │                ▼
      │         detectFormat() ──▶ format
      │                │
      │                ▼
      │         parse(input, format) ──▶ Schema
      │                │
      │                ▼
      │         JSON.stringify() ──▶ dist/schema.json
      │
      └─────────────────────────────────▶ cpSync() ──▶ dist/index.html, assets/
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `frontend/packages/cli/src/cli/erdCommand/buildCommand/index.ts` | ソース | buildコマンドメイン関数 |
| runPreprocess.ts | `frontend/packages/cli/src/cli/erdCommand/runPreprocess.ts` | ソース | スキーマパースとJSON出力 |
| getInputContent.ts | `frontend/packages/cli/src/cli/erdCommand/getInputContent.ts` | ソース | 入力ファイル/URL読み込み |
| index.ts | `frontend/packages/cli/src/cli/erdCommand/index.ts` | ソース | erdコマンド定義 |
| errors.ts | `frontend/packages/cli/src/cli/errors.ts` | ソース | エラー型定義 |
| actionRunner.ts | `frontend/packages/cli/src/cli/actionRunner.ts` | ソース | コマンド実行ラッパー |
| index.test.ts | `frontend/packages/cli/src/cli/erdCommand/index.test.ts` | テスト | erdコマンドの単体テスト |
| runPreprocess.test.ts | `frontend/packages/cli/src/cli/erdCommand/runPreprocess.test.ts` | テスト | 前処理の単体テスト |
