# 機能設計書 74-ルールクローン

## 概要

本ドキュメントは、Chatwootにおけるオートメーションルールの複製（クローン）機能の仕様を定義する機能設計書である。

### 本機能の処理概要

既存のオートメーションルールを複製して新しいルールを作成する機能。複雑な条件・アクション設定を持つルールを効率的に再利用できるようにし、類似ルールの作成作業を大幅に削減する。

**業務上の目的・背景**：オートメーションルールは条件やアクションが複雑になりがちで、一から作成するには時間がかかる。既存の動作実績のあるルールをベースに、一部の条件やアクションだけを変更した新しいルールを作成したい場合が多い。本機能により、ルール作成の効率化と設定ミスの削減を実現する。

**機能の利用シーン**：
- 既存ルールを元に、別のインボックス用のルールを作成する
- 条件を少し変えた複数のバリエーションルールを作成する
- テスト用ルールを本番用にコピーする
- 一時的にルールを無効化する際のバックアップとして複製する

**主要な処理内容**：
1. 既存ルールのIDを指定してクローンリクエストを送信
2. 指定されたルールの全属性を複製
3. 新しいルールとしてデータベースに保存
4. 複製されたルールの情報を返却

**関連システム・外部連携**：特になし（自己完結型の機能）

**権限による制御**：Administrator権限を持つユーザーのみがルールのクローンが可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 61 | 自動化ルール一覧画面 | 主画面 | ルール複製ボタンのクリック |

## 機能種別

データ複製 / 作成処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| automation_rule_id | Integer | Yes | 複製元ルールのID | 存在確認、アカウント所属確認 |

### 入力データソース

- URLパス経由（/api/v1/accounts/:account_id/automation_rules/:automation_rule_id/clone）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 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 | 有効/無効状態（元ルールと同一） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. クローンリクエスト受信
   └─ POST /api/v1/accounts/:account_id/automation_rules/:automation_rule_id/clone
2. 元ルール取得
   └─ AutomationRule.find_by(id: params[:automation_rule_id])
3. ルール複製
   └─ automation_rule.dup
4. 新ルール保存
   └─ new_rule.save!
5. レスポンス返却
   └─ 複製されたルール情報をJSON形式で返却
```

### フローチャート

```mermaid
flowchart TD
    A[POST /clone リクエスト] --> B[元ルール取得]
    B --> C{ルール存在?}
    C -->|No| D[404 Not Found]
    C -->|Yes| E[ルールを複製 (dup)]
    E --> F[新ルール保存]
    F --> G{保存成功?}
    G -->|No| H[エラーレスポンス]
    G -->|Yes| I[成功レスポンス]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-74-01 | 全属性複製 | name, description, event_name, conditions, actions, activeをすべて複製 | クローン実行時 |
| BR-74-02 | 新規ID付与 | 複製されたルールには新しいIDが付与される | クローン実行時 |
| BR-74-03 | タイムスタンプ更新 | created_at, updated_atは複製時の時刻が設定される | クローン実行時 |
| BR-74-04 | 同一アカウント | 複製元と複製先は同一アカウント内 | クローン実行時 |

### 計算ロジック

RubyのActiveRecordの`dup`メソッドを使用。`dup`はオブジェクトの浅いコピーを作成し、id, created_at, updated_atは新規設定される。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 元ルール取得 | automation_rules | SELECT | IDで元ルール取得 |
| 新ルール作成 | automation_rules | INSERT | 複製されたルールの挿入 |

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

#### automation_rules

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | id = :automation_rule_id | 複製元の取得 |
| INSERT | name, description, event_name, conditions, actions, active | 元ルールからコピー | id, created_at, updated_atは新規 |

## エラー処理

### エラーケース一覧

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

### リトライ仕様

特になし（単発の複製操作）

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

単一レコードのINSERT操作のため、ActiveRecordの標準トランザクション制御に依存。

## パフォーマンス要件

- クローン処理：200ms以内

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

- Administrator権限によるアクセス制御
- 同一アカウント内のルールのみ複製可能

## 備考

- `dup`メソッドは添付ファイル（has_many_attached :files）は複製しない
- 複製後のルール名は元ルールと同一のため、必要に応じて手動で変更が必要

---

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

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

### 推奨読解順序

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

AutomationRuleモデルの構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | automation_rule.rb | `app/models/automation_rule.rb` | モデル定義、複製対象の属性 |

**読解のコツ**:
- スキーマ情報（1-18行目）で複製される属性を確認
- `has_many_attached :files`は`dup`で複製されない点に注意

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

cloneアクションの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | automation_rules_controller.rb | `app/controllers/api/v1/accounts/automation_rules_controller.rb` | cloneアクション |

**主要処理フロー**:
1. **5行目**: before_action :fetch_automation_ruleでルール取得
2. **48-53行目**: cloneアクションの実装
   - `find_by(id: params[:automation_rule_id])`で元ルール取得
   - `automation_rule.dup`でオブジェクト複製
   - `new_rule.save!`で保存

#### Step 3: レスポンス生成を理解する

JSONビューテンプレートを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | clone.json.jbuilder | `app/views/api/v1/accounts/automation_rules/clone.json.jbuilder` | クローン結果のJSON出力 |

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

```
POST /api/v1/accounts/:account_id/automation_rules/:automation_rule_id/clone
    │
    ├─ before_action :fetch_automation_rule
    │      └─ Current.account.automation_rules.find_by(id: params[:id])
    │
    └─ clone アクション
           │
           ├─ find_by(id: params[:automation_rule_id])
           ├─ automation_rule.dup
           ├─ new_rule.save!
           └─ @automation_rule = new_rule
                  │
                  └─ clone.json.jbuilder
                         └─ _automation_rule.json.jbuilder (partial)
```

### データフロー図

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

URLパラメータ               コントローラー                  JSONレスポンス
(automation_rule_id) ───▶ AutomationRulesController ───▶ 新規ルール情報
                                │
                                ├─ 元ルール取得
                                ├─ dup (浅いコピー)
                                └─ save! (新規ID付与)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| automation_rules_controller.rb | `app/controllers/api/v1/accounts/automation_rules_controller.rb` | コントローラー | cloneアクション（48-53行目） |
| automation_rule.rb | `app/models/automation_rule.rb` | モデル | モデル定義 |
| clone.json.jbuilder | `app/views/api/v1/accounts/automation_rules/clone.json.jbuilder` | ビュー | クローンレスポンス |
| _automation_rule.json.jbuilder | `app/views/api/v1/accounts/automation_rules/partials/_automation_rule.json.jbuilder` | ビュー | ルールJSONパーシャル |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義（107行目: post :clone） |
