# 機能設計書 73-オートメーションルール作成・管理

## 概要

本ドキュメントは、Chatwootにおけるオートメーションルール（自動化ルール）の作成・管理機能の仕様を定義する機能設計書である。

### 本機能の処理概要

会話やメッセージのイベントに基づいて自動的にアクションを実行するルールを作成・管理する機能。条件ベースの自動化により、エージェントの手動作業を削減し、会話対応の効率化を実現する。

**業務上の目的・背景**：カスタマーサポート業務において、多くの定型的な対応作業が発生する。例えば、特定のキーワードを含むメッセージにラベルを付与する、VIP顧客の会話を特定チームに割り当てる、営業時間外の問い合わせに自動返信するなどである。本機能により、これらの反復作業を自動化し、エージェントがより付加価値の高い業務に集中できるようにする。

**機能の利用シーン**：
- 会話作成時に自動でラベルを付与する
- メッセージ内容に基づいて担当チームを自動割り当て
- 特定条件を満たす会話に対して自動返信メッセージを送信
- 会話ステータス変更時にWebhookを発火させる
- 特定キーワードを含むメッセージで会話の優先度を変更

**主要な処理内容**：
1. オートメーションルールのCRUD操作（作成・読取・更新・削除）
2. 条件（conditions）の定義と検証
3. アクション（actions）の定義と検証
4. イベントトリガーの設定
5. ルールの有効化/無効化制御
6. 添付ファイルの管理

**関連システム・外部連携**：
- イベントリスナー（AutomationRuleListener）によるイベント検知
- Webhook送信による外部システム連携
- メール送信サービスとの連携

**権限による制御**：Administrator権限を持つユーザーのみがルールの作成・編集・削除が可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 61 | 自動化ルール一覧画面 | 主画面 | オートメーションルールの一覧表示・管理 |
| 87 | 会話ワークフロー設定画面 | 補助画面 | 会話ワークフローとしてのルール設定 |

## 機能種別

CRUD操作 / イベント駆動型自動化

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | String | Yes | ルール名 | 必須 |
| description | Text | No | ルールの説明 | - |
| event_name | String | Yes | トリガーイベント名 | 必須、定義済みイベントのみ |
| active | Boolean | No | ルールの有効/無効 | デフォルトtrue |
| conditions | JSON | Yes | 条件配列 | 必須、形式検証 |
| actions | JSON | Yes | アクション配列 | 必須、形式検証 |

### 条件（conditions）の構造

```json
[
  {
    "attribute_key": "status",
    "filter_operator": "equal_to",
    "values": ["open"],
    "query_operator": "AND"
  }
]
```

| フィールド | 型 | 説明 |
|-----------|-----|------|
| attribute_key | String | 条件対象の属性キー |
| filter_operator | String | 比較演算子 |
| values | Array | 比較値 |
| query_operator | String | 論理演算子（AND/OR） |

### アクション（actions）の構造

```json
[
  {
    "action_name": "add_label",
    "action_params": ["urgent"]
  }
]
```

| フィールド | 型 | 説明 |
|-----------|-----|------|
| action_name | String | 実行するアクション名 |
| action_params | Array | アクションのパラメータ |

### サポートされるイベント名

- conversation_created
- conversation_updated
- conversation_opened
- conversation_resolved
- message_created

### サポートされる条件属性

content, email, country_code, status, message_type, browser_language, assignee_id, team_id, referer, city, company, inbox_id, mail_subject, phone_number, priority, conversation_language, labels

### サポートされるアクション

send_message, add_label, remove_label, send_email_to_team, assign_team, assign_agent, send_webhook_event, mute_conversation, send_attachment, change_status, resolve_conversation, open_conversation, snooze_conversation, change_priority, send_email_transcript, add_private_note

### 入力データソース

