# 画面設計書 11-プロジェクトセッション一覧画面

## 概要

本ドキュメントは、Liam DBアプリケーションにおけるプロジェクトセッション一覧画面の設計仕様を定義する。

### 本画面の処理概要

この画面では、特定のプロジェクトに紐づくデザインセッションの一覧表示と、新規セッションの作成が可能である。

**業務上の目的・背景**：
プロジェクト単位でデータベース設計セッションを管理する必要がある。この画面は、プロジェクトに関連するすべての設計セッションを一元的に閲覧し、新しいセッションを開始するための入口として機能する。開発者やDBアーキテクトがプロジェクトのコンテキストを維持しながら設計作業を継続できるようにする。

**画面へのアクセス方法**：
ブランチ詳細画面から「Sessions」タブをクリック、またはプロジェクト詳細画面からセッション一覧へのリンクをクリックしてアクセスする。URLパターンは `/projects/:projectId/ref/:branchOrCommit/sessions`。

**主要な操作・処理内容**：
1. プロジェクトに紐づくデザインセッション履歴の一覧表示
2. 新規デザインセッションの作成（複数のセッションモードから選択可能）
3. 既存セッションの選択と詳細画面への遷移

**画面遷移**：
- 遷移元: ブランチ詳細画面（`/projects/:projectId/ref/:branchOrCommit`）
- 遷移先: デザインセッション詳細画面（`/design_sessions/:id`）

**権限による表示制御**：
認証済みユーザーのみアクセス可能。未認証の場合はログイン画面へリダイレクトされる。表示されるセッション一覧は現在のユーザーが作成したものに限定される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 29 | デザインセッション | 主機能 | プロジェクトに紐づくデザインセッションの一覧表示と新規作成フォーム |
| 27 | プロジェクト管理 | 補助機能 | プロジェクト情報の取得と表示 |
| 39 | Supabaseクライアント | API連携 | セッション履歴データの取得 |

## 画面種別

一覧 / 登録

## URL/ルーティング

```
/projects/:projectId/ref/:branchOrCommit/sessions
```

動的パラメータ:
- `projectId`: プロジェクトの一意識別子
- `branchOrCommit`: ブランチ名またはコミットハッシュ

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| projectId | string | Yes | URLパラメータ - プロジェクトID |
| branchOrCommit | string | Yes | URLパラメータ - ブランチ名またはコミットハッシュ |
| セッションモード | enum | Yes | scratch / github / upload / url / paste から選択 |
| プロジェクト選択 | string | No | セッション作成時の関連プロジェクト選択（デフォルトは現在のプロジェクト） |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| sessions | ProjectSession[] | プロジェクトに関連するセッション一覧 |
| projects | Projects | セッション作成フォーム用のプロジェクト一覧 |

## 表示項目

### セッション履歴一覧

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | セッションID |
| name | string | セッション名 |
| created_at | string | 作成日時 |
| project_id | string | 関連プロジェクトID |

### 空状態表示

セッションが存在しない場合は、以下の空状態メッセージが表示される:
- アイコン: MessagesSquare（48pxサイズ）
- タイトル: "No sessions yet"
- 説明: "Start a new design session to explore ideas and generate artifacts for this project."

## イベント仕様

### 1-セッション作成モード選択

ユーザーがセッションモードセレクター（scratch / github / upload / url / paste）をクリックすると、対応するフォームが表示される。モード切り替え時はフェードアウト→モード変更→フェードインのアニメーションが実行される。

**処理フロー**:
1. `handleModeChange`関数がトリガー
2. 150msのフェードアウト
3. モード状態の更新
4. 300msの高さアニメーション
5. フェードイン完了

### 2-セッション作成実行

セッション作成フォームを送信すると、選択したモードに応じたセッション作成処理が実行される。

**処理フロー**:
1. フォームバリデーション
2. Server Actionの呼び出し
3. design_sessionsテーブルへの新規レコード挿入
4. 成功時: デザインセッション詳細画面へ遷移

### 3-既存セッション選択

セッション履歴一覧から既存セッションをクリックすると、該当セッションの詳細画面へ遷移する。

**遷移先**: `/design_sessions/:id`

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | design_sessions | SELECT | プロジェクトに関連するセッション一覧を取得 |
| 画面表示 | projects | SELECT | セッション作成フォーム用のプロジェクト一覧を取得 |
| セッション作成 | design_sessions | INSERT | 新規デザインセッションレコードの作成 |

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

#### design_sessions（取得）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id | セッションID | - |
| SELECT | name | セッション名 | - |
| SELECT | created_at | 作成日時 | 降順でソート |
| SELECT | project_id | 関連プロジェクトID | URLパラメータのprojectIdでフィルタ |

取得条件:
- `project_id = :projectId`
- `created_by_user_id = :currentUserId`
- `ORDER BY created_at DESC`
- `LIMIT 10`

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 表示条件 |
|------------|------|-----------|---------|
| MSG-001 | 情報 | No sessions yet | セッション履歴が空の場合 |
| MSG-002 | 情報 | Start a new design session to explore ideas and generate artifacts for this project. | セッション履歴が空の場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| パラメータバリデーションエラー | notFound()を呼び出し、404ページを表示 |
| 未認証 | ログイン画面へリダイレクト |
| 組織ID取得失敗 | ログイン画面へリダイレクト |
| セッション取得エラー | 空の配列を返却（エラーログ出力） |

