# 機能設計書 12-カスタムロール

## 概要

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

### 本機能の処理概要

カスタムロール機能は、Enterprise版において標準のAgent/Administratorロールに加えて、細粒度の権限を持つカスタムロールを定義・管理する機能である。これにより、組織の実際の役割分担に合わせた柔軟な権限設定が可能となる。

**業務上の目的・背景**：大規模な組織では、単純なAgent/Administrator の二分法では不十分な場合がある。例えば、「会話は管理できるが連絡先は閲覧のみ」「レポートは見られるがナレッジベースは編集不可」といった細かな権限制御が必要となる。カスタムロール機能により、組織の実際の職責に合わせた権限設定が実現できる。

**機能の利用シーン**：
- スーパーバイザーが担当チームの会話のみ管理する権限設定
- コンテンツ担当者がナレッジベースのみ編集する権限設定
- アナリストがレポートのみ閲覧する権限設定
- チームリーダーが未割り当て会話のみ自分に割り当てる権限設定

**主要な処理内容**：
1. CustomRoleモデルでのカスタムロール定義（名前、説明、権限配列）
2. 定義済み権限（PERMISSIONS定数）からの選択式権限設定
3. AccountUserへのカスタムロール紐付け（custom_role_id）
4. 各種ポリシーでのカスタムロール権限チェック
5. カスタムロール削除時のAccountUser参照解除（nullify）

**関連システム・外部連携**：
- Enterprise認証・ライセンス管理システム

**権限による制御**：
- カスタムロールの作成・編集・削除はAdministratorロールが必要
- カスタムロール自体が持つ権限は6種類の定義済み権限から選択

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 78 | カスタムロール一覧画面 | 主画面 | カスタムロールの一覧表示・管理 |
| 46 | エージェント一覧画面 | 参照画面 | エージェントへのカスタムロール適用 |

## 機能種別

CRUD操作 / 認可制御（Enterprise機能）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | String | Yes | カスタムロール名 | presence: true |
| description | String | No | 説明文 | - |
| permissions | Array | Yes | 権限配列 | PERMISSIONS定数内の値のみ許可 |

### 定義済み権限（PERMISSIONS）

| 権限名 | 説明 |
|--------|------|
| conversation_manage | すべての会話を管理可能 |
| conversation_unassigned_manage | 未割り当て会話の管理と自分への割り当てが可能 |
| conversation_participating_manage | 参加中（担当または参加者）の会話のみ管理可能 |
| contact_manage | 連絡先を管理可能 |
| report_manage | レポートを管理可能 |
| knowledge_base_manage | ナレッジベースポータルを管理可能 |

### 入力データソース

- 画面入力（カスタムロール一覧画面からの操作）
- API経由（Enterprise REST API）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | Integer | カスタムロールID |
| name | String | カスタムロール名 |
| description | String | 説明文 |
| permissions | Array | 権限配列 |
| account_id | Integer | 所属アカウントID |

### 出力先

- APIレスポンス（JSON形式）

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ CustomRolesController経由でCRUDリクエストを受信

2. Enterprise認証チェック
   └─ EnterpriseAccountsController継承により自動チェック

3. 認可チェック
   └─ CustomRolePolicyで操作者がAdministratorか確認

4. バリデーション
   └─ name必須チェック、permissions値の妥当性チェック

5. データベース操作
   └─ custom_rolesテーブルへのCRUD操作

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

### フローチャート

