# 機能設計書 86-ツール管理

## 概要

本ドキュメントは、Chatwoot Captain AIアシスタントで利用可能なツール管理機能の設計を記載する。組み込みツールの一覧表示とカスタムツールの作成・管理を行うEnterprise機能である。

### 本機能の処理概要

ツール管理機能は、AIアシスタントが使用できるツール（外部APIコール、データ検索等）を管理する機能である。

**業務上の目的・背景**：AIアシスタントが顧客の質問に回答する際、内部データの検索やサードパーティAPIとの連携が必要になる場合がある。ツール管理機能により、組み込みの標準ツールに加えて、企業固有のカスタムツールを定義し、AIアシスタントの機能を拡張できる。

**機能の利用シーン**：
- 管理者が利用可能なツール一覧を確認する際
- カスタムHTTPエンドポイントをツールとして登録する際
- ツールの認証設定（Bearer、Basic、API Key）を行う際
- シナリオでツールを参照する際

**主要な処理内容**：
1. 組み込みツール一覧の取得
2. カスタムツールの作成（CRUD）
3. ツールの認証設定管理
4. パラメータスキーマの定義
5. リクエスト/レスポンステンプレートの設定

**関連システム・外部連携**：カスタムツール経由での外部HTTPエンドポイント連携。

**権限による制御**：Captain::Assistantポリシー（toolsアクション）、Captain::CustomToolポリシーによる権限制御。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 107 | カスタムツール一覧画面 | 主画面 | カスタムツールの一覧と管理 |

## 機能種別

CRUD操作 / 外部連携設定

## 入力仕様

### 入力パラメータ（カスタムツール作成）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| title | String | Yes | ツール名 | presence: true |
| description | Text | No | ツール説明 | - |
| endpoint_url | Text | Yes | HTTPエンドポイントURL | presence: true, URL形式 |
| http_method | String | No | HTTPメソッド | GET/POST、デフォルト: GET |
| auth_type | String | No | 認証タイプ | none/bearer/basic/api_key、デフォルト: none |
| auth_config | JSONB | No | 認証設定 | auth_typeに応じた構造 |
| param_schema | JSONB | No | パラメータスキーマ | JSONスキーマ形式 |
| request_template | Text | No | リクエストテンプレート | - |
| response_template | Text | No | レスポンステンプレート | - |
| enabled | Boolean | No | 有効/無効 | デフォルト: true |

### 入力データソース

- 管理画面からのAPI呼び出し

## 出力仕様

### 出力データ（組み込みツール一覧）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | String | ツールID |
| title | String | ツール名 |
| description | String | ツール説明 |
| custom | Boolean | カスタムツールフラグ（false） |

### 出力データ（カスタムツール）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | BigInt | レコードID |
| slug | String | スラッグ（一意識別子） |
| title | String | ツール名 |
| description | Text | ツール説明 |
| endpoint_url | Text | HTTPエンドポイントURL |
| http_method | String | HTTPメソッド |
| auth_type | String | 認証タイプ |
| param_schema | JSONB | パラメータスキーマ |
| enabled | Boolean | 有効/無効 |

### 出力先

- JSON APIレスポンス

## 処理フロー

### 処理シーケンス

```
1. ツール一覧取得（tools アクション）
   └─ 新規Assistantインスタンス作成
   └─ available_agent_tools呼び出し
   └─ 組み込みツール + カスタムツールをマージ
2. カスタムツール作成（CustomToolsController#create）
   └─ パラメータ検証
   └─ スラッグ自動生成
   └─ captain_custom_toolsテーブルにINSERT
```

### フローチャート

```mermaid
flowchart TD
    A[ツール一覧画面] --> B[GET /captain/assistants/tools]
    B --> C[AssistantsController#tools]
    C --> D[Captain::Assistant.new]
    D --> E[available_agent_tools]
    E --> F[組み込みツール取得]
    E --> G[カスタムツール取得]
    F --> H[マージ]
    G --> H
    H --> I[JSON応答]

    J[カスタムツール作成] --> K[POST /captain/custom_tools]
    K --> L[CustomToolsController#create]
    L --> M{権限チェック}
    M -->|OK| N[custom_tool_params検証]
    M -->|NG| O[403 Forbidden]
    N --> P[スラッグ生成]
    P --> Q[Captain::CustomTool.create!]
    Q --> R[JSON応答]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-86-01 | スラッグ自動生成 | titleからスラッグを自動生成（custom_接頭辞） | 作成時 |
| BR-86-02 | スラッグ一意性 | account_id + slugの組み合わせで一意 | 作成・更新時 |
| BR-86-03 | パラメータスキーマ検証 | JSON Schema形式で検証 | 作成・更新時 |
| BR-86-04 | 有効ツールのみ | enabledがtrueのツールのみアシスタントで利用可能 | ツール取得時 |
| BR-86-05 | 認証タイプ制限 | none, bearer, basic, api_keyのいずれか | 作成・更新時 |
| BR-86-06 | HTTPメソッド制限 | GET, POSTのいずれか | 作成・更新時 |

### 計算ロジック

**スラッグ生成ロジック**:
```
base_slug = "custom_" + title.parameterize(separator: "_")
if slug_exists?(base_slug):
    slug = base_slug + "_" + random_alphanumeric(6)
