# 画面設計書 55-チーム一覧画面

## 概要

本ドキュメントは、Chatwootのチーム一覧画面の設計書です。エージェントをグループ化するチームの作成・編集・削除を管理する画面です。

### 本画面の処理概要

チームの一覧表示と管理を行う画面です。チームは複数のエージェントをグループ化し、会話の担当者割り当てや権限管理を効率化するために使用されます。

**業務上の目的・背景**：大規模なカスタマーサポート組織では、部門別（営業、技術サポート、請求など）にエージェントをチームに分けることで、適切な担当者への会話ルーティングを実現します。チーム単位での会話管理により、ワークフローの効率化と責任範囲の明確化が可能になります。

**画面へのアクセス方法**：設定メニュー > チーム

**主要な操作・処理内容**：
1. チーム一覧の表示（名前、説明）
2. 新規チーム作成（ウィザード画面へ遷移）
3. チーム編集（ウィザード画面へ遷移）
4. チーム削除（確認モーダル）

**画面遷移**：
- 遷移元: 設定ホーム画面
- 遷移先: チーム新規作成画面、チーム編集画面

**権限による表示制御**：管理者（administrator）のみがこの画面にアクセス可能。新規作成・編集・削除ボタンは管理者のみ表示

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 13 | チーム管理 | 主機能 | チームの一覧表示 |

## 画面種別

一覧

## URL/ルーティング

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

## 入出力項目

なし（一覧表示のみ、操作は遷移または削除モーダル）

## 表示項目

| 項目名 | 型 | 説明 |
|--------|------|------|
| teamsList | Array<Team> | チーム一覧 |
| team.id | Number | チームID |
| team.name | String | チーム名 |
| team.description | String | チーム説明 |

## イベント仕様

### 1-チーム追加ボタン押下

**トリガー**: 「新規チーム」ボタン押下

**処理フロー**:
1. `router-link`により`settings_teams_new`へ遷移

### 2-チーム編集ボタン押下

**トリガー**: 各チーム行の設定ボタン押下

**処理フロー**:
1. `router-link`により`settings_teams_edit`へ遷移
2. パラメータとして`teamId`を渡す

### 3-チーム削除ボタン押下（openDelete）

**トリガー**: 各チーム行の削除ボタン押下

**処理フロー**:
1. `showDeletePopup`をtrueに設定
2. `selectedTeam`に対象チームオブジェクトを格納
3. 削除確認モーダルを表示

### 4-削除確認（confirmDeletion）

**トリガー**: 削除確認モーダルで「はい」押下

**処理フロー**:
1. `deleteTeam(selectedTeam)`を呼び出し
2. モーダルを閉じる

### 5-チーム削除（deleteTeam）

**トリガー**: confirmDeletionから呼び出し

**処理フロー**:
1. `loading[team.id]`をtrueに設定
2. `store.dispatch('teams/delete', id)`を実行
3. 成功時: 成功メッセージをアラート表示
4. 失敗時: エラーメッセージをアラート表示
5. `loading[team.id]`をfalseに設定

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| チーム削除 | teams | DELETE | チームを削除 |
| チーム削除 | team_members | DELETE | チームメンバーも連動削除 |
| 画面表示 | teams | SELECT | チーム一覧を取得 |

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

#### teams

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | id | 対象チームのID | 物理削除 |

## メッセージ仕様

| 種別 | キー | 表示条件 | メッセージ内容 |
|------|------|----------|--------------|
| 成功 | TEAMS_SETTINGS.DELETE.API.SUCCESS_MESSAGE | チーム削除成功時 | チーム削除成功 |
| エラー | TEAMS_SETTINGS.DELETE.API.ERROR_MESSAGE | チーム削除失敗時 | チーム削除エラー |
| 情報 | TEAMS_SETTINGS.LOADING | 読み込み中 | 読み込み中メッセージ |
| 情報 | TEAMS_SETTINGS.LIST.404 | チームなし | チームが見つかりません |
| 確認 | TEAMS_SETTINGS.DELETE.CONFIRM.TITLE | 削除確認時 | 削除確認タイトル（チーム名含む） |
| 確認 | TEAMS_SETTINGS.DELETE.CONFIRM.MESSAGE | 削除確認時 | 削除確認メッセージ |
| 確認 | TEAMS_SETTINGS.DELETE.CONFIRM.PLACE_HOLDER | 削除確認時 | チーム名入力プレースホルダー |

