# 画面設計書 14-デザインセッション詳細画面

## 概要

本ドキュメントは、Liam DBアプリケーションにおけるデザインセッション詳細画面の設計仕様を定義する。

### 本画面の処理概要

この画面では、AIエージェントとの対話型データベース設計セッションを実行する。チャットインターフェースでAIと対話し、スキーマの分析・設計・修正をリアルタイムで行える。

**業務上の目的・背景**：
データベース設計作業の中核となる画面である。LangGraphベースのAIエージェント（Deep Modelingワークフロー）を活用し、ユーザーの要件を分析してスキーマ設計を自動生成・提案する。設計のバージョン管理機能により、変更履歴の追跡とロールバックが可能。また、公開共有機能によりチームメンバーとの設計レビューを促進する。

**画面へのアクセス方法**：
- デザインセッション新規作成画面からセッション開始後に遷移
- 最近のセッション一覧から既存セッションを選択
- プロジェクトセッション一覧から既存セッションを選択
- URLパターンは `/design_sessions/:id`

**主要な操作・処理内容**：
1. AIエージェントとのチャット対話（ストリーミング応答）
2. スキーマのER図表示と差分確認
3. バージョン管理（履歴閲覧、バージョン切り替え）
4. 公開共有設定の管理
5. 分析結果（Artifact）の確認

**画面遷移**：
- 遷移元: デザインセッション新規作成画面（`/design_sessions/new`）、プロジェクトセッション一覧画面
- 遷移先: 公開デザインセッション詳細画面（`/public/design_sessions/:id`）※公開共有有効化時

**権限による表示制御**：
認証済みユーザーのみアクセス可能。セッション作成者のみが編集・チャット操作可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 29 | デザインセッション | 主機能 | デザインセッションの詳細表示とAIチャット機能 |
| 18 | Deep Modelingワークフロー | 主機能 | LangGraphベースのAIエージェントによるスキーマ分析・設計支援 |
| 19 | DB Agentサブグラフ | 補助機能 | ReActパターンによる反復的なデータベーススキーマ設計 |
| 23 | ストリーミング応答 | 補助機能 | AIエージェントのリアルタイムストリーミング応答 |
| 24 | チェックポイント永続化 | 補助機能 | エージェント状態のSupabaseベース永続化 |
| 13 | マイグレーション操作生成 | 補助機能 | スキーマ差分からマイグレーション操作リストを生成 |
| 32 | 共有機能 | 補助機能 | セッションの公開共有設定 |
| 6 | スキーマ差分表示 | 補助機能 | スキーマの変更差分を視覚的に表示 |
| 1 | ER図表示 | 補助機能 | 設計中スキーマのER図表示 |
| 35 | レイアウトコンポーネント | 補助機能 | リサイズ可能なパネルレイアウト |

## 画面種別

詳細 / エディタ

## URL/ルーティング

```
/design_sessions/:id
```

動的パラメータ:
- `id`: デザインセッションの一意識別子

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| id | string | Yes | URLパラメータ - デザインセッションID |
| userInput | string | No | チャット入力メッセージ |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| messages | StoredMessage[] | チャットメッセージ履歴 |
| buildingSchema | object | 現在のビルディングスキーマ情報 |
| initialSchema | Schema | 現在のスキーマ |
| baselineSchema | Schema | 初期スキーマスナップショット |
| versions | Version[] | バージョン一覧 |
| initialIsPublic | boolean | 公開共有状態 |
| analyzedRequirements | AnalyzedRequirements | 分析された要件情報 |
| workflowError | string | ワークフローエラー情報 |

## 表示項目

### チャットパネル（左側）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| messages | ChatMessage[] | チャットメッセージ一覧 |
| isWorkflowRunning | boolean | ワークフロー実行中フラグ |
| error | string | エラーメッセージ |

### 出力パネル（右側）

#### ERDタブ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| schema | Schema | 表示中のスキーマ |
| baselineSchema | Schema | 比較用ベースラインスキーマ |
| versions | Version[] | バージョン一覧 |
| selectedVersion | Version | 選択中のバージョン |

#### Artifactタブ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| analyzedRequirements | AnalyzedRequirements | 分析結果 |

### バージョン情報

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | バージョンID |
| number | number | バージョン番号 |
| created_at | string | 作成日時 |
| patch | object | 変更パッチ |
| reverse_patch | object | 逆パッチ（ロールバック用） |

## イベント仕様

### 1-チャットメッセージ送信

ユーザーがチャット入力欄にメッセージを入力して送信する。

**処理フロー**:
1. ユーザー入力を受付
2. `start`関数を呼び出し
3. ワークフローが開始（isStreaming = true）
4. AIエージェントがストリーミング応答を返す
5. メッセージリストをリアルタイム更新
6. 分析結果があればArtifactタブに表示
7. スキーマ変更があればERDタブを更新

### 2-バージョン選択

バージョン一覧から特定のバージョンを選択する。