else:
    slug = base_slug
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 一覧取得 | captain_custom_tools | SELECT | 有効なカスタムツール取得 |
| 作成 | captain_custom_tools | INSERT | 新規レコード作成 |
| 更新 | captain_custom_tools | UPDATE | レコード更新 |
| 削除 | captain_custom_tools | DELETE | レコード削除 |

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

#### captain_custom_tools

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | account_id, enabled | Current.account.id, true | 有効ツール取得 |
| INSERT | slug | 自動生成 | custom_プレフィックス |
| INSERT | title | ユーザー入力 | 必須 |
| INSERT | endpoint_url | ユーザー入力 | 必須、安全URL検証 |
| INSERT | http_method | GET/POST | デフォルト: GET |
| INSERT | auth_type | none/bearer/basic/api_key | デフォルト: none |
| INSERT | auth_config | JSONB | 認証設定 |
| INSERT | param_schema | JSONB | パラメータ定義 |
| INSERT | enabled | Boolean | デフォルト: true |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 403 | Forbidden | 権限がない | 管理者に連絡 |
| 422 | ValidationError | バリデーションエラー | 入力内容を確認 |
| 422 | RecordNotUnique | スラッグ生成失敗 | リトライまたはtitle変更 |

### リトライ仕様

スラッグ生成で衝突が発生した場合、ランダム文字列付きスラッグで最大5回リトライ

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

単一レコード操作のため、暗黙的トランザクション

## パフォーマンス要件

- ツール一覧取得はアシスタント設定画面で頻繁に呼び出されるため高速であること
- enabledスコープとインデックスによる最適化

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

- SafeEndpointValidatableによるエンドポイントURL検証
- auth_configの機密情報は適切に保護
- 内部ネットワークへのアクセス制限

## 備考

- Enterprise版機能
- 組み込みツールはCaptainToolsHelpers concernで定義
- カスタムツールはToolableでツールインターフェース実装

---

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

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

### 推奨読解順序

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

まず、カスタムツールのデータモデルを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | custom_tool.rb | `enterprise/app/models/captain/custom_tool.rb` | モデル定義、バリデーション |

**読解のコツ**:
- **30-32行目**: テーブル名、定数定義
- **49-52行目**: http_method, auth_type enumの定義
- **54行目**: before_validationでスラッグ自動生成
- **56-61行目**: バリデーション（slug一意性、param_schemaスキーマ検証）
- **65-72行目**: to_tool_metadataでツールメタデータ形式に変換
- **76-99行目**: スラッグ生成ロジック（衝突時のリトライ含む）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | assistants_controller.rb | `enterprise/app/controllers/api/v1/accounts/captain/assistants_controller.rb` | toolsアクション |
| 2-2 | custom_tools_controller.rb | `enterprise/app/controllers/api/v1/accounts/captain/custom_tools_controller.rb` | カスタムツールCRUD |

**主要処理フロー（toolsアクション）**:
- **35-38行目**: Captain::Assistant.newで一時インスタンス作成
- available_agent_toolsで組み込み+カスタムツール取得

**主要処理フロー（CustomToolsController）**:
- **6-8行目**: indexで有効なカスタムツール取得
- **12-14行目**: createでツール作成
- **35-48行目**: custom_tool_paramsでパラメータ許可

#### Step 3: ツール定義の仕組みを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | assistant.rb | `enterprise/app/models/captain/assistant.rb` | available_agent_tools |

**主要処理フロー**:
- **53-59行目**: 組み込みツールとカスタムツールをマージ

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

```
AssistantsController#tools
    │
    └─ Captain::Assistant.new(account: Current.account)
           │
           └─ available_agent_tools
                  │
                  ├─ self.class.built_in_agent_tools.dup
                  │      └─ CaptainToolsHelpers で定義
                  │
                  └─ account.captain_custom_tools.enabled
                         │
                         └─ to_tool_metadata
                                └─ {id: slug, title, description, custom: true}

CustomToolsController
    │
    ├─ index
    │      └─ account_custom_tools.enabled
    │
    ├─ create
    │      └─ account_custom_tools.create!(custom_tool_params)
    │              └─ before_validation: generate_slug
    │
    └─ update/destroy
           └─ 標準CRUD
```

### データフロー図

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

custom_tool_params ───▶ CustomToolsController ───▶ Captain::CustomTool
                              │                        │
                              ├─ スラッグ生成            ├─ DB保存
                              │                        │
                              └─ バリデーション          └─ JSON応答

tools request ───▶ AssistantsController#tools ───▶ ツール一覧
                              │
                              ├─ 組み込みツール
                              └─ カスタムツール
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| assistants_controller.rb | `enterprise/app/controllers/api/v1/accounts/captain/assistants_controller.rb` | コントローラー | toolsアクション |
| custom_tools_controller.rb | `enterprise/app/controllers/api/v1/accounts/captain/custom_tools_controller.rb` | コントローラー | カスタムツールCRUD |
| custom_tool.rb | `enterprise/app/models/captain/custom_tool.rb` | モデル | カスタムツールモデル |
| assistant.rb | `enterprise/app/models/captain/assistant.rb` | モデル | available_agent_tools |
| captain_tools_helpers.rb | `app/models/concerns/captain_tools_helpers.rb` | Concern | 組み込みツール定義 |
| toolable.rb | `app/models/concerns/toolable.rb` | Concern | ツールインターフェース |
| safe_endpoint_validatable.rb | `app/models/concerns/safe_endpoint_validatable.rb` | Concern | URLセキュリティ検証 |
