# 画面設計書 6-組織新規作成画面

## 概要

本ドキュメントは、Liam DBアプリケーションの組織新規作成画面について定義する。

### 本画面の処理概要

組織新規作成画面は、ユーザーが新しい組織を作成するためのフォーム画面である。組織名を入力して作成ボタンをクリックすると、組織が作成され、作成者が自動的にその組織のメンバーとして追加される。

**業務上の目的・背景**：Liam DBでは組織単位でプロジェクトやメンバーを管理する。新規ユーザーがアプリケーションを利用開始するためには、最初に組織を作成する必要がある。また、既存ユーザーも新規の組織を作成して、異なるプロジェクトグループを管理できる。

**画面へのアクセス方法**：
- 組織一覧画面の「Create New Organization」ボタンをクリック
- 直接`/organizations/new`にアクセス

**主要な操作・処理内容**：
1. 組織名を入力フィールドに入力
2. 「Create Organization」ボタンをクリック
3. 組織作成処理を実行（organizations + organization_members）
4. 作成成功時、組織IDをCookieに設定しプロジェクト新規作成画面へ遷移

**画面遷移**：
- 組織作成成功時 → プロジェクト新規作成画面（`/projects/new`）

**権限による表示制御**：認証必須。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | 組織管理 | 主機能 | 新しい組織を作成するフォーム入力と作成処理 |
| 34 | 基本コンポーネント | 補助機能 | Input、Buttonコンポーネントによるフォーム表示 |
| 27 | プロジェクト管理 | 遷移先機能 | 組織作成成功後のプロジェクト新規作成画面への遷移 |

## 画面種別

登録フォーム

## URL/ルーティング

- URL: `/organizations/new`
- ファイル: `frontend/apps/app/app/organizations/new/page.tsx`
- レンダリング: クライアントコンポーネント（`'use client'`）

## 入出力項目

### 入力項目

| 項目名 | 項目ID | データ型 | 必須 | 最大長 | 備考 |
|--------|--------|----------|------|--------|------|
| 組織名 | name | string | はい | - | placeholder: "Organization name" |

## 表示項目

| 項目名 | 説明 | 備考 |
|--------|------|------|
| ページタイトル | "Create a New Organization" | h1要素 |
| 入力ラベル | "Organization Name" | label要素 |
| ヘルパーテキスト | "What's the name of your company or team?" | 入力フィールド下部 |
| 作成ボタン | "Create Organization" | submit ボタン |
| エラーメッセージ | 動的エラー表示 | エラー発生時のみ |

## イベント仕様

### 1-組織名入力

組織名テキストフィールドへの入力処理。

**トリガー**：テキストフィールドへの入力

**処理フロー**：
1. 入力値をstate（name）に保存
2. 入力値の有無でボタンの有効/無効状態を制御

### 2-組織作成

フォーム送信による組織作成処理。

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

**処理フロー**：
1. 組織名が空の場合、エラーメッセージ「Organization name is required」を表示
2. `createOrganization`サーバーアクションを呼び出し
3. organizations テーブルに新規組織を INSERT
4. organization_members テーブルに作成者をメンバーとして INSERT
5. 成功時：`setOrganizationIdCookie`で組織IDをCookieに設定
6. 成功時：`/projects/new`へリダイレクト
7. 失敗時：エラーメッセージを表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 組織作成 | organizations | INSERT | 新規組織レコードを作成 |
| 組織作成 | organization_members | INSERT | 作成者をメンバーとして追加 |

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

#### organizations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | 入力された組織名 | - |
| INSERT | id | 自動生成（UUID） | - |

#### organization_members

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | user_id | 現在の認証ユーザーID | - |
| INSERT | organization_id | 作成された組織ID | - |

## メッセージ仕様

| メッセージID | メッセージ内容 | 表示タイミング | 種別 |
|--------------|---------------|----------------|------|
| ERR-001 | "Organization name is required" | 空の組織名で送信時 | エラー |
| ERR-002 | "Failed to create organization. Please try again." | 作成処理失敗時 | エラー |
| ERR-003 | "Failed to get user information" | ユーザー情報取得失敗時 | エラー |
| ERR-004 | "Failed to add user to organization" | メンバー追加失敗時 | エラー |

## 例外処理

