# 機能設計書 11-ロール管理

## 概要

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

### 本機能の処理概要

ロール管理機能は、Chatwootにおいてアカウント内のユーザーに対してAgent（エージェント）またはAdministrator（管理者）のロールを割り当て、各ロールに応じた権限を制御する機能である。

**業務上の目的・背景**：カスタマーサポート業務においては、一般的なサポート担当者（エージェント）と、チーム全体を管理する管理者では必要な権限が異なる。エージェントは担当する会話のみを処理し、管理者はチーム設定、インボックス作成、レポート閲覧などの特権的操作を行う必要がある。このため、ユーザーごとにロールを設定し、操作可能な範囲を制御することでセキュリティと業務効率の両立を実現する。

**機能の利用シーン**：
- 新しいエージェントをアカウントに追加する際のロール設定
- 既存エージェントを管理者に昇格させる場合のロール変更
- エージェント一覧画面での権限確認
- APIアクセス時の権限チェック

**主要な処理内容**：
1. AccountUserモデルを通じたロール情報の管理（agent: 0, administrator: 1）
2. ユーザー作成時のデフォルトロール（agent）の自動設定
3. 各API・画面でのロールベースの認可チェック（Punditポリシー）
4. ロール変更時のイベント通知（AGENT_ADDED, AGENT_REMOVED）
5. オンラインステータス管理との連携

**関連システム・外部連携**：
- Redis（オンラインステータス追跡）
- WebSocket（リアルタイム通知）

**権限による制御**：
- Administratorロールを持つユーザーのみが他ユーザーのロールを変更可能
- 各操作（インボックス作成、チーム作成、レポート閲覧等）はAdministratorロールが必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 46 | エージェント一覧画面 | 主画面 | エージェントの一覧表示とロール管理 |
| 45 | 一般設定画面 | 参照画面 | アカウント設定での権限確認 |

## 機能種別

CRUD操作 / 認可制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| role | Integer | Yes | ロール種別（0: agent, 1: administrator） | enum値チェック |
| user_id | Integer | Yes | 対象ユーザーID | 存在確認、account_id内でのユニーク制約 |
| account_id | Integer | Yes | アカウントID | 存在確認 |

### 入力データソース

- 画面入力（エージェント一覧画面からのロール変更操作）
- API経由（Platform API、REST API）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | Integer | AccountUserレコードID |
| role | String | ロール名（"agent" or "administrator"） |
| availability | String | 可用性状態（online/offline/busy） |
| user_id | Integer | ユーザーID |
| permissions | Array | 権限配列（['administrator'] or ['agent']） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ AccountUsersController経由でロール変更リクエストを受信

2. 認可チェック
   └─ Punditポリシーで操作者がAdministratorか確認

3. AccountUserレコード更新
   └─ roleカラムを更新（0: agent, 1: administrator）

4. コールバック実行
   └─ after_save: オンラインステータス更新（availability変更時）
   └─ イベントディスパッチ（AGENT_ADDED/AGENT_REMOVED）

5. レスポンス返却
   └─ 更新後のAccountUser情報をJSON形式で返却
```

### フローチャート

```mermaid
flowchart TD
    A[ロール変更リクエスト] --> B{認可チェック}
    B -->|Administrator| C[AccountUser取得]
    B -->|Agent| D[403エラー返却]
    C --> E[roleカラム更新]
    E --> F{availability変更?}
    F -->|Yes| G[Redisステータス更新]
    F -->|No| H[イベント通知]
    G --> H
    H --> I[レスポンス返却]
    D --> J[終了]
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトロール | 新規ユーザー作成時はagentロールがデフォルト設定される | AccountUser作成時 |
| BR-002 | ロール変更権限 | ロール変更はAdministratorロールを持つユーザーのみ実行可能 | ロール変更操作時 |
| BR-003 | ユニーク制約 | 同一アカウント内で同一ユーザーは1つのAccountUserのみ持てる | AccountUser作成時 |
| BR-004 | 権限継承 | Administratorはagentの権限を包含する | 認可チェック時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ロール取得 | account_users | SELECT | 指定ユーザーのロール情報取得 |
| ロール変更 | account_users | UPDATE | roleカラムの更新 |
| ユーザー追加 | account_users | INSERT | 新規AccountUserレコード作成 |
| ユーザー削除 | account_users | DELETE | AccountUserレコード削除 |

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

