# 機能設計書 29-デザインセッション

## 概要

本ドキュメントは、Liam DBシステムにおけるデザインセッション機能の設計を記述するものである。本機能は、AIエージェントとの対話によるデータベース設計セッションの作成と管理を実現する。

### 本機能の処理概要

デザインセッション機能は、複数のソース（GitHub、URL、ペースト、スクラッチ、アップロード）からスキーマを取得し、AIエージェントとの対話セッションを作成する。セッションには初期スキーマが保存され、設計の変更履歴を追跡できる。

**業務上の目的・背景**：データベース設計はAIエージェントとの対話を通じて行われる。デザインセッションにより、設計の起点となるスキーマを設定し、変更履歴を追跡し、後から設計を継続できる。

**機能の利用シーン**：
- 新規デザインセッション作成画面でスキーマソースを選択
- GitHub連携プロジェクトからセッション開始
- URL指定でスキーマファイルを取得してセッション開始
- スキーマをペーストしてセッション開始
- スクラッチ（空スキーマ）でセッション開始

**主要な処理内容**：
1. セッション作成（createGitHubSession、createUrlSession、createPasteSession、createScratchSession）
2. スキーマパース（parseSchemaContent）
3. デザインセッション・ビルディングスキーマのDB保存
4. セッション名の自動生成

**関連システム・外部連携**：Supabase PostgreSQL、GitHub API（スキーマ取得）、@liam-hq/schema（パーサー）

**権限による制御**：認証ユーザーのみセッション作成可能。セッションは組織に紐づく。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 13 | デザインセッション新規作成画面 | 主画面 | セッション作成、スキーマソース選択 |
| 14 | デザインセッション詳細画面 | 主画面 | セッション利用、AIエージェント対話 |

## 機能種別

データ管理 / セッション管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| initialMessage | string | Yes | 初期メッセージ（最初の質問） | minLength(1) |
| isDeepModelingEnabled | boolean | No（デフォルトtrue） | DeepModeling有効化フラグ | - |
| parentDesignSessionId | string | No | 親セッションID（継続時） | UUID |
| projectId | string | No（GitHub時） | プロジェクトID | UUID |
| gitSha | string | No（GitHub時） | GitコミットSHA | - |
| schemaUrl | string | Yes（URL時） | スキーマファイルURL | url() |
| schemaContent | string | Yes（Paste時） | スキーマ内容 | minLength(1), maxLength(100000) |
| schemaFormat | string | Yes（URL/Paste/Upload時） | フォーマット | picklist(['postgres', 'schemarb', 'prisma', 'tbls']) |
| schemaFile | File | Yes（Upload時） | スキーマファイル | file() |

### 入力データソース

- フォーム入力
- GitHub API（スキーマファイル内容）
- URL経由でのファイル取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| designSessionId | string | 作成されたセッションID |
| redirectTo | string | リダイレクト先パス |
| userName | string | 作成ユーザー名 |
| initialMessage | string | 初期メッセージ |

### 出力先

- Supabase データベース（design_sessions、building_schemas）

## 処理フロー

### 処理シーケンス

```
1. フォームデータ検証
   └─ parseFormData() で valibot 検証
2. スキーマ取得（ソースに応じて）
   └─ GitHub: getFileContent() でリポジトリから取得
   └─ URL: fetchSchemaFromUrl() でURL取得
   └─ Paste: フォームデータから直接取得
   └─ Scratch: 空スキーマ使用
3. スキーマパース
   └─ parseSchemaContent() で Schema 型に変換
4. セッション作成
   └─ createSession()
   └─ getCurrentUserId() で認証確認
   └─ getOrganizationId() で組織ID取得
   └─ createDesignSession() で design_sessions INSERT
   └─ createBuildingSchema() で building_schemas INSERT
5. リダイレクト
   └─ /design_sessions/{designSessionId} へ
```

### フローチャート