**処理フロー**:
1. `handleVersionChange`関数がトリガー
2. `setSelectedVersion`で選択バージョンを更新
3. `setActiveTab`でERDタブをアクティブに
4. 該当バージョンのスキーマを表示

### 3-パネルリサイズ

チャットパネルと出力パネルの境界をドラッグしてリサイズする。

**処理フロー**:
1. ResizableHandleをドラッグ
2. `handleLayoutChange`関数でサイズ更新
3. Cookieにレイアウト状態を保存（7日間有効）

### 4-公開共有設定

セッションの公開共有設定を変更する。

**処理フロー**:
1. 共有設定UIを操作
2. `checkPublicShareStatus`でステータス確認
3. public_share_settingsテーブルを更新
4. 公開URLが利用可能になる

### 5-ワークフローリプレイ

中断したワークフローを再開する。

**処理フロー**:
1. `getWorkflowInProgress`で中断状態を確認
2. `determineWorkflowAction`でアクション決定
3. 'replay'の場合、`replay`関数を呼び出し
4. ワークフローを中断地点から再開

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | building_schemas | SELECT | ビルディングスキーマ情報取得 |
| 画面表示 | building_schema_versions | SELECT | バージョン一覧取得 |
| 画面表示 | public_share_settings | SELECT | 公開共有設定取得 |
| バージョン作成 | building_schema_versions | INSERT | 新規バージョン作成 |
| スキーマ更新 | building_schemas | UPDATE | スキーマ内容更新 |
| 公開設定変更 | public_share_settings | INSERT/DELETE | 公開設定の追加・削除 |

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

#### building_schemas（取得）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id | ビルディングスキーマID | - |
| SELECT | design_session_id | セッションID | - |
| SELECT | organization_id | 組織ID | - |
| SELECT | schema | 現在のスキーマ（JSON） | - |
| SELECT | initial_schema_snapshot | 初期スキーマスナップショット | - |
| SELECT | git_sha | GitコミットSHA | - |

取得条件:
- `design_session_id = :designSessionId`

#### building_schema_versions（取得）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id | バージョンID | - |
| SELECT | building_schema_id | ビルディングスキーマID | - |
| SELECT | number | バージョン番号 | - |
| SELECT | created_at | 作成日時 | - |
| SELECT | patch | 変更パッチ | - |
| SELECT | reverse_patch | 逆パッチ | - |

取得条件:
- `building_schema_id = :buildingSchemaId`
- `ORDER BY number DESC`

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 表示条件 |
|------------|------|-----------|---------|
| MSG-001 | エラー | Building schema not found for design session | ビルディングスキーマが見つからない場合 |
| MSG-002 | エラー | Invalid schema format | スキーマフォーマットが不正な場合 |
| MSG-003 | エラー | ワークフローエラー | チェックポイントエラーがある場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| パラメータバリデーションエラー | notFound()を呼び出し、404ページを表示 |
| ビルディングスキーマ未発見 | エラーをスロー |
| スキーマフォーマット不正 | エラーをスロー |
| ワークフローエラー | エラーメッセージをUIに表示、リプレイ可能 |
| ストリーミングエラー | エラーメッセージをチャットパネルに表示 |

## 備考

- サーバーコンポーネントとクライアントコンポーネントのハイブリッド実装
- Suspenseでローディング状態をハンドリング
- ViewModeProviderで'private'モードを設定
- パネルレイアウトはCookieで永続化（7日間、PANEL_LAYOUT_COOKIE_NAME）
- デフォルトパネルサイズはDEFAULT_PANEL_SIZESで定義
- BaseMessageは直接渡せないためStoredMessageにシリアライズ
- ワークフロー実行中は自動的にhasTriggeredInitialWorkflowフラグで重複実行を防止

---

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

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

### 推奨読解順序

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

まず、プログラム間で受け渡されるデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `frontend/apps/app/components/SessionDetailPage/types.ts` | Version型、Props型の定義 |
| 1-2 | Schema型 | `frontend/packages/schema/src/schema/index.ts` | スキーマデータ構造 |

**読解のコツ**: Version型はid, number, created_at, building_schema_id, patch, reverse_patchを持つ。StoredMessageはLangChainのメッセージシリアライズ形式。

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

処理の起点となるファイル・関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | page.tsx | `frontend/apps/app/app/design_sessions/[id]/page.tsx` | パラメータバリデーションとSessionDetailPage呼び出し |

**主要処理フロー**:
1. **行6-8**: paramsSchemaでidをバリデーション
2. **行10-12**: パラメータ検証、失敗時は404
3. **行14**: designSessionIdを抽出
4. **行16**: SessionDetailPageコンポーネントを呼び出し

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | SessionDetailPage.tsx | `frontend/apps/app/components/SessionDetailPage/SessionDetailPage.tsx` | サーバーサイドデータ取得 |