- 管理画面からのフォーム入力
- REST API経由

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | Integer | ルールID |
| account_id | Integer | アカウントID |
| name | String | ルール名 |
| description | Text | ルールの説明 |
| event_name | String | トリガーイベント |
| conditions | JSON | 条件配列 |
| actions | JSON | アクション配列 |
| created_on | Integer | 作成日時（Unix timestamp） |
| active | Boolean | 有効/無効状態 |
| files | Array | 添付ファイル情報 |

### 出力先

- APIレスポンス（JSON形式）
- データベース（automation_rulesテーブル）

## 処理フロー

### 処理シーケンス

```
1. ルール作成リクエスト受信
   └─ POST /api/v1/accounts/:account_id/automation_rules
2. パラメータ検証
   └─ 条件・アクションのJSON形式検証
3. 添付ファイル処理
   └─ send_attachmentアクションがある場合、ファイルをアップロード
4. ルール保存
   └─ automation_rulesテーブルへINSERT
5. レスポンス返却
   └─ 作成されたルール情報をJSON形式で返却
```

### フローチャート

```mermaid
flowchart TD
    A[ルール作成リクエスト] --> B[パラメータ検証]
    B --> C{検証OK?}
    C -->|No| D[422 Unprocessable Entity]
    C -->|Yes| E[添付ファイル処理]
    E --> F{ファイルあり?}
    F -->|Yes| G[Blob作成・アップロード]
    F -->|No| H[ルール保存]
    G --> H
    H --> I{保存成功?}
    I -->|No| J[エラーレスポンス]
    I -->|Yes| K[ファイル添付]
    K --> L[成功レスポンス]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-73-01 | 条件属性検証 | conditions内のattribute_keyは定義済み属性またはカスタム属性のみ | ルール保存時 |
| BR-73-02 | アクション検証 | actions内のaction_nameは定義済みアクションのみ | ルール保存時 |
| BR-73-03 | クエリ演算子 | query_operatorはANDまたはORのみ | 条件検証時 |
| BR-73-04 | 最終条件演算子 | 最後の条件のquery_operatorはnilまたは空 | 条件検証時 |
| BR-73-05 | イベント駆動 | ルールはイベント発生時に自動実行される | ルールがactive時 |

### 計算ロジック

条件評価はAND/ORの論理演算で結合され、すべての条件を満たした場合のみアクションが実行される。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ルール作成 | automation_rules | INSERT | 新規ルールレコードの挿入 |
| ルール更新 | automation_rules | UPDATE | 既存ルールの更新 |
| ルール削除 | automation_rules | DELETE | ルールの削除 |
| ルール一覧取得 | automation_rules | SELECT | アカウント内ルール全件取得 |
| ファイル添付 | active_storage_* | INSERT | 添付ファイルの保存 |

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

#### automation_rules

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name, description, event_name, active, conditions, actions | リクエストパラメータ | account_idは自動設定 |
| UPDATE | name, description, event_name, active, conditions, actions | リクエストパラメータ | 既存レコードを更新 |
| DELETE | - | id = :id | 論理削除ではなく物理削除 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 422 | Unprocessable Entity | 条件・アクションのバリデーションエラー | エラーメッセージに従い修正 |
| 404 | Not Found | 指定ルールが存在しない | 正しいIDを指定 |
| 403 | Forbidden | Administrator権限がない | 管理者権限でアクセス |
| 401 | Unauthorized | 未認証 | ログイン後に再試行 |

### リトライ仕様

オートメーションルールのアクション実行時にエラーが発生した場合、ChatwootExceptionTrackerで例外をキャプチャするが、自動リトライは行わない。

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

- ルール更新時はトランザクション内で処理
- ファイル添付はルール保存成功後に実行

## パフォーマンス要件

- ルール一覧取得：200ms以内
- ルール作成/更新：500ms以内
- 条件評価（実行時）：100ms以内

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

- Administrator権限によるアクセス制御
- 条件・アクションのサニタイズ処理
- query_operatorのホワイトリスト検証（SQLインジェクション対策）
- Webhook URLの検証

## 備考

- ルールの条件変更時はReauthorizable concernにより再認証処理が実行される
- Enterprise版では監査ログ機能が追加される

---

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

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

### 推奨読解順序

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

オートメーションルールのモデル定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | automation_rule.rb | `app/models/automation_rule.rb` | モデル定義、バリデーション、条件・アクション属性 |

**読解のコツ**:
- **27-30行目**: バリデーション定義（json_conditions_format, json_actions_format）
- **37-40行目**: conditions_attributes - サポートされる条件属性のリスト
- **42-46行目**: actions_attributes - サポートされるアクションのリスト
- **64-80行目**: JSON形式のバリデーション実装

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

APIコントローラーのCRUD操作を確認する。

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

**主要処理フロー**:
1. **7-9行目**: indexアクションで全ルール取得
2. **13-25行目**: createアクションでルール作成、添付ファイル処理
3. **27-41行目**: updateアクションでトランザクション内更新
4. **43-46行目**: destroyアクションで削除
5. **57-63行目**: permitted_paramsでパラメータのホワイトリスト

#### Step 3: イベント駆動処理を理解する

リスナーによるイベント処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | automation_rule_listener.rb | `app/listeners/automation_rule_listener.rb` | イベントリスナーの実装 |

**主要処理フロー**:
- **2-16行目**: 各イベント（conversation_updated, conversation_created等）のハンドラ
- **39-57行目**: process_conversation_event - 条件マッチングとアクション実行
- **59-71行目**: current_account_rules - activeなルールのみ取得

#### Step 4: 条件評価とアクション実行を理解する

サービスクラスの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | conditions_filter_service.rb | `app/services/automation_rules/conditions_filter_service.rb` | 条件評価ロジック |
| 4-2 | action_service.rb | `app/services/automation_rules/action_service.rb` | アクション実行ロジック |

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

```
[管理API]
AutomationRulesController
    │
    ├─ index: ルール一覧取得
    ├─ create: ルール作成
    │      ├─ validate_and_prepare_attachments
    │      └─ AutomationRule.create!
    ├─ update: ルール更新
    │      └─ トランザクション内で更新
    └─ destroy: ルール削除