| 例外ケース | 処理内容 |
|------------|----------|
| 組織名未入力 | フロントエンドでエラーメッセージ表示、送信をブロック |
| 組織作成失敗 | エラーメッセージ表示、サーバーログ出力 |
| ユーザー情報取得失敗 | エラーメッセージ表示、サーバーログ出力 |
| メンバー追加失敗 | エラーメッセージ表示、サーバーログ出力 |

## 備考

- クライアントコンポーネント（`'use client'`）として実装
- useTransitionを使用してローディング状態を管理
- ボタンは組織名が入力されるまで無効化（disabled）
- 組織作成とメンバー追加はトランザクションで管理されていないため、部分的な失敗の可能性がある（TODO）

---

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

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

### 推奨読解順序

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

組織作成処理の戻り値を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | createOrganizations.ts | `frontend/apps/app/components/OrganizationNewPage/actions/createOrganizations.ts` | 組織作成の成功/失敗の型定義 |

**読解のコツ**: `CreateOrganizationResult`型（success/error）を確認する。

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

組織新規作成ページのエントリーポイントを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | page.tsx | `frontend/apps/app/app/organizations/new/page.tsx` | ページコンポーネントの定義 |
| 2-2 | OrganizationNewPage.tsx | `frontend/apps/app/components/OrganizationNewPage/OrganizationNewPage.tsx` | フォームコンポーネント |

**主要処理フロー（OrganizationNewPage.tsx）**:
- **11-16行目**: state定義（name, loading, error）
- **19行目**: `isFormValid`算出（組織名の有無）
- **21-42行目**: `handleSubmit`でフォーム送信処理
- **31-36行目**: 成功時のCookie設定とリダイレクト

#### Step 3: サーバーアクションを理解する

組織作成のサーバーアクション処理。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | createOrganizations.ts | `frontend/apps/app/components/OrganizationNewPage/actions/createOrganizations.ts` | 組織作成処理 |

**主要処理フロー**:
- **20-28行目**: organizationsテーブルへINSERT
- **32-35行目**: ユーザー情報取得
- **39-44行目**: organization_membersテーブルへINSERT
- **51-54行目**: 成功時のレスポンス

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

```
app/organizations/new/page.tsx
    │
    └─ components/OrganizationNewPage/OrganizationNewPage.tsx
           │
           ├─ @liam-hq/ui (Button, Input)
           │
           ├─ actions/createOrganizations.ts [Server Action]
           │      ├─ supabase.from('organizations').insert()
           │      ├─ supabase.auth.getUser()
           │      └─ supabase.from('organization_members').insert()
           │
           └─ services/setOrganizationIdCookie.ts
                  └─ Cookie設定
```

### データフロー図

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

組織名入力          ───▶ state更新                   ───▶ ボタン有効化
     │
     │
フォーム送信        ───▶ createOrganization          ───▶ 組織作成結果
                         │
                         ├─ organizations INSERT
                         └─ organization_members INSERT
                                │
                         ┌──────┴──────┐
                         │             │
                      成功          失敗
                         │             │
                         ▼             ▼
              setOrganizationIdCookie  エラー表示
                         │
                         ▼
                   /projects/new へ遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `frontend/apps/app/app/organizations/new/page.tsx` | ソース | 組織新規作成ページのエントリーポイント |
| OrganizationNewPage.tsx | `frontend/apps/app/components/OrganizationNewPage/OrganizationNewPage.tsx` | ソース | 組織作成フォームコンポーネント |
| createOrganizations.ts | `frontend/apps/app/components/OrganizationNewPage/actions/createOrganizations.ts` | ソース | 組織作成サーバーアクション |
| OrganizationNewPage.module.css | `frontend/apps/app/components/OrganizationNewPage/OrganizationNewPage.module.css` | スタイル | 組織新規作成ページのスタイル |
| setOrganizationIdCookie.ts | `frontend/apps/app/features/organizations/services/setOrganizationIdCookie.ts` | ソース | 組織IDのCookie設定 |
| server.ts | `frontend/apps/app/libs/db/server.ts` | ソース | Supabaseクライアント生成 |
| urlgen.ts | `frontend/apps/app/libs/routes/urlgen.ts` | ソース | URL生成ユーティリティ |
