# 画面設計書 84-エージェント容量一覧

## 概要

本ドキュメントは、Chatwootのエージェント容量ポリシー一覧画面の設計を記述したものです。この画面では、エージェントごとの会話処理容量を制御するポリシーを一覧表示・管理します。

### 本画面の処理概要

**業務上の目的・背景**：顧客サポート業務において、各エージェントが同時に処理できる会話数を制限することで、過負荷を防ぎ、対応品質を維持します。容量ポリシーにより、エージェントの業務負荷を適切に管理し、バーンアウトを防止することができます。

**画面へのアクセス方法**：サイドメニューの「設定」から「割り当てポリシー」を選択し、その後「エージェント容量」タブをクリックしてアクセスします。URLパスは `/app/accounts/:accountId/settings/assignment-policy/capacity` です。

**主要な操作・処理内容**：
1. 容量ポリシーの一覧表示（カード形式でポリシー名、説明、関連エージェント数を表示）
2. 新規ポリシー作成画面への遷移（「ポリシーを作成」ボタン）
3. 既存ポリシーの編集画面への遷移（各カードの編集ボタン）
4. ポリシーの削除（削除確認ダイアログ表示後に実行）
5. 各ポリシーに紐づくエージェントの展開表示

**画面遷移**：
- 遷移元：割り当てポリシーインデックス画面
- 遷移先：エージェント容量作成画面、エージェント容量編集画面

**権限による表示制御**：管理者（administrator）ロールのユーザーのみがアクセス可能です。ASSIGNMENT_V2フィーチャーフラグが有効な場合にのみ表示されます。Enterprise版またはCloud版でのみ利用可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 184 | 容量ポリシー | 主機能 | エージェント容量設定の一覧表示・管理 |

## 画面種別

一覧

## URL/ルーティング

- **パス**: `/app/accounts/:accountId/settings/assignment-policy/capacity`
- **ルート名**: `agent_capacity_policy_index`

## 入出力項目

| 項目名 | 入出力 | データ型 | 必須 | 説明 |
|--------|--------|----------|------|------|
| accountId | 入力（URLパラメータ） | Number | 必須 | アカウントID |

## 表示項目

### ポリシーカード（AgentCapacityPolicyCard）

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ポリシー名 | String | 容量ポリシーの名前 |
| 説明 | String | ポリシーの説明文 |
| 関連エージェント数 | Number | このポリシーに紐づくエージェントの数 |
| 除外ルール | Object | excludedLabels（除外ラベル）, excludeOlderThanHours（古い会話の除外時間） |
| インボックス容量制限 | Array | インボックスごとの会話上限設定 |
| 関連エージェント一覧 | Array | 展開時に表示されるエージェントリスト |

## イベント仕様

### 1-ポリシー作成ボタン押下

「ポリシーを作成」ボタン押下時、エージェント容量作成画面（`agent_capacity_policy_create`）に遷移します。

### 2-ポリシー編集ボタン押下

各ポリシーカードの編集アイコンボタン押下時、該当ポリシーのID付きでエージェント容量編集画面（`agent_capacity_policy_edit`）に遷移します。

### 3-ポリシー削除ボタン押下

各ポリシーカードの削除アイコンボタン押下時、削除確認ダイアログ（ConfirmDeletePolicyDialog）を表示します。ダイアログで確認後、Vuex Action `agentCapacityPolicies/delete` を実行してポリシーを削除します。

### 4-エージェント展開

各ポリシーカードの展開トリガー操作時、Vuex Action `agentCapacityPolicies/getUsers` を実行し、該当ポリシーに紐づくエージェント一覧を取得・表示します。

### 5-画面マウント時

画面マウント時（onMounted）、Vuex Action `agentCapacityPolicies/get` を実行し、全ての容量ポリシーを取得します。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | agent_capacity_policies | SELECT | 全ポリシー一覧の取得 |
| エージェント展開 | account_users | SELECT | ポリシーに紐づくエージェント取得 |
| ポリシー削除 | agent_capacity_policies | DELETE | 指定ポリシーの削除 |

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

#### agent_capacity_policies

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | account_id = 現在のアカウントID | 一覧取得 |
| DELETE | - | id = 指定のポリシーID | 関連レコードは依存関係で削除/nullify |

#### account_users

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | agent_capacity_policy_id = ポリシーID | 紐づきエージェント取得 |

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|-------------|------|----------|--------------|
| DELETE_POLICY.SUCCESS_MESSAGE | 成功 | ポリシー削除成功時 | ポリシーが正常に削除されました |
| DELETE_POLICY.ERROR_MESSAGE | エラー | ポリシー削除失敗時 | ポリシーの削除に失敗しました |
| INDEX.NO_RECORDS_FOUND | 情報 | ポリシーが0件の場合 | 容量ポリシーが見つかりません |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| ポリシー取得失敗 | エラーメッセージをアラート表示 |
| ポリシー削除失敗 | エラーメッセージをアラート表示、削除ダイアログは閉じない |
| 権限不足 | 画面アクセス不可（ルートガードで制御） |
| フィーチャーフラグ無効 | 画面アクセス不可（ルートガードで制御） |

## 備考

