# 機能設計書 30-ラベル管理

## 概要

本ドキュメントは、Chatwootにおける会話へのラベル付与機能について記述する。

### 本機能の処理概要

**業務上の目的・背景**：カスタマーサポートにおいて、会話を分類・整理するためにラベルを付与する。ラベルにより、問い合わせの種類（問い合わせ、クレーム、フィードバック等）、優先度、対応状況などを視覚的に識別でき、フィルタリングやレポーティングに活用できる。

**機能の利用シーン**：
- エージェントが会話にラベルを付与/削除
- ラベルによる会話のフィルタリング
- オートメーションルールによる自動ラベル付与
- ラベル別レポートの生成

**主要な処理内容**：
1. ラベル一覧の取得（index）
2. ラベルの更新（create: 全置換）
3. ラベルの追加（add_labels）
4. acts_as_taggable_onによるタグ管理
5. cached_label_listによるキャッシュ

**関連システム・外部連携**：acts_as_taggable_on gem、オートメーションルール

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | 会話詳細画面 | 主画面 | ラベル付与・削除 |
| 12 | ラベル別会話一覧 | 参照画面 | ラベルによるフィルタリング |

## 機能種別

ラベル管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| labels | Array | No | ラベル名の配列 | 文字列配列 |

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| labels | Array | 設定されているラベル一覧 |

## 処理フロー

### 処理シーケンス

```
1. ラベル操作リクエスト受信
2. [index] model.label_list を返却
3. [create] model.update_labels(labels) で全置換
4. 内部的にacts_as_taggable_onのlabel_listを更新
5. cached_label_listにカンマ区切りで保存
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-30-01 | 全置換 | create時は既存ラベルを全置換 | create時 |
| BR-30-02 | 追加 | add_labelsで既存ラベルに追加 | add_labels時 |
| BR-30-03 | ラベルフィルタ | tagged_with(labels, any: true)でOR検索 | 検索時 |
| BR-30-04 | キャッシュ | cached_label_listにカンマ区切りで保存 | 更新時 |

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

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

#### conversations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | cached_label_list | カンマ区切りのラベル文字列 | キャッシュ用 |

#### taggings

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/DELETE | taggable_id, taggable_type, tag_id | 会話ID、タグID | acts_as_taggable_on |

---

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

### 推奨読解順序

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1 | labels_controller.rb | `app/controllers/api/v1/accounts/conversations/labels_controller.rb` | LabelConcern使用 |
| 2 | label_concern.rb | `app/controllers/concerns/label_concern.rb` | create/indexアクション |
| 3 | labelable.rb | `app/models/concerns/labelable.rb` | acts_as_taggable_on、update_labels、add_labels |
| 4 | conversation.rb | `app/models/conversation.rb` | cached_label_list_array（178-180行目） |

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

```
LabelsController
    │
    └─ LabelConcern
           │
           ├─ #index
           │      └─ model.label_list
           │
           └─ #create
                  └─ model.update_labels(labels)
                         └─ update!(label_list: labels)
                                └─ acts_as_taggable_on
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| labels_controller.rb | `app/controllers/api/v1/accounts/conversations/labels_controller.rb` | コントローラー | ラベルAPI |
| label_concern.rb | `app/controllers/concerns/label_concern.rb` | Concern | 共通アクション |
| labelable.rb | `app/models/concerns/labelable.rb` | Concern | ラベル機能 |
| conversation.rb | `app/models/conversation.rb` | モデル | ラベル使用 |