**主要処理フロー**:
- **行26-28**: serializeMessages - BaseMessageをStoredMessageに変換
- **行30-92**: loadSessionData - セッションデータの非同期取得
  - **行43-45**: getBuildingSchemaでビルディングスキーマ取得
  - **行48-56**: LangGraph用のリポジトリとコンフィグ設定
  - **行57-59**: getMessages, getAnalyzedRequirementsでAI関連データ取得
  - **行62-66**: getCheckpointErrorsでエラー取得
  - **行68-82**: スキーマのバリデーション
- **行117**: getVersionsでバージョン一覧取得
- **行120-121**: checkPublicShareStatusで公開設定確認
- **行143-164**: Suspense + ViewModeProviderでレンダリング

#### Step 4: クライアントコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | SessionDetailPageClient.tsx | `frontend/apps/app/components/SessionDetailPage/SessionDetailPageClient.tsx` | クライアントサイドの状態管理とUI |

**主要処理フロー**:
- **行43-53**: determineInitialTab - 初期タブの決定ロジック
- **行67-84**: useRealtimeVersionsWithSchema - リアルタイムバージョン管理フック
- **行95-100**: useStream - ストリーミング通信フック
- **行102-111**: analyzedRequirements変更時のタブ切り替え
- **行129-159**: 初期ワークフロー自動トリガー処理
- **行161-212**: ResizablePanelGroupによるレイアウト

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

```
page.tsx (エントリーポイント)
    │
    └─ SessionDetailPage.tsx (サーバーコンポーネント)
           │
           ├─ loadSessionData()
           │      ├─ getBuildingSchema()
           │      │      └─ Supabase (building_schemas SELECT)
           │      │
           │      ├─ createSupabaseRepositories()
           │      │
           │      ├─ getMessages() (@liam-hq/agent)
           │      │
           │      ├─ getAnalyzedRequirements() (@liam-hq/agent)
           │      │
           │      └─ getCheckpointErrors() (@liam-hq/agent)
           │
           ├─ getVersions()
           │      └─ Supabase (building_schema_versions SELECT)
           │
           ├─ checkPublicShareStatus()
           │      └─ Supabase (public_share_settings SELECT)
           │
           └─ SessionDetailPageClient.tsx (クライアントコンポーネント)
                  │
                  ├─ useRealtimeVersionsWithSchema()
                  │
                  ├─ useStream()
                  │      ├─ start() - ワークフロー開始
                  │      └─ replay() - ワークフロー再開
                  │
                  ├─ Chat.tsx (チャットUI)
                  │
                  └─ Output.tsx (出力パネル)
                         ├─ ERD表示
                         └─ Artifact表示
```

### データフロー図

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

URLパラメータ ───▶ page.tsx ───────────────▶ SessionDetailPage
(id)               (バリデーション)

セッションID ────▶ loadSessionData ─────────▶ messages, schema,
                   (サーバー処理)              versions, etc.

初期データ ──────▶ SessionDetailPageClient ─▶ UI状態管理
                   (クライアント処理)

ユーザー入力 ───▶ useStream.start() ────────▶ ストリーミング応答
                   (API呼び出し)               メッセージ更新

バージョン選択 ─▶ handleVersionChange ─────▶ スキーマ表示更新
                   (状態更新)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `frontend/apps/app/app/design_sessions/[id]/page.tsx` | ソース | ページエントリーポイント |
| SessionDetailPage.tsx | `frontend/apps/app/components/SessionDetailPage/SessionDetailPage.tsx` | ソース | サーバーコンポーネント |
| SessionDetailPageClient.tsx | `frontend/apps/app/components/SessionDetailPage/SessionDetailPageClient.tsx` | ソース | クライアントコンポーネント |
| Chat.tsx | `frontend/apps/app/components/SessionDetailPage/components/Chat/Chat.tsx` | ソース | チャットUI |
| Output.tsx | `frontend/apps/app/components/SessionDetailPage/components/Output/Output.tsx` | ソース | 出力パネル |
| constants.ts | `frontend/apps/app/components/SessionDetailPage/constants.ts` | ソース | 定数定義 |
| types.ts | `frontend/apps/app/components/SessionDetailPage/types.ts` | ソース | 型定義 |
| useStream.ts | `frontend/apps/app/components/SessionDetailPage/hooks/useStream.ts` | ソース | ストリーミングフック |
| useRealtimeVersionsWithSchema.ts | `frontend/apps/app/components/SessionDetailPage/hooks/useRealtimeVersionsWithSchema.ts` | ソース | バージョン管理フック |
| getBuildingSchema.ts | `frontend/apps/app/components/SessionDetailPage/services/buildingSchema/server/getBuildingSchema.ts` | ソース | スキーマ取得サービス |
| getVersions.ts | `frontend/apps/app/components/SessionDetailPage/services/getVersions.ts` | ソース | バージョン取得サービス |
| ViewModeContext.tsx | `frontend/apps/app/components/SessionDetailPage/contexts/ViewModeContext.tsx` | ソース | 表示モードコンテキスト |