```mermaid
flowchart TD
    A[フォーム送信] --> B{スキーマソース}
    B -->|GitHub| C[getFileContent]
    B -->|URL| D[fetchSchemaFromUrl]
    B -->|Paste| E[formData取得]
    B -->|Scratch| F[空スキーマ]
    C --> G[parseSchemaContent]
    D --> G
    E --> G
    F --> H[createSession]
    G --> H
    H --> I[getCurrentUserId]
    I --> J{認証済み?}
    J -->|No| K[エラー返却]
    J -->|Yes| L[getOrganizationId]
    L --> M[createDesignSession]
    M --> N[createBuildingSchema]
    N --> O[リダイレクト]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-29-01 | セッション名生成 | 初期メッセージの先頭20文字から生成 | 全セッション |
| BR-29-02 | スキーマコンテンツ上限 | 100KB（100,000文字）まで | Paste時 |
| BR-29-03 | サポートフォーマット | postgres, schemarb, prisma, tbls | スキーマパース時 |
| BR-29-04 | 空スキーマ | tables: {}, enums: {}, extensions: {} | Scratch時 |

### 計算ロジック

- セッション名生成: `generateSessionName(initialMessage)`
  - 空文字または3文字未満の場合: `Design Session - {ISO日時}`
  - それ以外: 先頭20文字 + "..."（20文字超の場合）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| createDesignSession | design_sessions | INSERT | セッション作成 |
| createBuildingSchema | building_schemas | INSERT | スキーマ保存 |
| getProject | projects, project_repository_mappings, github_repositories | SELECT | プロジェクト情報取得 |
| getRepositoryInfo | project_repository_mappings, github_repositories, schema_file_paths | SELECT | リポジトリ情報取得 |

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

#### design_sessions

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name, project_id, organization_id, created_by_user_id, parent_design_session_id | フォーム入力値 | createDesignSession |

#### building_schemas

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | design_session_id, organization_id, schema, initial_schema_snapshot, schema_file_path, git_sha | パース済みスキーマ | createBuildingSchema |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| invalid_form | 検証エラー | フォームデータ不正 | エラーメッセージ返却 |
| auth_required | 認証エラー | 未認証ユーザー | エラーメッセージ返却 |
| user_info_failed | ユーザー情報エラー | ユーザー情報取得失敗 | エラーメッセージ返却 |
| org_id_failed | 組織IDエラー | 組織ID取得失敗 | エラーメッセージ返却 |
| schema_fetch_failed | スキーマ取得エラー | GitHub/URL取得失敗 | エラーメッセージ返却 |
| schema_parse_failed | パースエラー | スキーマパース失敗 | エラーメッセージ返却 |
| session_create_failed | 作成エラー | DBインサート失敗 | エラーメッセージ返却 |

### リトライ仕様

- スキーマ取得・パース・DB操作にリトライなし
- ユーザーは再度フォーム送信で再試行可能

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

- createSession内で design_sessions と building_schemas を順次 INSERT
- 現状トランザクション制御なし（改善候補）

## パフォーマンス要件

- スキーマパース: prism.wasm を使用して高速パース
- 大きなスキーマファイル: 100KB制限（Paste時）

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

- 認証ユーザーのみセッション作成可能
- 組織IDによるデータ分離
- URL取得時は外部URLへのアクセスに注意（SSRF対策は要確認）

## 備考

スキーマパーサーは @liam-hq/schema パッケージの parse 関数を使用。prism.wasm は process.cwd() から読み込む。

---

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

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

### 推奨読解順序

#### Step 1: フォームバリデーションスキーマを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sessionFormValidation.ts | `frontend/apps/app/features/sessions/components/shared/validation/sessionFormValidation.ts` | 各フォームスキーマ定義 |

**主要処理フロー**:
- **23-36行目**: BaseFormDataSchema（共通フィールド）
- **39-43行目**: GitHubFormDataSchema
- **49-56行目**: UploadFormDataSchema
- **59-66行目**: UrlFormDataSchema
- **69-80行目**: PasteFormDataSchema
- **102-108行目**: parseFormData ヘルパー

#### Step 2: 共通セッション作成ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sessionCreationHelpers.ts | `frontend/apps/app/features/sessions/components/shared/services/sessionCreationHelpers.ts` | 共通処理 |

**主要処理フロー**:
- **23-32行目**: generateSessionName（セッション名生成）
- **39-44行目**: getCurrentUserId（認証ユーザーID取得）
- **56-80行目**: createDesignSession（design_sessions INSERT）
- **82-109行目**: createBuildingSchema（building_schemas INSERT）
- **111-128行目**: parseSchemaContent（スキーマパース）
- **130-192行目**: createSession（メイン処理）

#### Step 3: 各ソース別セッション作成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | createGitHubSession.ts | `frontend/apps/app/features/sessions/components/GitHubSessionForm/actions/createGitHubSession.ts` | GitHub連携 |
| 3-2 | createUrlSession.ts | `frontend/apps/app/features/sessions/components/UrlSessionForm/actions/createUrlSession.ts` | URL指定 |
| 3-3 | createPasteSession.ts | `frontend/apps/app/features/sessions/components/PasteSessionForm/actions/createPasteSession.ts` | ペースト |
| 3-4 | createScratchSession.ts | `frontend/apps/app/features/sessions/components/ScratchSessionForm/actions/createScratchSession.ts` | スクラッチ |

**主要処理フロー**:
- **123-169行目（createGitHubSession.ts）**: GitHubからスキーマ取得してセッション作成
- **36-72行目（createUrlSession.ts）**: URLからスキーマ取得
- **13-56行目（createPasteSession.ts）**: ペーストコンテンツをパース
- **10-30行目（createScratchSession.ts）**: 空スキーマでセッション作成

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

```
[GitHub セッション]
createGitHubSession
    │
    ├─ parseFormData (GitHubFormDataSchema)
    │
    ├─ getProject
    │      └─ supabase.from('projects').select
    │
    ├─ processGitHubSchema
    │      ├─ getRepositoryInfo
    │      │      └─ supabase.from('project_repository_mappings').select
    │      │
    │      ├─ getFileContent (GitHub API)
    │      │
    │      └─ parseSchemaContent
    │             └─ parse (prism.wasm)
    │
    └─ createSession
           ├─ getCurrentUserId
           ├─ getUserInfo
           ├─ getOrganizationId
           ├─ createDesignSession
           │      └─ supabase.from('design_sessions').insert
           │
           └─ createBuildingSchema
                  └─ supabase.from('building_schemas').insert