## 例外処理

| 例外状況 | 対応処理 |
|----------|----------|
| チーム一覧が空 | 「チームが見つかりません」メッセージを表示 |
| API通信エラー | `useAlert()`でエラーメッセージをトースト表示 |
| 権限不足 | ルートガードにより画面アクセス自体をブロック |
| 読み込み中 | ローディングスピナーを表示 |

## 備考

- 削除確認モーダルでは、チーム名を入力して確認する必要がある（woot-confirm-delete-modal使用）
- 新規作成・編集・削除ボタンは管理者のみ表示（isAdmin判定）
- チーム一覧はVuexストアから取得（`teams/getTeams`ゲッター）

---

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

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

### 推奨読解順序

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

チームのデータ構造とストア管理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.js | `app/javascript/dashboard/store/modules/teams/index.js` | Vuexストアの構造 |
| 1-2 | actions.js | `app/javascript/dashboard/store/modules/teams/actions.js` | CRUD操作 |
| 1-3 | teams.js | `app/javascript/dashboard/api/teams.js` | APIクライアント定義 |

**読解のコツ**: `CacheEnabledApiClient`を継承しており、キャッシュ機能付きのAPI通信を行う。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Index.vue | `app/javascript/dashboard/routes/dashboard/settings/teams/Index.vue` | 一覧表示、削除処理 |

**主要処理フロー**:
1. **L15**: `teamsList`でチーム一覧を取得（`teams/getTeams`ゲッター）
2. **L17**: `isAdmin`で管理者権限を判定
3. **L21-30**: `deleteTeam()`で削除処理
4. **L46-49**: `confirmDeletion()`で削除確認

#### Step 3: ルーティング設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | teams.routes.js | `app/javascript/dashboard/routes/dashboard/settings/teams/teams.routes.js` | ルート定義、ウィザードフロー |

**主要処理フロー**:
- **L28-35**: `settings_teams_list`ルートの定義
- **L48-80**: 新規作成ウィザードのルート定義
- **L82-114**: 編集ウィザードのルート定義

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

```
Index.vue (コンポーネント)
    │
    ├─ computed: teamsList
    │      └─ getters['teams/getTeams']
    │
    ├─ router-link (新規作成)
    │      └─ settings_teams_new → CreateTeam.vue
    │
    ├─ router-link (編集)
    │      └─ settings_teams_edit → EditTeam.vue
    │
    └─ openDelete(team)
           └─ woot-confirm-delete-modal
                  └─ confirmDeletion()
                         └─ deleteTeam(team)
                                └─ store.dispatch('teams/delete', id)
                                       └─ TeamsAPI.delete()
```

### データフロー図

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

                    ┌──▶ getters['teams/getTeams']
computed ───────────┤         │
                    │         ▼
                    │    teamsList ─────────────────────▶ テーブル表示
                    │
                    └──▶ getters['teams/getUIFlags']
                                │
                                ▼
                          uiFlags.isFetching ──────────▶ ローディング表示

[削除操作]
openDelete(team) ──▶ selectedTeam
        │
        ▼
woot-confirm-delete-modal
        │
        ▼
confirmDeletion() ──▶ deleteTeam(team)
        │
        ▼
store.dispatch('teams/delete', id)
        │
        ▼
TeamsAPI.delete() ──▶ DELETE_TEAM (mutation)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Index.vue | `app/javascript/dashboard/routes/dashboard/settings/teams/Index.vue` | ソース | メインコンポーネント |
| teams.routes.js | `app/javascript/dashboard/routes/dashboard/settings/teams/teams.routes.js` | ソース | ルーティング定義 |
| index.js | `app/javascript/dashboard/store/modules/teams/index.js` | ソース | Vuexストア |
| actions.js | `app/javascript/dashboard/store/modules/teams/actions.js` | ソース | Vuexアクション |
| teams.js | `app/javascript/dashboard/api/teams.js` | ソース | APIクライアント |
| BaseSettingsHeader.vue | `app/javascript/dashboard/routes/dashboard/settings/components/BaseSettingsHeader.vue` | ソース | ヘッダーコンポーネント |
| useAdmin.js | `app/javascript/dashboard/composables/useAdmin.js` | ソース | 管理者権限判定コンポーザブル |
