# 画面設計書 22-ドキュメント詳細画面

## 概要

本ドキュメントは、Liam ERDドキュメントサイトのドキュメント詳細画面の設計仕様を定義する。この画面はFumadocsフレームワークを使用してMDXコンテンツをレンダリングし、ユーザーにインタラクティブなドキュメント閲覧体験を提供する。

### 本画面の処理概要

**業務上の目的・背景**：ドキュメント詳細画面は、Liam ERDプロジェクトの技術ドキュメント、ユーザーガイド、API仕様、コントリビューションガイドなどを閲覧するための中核画面である。開発者やユーザーがLiam ERDの使い方を学習し、プロジェクトへの貢献方法を理解するための重要な情報源として機能する。パーサーのサポートフォーマット一覧、CLI/Web版の使い方、UI機能の説明、ADR（Architecture Decision Records）などの技術的意思決定記録など、プロジェクトに関する包括的なドキュメントを提供する。

**画面へのアクセス方法**：以下の方法でアクセス可能である：
- ドキュメントサイトのルートURL（`/`）からの自動リダイレクト
- サイドバーナビゲーションからのドキュメント選択
- パンくずリストからのナビゲーション
- 検索機能を使用したドキュメント検索結果からのアクセス
- 外部サイトからの直接リンク

**主要な操作・処理内容**：
1. URLパスに基づいて対応するMDXドキュメントを取得・表示
2. 目次（Table of Contents）の自動生成と表示
3. パンくずリストによる階層ナビゲーション
4. 前後のドキュメントへのナビゲーション（FooterNavi）
5. GitHub上での編集リンクの提供
6. 検索機能によるドキュメント横断検索
7. コードブロックのシンタックスハイライト表示
8. Tabs、Calloutなどのカスタムコンポーネントによるリッチコンテンツ表示

**画面遷移**：
- **遷移元**: ドキュメントホーム画面（リダイレクト）、サイドバー、検索結果、外部サイト、他のドキュメントページ
- **遷移先**: 他のドキュメントページ、外部サイト（GitHub等）

**権限による表示制御**：本画面は認証不要で、すべてのユーザーがアクセス可能である。権限による表示制御は存在しない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 49 | ドキュメントサイト | 主機能 | FumadocsベースのMDXドキュメントレンダリング |

## 画面種別

詳細

## URL/ルーティング

| 項目 | 値 |
|------|-----|
| パス | `/docs/[[...slug]]` |
| ファイル | `frontend/apps/docs/app/docs/[[...slug]]/page.tsx` |
| コンポーネントタイプ | サーバーコンポーネント（Async） |
| ルートタイプ | オプショナルキャッチオールルート |
| 静的生成 | 対応（`generateStaticParams`） |

### パスパラメータ

| パラメータ | 必須 | 型 | 説明 | 例 |
|-----------|------|-----|------|-----|
| slug | 任意 | string[] | ドキュメントパス | `['cli', 'ci-cd']`, `['parser', 'supported-formats', 'postgresql']` |

### 生成されるURL例

| URL | 対応するコンテンツ |
|-----|-------------------|
| `/docs` | Welcome to Liam ERD（トップページ） |
| `/docs/cli` | CLI版ドキュメント |
| `/docs/cli/ci-cd` | CLI CI/CDガイド |
| `/docs/parser/supported-formats` | サポートフォーマット一覧 |
| `/docs/parser/supported-formats/postgresql` | PostgreSQLフォーマット詳細 |
| `/docs/ui-features` | UI機能ガイド |
| `/docs/contributing` | コントリビューションガイド |
| `/docs/contributing/adr` | ADR一覧 |

## 入出力項目

### 入力項目（パスパラメータ）

| 区分 | 項目名 | 型 | 必須 | 説明 |
|------|--------|-----|------|------|
| パスパラメータ | slug | string[] | 任意 | ドキュメントのパス階層 |

