# 機能設計書 91-カスタムツール

## 概要

本ドキュメントは、Chatwoot の Captain AI 機能におけるカスタムツール管理機能の設計を記載する。

### 本機能の処理概要

カスタムツール機能は、AIアシスタント（Captain）が外部APIを呼び出して情報を取得したり、アクションを実行したりするためのユーザー定義ツールを作成・管理する機能である。

**業務上の目的・背景**：AIアシスタントは顧客対応において様々な情報を必要とするが、標準で提供されるツールだけでは業務固有の要件に対応できない場合がある。カスタムツールを定義することで、CRM、在庫管理システム、社内システムなど外部サービスと連携し、AIアシスタントの能力を拡張できる。

**機能の利用シーン**：
- 顧客からの問い合わせ時に、外部CRMから顧客の契約情報を取得する
- 在庫確認のために外部在庫管理システムのAPIを呼び出す
- 社内の技術サポートデータベースから関連情報を検索する

**主要な処理内容**：
1. カスタムツールの一覧取得（有効なツールのみ）
2. カスタムツールの詳細表示
3. 新規カスタムツールの作成（タイトル、エンドポイントURL、HTTPメソッド、認証設定等）
4. 既存カスタムツールの更新
5. カスタムツールの削除

**関連システム・外部連携**：カスタムツールは外部APIエンドポイントへのリクエストを定義するため、連携先の外部システムのAPI仕様に依存する。認証方式はnone/bearer/basic/api_keyをサポート。

**権限による制御**：カスタムツールの作成・更新・削除は管理者（Administrator）のみ可能。一覧表示・詳細表示はすべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 107 | カスタムツール一覧画面 | 主画面 | カスタムツールの一覧表示・作成・編集・削除 |

## 機能種別

CRUD操作 / API連携設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| title | String | Yes | ツールのタイトル | 必須 |
| description | Text | No | ツールの説明（AIがツール選択時に使用） | - |
| endpoint_url | Text | Yes | 呼び出すAPIのエンドポイントURL | 必須、安全なエンドポイント検証 |
| http_method | String | No | HTTPメソッド（GET/POST） | デフォルト: GET |
| request_template | Text | No | リクエストテンプレート | - |
| response_template | Text | No | レスポンステンプレート | - |
| auth_type | String | No | 認証タイプ（none/bearer/basic/api_key） | デフォルト: none |
| auth_config | JSON | No | 認証設定の詳細 | - |
| param_schema | JSON | No | パラメータスキーマ定義 | JSONスキーマ形式 |
| enabled | Boolean | No | ツールの有効/無効 | デフォルト: true |

### 入力データソース

画面入力（API経由）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | Integer | カスタムツールID |
| slug | String | ツールの識別子（自動生成） |
| title | String | ツールのタイトル |
| description | Text | ツールの説明 |
| endpoint_url | Text | エンドポイントURL |
| http_method | String | HTTPメソッド |
| request_template | Text | リクエストテンプレート |
| response_template | Text | レスポンステンプレート |
| auth_type | String | 認証タイプ |
| auth_config | JSON | 認証設定 |
| param_schema | JSON | パラメータスキーマ |
| enabled | Boolean | 有効/無効 |
| account_id | Integer | アカウントID |
| created_at | Integer | 作成日時（UNIX時間） |
| updated_at | Integer | 更新日時（UNIX時間） |

### 出力先

API レスポンス（JSON形式）

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ APIコントローラーがリクエストを受信
2. 認証・認可チェック
   └─ current_account確認、Captain::CustomToolポリシーによる権限確認
3. 各アクション実行
   ├─ index: 有効なツール一覧を取得
   ├─ show: 指定IDのツール詳細を取得
   ├─ create: 新規ツールを作成（slug自動生成）
   ├─ update: 既存ツールを更新
   └─ destroy: ツールを削除
4. レスポンス返却
   └─ jbuilderによるJSON整形
```

### フローチャート

```mermaid
flowchart TD
    A[リクエスト受信] --> B{認可チェック}
    B -->|失敗| C[403エラー]
    B -->|成功| D{アクション判定}
    D -->|index| E[有効ツール一覧取得]
    D -->|show| F[ツール詳細取得]
    D -->|create| G[パラメータ検証]
    D -->|update| H[既存ツール取得]
    D -->|destroy| I[ツール削除]
    G -->|有効| J[slug生成・保存]
    G -->|無効| K[422エラー]
    J --> L[レスポンス返却]
    E --> L
    F --> L
    H --> M[ツール更新]
    M --> L
    I --> N[204 No Content]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-91-01 | slug自動生成 | titleからslugを自動生成（custom_タイトル形式） | 新規作成時 |
| BR-91-02 | slug一意性保証 | 同一アカウント内でslugは一意 | 新規作成時 |
| BR-91-03 | 管理者権限必須 | 作成・更新・削除は管理者のみ可能 | create/update/destroy時 |
| BR-91-04 | 有効ツールのみ表示 | index APIは有効なツールのみ返却 | 一覧取得時 |

### 計算ロジック

