# 機能設計書 13-チーム管理

## 概要

本ドキュメントは、Chatwootのチーム管理機能について、その処理内容、データベース操作、およびコード構成を詳細に記述した設計書である。

### 本機能の処理概要

チーム管理機能は、Chatwootにおいてエージェントをグループ化し、チームとして管理する機能である。チームを作成することで、会話の割り当て、レポート分析、アクセス制御などをチーム単位で行うことが可能となる。

**業務上の目的・背景**：カスタマーサポート組織では、技術サポート、営業サポート、一般問い合わせなど、業務内容に応じてエージェントをグループ化することが一般的である。チーム機能により、会話をチーム単位で割り当て、チームごとのパフォーマンス分析、チームメンバー間での協働が実現できる。

**機能の利用シーン**：
- 新しいサポートチームの作成（例：テクニカルサポートチーム）
- チームへのエージェント追加・削除
- 会話のチームへの割り当て
- チーム単位でのレポート分析
- チーム別の会話フィルタリング

**主要な処理内容**：
1. Teamモデルでのチーム基本情報管理（名前、説明、自動割り当て設定）
2. TeamMemberモデルでのチームメンバーシップ管理
3. チームへのメンバー追加・削除処理（add_members, remove_members）
4. チーム関連の会話・メッセージ取得
5. アカウントキャッシュの更新（AccountCacheRevalidator）

**関連システム・外部連携**：
- レポーティングシステム（チーム別レポート）
- 会話管理システム（チーム割り当て）

**権限による制御**：
- チームの作成・編集・削除はAdministratorロールのみ
- チームの閲覧は全ユーザー可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 55 | チーム一覧画面 | 主画面 | チームの一覧表示 |
| 56 | チーム新規作成画面 | 主画面 | 新しいチームの作成 |
| 57 | チームエージェント追加画面 | 主画面 | チームへのエージェント追加 |
| 58 | チーム設定完了画面 | 参照画面 | チーム設定の完了確認 |
| 59 | チーム編集画面 | 主画面 | 既存チームの編集 |
| 60 | チームメンバー編集画面 | 主画面 | チームメンバーの編集 |
| 13 | チーム別会話一覧 | 参照画面 | 特定チームの会話一覧表示 |

## 機能種別

CRUD操作 / メンバー管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | String | Yes | チーム名 | presence, アカウント内でユニーク |
| description | Text | No | チームの説明 | - |
| allow_auto_assign | Boolean | No | 自動割り当て許可（デフォルト: true） | - |
| user_ids | Array | Yes（メンバー操作時） | メンバーに追加するユーザーID配列 | アカウント内のユーザーIDのみ |

### 入力データソース

- 画面入力（チーム管理画面からの操作）
- API経由（REST API）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | Integer | チームID |
| name | String | チーム名 |
| description | Text | チームの説明 |
| allow_auto_assign | Boolean | 自動割り当て許可フラグ |
| account_id | Integer | 所属アカウントID |
| members | Array | チームメンバー（User）の配列 |

### 出力先

- APIレスポンス（JSON形式）
- WebSocket経由のリアルタイム通知

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ TeamsController または TeamMembersController経由でリクエスト受信

2. 認可チェック
   └─ TeamPolicyで操作者の権限を確認

3. チーム操作実行
   ├─ Create: チームレコード作成
   ├─ Update: チーム情報更新
   ├─ Delete: チームレコード削除（関連TeamMemberも削除）
   └─ Members: メンバー追加・削除

4. キャッシュ更新
   └─ AccountCacheRevalidatorでアカウントキャッシュ更新

5. レスポンス返却
   └─ 操作結果をJSON形式で返却
```

### フローチャート

```mermaid
flowchart TD
    A[チーム操作リクエスト] --> B{認可チェック}
    B -->|Administrator| C{操作種別}
    B -->|Agent閲覧のみ| D{閲覧操作?}
    D -->|Yes| E[チーム情報取得]
    D -->|No| F[403エラー]
    C -->|Create| G[チーム作成]
    C -->|Update| H[チーム更新]
    C -->|Delete| I[チーム削除]
    C -->|Members| J{メンバー操作}
    G --> K[キャッシュ更新]
    H --> K
    I --> L[関連データ削除]
    L --> K
    J -->|Add| M[メンバー追加]
    J -->|Remove| N[メンバー削除]
    M --> K
    N --> K
    E --> O[レスポンス返却]
    K --> O
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | チーム名ユニーク | 同一アカウント内でチーム名は一意でなければならない | チーム作成・更新時 |
| BR-002 | チーム名小文字化 | チーム名は保存前に小文字に変換される | チーム作成・更新時 |
| BR-003 | メンバー検証 | 追加するユーザーIDはアカウント内に存在する必要がある | メンバー追加時 |
| BR-004 | デフォルト自動割り当て | allow_auto_assignのデフォルト値はtrue | チーム作成時 |
| BR-005 | 削除時のnullify | チーム削除時、関連する会話のteam_idはnullになる | チーム削除時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| チーム一覧取得 | teams | SELECT | アカウント内のチーム一覧取得 |
| チーム作成 | teams | INSERT | 新規チームレコード作成 |
| チーム更新 | teams | UPDATE | チーム情報更新 |
| チーム削除 | teams | DELETE | チームレコード削除 |
| メンバー追加 | team_members | INSERT | チームメンバーレコード作成 |
| メンバー削除 | team_members | DELETE | チームメンバーレコード削除 |
| 会話更新 | conversations | UPDATE | チーム削除時のteam_id nullify |

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