[URL セッション]
createUrlSession
    │
    ├─ parseFormData (UrlFormDataSchema)
    │
    ├─ fetchSchemaFromUrl
    │
    ├─ parseSchemaContent
    │
    └─ createSession

[Paste セッション]
createPasteSession
    │
    ├─ parseFormData (PasteFormDataSchema)
    │
    ├─ parseSchemaContent
    │
    └─ createSession

[Scratch セッション]
createScratchSession
    │
    ├─ parseFormData (BaseFormDataSchema)
    │
    └─ createSession (空スキーマ)
```

### データフロー図

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

formData ────────────────▶ parseFormData
       │                        │
       │                        └─ validation
       │                               │
       │                               ▼
       │                        [スキーマ取得]
       │                               │
       │                        ┌──────┼──────┬──────┬──────┐
       │                        ▼      ▼      ▼      ▼      ▼
       │                    GitHub   URL   Paste  Upload Scratch
       │                        │      │      │      │      │
       │                        └──────┴──────┴──────┴──────┘
       │                               │
       │                               ▼
       │                        parseSchemaContent
       │                               │
       │                               └─ Schema
       │                                      │
       │                                      ▼
       │                        createSession
       │                               │
       │                               ├─ design_sessions INSERT
       │                               │
       │                               └─ building_schemas INSERT
       │                                      │
       └───────────────────────────────────────▶ redirectTo
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sessionFormValidation.ts | `frontend/apps/app/features/sessions/components/shared/validation/sessionFormValidation.ts` | ソース | フォームバリデーション |
| sessionCreationHelpers.ts | `frontend/apps/app/features/sessions/components/shared/services/sessionCreationHelpers.ts` | ソース | 共通セッション作成処理 |
| createGitHubSession.ts | `frontend/apps/app/features/sessions/components/GitHubSessionForm/actions/createGitHubSession.ts` | ソース | GitHub連携セッション |
| createUrlSession.ts | `frontend/apps/app/features/sessions/components/UrlSessionForm/actions/createUrlSession.ts` | ソース | URLセッション |
| createPasteSession.ts | `frontend/apps/app/features/sessions/components/PasteSessionForm/actions/createPasteSession.ts` | ソース | ペーストセッション |
| createScratchSession.ts | `frontend/apps/app/features/sessions/components/ScratchSessionForm/actions/createScratchSession.ts` | ソース | スクラッチセッション |
| urlValidation.ts | `frontend/apps/app/features/sessions/components/UrlSessionForm/utils/urlValidation.ts` | ソース | URL検証 |