[イベント駆動処理]
イベント発生（conversation_created等）
    │
    └─ AutomationRuleListener
           │
           ├─ rule_present?: activeルールの存在確認
           │
           └─ rules.each
                  ├─ ConditionsFilterService.perform
                  │      └─ 条件評価（SQL生成・実行）
                  │
                  └─ ActionService.perform
                         └─ 各アクションを順次実行
```

### データフロー図

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

管理者設定                  ルール保存                     DBへ永続化
(name, conditions,  ───▶ AutomationRulesController ───▶ automation_rules
 actions)

イベント発生               条件評価・アクション実行         会話への変更
(conversation_*    ───▶ AutomationRuleListener ────▶ ラベル付与、
 message_*)               │                              割り当て変更、
                          ├─ ConditionsFilterService      メッセージ送信等
                          └─ ActionService
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| automation_rule.rb | `app/models/automation_rule.rb` | モデル | データ構造・バリデーション |
| automation_rules_controller.rb | `app/controllers/api/v1/accounts/automation_rules_controller.rb` | コントローラー | CRUD API |
| automation_rule_listener.rb | `app/listeners/automation_rule_listener.rb` | リスナー | イベント検知・ルール実行 |
| conditions_filter_service.rb | `app/services/automation_rules/conditions_filter_service.rb` | サービス | 条件評価 |
| action_service.rb | `app/services/automation_rules/action_service.rb` | サービス | アクション実行 |
| action_service.rb | `app/services/action_service.rb` | サービス | 基底アクションサービス |
| _automation_rule.json.jbuilder | `app/views/api/v1/accounts/automation_rules/partials/_automation_rule.json.jbuilder` | ビュー | JSONレスポンス |
| filter_keys.yml | `lib/filters/filter_keys.yml` | 設定 | フィルタ条件定義 |
