# 画面設計書 10-ブランチ詳細画面

## 概要

本ドキュメントは、Liam DBアプリケーションのブランチ詳細画面について定義する。

### 本画面の処理概要

ブランチ詳細画面は、特定のプロジェクトの特定ブランチ（またはコミット）の詳細情報を表示する画面である。スキーマファイルのパスとフォーマットを設定し、ERD図を表示するためのリンクを提供する。

**業務上の目的・背景**：Liam DBではGitHubリポジトリのブランチ単位でデータベーススキーマを管理する。この画面では、対象ブランチのスキーマファイル設定を行い、設定されたスキーマファイルのERD図へアクセスできる。複数のブランチを切り替えて作業することで、スキーマの変更をブランチごとに追跡できる。

**画面へのアクセス方法**：
- プロジェクト詳細画面（`/projects/[projectId]`）から自動リダイレクト
- 直接`/projects/[projectId]/ref/[branchOrCommit]`にアクセス

**主要な操作・処理内容**：
1. プロジェクト情報とスキーマパス情報をデータベースから取得
2. スキーマファイルパスとフォーマットを設定・更新
3. ERD表示画面へのリンクをクリックしてER図を表示
4. プロジェクト一覧へ戻る

**画面遷移**：
- ERD表示リンククリック時 → スキーマ画面（`/projects/[projectId]/ref/[branchOrCommit]/schema/[schemaFilePath]`）
- 「Back to Project」クリック時 → プロジェクト詳細画面（`/projects/[projectId]`）

**権限による表示制御**：認証必須。プロジェクトへのアクセス権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 27 | プロジェクト管理 | 主機能 | 特定ブランチまたはコミットのプロジェクト詳細情報を表示 |
| 28 | GitHub連携 | 補助機能 | GitHubリポジトリ情報の取得 |
| 39 | Supabaseクライアント | API連携 | プロジェクトおよびスキーマパス情報の取得 |

## 画面種別

詳細

## URL/ルーティング

- URL: `/projects/[projectId]/ref/[branchOrCommit]`
- ファイル: `frontend/apps/app/app/projects/[projectId]/ref/[branchOrCommit]/page.tsx`
- レンダリング: サーバーコンポーネント
- 動的パラメータ: `projectId`（プロジェクトID）、`branchOrCommit`（ブランチ名またはコミットハッシュ）

## 入出力項目

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

| 項目名 | 項目ID | データ型 | 必須 | 備考 |
|--------|--------|----------|------|------|
| プロジェクトID | projectId | string | はい | URLパスパラメータ |
| ブランチ/コミット | branchOrCommit | string | はい | URLパスパラメータ、エンコード対応 |

### 入力項目（フォーム）

| 項目名 | 項目ID | データ型 | 必須 | 備考 |
|--------|--------|----------|------|------|
| スキーマファイルパス | path | string | はい | e.g., schema.sql or path/to/schema.rb |
| スキーマフォーマット | format | FormatType | はい | ドロップダウン選択、デフォルト: postgres |

## 表示項目

| 項目名 | 説明 | 備考 |
|--------|------|------|
| 戻るリンク | "Back to Project" | プロジェクト詳細へのリンク |
| ページタイトル | "{プロジェクト名} / {ブランチ名}" | h1要素 |
| セクションタイトル | "Schema Configuration" | h2要素 |
| スキーマパス設定フォーム | パスとフォーマットの入力 | SchemaFilePathFormコンポーネント |
| ERD表示リンク | "View ERD for {スキーマパス}" | スキーマパス設定済みの場合のみ表示 |

## イベント仕様

### 1-スキーマパス保存

スキーマファイルパスとフォーマットを保存。

**トリガー**：「Save」ボタンクリック

**処理フロー**：
1. フォームデータ（projectId, path, format）を取得
2. `saveSchemaFilePath`サーバーアクションを呼び出し
3. schema_file_pathsテーブルをUPSERT（存在すれば更新、なければ挿入）
4. 成功時：トースト通知で成功メッセージ表示
5. 失敗時：トースト通知でエラーメッセージ表示

### 2-ERD表示画面への遷移

設定されたスキーマファイルのERD図を表示。