### 出力項目（ページメタデータ）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| title | string | ドキュメントタイトル（MDXフロントマターから取得） |
| description | string | ドキュメント概要（MDXフロントマターから取得） |
| openGraph.images | string | OGP画像パス（`/images/liam_erd.png`） |

## 表示項目

### メインコンテンツエリア

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Breadcrumb | コンポーネント | パンくずリスト（ドキュメント階層表示） |
| DocsTitle | テキスト | ドキュメントタイトル |
| DocsDescription | テキスト | ドキュメント概要 |
| DocsBody | MDXコンテンツ | ドキュメント本文（MDXレンダリング結果） |
| FooterNavi | コンポーネント | 前後のドキュメントへのナビゲーション |
| Edit on GitHub | リンク | GitHubでの編集リンク |

### サイドバー（DocsLayoutより提供）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| LiamLogo | SVG | サイトロゴ |
| ドキュメントツリー | ナビゲーション | 階層構造のドキュメント一覧 |
| GitHubリンク | リンク | GitHubリポジトリへのリンク |
| Roadmapリンク | リンク | プロジェクトロードマップへのリンク |

### 目次（Table of Contents）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| toc | 配列 | 見出しリスト（h2-h6から自動生成） |

### MDXコンポーネント

| コンポーネント | 説明 |
|---------------|------|
| Tabs / Tab | タブ切り替えコンテンツ |
| Callout | 注意書き・警告・情報ボックス |
| Heading (h1-h6) | カスタムスタイル付き見出し |
| コードブロック | シンタックスハイライト付きコード表示 |

## イベント仕様

### 1-ページアクセス

URLパスに基づいて対応するMDXドキュメントを取得し、レンダリングする。

**処理フロー**:
1. URLの`slug`パラメータを取得（Promise解決）
2. `source.getPage(slug)`でMDXドキュメントを検索
3. ドキュメントが存在しない場合は`notFound()`で404エラー
4. ドキュメントが存在する場合、メタデータ（body, toc, full, title, description）を展開
5. `DocsPage`コンポーネントでレンダリング

### 2-パンくずリストナビゲーション

ユーザーがパンくずリストの項目をクリックすると、該当するドキュメントページに遷移する。

**処理フロー**:
1. `Breadcrumb`コンポーネントが現在のパスを`useBreadcrumb`フックで解析
2. `pageTree`から階層情報を取得
3. 各階層をリンク付きで表示
4. クリック時に該当ページへ遷移

### 3-前後ドキュメントナビゲーション

ページ下部のナビゲーションから前後のドキュメントに遷移する。

**処理フロー**:
1. `FooterNavi`コンポーネントが現在のパスを取得
2. `findNeighbour(pageTree, pathname)`で前後のドキュメントを検索
3. Previous/Nextリンクを表示
4. クリック時に該当ページへ遷移

### 4-GitHubで編集

「Edit on GitHub」リンクをクリックすると、対応するMDXファイルのGitHub編集ページが開く。

**処理フロー**:
1. `editOnGithub`プロパティで編集URLを生成
2. リポジトリ: `liam-hq/liam`
3. ブランチ: `main`
4. パス: `frontend/apps/docs/content/docs/${filePath}`
5. クリック時にGitHub編集ページへ遷移（新規タブ）

### 5-検索機能

ヘッダーの検索機能を使用してドキュメントを検索する。

**処理フロー**:
1. ユーザーが検索キーワードを入力
2. `RootProvider`の検索設定により`/docs/api/search`にリクエスト
3. `createFromSource(source)`で生成されたAPIがドキュメントを検索
4. 検索結果を表示
5. 結果クリック時に該当ドキュメントへ遷移

## データベース更新仕様

本画面はデータベースへのアクセスを行わない。すべてのコンテンツはMDXファイルから静的に生成される。

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

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

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| - | - | - | システムメッセージなし |

## 例外処理

| 例外条件 | 処理内容 | ユーザーへの影響 |
|---------|---------|-----------------|
| 指定されたslugのドキュメントが存在しない | `notFound()`関数を呼び出し | 404エラーページ表示 |
| MDXパースエラー | ビルド時エラー | 該当ページが生成されない |