#### account_users

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | role | 0（agent）または 1（administrator） | enum値 |
| UPDATE | updated_at | 現在時刻 | Rails自動更新 |
| SELECT | role, availability, user_id | account_id条件で取得 | - |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 403 | Forbidden | 操作者がAdministratorでない | 権限確認メッセージ表示 |
| 404 | NotFound | 指定AccountUserが存在しない | 対象確認メッセージ表示 |
| 422 | UnprocessableEntity | バリデーションエラー | エラー内容を表示 |

### リトライ仕様

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

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

AccountUser更新はActiveRecordの暗黙的トランザクション内で実行される。関連するnotification_settingsの作成もトランザクション内で行われる。

## パフォーマンス要件

- ロール変更操作: 200ms以内のレスポンス
- ユニークインデックス（account_id, user_id）による高速検索

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

- Punditによる認可制御でAdministrator権限を必須とする
- APIトークン経由のアクセスも同様の権限チェックを適用
- ロール変更は監査ログ（Enterprise機能）に記録される

## 備考

- Enterprise版ではCustomRoleによる細かな権限制御が追加される
- AccountUser.prepend_mod_with により Enterprise拡張が適用される

---

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

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

### 推奨読解順序

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

AccountUserモデルのスキーマとenum定義を理解することで、ロール管理の基盤を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | account_user.rb | `app/models/account_user.rb` | roleのenum定義、アソシエーション、バリデーション |

**読解のコツ**:
- `enum role: { agent: 0, administrator: 1 }` でロール値の定義を確認
- `validates :user_id, uniqueness: { scope: :account_id }` でユニーク制約を確認
- `prepend_mod_with`, `include_mod_with` でEnterprise拡張ポイントを把握

**主要処理フロー**:
1. **27-87行目**: AccountUserクラス全体の定義
2. **34行目**: ロールのenum定義（agent: 0, administrator: 1）
3. **35行目**: 可用性のenum定義
4. **43行目**: account_idとuser_idの組み合わせでユニーク制約
5. **56-58行目**: permissionsメソッドで権限配列を返却

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | agents_controller.rb | `app/controllers/api/v1/accounts/agents_controller.rb` | エージェント管理APIの入り口 |

**主要処理フロー**:
- エージェントのCRUD操作を提供
- ロール変更はupdateアクションで実行

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

Punditポリシーによる権限チェックの仕組みを把握する。

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

**主要処理フロー**:
- `@account_user.administrator?` でAdministrator権限チェック

#### Step 4: コールバック処理を理解する

ロール変更時のイベント通知とステータス更新の処理を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | account_user.rb | `app/models/account_user.rb` | after_create_commit, after_destroy コールバック |

**主要処理フロー**:
- **39行目**: `after_create_commit :notify_creation, :create_notification_setting`
- **40行目**: `after_destroy :notify_deletion, :remove_user_from_account`
- **71-77行目**: AGENT_ADDED/AGENT_REMOVED イベントディスパッチ

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

```
Api::V1::Accounts::AgentsController
    │
    ├─ AgentPolicy (認可チェック)
    │      └─ account_user.administrator?
    │
    └─ AccountUser (モデル操作)
           ├─ validates (バリデーション)
           ├─ after_create_commit
           │      ├─ notify_creation (イベント通知)
           │      └─ create_notification_setting
           └─ after_destroy
                  ├─ notify_deletion (イベント通知)
                  └─ remove_user_from_account (非同期ジョブ)
```

### データフロー図

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

APIリクエスト ────▶ AgentsController ────▶ JSONレスポンス
(role: 1)              │
                       ▼
                   AgentPolicy
                   (認可チェック)
                       │
                       ▼
                   AccountUser
                   (モデル更新)
                       │
                       ├──────▶ account_users テーブル
                       │
                       └──────▶ Redis (ステータス更新)
                                  │
                                  ▼
                              WebSocket通知
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| account_user.rb | `app/models/account_user.rb` | モデル | ロール情報を持つ中間テーブルモデル |
| agents_controller.rb | `app/controllers/api/v1/accounts/agents_controller.rb` | コントローラ | エージェント管理API |
| agent_policy.rb | `app/policies/agent_policy.rb` | ポリシー | エージェント操作の認可 |
| availability_statusable.rb | `app/models/concerns/availability_statusable.rb` | Concern | 可用性状態管理 |
| online_status_tracker.rb | `app/services/online_status_tracker.rb` | サービス | Redisでのステータス追跡 |
| destroy_job.rb | `app/jobs/agents/destroy_job.rb` | ジョブ | エージェント削除の非同期処理 |
