# 機能設計書 49-ドキュメントサイト

## 概要

本ドキュメントは、FumadocsベースのドキュメントサイトWebアプリケーションの設計について記載する。この機能は、Liamアプリケーションの使用方法、APIリファレンス、貢献ガイドラインなどのドキュメントを提供するWebサイトを構築する。

### 本機能の処理概要

**業務上の目的・背景**：Liamアプリケーションは、ER図可視化ツール、スキーマパーサー、CLIツールなど多様な機能を提供する。ユーザーや開発者がこれらの機能を効果的に活用するためには、包括的なドキュメントが必要である。Fumadocsフレームワークを使用することで、MDXベースの美しいドキュメントサイトを構築し、検索機能やナビゲーションを提供する。

**機能の利用シーン**：
- ユーザーがLiamの使用方法を学習する際
- 開発者がAPIリファレンスを参照する際
- コントリビューターが貢献ガイドラインを確認する際
- サポート対象フォーマット（PostgreSQL、Prisma等）の詳細を確認する際

**主要な処理内容**：
1. MDXファイルの読み込みとパース
2. ドキュメントページのレンダリング
3. サイドバーナビゲーションの生成
4. 検索機能の提供
5. 静的サイト生成（SSG）
6. パンくずリスト・フッターナビゲーションの表示

**関連システム・外部連携**：
- Fumadocs（ドキュメントフレームワーク）
- Next.js 15（Webフレームワーク）
- MDX（マークダウン拡張）
- Sentry（エラー監視）
- Google Tag Manager（アナリティクス）

**権限による制御**：公開サイトのため、認証・認可は不要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | ドキュメントホーム画面 | 主画面 | /docsへのリダイレクト処理 |
| 22 | ドキュメント詳細画面 | 主画面 | FumadocsベースのMDXドキュメントレンダリング |

## 機能種別

Webアプリケーション / ドキュメントサイト / 静的サイト生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| slug | string[] | No | ドキュメントパス（URLセグメント） | - |

### 入力データソース

- MDXファイル（content/docs/配下）
- メタデータファイル（meta.json）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| HTMLページ | React.ReactNode | レンダリングされたドキュメントページ |
| メタデータ | Metadata | SEO用メタデータ（title、description、OGP） |

### 出力先

Webブラウザへのレスポンス

## 処理フロー

### 処理シーケンス

```
1. ユーザーがドキュメントURLにアクセス
2. Next.jsルーターがリクエストを処理
3. slug パラメータを解析
4. source.getPage(slug)でMDXファイルを取得
5. MDXコンテンツをパースしてReactコンポーネントに変換
6. DocsLayout内でページをレンダリング
   ├─ サイドバー（ナビゲーションツリー）
   ├─ パンくずリスト
   ├─ ドキュメント本文
   ├─ 目次（TOC）
   └─ フッターナビゲーション
7. HTMLレスポンスを返却
```

### フローチャート

```mermaid
flowchart TD
    A[ドキュメントURLアクセス] --> B{ルートパス?}
    B -->|Yes| C[/docsへリダイレクト]
    B -->|No| D[slugパラメータ解析]
    D --> E[source.getPage呼び出し]
    E --> F{ページ存在?}
    F -->|No| G[404 notFound]
    F -->|Yes| H[MDXパース]
    H --> I[Reactコンポーネント生成]
    I --> J[DocsLayoutでレンダリング]
    J --> K[HTMLレスポンス返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-49-01 | ルートリダイレクト | /にアクセス時は/docsにリダイレクト | ルートパスアクセス時 |
| BR-49-02 | 404ハンドリング | 存在しないページはnotFound()を呼び出し | ページ不在時 |
| BR-49-03 | 静的生成 | generateStaticParamsで事前ビルド | ビルド時 |
| BR-49-04 | メタデータ生成 | ページごとにtitle、descriptionを設定 | 各ページ |
| BR-49-05 | Edit on GitHub | 各ページにGitHub編集リンクを表示 | 全ドキュメントページ |

### 計算ロジック

**ドキュメントソース設定**：
```typescript
export const source = loader({
  baseUrl: '/docs',
  source: createMDXSource(docs, meta),
})
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本機能はデータベースを操作しない |

### テーブル別操作詳細

本機能は静的サイトであり、データベースは使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 404 | ページ不在 | 指定slugに対応するMDXファイルがない | notFound()で404ページ表示 |
| - | ビルドエラー | MDXパースエラー | ビルド時にエラーメッセージを表示 |
| - | ランタイムエラー | コンポーネントレンダリングエラー | Sentryでキャプチャ |

### リトライ仕様

静的サイトのためリトライは不要。CDNキャッシュにより高可用性を確保。

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

本機能はデータベースを使用しないため、トランザクション管理は不要。

## パフォーマンス要件

- 静的サイト生成: ビルド時に全ページを事前生成
- CDNキャッシュ: エッジでのキャッシュによる高速配信
- 検索: クライアントサイドでの全文検索

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

