# 機能設計書 29-割り当て管理

## 概要

本ドキュメントは、Chatwootにおける会話のエージェント・チーム・ボットへの割り当て機能について記述する。

### 本機能の処理概要

**業務上の目的・背景**：カスタマーサポートにおいて、適切なエージェントやチームに会話を割り当てることで、専門性に応じた対応や負荷分散を実現する。また、AIボットへの割り当てにより、初期対応の自動化や24時間対応を可能にする。

**機能の利用シーン**：
- 管理者・エージェントによる手動割り当て
- 自動割り当て（ラウンドロビン）
- チーム割り当てによるエスカレーション
- ボット割り当てによる自動対応

**主要な処理内容**：
1. エージェント割り当て（assignee_id設定）
2. チーム割り当て（team_id設定）
3. ボット割り当て（assignee_agent_bot_id設定）
4. AssignmentServiceによる割り当て処理
5. 割り当て変更時のイベント発火

**関連システム・外部連携**：自動割り当てサービス、通知システム

**権限による制御**：会話へのアクセス権限を持つエージェントが操作可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | 会話詳細画面 | 主画面 | 担当者・チーム変更 |

## 機能種別

割り当て管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| assignee_id | Integer | No | 担当者ID | null可、存在チェック |
| assignee_type | String | No | 担当者タイプ | User/AgentBot |
| team_id | Integer | No | チームID | null可、存在チェック |

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| assignee | Object | 担当者情報（User/AgentBot） |
| team | Object | チーム情報 |

## 処理フロー

### 処理シーケンス

```
1. 割り当てリクエスト受信
2. assignee_id/assignee_type または team_id の判定
3. [エージェント/ボット割り当て]
   3-1. AssignmentService#perform呼び出し
   3-2. assignee_typeによりUser/AgentBotを判定
   3-3. conversation.assignee または assignee_agent_bot を更新
4. [チーム割り当て]
   4-1. team_idでチームを取得
   4-2. conversation.team を更新
5. ASSIGNEE_CHANGEDイベント発火
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-29-01 | 排他的割り当て | assignee設定時はassignee_agent_bot_idをクリア | エージェント割り当て時 |
| BR-29-02 | ボット割り当て | assignee_type=AgentBot時はassignee_idをクリア | ボット割り当て時 |
| BR-29-03 | 割り当て解除 | assignee_id=nullで担当者解除 | 常時 |
| BR-29-04 | チーム独立 | team_idはassignee_idと独立して設定可能 | 常時 |

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

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

#### conversations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | assignee_id | user_id または null | エージェント割り当て |
| UPDATE | assignee_agent_bot_id | agent_bot_id または null | ボット割り当て |
| UPDATE | team_id | team_id または null | チーム割り当て |

---

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

### 推奨読解順序

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1 | assignments_controller.rb | `app/controllers/api/v1/accounts/conversations/assignments_controller.rb` | createアクション |
| 2 | assignment_service.rb | `app/services/conversations/assignment_service.rb` | 割り当てロジック |
| 3 | conversation.rb | `app/models/conversation.rb` | reset_agent_bot_when_assignee_present（248-252行目） |

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

```
AssignmentsController#create
    │
    ├─ [assignee_id指定]
    │      └─ set_agent
    │             └─ Conversations::AssignmentService#perform
    │                    ├─ assign_agent (User)
    │                    └─ assign_agent_bot (AgentBot)
    │
    └─ [team_id指定]
           └─ set_team
                  └─ @conversation.update!(team: @team)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| assignments_controller.rb | `app/controllers/api/v1/accounts/conversations/assignments_controller.rb` | コントローラー | 割り当てAPI |
| assignment_service.rb | `app/services/conversations/assignment_service.rb` | サービス | 割り当てロジック |
| conversation.rb | `app/models/conversation.rb` | モデル | 割り当て状態管理 |
| assignment_handler.rb | `app/models/concerns/assignment_handler.rb` | Concern | 割り当て変更ハンドラ |
