# 画面設計書 56-チーム新規作成画面

## 概要

本ドキュメントは、Chatwootのチーム新規作成画面の設計書です。チーム作成ウィザードの最初のステップとして、チームの基本情報を入力する画面です。

### 本画面の処理概要

新規チームの基本情報（名前、説明、自動割り当て設定）を入力し、チームを作成する画面です。作成後はエージェント追加画面へ遷移します。

**業務上の目的・背景**：新しい部門やプロジェクトチームを立ち上げる際に、チームの基本情報を設定します。自動割り当て設定により、そのチームへの会話自動ルーティングを有効化できます。

**画面へのアクセス方法**：設定メニュー > チーム > 「新規チーム」ボタン押下

**主要な操作・処理内容**：
1. チーム名の入力（必須）
2. チーム説明の入力（任意）
3. 自動割り当て設定のオン/オフ
4. 「次へ」ボタン押下でチーム作成、エージェント追加画面へ遷移

**画面遷移**：
- 遷移元: チーム一覧画面
- 遷移先: チームエージェント追加画面（settings_teams_add_agents）

**権限による表示制御**：管理者（administrator）のみがこの画面にアクセス可能

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 13 | チーム管理 | 主機能 | 新しいチームの作成 |

## 画面種別

登録（ウィザード形式の第1ステップ）

## URL/ルーティング

- パス: `/app/accounts/:accountId/settings/teams/new`
- ルート名: `settings_teams_new`
- 権限: administrator

## 入出力項目

| 項目名 | 型 | 必須 | 説明 | バリデーション |
|--------|------|------|------|--------------|
| title (name) | String | Yes | チーム名 | 必須 |
| description | String | No | チーム説明 | なし |
| allowAutoAssign | Boolean | No | 自動割り当て有効化 | デフォルトtrue |

## 表示項目

なし（入力フォームのみ）

## イベント仕様

### 1-フォーム送信（createTeam）

**トリガー**: 「次へ」ボタン押下

**処理フロー**:
1. Vuelidateによるバリデーション実行（`v$.$touch()`）
2. バリデーションエラーがあれば処理中断
3. `store.dispatch('teams/create', {...})`を実行
4. 成功時: 作成されたチームのIDを取得し、`settings_teams_add_agents`へ遷移
5. 失敗時: エラーメッセージをアラート表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| チーム作成 | teams | INSERT | 新規チームを作成 |

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

#### teams

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | フォーム入力値（title） | 必須 |
| INSERT | description | フォーム入力値 | 任意 |
| INSERT | allow_auto_assign | チェックボックスの値 | デフォルトtrue |
| INSERT | account_id | 現在のアカウントID | 自動設定 |

## メッセージ仕様

| 種別 | キー | 表示条件 | メッセージ内容 |
|------|------|----------|--------------|
| エラー | TEAMS_SETTINGS.TEAM_FORM.ERROR_MESSAGE | チーム作成失敗時 | チーム作成エラー |
| エラー | バリデーションエラー | 入力値が無効な場合 | フォームにエラーメッセージ表示 |

## 例外処理

| 例外状況 | 対応処理 |
|----------|----------|
| チーム名未入力 | バリデーションエラーメッセージを表示、送信ボタン無効化 |
| API通信エラー | `useAlert()`でエラーメッセージをトースト表示 |
| 権限不足 | ルートガードにより画面アクセス自体をブロック |

## 備考

- TeamFormコンポーネントを共有使用（新規作成・編集共通）
- 自動割り当て設定はデフォルトでオン
- 作成成功時に返されるteam.idを使用して次画面へ遷移

---

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

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

### 推奨読解順序

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

チームのデータ構造とAPIリクエスト形式を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | teams.js | `app/javascript/dashboard/api/teams.js` | APIクライアント定義 |
| 1-2 | actions.js | `app/javascript/dashboard/store/modules/teams/actions.js` | createアクション |

**読解のコツ**: `TeamsAPI.create()`はPOSTリクエストを送信し、作成されたチームオブジェクトを返す。

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

Vueコンポーネントの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CreateTeam.vue | `app/javascript/dashboard/routes/dashboard/settings/teams/Create/CreateTeam.vue` | メインコンポーネント |
| 2-2 | TeamForm.vue | `app/javascript/dashboard/routes/dashboard/settings/teams/TeamForm.vue` | 共通フォームコンポーネント |

**主要処理フロー**:
1. **CreateTeam L18-34**: `createTeam()`メソッドでチーム作成処理
2. **CreateTeam L20-22**: ストアディスパッチでチーム作成
3. **CreateTeam L24-30**: 成功時にエージェント追加画面へ遷移
4. **TeamForm L51-61**: `handleSubmit()`でバリデーション実行後、親コンポーネントのonSubmit呼び出し

#### Step 3: バリデーション設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | validations.js | `app/javascript/dashboard/routes/dashboard/settings/teams/helpers/validations.js` | バリデーションルール |

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

```
CreateTeam.vue (コンポーネント)
    │
    └─ TeamForm.vue (子コンポーネント)
           │
           ├─ setup()
           │      └─ useVuelidate(rules, state)
           │
           └─ handleSubmit()
                  │
                  ├─ v$.$touch()
                  │
                  └─ onSubmit({ description, name, allow_auto_assign })
                         │
                         ▼
                  createTeam(data) [CreateTeam.vue]
                         │
                         ├─ store.dispatch('teams/create', data)
                         │      └─ TeamsAPI.create()
                         │             └─ POST /api/v1/accounts/:id/teams
                         │
                         └─ router.replace({ name: 'settings_teams_add_agents' })
```

### データフロー図

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

フォーム入力
    │
    ├─ title ────────────▶ state.title ─────────────────▶ name
    ├─ description ──────▶ state.description ───────────▶ description
    └─ allowAutoAssign ──▶ state.allowAutoAssign ───────▶ allow_auto_assign
                                │
                                ▼
                          handleSubmit()
                                │
                                ▼
                          v$.$touch()
                          (バリデーション)
                                │
                                ▼
                          onSubmit(data)
                                │
                                ▼
                          store.dispatch('teams/create')
                                │
                                ▼
                          TeamsAPI.create()
                                │
                                ▼
                          team (作成されたチーム)
                                │
                                ▼
                          router.replace()
                          (エージェント追加画面へ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CreateTeam.vue | `app/javascript/dashboard/routes/dashboard/settings/teams/Create/CreateTeam.vue` | ソース | メインコンポーネント |
| TeamForm.vue | `app/javascript/dashboard/routes/dashboard/settings/teams/TeamForm.vue` | ソース | フォームコンポーネント |
| validations.js | `app/javascript/dashboard/routes/dashboard/settings/teams/helpers/validations.js` | ソース | バリデーション定義 |
| teams.routes.js | `app/javascript/dashboard/routes/dashboard/settings/teams/teams.routes.js` | ソース | ルーティング定義 |
| actions.js | `app/javascript/dashboard/store/modules/teams/actions.js` | ソース | Vuexアクション |
| teams.js | `app/javascript/dashboard/api/teams.js` | ソース | APIクライアント |
| SettingsSubPageHeader.vue | `app/javascript/dashboard/routes/dashboard/settings/inbox/SettingsSubPageHeader.vue` | ソース | ヘッダーコンポーネント |
| FormInput.vue | `app/javascript/v3/components/Form/Input.vue` | ソース | 入力フォームコンポーネント |