- **公開サイト**: 認証不要の公開コンテンツ
- **XSS対策**: MDXコンテンツはサニタイズ済み
- **CSP**: Next.jsのセキュリティヘッダー
- **Sentry**: エラー監視とアラート
- **Cookie同意**: GTMとCookie同意バナー

## 備考

- Fumadocs UIコンポーネントを使用
- MDXでカスタムコンポーネント（Tabs、Callout等）をサポート
- llms.txt対応（AI向けドキュメント）
- サイトマップ自動生成

---

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

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

### 推奨読解順序

#### Step 1: ドキュメントソース設定を理解する

まず、ドキュメントソースの設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | source.ts | `frontend/apps/docs/lib/source.ts` | loaderとcreateMDXSourceの設定 |

**読解のコツ**:
- loader関数でbaseUrlとsourceを設定
- createMDXSourceでdocsとmetaを読み込み

#### Step 2: ルートレイアウトを理解する

アプリケーション全体のレイアウトを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | layout.tsx | `frontend/apps/docs/app/layout.tsx` | ルートレイアウト |

**主要処理フロー**:
1. **9行目**: RootProviderでFumadocs UIを初期化
2. **74-80行目**: 検索APIの設定
3. **82-88行目**: Bannerコンポーネントの表示
4. **91-95行目**: CookieConsent（同意バナー）

#### Step 3: ドキュメントレイアウトを理解する

ドキュメント専用レイアウトを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | layout.tsx | `frontend/apps/docs/app/docs/layout.tsx` | DocsLayout設定 |

**主要処理フロー**:
- **6-11行目**: DocsLayoutでサイドバーツリーを設定
- **8行目**: source.pageTreeでナビゲーション構造を渡す

#### Step 4: ドキュメントページを理解する

各ドキュメントページのレンダリングを確認する。

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

**主要処理フロー**:
- **21-33行目**: Page関数でsource.getPageを呼び出し
- **34-72行目**: DocsPageコンポーネントでレンダリング
- **38-43行目**: editOnGithub設定
- **44-47行目**: パンくずリスト設定
- **48-51行目**: フッターナビゲーション設定
- **55-69行目**: MDXコンポーネントのマッピング
- **75-77行目**: generateStaticParamsで静的パス生成
- **81-101行目**: generateMetadataでSEOメタデータ生成

#### Step 5: レイアウト設定を理解する

共有レイアウト設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | layout.config.tsx | `frontend/apps/docs/app/layout.config.tsx` | baseOptions設定 |

**主要処理フロー**:
- **12-25行目**: ナビゲーション設定（ロゴ、GitHubリンク、ロードマップリンク）

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

検索機能の実装を確認する。

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

**主要処理フロー**:
- **4行目**: createFromSourceでsourceから検索ハンドラを生成

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

```
ユーザーアクセス (/docs/xxx)
    │
    └─ Next.js Router
           │
           ├─ app/docs/layout.tsx (DocsLayout)
           │      └─ source.pageTree (サイドバー)
           │
           └─ app/docs/[[...slug]]/page.tsx
                  │
                  ├─ source.getPage(slug)
                  │      └─ MDXファイル取得・パース
                  │
                  └─ DocsPage
                         ├─ DocsTitle
                         ├─ DocsDescription
                         ├─ DocsBody
                         │      └─ MDX (カスタムコンポーネント)
                         │
                         ├─ Breadcrumb
                         ├─ FooterNavi
                         └─ TOC (目次)
```

### データフロー図

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

                     ┌─────────────────────────┐
URLパス ────────────▶│   Next.js Router       │
(/docs/cli/index)    │                         │
                     └──────────┬──────────────┘
                                │
                     ┌──────────▼──────────────┐
slug ───────────────▶│   source.getPage()     │
['cli', 'index']     │   (MDXファイル検索)     │
                     └──────────┬──────────────┘
                                │
                     ┌──────────▼──────────────┐
MDXファイル ────────▶│   MDXパース             │
(content/docs/cli/   │   createMDXSource()     │
 index.mdx)          └──────────┬──────────────┘
                                │
                     ┌──────────▼──────────────┐
                     │   DocsPage              │──────────▶ HTMLページ
                     │   (React コンポーネント)│
                     └─────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `frontend/apps/docs/app/docs/[[...slug]]/page.tsx` | ソース | ドキュメントページコンポーネント |
| layout.tsx | `frontend/apps/docs/app/docs/layout.tsx` | ソース | ドキュメントレイアウト |
| layout.tsx | `frontend/apps/docs/app/layout.tsx` | ソース | ルートレイアウト |
| layout.config.tsx | `frontend/apps/docs/app/layout.config.tsx` | ソース | レイアウト設定 |
| source.ts | `frontend/apps/docs/lib/source.ts` | ソース | ドキュメントソース設定 |
| route.ts | `frontend/apps/docs/app/docs/api/search/route.ts` | ソース | 検索API |
| page.tsx | `frontend/apps/docs/app/page.tsx` | ソース | ルートリダイレクト |
| next.config.mjs | `frontend/apps/docs/next.config.mjs` | 設定 | Next.js設定 |
| content/docs/ | `frontend/apps/docs/content/docs/` | コンテンツ | MDXドキュメントファイル |