## 備考

- 本画面はサーバーコンポーネント（Async）として実装されている
- Fumadocsフレームワーク（fumadocs-ui, fumadocs-core, fumadocs-mdx）を使用
- コンテンツは`frontend/apps/docs/content/docs/`ディレクトリ配下のMDXファイルから生成
- 静的サイト生成（SSG）対応：`generateStaticParams`で全ページのパスを事前生成
- コードブロックのテーマ：ライトモード`light-plus`、ダークモード`github-dark-high-contrast`
- OGP画像は全ページ共通で`/images/liam_erd.png`を使用
- 本番環境のベースURLは環境変数`NEXT_PUBLIC_BASE_URL`で設定される（デフォルト: `http://localhost:3002`）

---

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

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

### 推奨読解順序

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

まず、MDXコンテンツの管理方法とデータ構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | source.config.ts | `frontend/apps/docs/source.config.ts` | MDXソース設定、コンテンツディレクトリ、コードテーマ設定 |
| 1-2 | source.ts | `frontend/apps/docs/lib/source.ts` | loaderによるソース生成、baseUrl設定 |
| 1-3 | index.mdx | `frontend/apps/docs/content/docs/index.mdx` | トップページMDXのフロントマター構造（title, description） |

**読解のコツ**: Fumadocsでは`defineDocs`でコンテンツディレクトリを定義し、`loader`でページ構造を生成する。`source.getPage(slug)`でページデータにアクセスできる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | page.tsx | `frontend/apps/docs/app/docs/[[...slug]]/page.tsx` | メインのページコンポーネント |

**主要処理フロー**:
1. **21-32行目**: `Page`関数コンポーネント - paramsからslugを取得し、ソースからページを検索
2. **27行目**: `notFound()`呼び出し - ページが存在しない場合の404処理
3. **29-32行目**: ページデータの展開（body, toc, full, title, description, filePath）
4. **34-72行目**: `DocsPage`コンポーネントによるレンダリング
5. **75-77行目**: `generateStaticParams` - 静的生成用のパラメータ生成
6. **81-101行目**: `generateMetadata` - メタデータ生成（タイトル、OGP等）

#### Step 3: レイアウト構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | layout.tsx | `frontend/apps/docs/app/docs/layout.tsx` | docs配下のレイアウト（DocsLayout使用） |
| 3-2 | layout.config.tsx | `frontend/apps/docs/app/layout.config.tsx` | 共通レイアウト設定（ナビ、ロゴ、外部リンク） |
| 3-3 | layout.tsx | `frontend/apps/docs/app/layout.tsx` | ルートレイアウト（GTM、Cookie Consent等） |

**主要処理フロー**:
- **layout.tsx (docs)**: `DocsLayout`でサイドバー付きレイアウトを構成
- **layout.config.tsx**: `baseOptions`でLiamロゴ、GitHub/Roadmapリンクを設定

#### Step 4: カスタムコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Breadcrumb.tsx | `frontend/apps/docs/components/Breadcrumb/Breadcrumb.tsx` | パンくずリストの実装 |
| 4-2 | FooterNavi.tsx | `frontend/apps/docs/components/FooterNavi/FooterNavi.tsx` | 前後ナビゲーションの実装 |
| 4-3 | Tabs.tsx | `frontend/apps/docs/components/Tabs/Tabs.tsx` | タブコンポーネントの実装 |
| 4-4 | Callout.tsx | `frontend/apps/docs/components/Callout/Callout.tsx` | 注意書きボックスの実装 |
| 4-5 | Heading.tsx | `frontend/apps/docs/components/Heading/Heading.tsx` | 見出しコンポーネントの実装 |

**主要処理フロー**:
- **Breadcrumb.tsx**: `useBreadcrumb`フックで現在パスから階層を取得
- **FooterNavi.tsx**: `findNeighbour`で前後ページを検索
- **Callout.tsx**: info/warn/errorの3種類のスタイル対応