#### teams

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | リクエストパラメータ（小文字化） | 必須、ユニーク |
| INSERT | description | リクエストパラメータ | 任意 |
| INSERT | allow_auto_assign | リクエストパラメータ or true | デフォルトtrue |
| INSERT | account_id | Current.account.id | 自動設定 |
| SELECT | * | account_id条件 | - |

#### team_members

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | team_id | 対象チームID | 必須 |
| INSERT | user_id | リクエストパラメータ | アカウント内ユーザー |
| DELETE | - | team_id, user_id条件 | - |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 403 | Forbidden | Administrator権限がない（作成・更新・削除時） | 権限確認メッセージ表示 |
| 401 | Unauthorized | 無効なユーザーIDを含むメンバー追加 | エラーメッセージ表示 |
| 404 | NotFound | 指定チームが存在しない | 対象確認メッセージ表示 |
| 422 | UnprocessableEntity | バリデーションエラー（チーム名重複等） | エラー内容を表示 |

### リトライ仕様

特になし（同期処理のため）

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

- メンバー追加・削除はActiveRecord::Base.transactionでラップされている
- チーム削除時、関連するteam_membersはdependent: :destroy_asyncで非同期削除
- 関連するconversationsのteam_idはdependent: :nullifyで自動的にnull設定

## パフォーマンス要件

- チーム一覧取得: 100ms以内のレスポンス
- インデックス（name, account_id）による高速検索

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

- TeamPolicyによる認可制御
- メンバー追加時のアカウント内ユーザー検証
- 監査ログ（Enterprise機能）による操作追跡

## 備考

- Team.include_mod_with('Audit::Team') により監査ログ機能が拡張される
- AccountCacheRevalidatorでアカウントキャッシュが更新され、UIの即座反映を実現

---

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

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

### 推奨読解順序

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

TeamモデルとTeamMemberモデルのスキーマとアソシエーションを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | team.rb | `app/models/team.rb` | スキーマ、アソシエーション、バリデーション |
| 1-2 | team_member.rb | `app/models/team_member.rb` | チームメンバー中間テーブル |

**読解のコツ**:
- `belongs_to :account` と `has_many :team_members` のアソシエーション構造を確認
- `before_validation` で名前の小文字化処理を確認
- `add_members` / `remove_members` メソッドでメンバー操作を確認

**主要処理フロー**:
1. **18-68行目**: Teamクラス全体の定義
2. **22-24行目**: アソシエーション定義（team_members, members, conversations）
3. **26-28行目**: nameのバリデーション（presence, uniqueness）
4. **30-32行目**: before_validationで名前小文字化
5. **37-44行目**: add_members メソッド
6. **49-52行目**: remove_members メソッド

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

コントローラでのチーム操作の入り口を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | teams_controller.rb | `app/controllers/api/v1/accounts/teams_controller.rb` | チームCRUD API |
| 2-2 | team_members_controller.rb | `app/controllers/api/v1/accounts/team_members_controller.rb` | メンバー管理API |

**主要処理フロー（teams_controller.rb）**:
1. **5-7行目**: index - チーム一覧取得
2. **11-14行目**: create - チーム作成
3. **16-18行目**: update - チーム更新
4. **20-23行目**: destroy - チーム削除
5. **31-33行目**: team_params - 許可パラメータ

**主要処理フロー（team_members_controller.rb）**:
1. **6-8行目**: index - メンバー一覧取得
2. **10-14行目**: create - メンバー追加（トランザクション内）
3. **16-23行目**: update - メンバー一括更新
4. **25-30行目**: destroy - メンバー削除
5. **50-53行目**: validate_member_id_params - アカウント内ユーザー検証

#### Step 3: 認可ポリシーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | team_policy.rb | `app/policies/team_policy.rb` | チーム操作の認可ルール |

**主要処理フロー**:
1. **2-4行目**: index? - 全ユーザー閲覧可能
2. **6-8行目**: update? - Administratorのみ
3. **14-16行目**: create? - Administratorのみ
4. **18-20行目**: destroy? - Administratorのみ

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

```
Api::V1::Accounts::TeamsController
    │
    ├─ TeamPolicy (認可チェック)
    │      ├─ index?, show? → true（全ユーザー）
    │      └─ create?, update?, destroy? → administrator?
    │
    └─ Team (モデル操作)
           ├─ validates :name
           ├─ before_validation (小文字化)
           ├─ has_many :team_members
           └─ AccountCacheRevalidator

Api::V1::Accounts::TeamMembersController
    │
    ├─ validate_member_id_params (アカウント内検証)
    │
    └─ Team
           ├─ add_members(user_ids)
           │      └─ team_members.create
           └─ remove_members(user_ids)
                  └─ team_members.destroy_all
```

### データフロー図

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

APIリクエスト ────────▶ TeamsController ────────────▶ JSONレスポンス
(name, description)           │
                              ▼
                         TeamPolicy
                        (認可チェック)
                              │
                              ▼
                           Team
                     (バリデーション)
                              │
                              ├───────▶ teams テーブル
                              │
                              └───────▶ AccountCacheRevalidator
                                              │
                                              ▼
                                        キャッシュ更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| team.rb | `app/models/team.rb` | モデル | チームデータモデル |
| team_member.rb | `app/models/team_member.rb` | モデル | チームメンバー中間テーブル |
| teams_controller.rb | `app/controllers/api/v1/accounts/teams_controller.rb` | コントローラ | チームCRUD API |
| team_members_controller.rb | `app/controllers/api/v1/accounts/team_members_controller.rb` | コントローラ | メンバー管理API |
| team_policy.rb | `app/policies/team_policy.rb` | ポリシー | チーム操作の認可 |
| account_cache_revalidator.rb | `app/models/concerns/account_cache_revalidator.rb` | Concern | キャッシュ更新 |