**トリガー**：ERD表示リンククリック

**処理フロー**：
1. `/projects/[projectId]/ref/[branchOrCommit]/schema/[schemaFilePath]`へ遷移

### 3-プロジェクトへ戻る

プロジェクト詳細画面へ戻る。

**トリガー**：「Back to Project」リンククリック

**処理フロー**：
1. `/projects/[projectId]`へ遷移

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ページ読み込み | projects | SELECT | プロジェクト情報取得 |
| ページ読み込み | project_repository_mappings | SELECT | リポジトリマッピング取得 |
| ページ読み込み | github_repositories | SELECT | リポジトリ情報取得 |
| ページ読み込み | schema_file_paths | SELECT | スキーマパス情報取得 |
| スキーマパス保存 | schema_file_paths | UPSERT | スキーマパスとフォーマットを保存 |

### テーブル別更新項目詳細

#### projects

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | project_idで取得 | プロジェクト情報全体 |

#### project_repository_mappings / github_repositories

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, name, owner | project_idに紐づくリポジトリ情報 | JOINで取得 |

#### schema_file_paths

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | path, format | project_idで取得 | - |
| UPSERT | path | 入力されたパス | - |
| UPSERT | format | 選択されたフォーマット | - |

## メッセージ仕様

| メッセージID | メッセージ内容 | 表示タイミング | 種別 |
|--------------|---------------|----------------|------|
| MSG-001 | "Saved" + 詳細メッセージ | スキーマパス保存成功時 | 成功（トースト） |
| ERR-001 | "Error" + 詳細メッセージ | スキーマパス保存失敗時 | エラー（トースト） |

## 例外処理

| 例外ケース | 処理内容 |
|------------|----------|
| URLパラメータ不正 | 404 Not Found を返却 |
| プロジェクト未存在 | 404 Not Found を返却、コンソールにエラーログ |
| スキーマパス取得エラー | 警告ログ出力、nullとして処理続行 |
| スキーマパス保存失敗 | エラートースト表示 |

## 備考

- 動的ルート`[projectId]/ref/[branchOrCommit]`を使用
- branchOrCommitはURLエンコードに対応（`branchOrCommitSchema`でバリデーション）
- スキーマパスが未設定の場合、ERD表示リンクは非表示
- スキーマパス保存はuseActionStateを使用した最適化されたフォーム
- トースト通知は@liam-hq/uiのuseToastフックを使用

---

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

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

### 推奨読解順序

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

プロジェクトとスキーマパスのデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | BranchDetailPage.tsx | `frontend/apps/app/components/BranchDetailPage/BranchDetailPage.tsx` | データ取得ロジック、getBranchDetails関数 |

**読解のコツ**: projects, project_repository_mappings, github_repositories, schema_file_pathsの4テーブルをJOINで取得している点に注目。

**主要処理フロー（getBranchDetails）**:
- **12-26行目**: projectsテーブルからリポジトリ情報も含めて取得
- **32-37行目**: schema_file_pathsテーブルからスキーマパス取得
- **48-53行目**: データを整形して返却

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

ブランチ詳細ページのエントリーポイントを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | page.tsx | `frontend/apps/app/app/projects/[projectId]/ref/[branchOrCommit]/page.tsx` | URLパラメータのバリデーション |
| 2-2 | BranchDetailPage.tsx | `frontend/apps/app/components/BranchDetailPage/BranchDetailPage.tsx` | サーバーコンポーネント |

**主要処理フロー（page.tsx）**:
- **7-10行目**: パラメータスキーマ定義（branchOrCommitSchemaを使用）
- **12-14行目**: パラメータバリデーション
- **17-19行目**: BranchDetailPageコンポーネントに渡す

#### Step 3: ビューコンポーネントを理解する

表示UIの実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | BranchDetailPageView.tsx | `frontend/apps/app/components/BranchDetailPage/BranchDetailPageView.tsx` | UI実装 |

**主要処理フロー**:
- **28-29行目**: 戻るリンク
- **30-33行目**: タイトル表示
- **39-45行目**: SchemaFilePathFormコンポーネント
- **46-63行目**: ERD表示リンク（条件付き表示）