#### Step 5: 検索APIを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | route.ts | `frontend/apps/docs/app/docs/api/search/route.ts` | 検索API実装 |

**主要処理フロー**:
- **4行目**: `createFromSource(source)`でFumadocsの検索エンドポイントを生成

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

```
/docs/[[...slug]]（ドキュメント詳細ページ）
    │
    ├─ layout.tsx (app)
    │      ├─ GoogleTagManager
    │      ├─ GTMConsent
    │      ├─ RootProvider
    │      │      └─ 検索設定（/docs/api/search）
    │      ├─ Banner
    │      └─ CookieConsent
    │
    ├─ layout.tsx (docs)
    │      └─ DocsLayout
    │             ├─ サイドバー（source.pageTree）
    │             └─ baseOptions（ナビ設定）
    │
    └─ page.tsx ([[...slug]])
           │
           ├─ source.getPage(slug)
           │      └─ MDXコンテンツ取得
           │
           └─ DocsPage
                  ├─ Breadcrumb
                  ├─ DocsTitle
                  ├─ DocsDescription
                  ├─ DocsBody
                  │      └─ MDXコンポーネント
                  │             ├─ Tabs / Tab
                  │             ├─ Callout
                  │             └─ Heading (h1-h6)
                  ├─ FooterNavi
                  └─ editOnGithub
```

### データフロー図

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

URLパス              ───▶ Next.js Router          ───▶ slugパラメータ
  /docs/cli/ci-cd          │
                           ▼
                      source.getPage(slug)
                           │
                           ▼
MDXファイル          ───▶ fumadocs-mdx            ───▶ ページデータ
  content/docs/            │                            {body, toc, title...}
  cli/ci-cd.mdx            │
                           ▼
                      DocsPage + MDXコンポーネント
                           │
                           ▼
                      HTMLレンダリング           ───▶ ドキュメント表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `frontend/apps/docs/app/docs/[[...slug]]/page.tsx` | ソース | ドキュメント詳細ページコンポーネント |
| layout.tsx | `frontend/apps/docs/app/docs/layout.tsx` | ソース | docsレイアウト（サイドバー付き） |
| layout.tsx | `frontend/apps/docs/app/layout.tsx` | ソース | ルートレイアウト（GTM等） |
| layout.config.tsx | `frontend/apps/docs/app/layout.config.tsx` | 設定 | レイアウト共通設定 |
| source.ts | `frontend/apps/docs/lib/source.ts` | ソース | MDXソースローダー |
| source.config.ts | `frontend/apps/docs/source.config.ts` | 設定 | MDX設定（テーマ等） |
| route.ts | `frontend/apps/docs/app/docs/api/search/route.ts` | API | 検索エンドポイント |
| Breadcrumb.tsx | `frontend/apps/docs/components/Breadcrumb/Breadcrumb.tsx` | コンポーネント | パンくずリスト |
| FooterNavi.tsx | `frontend/apps/docs/components/FooterNavi/FooterNavi.tsx` | コンポーネント | 前後ナビゲーション |
| Tabs.tsx | `frontend/apps/docs/components/Tabs/Tabs.tsx` | コンポーネント | タブUI |
| Callout.tsx | `frontend/apps/docs/components/Callout/Callout.tsx` | コンポーネント | 注意書きボックス |
| Heading.tsx | `frontend/apps/docs/components/Heading/Heading.tsx` | コンポーネント | 見出し |
| LiamLogo.tsx | `frontend/apps/docs/components/LiamLogo/LiamLogo.tsx` | コンポーネント | ロゴSVG |
| Banner.tsx | `frontend/apps/docs/components/Banner/Banner.tsx` | コンポーネント | 告知バナー |
| index.mdx | `frontend/apps/docs/content/docs/index.mdx` | コンテンツ | トップページMDX |
| *.mdx | `frontend/apps/docs/content/docs/**/*.mdx` | コンテンツ | 各種ドキュメント |