```mermaid
flowchart TD
    A[カスタムロール操作リクエスト] --> B{Enterprise版?}
    B -->|No| C[403エラー返却]
    B -->|Yes| D{認可チェック}
    D -->|Administrator| E{操作種別}
    D -->|その他| C
    E -->|Create| F[バリデーション]
    E -->|Read| G[レコード取得]
    E -->|Update| H[レコード更新]
    E -->|Delete| I[レコード削除]
    F --> J{permissions有効?}
    J -->|Yes| K[レコード作成]
    J -->|No| L[422エラー]
    K --> M[レスポンス返却]
    G --> M
    H --> M
    I --> N[関連AccountUser解除]
    N --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Enterprise限定 | カスタムロール機能はEnterprise版のみ利用可能 | 全操作時 |
| BR-002 | 権限制限 | permissionsは定義済みPERMISSIONS定数の値のみ許可 | 作成・更新時 |
| BR-003 | 名前必須 | カスタムロール名は必須 | 作成・更新時 |
| BR-004 | 削除時nullify | カスタムロール削除時、紐付いたAccountUserのcustom_role_idはnullになる | 削除時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 一覧取得 | custom_roles | SELECT | アカウント内のカスタムロール一覧取得 |
| 詳細取得 | custom_roles | SELECT | 指定IDのカスタムロール取得 |
| 作成 | custom_roles | INSERT | 新規カスタムロール作成 |
| 更新 | custom_roles | UPDATE | カスタムロール情報更新 |
| 削除 | custom_roles | DELETE | カスタムロール削除 |
| 削除 | account_users | UPDATE | custom_role_idをnullに更新 |

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

#### custom_roles

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | リクエストパラメータ | 必須 |
| INSERT | description | リクエストパラメータ | 任意 |
| INSERT | permissions | リクエストパラメータ（配列） | PostgreSQL配列型 |
| INSERT | account_id | Current.account.id | 自動設定 |
| SELECT | * | account_id条件 | - |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 403 | Forbidden | Enterprise版でない / Administrator権限なし | プランアップグレード案内 |
| 404 | NotFound | 指定カスタムロールが存在しない | 対象確認メッセージ表示 |
| 422 | UnprocessableEntity | バリデーションエラー（無効なpermissions等） | エラー内容を表示 |

### リトライ仕様

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

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

カスタムロール削除時、関連するAccountUserのcustom_role_id更新はRailsのdependent: :nullifyにより自動的に処理される。

## パフォーマンス要件

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

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

- Enterprise認証によるアクセス制御
- Administratorロール必須の認可制御
- permissions配列の値はPERMISSIONS定数で制限（任意の値を許可しない）

## 備考

- CustomRoleはEnterprise版専用機能であり、enterprise/ディレクトリ配下に実装されている
- 標準のAgent/Administratorロールとは独立して動作し、より細かな権限制御を提供する

---

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

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

### 推奨読解順序

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

CustomRoleモデルのスキーマと権限定義を理解することで、カスタムロールの基盤を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | custom_role.rb | `enterprise/app/models/custom_role.rb` | PERMISSIONS定数、バリデーション、アソシエーション |

**読解のコツ**:
- `PERMISSIONS`定数で定義された6種類の権限を確認
- `validates :permissions, inclusion: { in: PERMISSIONS }` でpermissions値の制限を確認
- `has_many :account_users, dependent: :nullify` で削除時の動作を確認

**主要処理フロー**:
1. **1-16行目**: スキーマ情報（テーブル名: custom_roles）
2. **19-25行目**: 権限の説明コメント
3. **31-38行目**: PERMISSIONS定数の定義
4. **40行目**: name必須バリデーション
5. **41行目**: permissions値のバリデーション

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | custom_roles_controller.rb | `enterprise/app/controllers/api/v1/accounts/custom_roles_controller.rb` | CRUD操作の実装 |

**読解のコツ**:
- `EnterpriseAccountsController`を継承しているためEnterprise認証が自動適用される
- `permitted_params`でname, description, permissions配列を許可

**主要処理フロー**:
1. **1行目**: EnterpriseAccountsController継承
2. **5-7行目**: index - カスタムロール一覧取得
3. **11-13行目**: create - カスタムロール作成
4. **15-17行目**: update - カスタムロール更新
5. **19-22行目**: destroy - カスタムロール削除
6. **24-26行目**: permitted_params - 許可パラメータ定義

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

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

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

**主要処理フロー**:
- Administrator権限チェック

#### Step 4: AccountUserとの関連を理解する

AccountUserモデルでのカスタムロール参照を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | account_user.rb | `app/models/account_user.rb` | custom_role_idカラム、Enterprise拡張 |

**主要処理フロー**:
- **14行目**: custom_role_id カラムの存在確認
- **23行目**: インデックス定義

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

```
Api::V1::Accounts::CustomRolesController
    │
    ├─ EnterpriseAccountsController (Enterprise認証)
    │
    ├─ CustomRolePolicy (認可チェック)
    │      └─ account_user.administrator?
    │
    └─ CustomRole (モデル操作)
           ├─ validates :name
           ├─ validates :permissions
           └─ has_many :account_users (dependent: :nullify)
```

### データフロー図

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

APIリクエスト ────────▶ CustomRolesController ────────▶ JSONレスポンス
(name, permissions)            │
                               ▼
                      EnterpriseAccountsController
                         (Enterprise認証)
                               │
                               ▼
                        CustomRolePolicy
                         (認可チェック)
                               │
                               ▼
                          CustomRole
                        (バリデーション)
                               │
                               ▼
                      custom_roles テーブル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| custom_role.rb | `enterprise/app/models/custom_role.rb` | モデル | カスタムロールデータモデル |
| custom_roles_controller.rb | `enterprise/app/controllers/api/v1/accounts/custom_roles_controller.rb` | コントローラ | カスタムロールAPI |
| custom_role_policy.rb | `enterprise/app/policies/custom_role_policy.rb` | ポリシー | カスタムロール操作の認可 |
| enterprise_accounts_controller.rb | `enterprise/app/controllers/api/v1/accounts/enterprise_accounts_controller.rb` | コントローラ | Enterprise認証基底クラス |
| account_user.rb | `app/models/account_user.rb` | モデル | カスタムロール参照元 |