#### Step 4: フォームコンポーネントを理解する

スキーマパス設定フォームの実装。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | SchemaFilePathForm.tsx | `frontend/apps/app/components/BranchDetailPage/components/SchemaFilePathForm/SchemaFilePathForm.tsx` | フォームUI、useActionState |
| 4-2 | saveSchemaFilePath.ts | `frontend/apps/app/components/BranchDetailPage/actions/saveSchemaFilePath.ts` | サーバーアクション |

**主要処理フロー（SchemaFilePathForm.tsx）**:
- **27-31行目**: useActionStateでフォーム状態管理
- **33-47行目**: useEffectでトースト表示
- **59-66行目**: パス入力フィールド
- **70-73行目**: フォーマット選択ドロップダウン
- **81-87行目**: フォーム送信

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

```
app/projects/[projectId]/ref/[branchOrCommit]/page.tsx
    │
    └─ components/BranchDetailPage/BranchDetailPage.tsx
           │
           ├─ getBranchDetails()
           │      ├─ supabase.from('projects').select()
           │      └─ supabase.from('schema_file_paths').select()
           │
           └─ BranchDetailPageView.tsx
                  │
                  ├─ Link (Back to Project)
                  │
                  ├─ SchemaFilePathForm.tsx
                  │      ├─ useActionState()
                  │      ├─ FormatSelectDropdown
                  │      └─ actions/saveSchemaFilePath.ts [Server Action]
                  │
                  └─ Link (View ERD) [条件付き]
```

### データフロー図

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

/projects/[id]/ref/[b] ───▶ page.tsx                   ───▶ BranchDetailPage
     │                        │
     │                        └─ Valibotバリデーション
     │
     └─────────────────────▶ BranchDetailPage          ───▶ BranchDetailPageView
                               │
                               └─ getBranchDetails()
                                      ├─ projects
                                      ├─ project_repository_mappings
                                      ├─ github_repositories
                                      └─ schema_file_paths

パス/フォーマット入力 ───▶ SchemaFilePathForm          ───▶ state更新
                               │
                               └─ useActionState

Saveクリック          ───▶ saveSchemaFilePath          ───▶ schema_file_paths UPSERT
                               │
                               └─ トースト表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `frontend/apps/app/app/projects/[projectId]/ref/[branchOrCommit]/page.tsx` | ソース | ブランチ詳細ページのエントリーポイント |
| BranchDetailPage.tsx | `frontend/apps/app/components/BranchDetailPage/BranchDetailPage.tsx` | ソース | ブランチ詳細のサーバーコンポーネント |
| BranchDetailPageView.tsx | `frontend/apps/app/components/BranchDetailPage/BranchDetailPageView.tsx` | ソース | ブランチ詳細のビューコンポーネント |
| SchemaFilePathForm.tsx | `frontend/apps/app/components/BranchDetailPage/components/SchemaFilePathForm/SchemaFilePathForm.tsx` | ソース | スキーマパス設定フォーム |
| saveSchemaFilePath.ts | `frontend/apps/app/components/BranchDetailPage/actions/saveSchemaFilePath.ts` | ソース | スキーマパス保存サーバーアクション |
| FormatSelectDropdown.tsx | `frontend/apps/app/features/sessions/components/shared/FormatSelectDropdown/FormatSelectDropdown.tsx` | ソース | フォーマット選択ドロップダウン |
| BranchDetailPageView.module.css | `frontend/apps/app/components/BranchDetailPage/BranchDetailPageView.module.css` | スタイル | ブランチ詳細ページのスタイル |
| SchemaFilePathForm.module.css | `frontend/apps/app/components/BranchDetailPage/components/SchemaFilePathForm/SchemaFilePathForm.module.css` | スタイル | スキーマパスフォームのスタイル |
| paramsSchema.ts | `frontend/apps/app/libs/routes/paramsSchema.ts` | ソース | branchOrCommitSchemaの定義 |
| server.ts | `frontend/apps/app/libs/db/server.ts` | ソース | Supabaseクライアント生成 |
| urlgen.ts | `frontend/apps/app/libs/routes/urlgen.ts` | ソース | URL生成ユーティリティ |
