# 機能設計書 27-会話ステータス管理

## 概要

本ドキュメントは、Chatwootにおける会話ステータス（オープン・クローズ・保留・スヌーズ）の管理機能について記述する。

### 本機能の処理概要

**業務上の目的・背景**：カスタマーサポートにおいて、会話のライフサイクルを適切に管理することは業務効率化に不可欠である。オープン、解決済み、保留中、スヌーズの4つのステータスにより、対応状況を明確にし、優先度に基づいた業務遂行を可能にする。

**機能の利用シーン**：
- エージェントが会話を解決してクローズする
- 顧客からの返信により会話が再オープンする
- ボット対応中の会話を保留状態に設定
- 後で対応するためにスヌーズを設定

**主要な処理内容**：
1. toggle_statusによるステータス切り替え（open <-> resolved）
2. 明示的なステータス設定（params[:status]）
3. スヌーズ時間の設定（snoozed_until）
4. 自動解決（ResolutionJob）による自動クローズ
5. ボットハンドオフ時の状態遷移

**関連システム・外部連携**：イベントディスパッチャー、自動解決ジョブ

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | 会話詳細画面 | 主画面 | ステータス変更ボタン |
| 16 | 未対応会話一覧 | 参照画面 | ステータスによるフィルタリング |

## 機能種別

状態管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| status | String | No | 設定するステータス | open/resolved/pending/snoozed |
| snoozed_until | DateTime | No | スヌーズ解除日時 | 有効な日時形式 |

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| status | String | 更新後のステータス |
| snoozed_until | DateTime | スヌーズ解除日時（snoozed時のみ） |

## 処理フロー

### 処理シーケンス

```
1. toggle_statusリクエスト受信
2. ボットハンドオフ判定（pending -> open by bot）
3. 明示的ステータス設定またはトグル
4. スヌーズ時間設定（snoozed時のみ）
5. 自動担当者割り当て（オープン時、エージェント操作）
6. イベント発火（CONVERSATION_OPENED/RESOLVED/STATUS_CHANGED）
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-27-01 | トグル動作 | open時はresolved、それ以外はopenに切り替え | toggle_status呼び出し時 |
| BR-27-02 | スヌーズリセット | snoozed以外のステータス時、snoozed_untilをクリア | ステータス変更時 |
| BR-27-03 | 自動解決 | auto_resolve_after分経過後に自動でresolved | ResolutionJob実行時 |
| BR-27-04 | waiting_sinceクリア | resolved時にwaiting_sinceをnullに | resolved変更時 |

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

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

#### conversations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | status | 0(open)/1(resolved)/2(pending)/3(snoozed) | enum |
| UPDATE | snoozed_until | スヌーズ解除日時またはnull | - |
| UPDATE | waiting_since | nullに更新 | resolved時 |

---

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

### 推奨読解順序

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1 | conversation.rb | `app/models/conversation.rb` | statusのenum定義（75行目）、toggle_status（149-154行目） |
| 2 | conversations_controller.rb | `app/controllers/api/v1/accounts/conversations_controller.rb` | toggle_statusアクション（78-89行目） |
| 3 | resolution_job.rb | `app/jobs/conversations/resolution_job.rb` | 自動解決処理 |

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

```
ConversationsController#toggle_status
    │
    ├─ pending_to_open_by_bot? -> bot_handoff!
    │
    ├─ set_conversation_status (明示的設定)
    │      └─ @conversation.save!
    │
    └─ @conversation.toggle_status (トグル)
           │
           └─ execute_after_update_commit_callbacks
                  ├─ handle_resolved_status_change
                  └─ notify_status_change
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| conversation.rb | `app/models/conversation.rb` | モデル | ステータス管理 |
| conversations_controller.rb | `app/controllers/api/v1/accounts/conversations_controller.rb` | コントローラー | toggle_status API |
| resolution_job.rb | `app/jobs/conversations/resolution_job.rb` | ジョブ | 自動解決 |