- Enterprise版またはCloud版でのみ利用可能な機能です
- ASSIGNMENT_V2フィーチャーフラグが有効な場合のみアクセス可能
- ポリシー削除時、紐づくエージェントのagent_capacity_policy_idはnullifyされます
- 容量ポリシーにはインボックスごとの会話上限も設定可能です

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | agentCapacityPolicies.js | `app/javascript/dashboard/store/modules/agentCapacityPolicies.js` | state構造（records, uiFlags, usersUiFlags）とgettersの定義 |
| 1-2 | agent_capacity_policy.rb | `enterprise/app/models/agent_capacity_policy.rb` | モデル定義、バリデーション、関連（has_many :account_users） |

**読解のコツ**: Enterprise版のモデルはenterprise/ディレクトリにあることに注意

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AgentCapacityIndexPage.vue | `app/javascript/dashboard/routes/dashboard/settings/assignmentPolicy/pages/AgentCapacityIndexPage.vue` | setup関数内のstore接続、onMountedでのデータ取得 |

**主要処理フロー**:
1. **行14-22**: useMapGetterでVuexストアのgettersを取得
2. **行83-85**: onMountedで`agentCapacityPolicies/get`アクションをディスパッチ
3. **行45-58**: 編集・作成画面への遷移処理
4. **行69-81**: 削除処理の実装

#### Step 3: コンポーネント層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AgentCapacityPolicyCard.vue | `app/javascript/dashboard/components-next/AssignmentPolicy/AgentCapacityPolicyCard/AgentCapacityPolicyCard.vue` | カード表示のUI構造、emitイベント |
| 3-2 | ConfirmDeletePolicyDialog.vue | `app/javascript/dashboard/routes/dashboard/settings/assignmentPolicy/pages/components/ConfirmDeletePolicyDialog.vue` | 削除確認ダイアログ（割り当てポリシーと共用） |

#### Step 4: API層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | agentCapacityPolicies.js | `app/javascript/dashboard/api/agentCapacityPolicies.js` | APIクライアントのエンドポイント定義 |
| 4-2 | agent_capacity_policies_controller.rb | `enterprise/app/controllers/api/v1/accounts/agent_capacity_policies_controller.rb` | バックエンドのコントローラー処理 |

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

```
AgentCapacityIndexPage.vue (エントリーポイント)
    │
    ├─ onMounted
    │      └─ store.dispatch('agentCapacityPolicies/get')
    │              └─ AgentCapacityPoliciesAPI.get()
    │                      └─ GET /api/v1/accounts/:id/agent_capacity_policies
    │
    ├─ AgentCapacityPolicyCard.vue
    │      ├─ @edit → onClickEditPolicy → router.push
    │      ├─ @delete → handleDelete → ConfirmDeletePolicyDialog
    │      └─ @fetch-users → handleFetchUsers
    │              └─ store.dispatch('agentCapacityPolicies/getUsers')
    │
    └─ ConfirmDeletePolicyDialog.vue
           └─ @delete → handleDeletePolicy
                   └─ store.dispatch('agentCapacityPolicies/delete')
                           └─ AgentCapacityPoliciesAPI.delete()
```

### データフロー図

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

画面マウント ────────▶ agentCapacityPolicies/get ──────▶ ポリシー一覧表示
                              │
                              ▼
                      API: GET /agent_capacity_policies
                              │
                              ▼
                      Vuex State更新
                              │
                              ▼
                      useMapGetter取得
                              │
                              ▼
                      AgentCapacityPolicyCard表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AgentCapacityIndexPage.vue | `app/javascript/dashboard/routes/dashboard/settings/assignmentPolicy/pages/AgentCapacityIndexPage.vue` | ソース | メインページコンポーネント |
| agentCapacityPolicies.js | `app/javascript/dashboard/store/modules/agentCapacityPolicies.js` | ソース | Vuexストアモジュール |
| agentCapacityPolicies.js | `app/javascript/dashboard/api/agentCapacityPolicies.js` | ソース | APIクライアント |
| AgentCapacityPolicyCard.vue | `app/javascript/dashboard/components-next/AssignmentPolicy/AgentCapacityPolicyCard/AgentCapacityPolicyCard.vue` | ソース | ポリシーカードコンポーネント |
| ConfirmDeletePolicyDialog.vue | `app/javascript/dashboard/routes/dashboard/settings/assignmentPolicy/pages/components/ConfirmDeletePolicyDialog.vue` | ソース | 削除確認ダイアログ |
| assignmentPolicy.routes.js | `app/javascript/dashboard/routes/dashboard/settings/assignmentPolicy/assignmentPolicy.routes.js` | ソース | ルーティング定義 |
| agent_capacity_policies_controller.rb | `enterprise/app/controllers/api/v1/accounts/agent_capacity_policies_controller.rb` | ソース | バックエンドコントローラー |
| agent_capacity_policy.rb | `enterprise/app/models/agent_capacity_policy.rb` | ソース | モデル定義 |
| SettingsLayout.vue | `app/javascript/dashboard/routes/dashboard/settings/SettingsLayout.vue` | ソース | 設定画面共通レイアウト |
| Breadcrumb.vue | `app/javascript/dashboard/components-next/breadcrumb/Breadcrumb.vue` | ソース | パンくずリストコンポーネント |