slug生成ロジック：
```
1. titleをパラメータ化（スペースをアンダースコアに変換等）
2. "custom_" + パラメータ化したtitle でbase_slugを生成
3. 重複する場合は6文字のランダム英数字を追加
4. 5回試行しても一意にならない場合はエラー
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| index | captain_custom_tools | SELECT | 有効なカスタムツール一覧取得 |
| show | captain_custom_tools | SELECT | 指定IDのツール取得 |
| create | captain_custom_tools | INSERT | 新規ツール作成 |
| update | captain_custom_tools | UPDATE | ツール情報更新 |
| destroy | captain_custom_tools | DELETE | ツール削除 |

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

#### captain_custom_tools

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT (index) | * | account_id = current_account.id AND enabled = true | 有効ツールのみ |
| SELECT (show) | * | id = params[:id] AND account_id = current_account.id | - |
| INSERT | title, description, endpoint_url, http_method, ... | 入力値 | slug自動生成 |
| UPDATE | 全カラム | 入力値 | - |
| DELETE | - | id = params[:id] | 物理削除 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 403 | Forbidden | 権限不足 | 管理者権限が必要 |
| 404 | Not Found | 指定IDのツールが存在しない | 正しいIDを指定 |
| 422 | Unprocessable Entity | バリデーションエラー | 入力値を修正 |
| 422 | Unprocessable Entity | slug生成失敗（5回試行後） | タイトルを変更 |

### リトライ仕様

slug生成時に重複が発生した場合、ランダム文字列を追加して最大5回リトライする。

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

create/update/destroyは各レコード単位でトランザクション管理される（Rails標準動作）。

## パフォーマンス要件

- 一覧取得は100件以下を想定
- account_idとslugの複合ユニークインデックスによる高速検索

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

- endpoint_urlはSafeEndpointValidatableによる検証（内部ネットワークへのアクセス防止）
- auth_configには認証情報が含まれるため、APIレスポンスでの取り扱いに注意
- 管理者権限によるアクセス制御

## 備考

Enterprise Edition機能として提供される。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | custom_tool.rb | `enterprise/app/models/captain/custom_tool.rb` | カスタムツールのスキーマ定義、バリデーション、slug生成ロジック |

**読解のコツ**:
- **26-30行目**: belongs_to :accountでアカウントとの関連を定義
- **51-52行目**: http_method, auth_typeのenum定義
- **54-61行目**: バリデーション定義（slug一意性、title必須、endpoint_url必須、JSONスキーマ検証）
- **76-99行目**: slug自動生成ロジック（generate_slug, find_unique_slug）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | custom_tools_controller.rb | `enterprise/app/controllers/api/v1/accounts/captain/custom_tools_controller.rb` | APIエンドポイントの実装 |

**主要処理フロー**:
1. **3行目**: before_action で Captain::CustomTool ポリシーによる認可チェック
2. **6-8行目**: index アクション - 有効なツール一覧を取得
3. **12-14行目**: create アクション - 新規ツール作成
4. **16-18行目**: update アクション - ツール更新
5. **20-23行目**: destroy アクション - ツール削除

#### Step 3: 認可ポリシーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | custom_tool_policy.rb | `enterprise/app/policies/captain/custom_tool_policy.rb` | 権限制御ロジック |

**主要処理フロー**:
- **2-8行目**: index?, show? は true（全ユーザー許可）
- **10-20行目**: create?, update?, destroy? は administrator? チェック

#### Step 4: ビュー（JSON出力）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | _custom_tool.json.jbuilder | `enterprise/app/views/api/v1/models/captain/_custom_tool.json.jbuilder` | JSON出力フォーマット |

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

```
Api::V1::Accounts::Captain::CustomToolsController
    │
    ├─ before_action :current_account
    │      └─ Api::V1::Accounts::BaseController から継承
    │
    ├─ before_action -> { check_authorization(Captain::CustomTool) }
    │      └─ Captain::CustomToolPolicy
    │             ├─ index? / show? → true
    │             └─ create? / update? / destroy? → administrator?
    │
    ├─ index
    │      └─ Current.account.captain_custom_tools.enabled
    │
    ├─ create
    │      └─ account_custom_tools.create!(custom_tool_params)
    │             └─ Captain::CustomTool
    │                    └─ before_validation :generate_slug
    │
    ├─ update
    │      └─ @custom_tool.update!(custom_tool_params)
    │
    └─ destroy
           └─ @custom_tool.destroy
```

### データフロー図

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

HTTPリクエスト
    │
    ├─ GET /captain/custom_tools
    │       │
    │       └──▶ CustomToolsController#index
    │                    │
    │                    └──▶ captain_custom_tools.enabled ──▶ JSON配列
    │
    ├─ POST /captain/custom_tools
    │       │
    │       └──▶ CustomToolsController#create
    │                    │
    │                    ├──▶ generate_slug（モデル）
    │                    └──▶ INSERT ──▶ JSON
    │
    └─ DELETE /captain/custom_tools/:id
            │
            └──▶ CustomToolsController#destroy ──▶ DELETE ──▶ 204
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| custom_tools_controller.rb | `enterprise/app/controllers/api/v1/accounts/captain/custom_tools_controller.rb` | コントローラー | APIエンドポイント |
| custom_tool.rb | `enterprise/app/models/captain/custom_tool.rb` | モデル | データ定義・バリデーション |
| custom_tool_policy.rb | `enterprise/app/policies/captain/custom_tool_policy.rb` | ポリシー | 認可制御 |
| _custom_tool.json.jbuilder | `enterprise/app/views/api/v1/models/captain/_custom_tool.json.jbuilder` | ビュー | JSON出力 |
| index.json.jbuilder | `enterprise/app/views/api/v1/accounts/captain/custom_tools/index.json.jbuilder` | ビュー | 一覧JSON出力 |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義 |
| toolable.rb | `enterprise/app/models/concerns/toolable.rb` | Concern | ツール共通機能 |
| safe_endpoint_validatable.rb | `enterprise/app/models/concerns/safe_endpoint_validatable.rb` | Concern | エンドポイント検証 |