## 備考

- サーバーコンポーネントとして実装されている
- セッション履歴は最大10件まで表示される（limit=10）
- ユーザー自身が作成したセッションのみが表示される
- セッションモード切り替え時のアニメーションはアクセシビリティに配慮し、`prefers-reduced-motion`設定を尊重する

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | fetchProjectSessions.ts | `frontend/apps/app/components/ProjectSessionsPage/services/fetchProjectSessions.ts` | ProjectSession型の定義とデータ取得ロジック |

**読解のコツ**: `ProjectSession`型はid, name, created_at, project_idの4フィールドで構成される。Supabaseクエリの条件（project_id, created_by_user_id）に注目。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | page.tsx | `frontend/apps/app/app/projects/[projectId]/ref/[branchOrCommit]/sessions/page.tsx` | ルーティングとパラメータバリデーション |

**主要処理フロー**:
1. **行7-10**: paramsSchemaでURLパラメータのバリデーション定義
2. **行12-14**: パラメータ検証、失敗時は404
3. **行16-17**: projectIdを抽出しProjectSessionsPageコンポーネントを呼び出し

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ProjectSessionsPage.tsx | `frontend/apps/app/components/ProjectSessionsPage/ProjectSessionsPage.tsx` | メイン画面コンポーネントの構造 |

**主要処理フロー**:
- **行17**: fetchProjectSessionsでセッション履歴を取得
- **行18-21**: 組織IDの取得と認証チェック
- **行24-25**: プロジェクト一覧の取得
- **行35-38**: SessionFormContainerによるセッション作成フォーム表示
- **行40-49**: セッション履歴の条件付き表示
- **行51-62**: 空状態時のUI表示

#### Step 4: セッションフォームコンテナを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | SessionFormContainer.tsx | `frontend/apps/app/features/sessions/components/SessionFormContainer/SessionFormContainer.tsx` | セッション作成モードの切り替えロジック |

**主要処理フロー**:
- **行27-31**: 状態管理（mode, modeIds, isTransitioning）
- **行34-60**: handleModeChange関数によるモード切り替えアニメーション
- **行124-176**: 各モードに対応するフォームの条件付きレンダリング

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

```
page.tsx (エントリーポイント)
    │
    └─ ProjectSessionsPage.tsx
           │
           ├─ fetchProjectSessions.ts (セッション履歴取得)
           │      └─ Supabase Client (design_sessions SELECT)
           │
           ├─ getOrganizationId.ts (組織ID取得)
           │
           ├─ getProjects.ts (プロジェクト一覧取得)
           │
           ├─ SessionFormContainer.tsx (セッション作成フォーム)
           │      ├─ ScratchSessionForm
           │      ├─ GitHubSessionForm
           │      ├─ UploadSessionForm
           │      ├─ UrlSessionForm
           │      └─ PasteSessionForm
           │
           └─ SessionItem.tsx (セッション履歴表示)
```

### データフロー図

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

URLパラメータ ───▶ page.tsx ───────────────▶ ProjectSessionsPage
(projectId,        (バリデーション)
branchOrCommit)

認証情報 ─────────▶ getOrganizationId ─────▶ organizationId / redirect
                   (認証チェック)

組織ID ───────────▶ getProjects ────────────▶ projects[]
                   (プロジェクト取得)

プロジェクトID ───▶ fetchProjectSessions ──▶ sessions[]
ユーザーID         (セッション取得)

セッション一覧 ───▶ SessionItem ────────────▶ UI表示
プロジェクト一覧 ─▶ SessionFormContainer ──▶ UI表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `frontend/apps/app/app/projects/[projectId]/ref/[branchOrCommit]/sessions/page.tsx` | ソース | ページエントリーポイント |
| ProjectSessionsPage.tsx | `frontend/apps/app/components/ProjectSessionsPage/ProjectSessionsPage.tsx` | ソース | メイン画面コンポーネント |
| fetchProjectSessions.ts | `frontend/apps/app/components/ProjectSessionsPage/services/fetchProjectSessions.ts` | ソース | セッションデータ取得サービス |
| SessionFormContainer.tsx | `frontend/apps/app/features/sessions/components/SessionFormContainer/SessionFormContainer.tsx` | ソース | セッション作成フォームコンテナ |
| SessionItem.tsx | `frontend/apps/app/components/ProjectSessionsPage/SessionItem/SessionItem.tsx` | ソース | セッション一覧アイテム表示 |
| ProjectSessionsPage.module.css | `frontend/apps/app/components/ProjectSessionsPage/ProjectSessionsPage.module.css` | スタイル | 画面スタイル定義 |
| getOrganizationId.ts | `frontend/apps/app/features/organizations/services/getOrganizationId.ts` | ソース | 組織ID取得サービス |
| getProjects.ts | `frontend/apps/app/components/CommonLayout/AppBar/ProjectsDropdownMenu/services/getProjects.ts` | ソース | プロジェクト一覧取得サービス |
