# 画面設計書 107-カスタムツール一覧画面

## 概要

Captain AIアシスタントが使用するカスタムツールを管理するための一覧画面設計書です。外部APIやWebhookを呼び出すカスタムツールの作成、編集、削除機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：Captain AIアシスタントは会話中に外部システムと連携するためのカスタムツールを使用できます。例えば、CRMシステムから顧客情報を取得したり、外部APIで注文状況を確認したりすることが可能です。この画面では、そのようなカスタムツールを定義・管理し、AIアシスタントの機能を拡張します。

**画面へのアクセス方法**：Captain機能のサイドナビゲーションから「Tools」を選択してアクセスします。URLパスは `/app/accounts/:accountId/captain/:assistantId/tools` です。

**主要な操作・処理内容**：
1. カスタムツール一覧の表示（ページネーション対応）
2. 新規カスタムツールの作成
3. 既存カスタムツールの編集
4. カスタムツールの削除

**画面遷移**：
- 遷移元：Captainアシスタント一覧画面、サイドナビゲーション
- 遷移先：作成/編集ダイアログ（モーダル）、削除確認ダイアログ（モーダル）

**権限による表示制御**：administrator および agent ロールがアクセス可能です。CAPTAIN_V2フィーチャーフラグが有効で、CloudまたはEnterpriseインストールタイプの場合のみ利用可能です。新規作成ボタンはadministratorのみ表示されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 91 | カスタムツール | 主機能 | カスタムツールの一覧表示、CRUD操作 |

## 画面種別

一覧 / 登録（ダイアログ） / 編集（ダイアログ）

## URL/ルーティング

| パス | ルート名 |
|------|----------|
| `/app/accounts/:accountId/captain/:assistantId/tools` | `captain_tools_index` |

## 入出力項目

### カスタムツール作成/編集フォーム

| 項目名 | 物理名 | 型 | 必須 | バリデーション | 備考 |
|--------|--------|-----|------|---------------|------|
| タイトル | title | string | Yes | 必須 | ツール名 |
| 説明 | description | string | Yes | 必須 | ツールの説明 |
| エンドポイントURL | endpoint_url | string | Yes | URL形式 | APIエンドポイント |
| HTTPメソッド | http_method | string | Yes | GET/POST/PUT/DELETE | リクエストメソッド |
| 認証タイプ | auth_type | string | No | - | 認証方式 |
| パラメータスキーマ | param_schema | object | No | JSON形式 | リクエストパラメータ定義 |
| 有効/無効 | enabled | boolean | No | - | ツールの有効状態 |

### 出力項目（一覧）

| 項目名 | 物理名 | 型 | 備考 |
|--------|--------|-----|------|
| ツールID | id | number | 内部識別子 |
| タイトル | title | string | ツール名 |
| 説明 | description | string | ツールの説明 |
| エンドポイントURL | endpoint_url | string | APIエンドポイント |
| HTTPメソッド | http_method | string | GET/POST/PUT/DELETE |
| 認証タイプ | auth_type | string | 認証方式 |
| パラメータスキーマ | param_schema | object | パラメータ定義 |
| 有効状態 | enabled | boolean | 有効/無効 |
| 作成日時 | created_at | datetime | 作成日時 |
| 更新日時 | updated_at | datetime | 更新日時 |

## 表示項目

### ヘッダー領域

| 項目名 | 表示形式 | 備考 |
|--------|----------|------|
| タイトル | "Custom Tools" | ヘッダータイトル |
| Add newボタン | プライマリボタン | administratorのみ表示 |

### カスタムツールカード

| 項目名 | 表示形式 | 備考 |
|--------|----------|------|
| タイトル | テキスト（太字） | ツール名 |
| 説明 | テキスト | ツールの説明 |
| エンドポイントURL | テキスト | APIエンドポイント表示 |
| HTTPメソッド | バッジ | メソッド表示 |
| 認証タイプ | バッジ | 認証方式表示 |
| 有効状態 | トグルまたはバッジ | 有効/無効表示 |
| 作成/更新日時 | 相対日時 | フォーマット済み |
| アクションメニュー | ドロップダウン | 編集/削除 |

### ページネーション

| 項目名 | 表示形式 | 備考 |
|--------|----------|------|
| 現在ページ | テキスト | ページ番号表示 |
| 総件数 | テキスト | 総レコード数 |
| ページ送りボタン | ボタン群 | 前後ナビゲーション |

## イベント仕様

### 1-カスタムツール作成

1. 「Add new」ボタンをクリック
2. `openCreateDialog()` が呼び出される
3. `dialogType` を 'create' に設定
4. `CreateCustomToolDialog` がモーダル表示される
5. フォーム入力後、Submit時に `captainCustomTools/create` アクションが dispatch される
6. API成功時：成功メッセージ表示、ダイアログクローズ、一覧更新
7. API失敗時：エラーメッセージ表示

### 2-カスタムツール編集

1. ツールカードのメニューから「Edit」を選択
2. `handleAction({action: 'edit', id})` が呼び出される
3. `handleEdit(tool)` で `dialogType` を 'edit' に設定、`selectedTool` をセット
4. `CreateCustomToolDialog` が編集モードで表示される

### 3-カスタムツール削除

1. ツールカードのメニューから「Delete」を選択
2. `handleAction({action: 'delete', id})` が呼び出される
3. `handleDelete(tool)` で `DeleteDialog` を表示
4. 確認後、`captainCustomTools/delete` アクションが dispatch される
5. API成功時：一覧から削除、必要に応じてページ調整

### 4-ページ遷移

1. ページネーションボタンをクリック
2. `onPageChange(page)` が呼び出される
3. `fetchCustomTools(page)` でデータ取得

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ツール一覧取得 | captain_custom_tools | SELECT | カスタムツール取得 |
| ツール作成 | captain_custom_tools | INSERT | 新規ツール作成 |
| ツール編集 | captain_custom_tools | UPDATE | ツール情報更新 |
| ツール削除 | captain_custom_tools | DELETE | ツール削除 |

### テーブル別更新項目詳細

#### captain_custom_tools

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | - | `account_id = current_account.id` | 一覧取得条件 |
| INSERT | title, description, endpoint_url, http_method, auth_type, param_schema, enabled | フォーム入力値 | 新規作成 |
| UPDATE | title, description, endpoint_url, http_method, auth_type, param_schema, enabled | フォーム入力値 | 編集 |
| DELETE | - | `id = :toolId` | 指定ID削除 |

## メッセージ仕様

| 種別 | メッセージキー | メッセージ内容 |
|------|---------------|---------------|
| 成功 | CAPTAIN.CUSTOM_TOOLS.CREATE.SUCCESS_MESSAGE | ツール作成成功 |
| エラー | CAPTAIN.CUSTOM_TOOLS.CREATE.ERROR_MESSAGE | ツール作成失敗 |
| 成功 | CAPTAIN.CUSTOM_TOOLS.EDIT.SUCCESS_MESSAGE | ツール編集成功 |
| エラー | CAPTAIN.CUSTOM_TOOLS.EDIT.ERROR_MESSAGE | ツール編集失敗 |
| 成功 | CAPTAIN.CUSTOM_TOOLS.DELETE.SUCCESS_MESSAGE | ツール削除成功 |
| エラー | CAPTAIN.CUSTOM_TOOLS.DELETE.ERROR_MESSAGE | ツール削除失敗 |

## 例外処理

| 例外条件 | 処理内容 | 表示 |
|----------|----------|------|
| データ取得中 | isFetchingフラグでローディング表示 | Spinner |
| ツール0件 | 空状態表示 | CustomToolsPageEmptyState |
| API通信エラー | アラート表示 | エラーメッセージ |
| 最後の1件削除後 | 前のページに遷移 | 自動ページ調整 |
| Captain未有効 | Paywallコンポーネント表示 | アップグレード案内 |

## 備考

- CAPTAIN_V2フィーチャーフラグが必要（V2専用機能）
- カスタムツールはシナリオで参照される
- 認証タイプには Bearer、API Key などが設定可能
- param_schema はJSON Schemaフォーマットで定義

---

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

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

### 推奨読解順序

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

まず、カスタムツールデータの構造とストアの状態管理を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | customTools.js (store) | `app/javascript/dashboard/store/captain/customTools.js` | ストア定義、カスタムのupdate/deleteアクションを確認 |
| 1-2 | customTools.js (api) | `app/javascript/dashboard/api/captain/customTools.js` | APIクライアント、CRUD操作を確認 |

**読解のコツ**: `createStore` ベースですが、`update` と `delete` アクションはカスタム実装されています（9-34行目）。

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

処理の起点となるVueコンポーネントを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Index.vue (tools) | `app/javascript/dashboard/routes/dashboard/captain/tools/Index.vue` | メインコンポーネントの構造を確認 |

**主要処理フロー**:
1. **15-18行目**: ストアゲッターの取得
2. **25-27行目**: `fetchCustomTools()` でデータ取得
3. **31-35行目**: `openCreateDialog()` で作成ダイアログ表示
4. **37-46行目**: `handleEdit()`、`handleDelete()` で編集/削除処理
5. **48-55行目**: `handleAction()` でアクション振り分け
6. **62-72行目**: `onDeleteSuccess()` で削除後処理

#### Step 3: フォームダイアログを理解する

カスタムツール作成/編集フォームの実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CreateCustomToolDialog.vue | `app/javascript/dashboard/components-next/captain/pageComponents/customTool/CreateCustomToolDialog.vue` | フォーム項目とバリデーションを確認 |

#### Step 4: API通信層を理解する

バックエンドとの通信処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | customTools.js (api) | `app/javascript/dashboard/api/captain/customTools.js` | CRUDメソッドの実装を確認 |

**主要処理フロー**:
- **5行目**: `captain/custom_tools` エンドポイント
- **19-22行目**: `create` メソッドでcustom_toolラッパー使用
- **24-28行目**: `update` メソッドも同様

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

```
Index.vue (tools)
    |
    +-- PageLayout.vue
    |       |
    |       +-- ヘッダー、ボタン、ページネーション
    |       +-- feature-flag: CAPTAIN_V2
    |
    +-- CustomToolCard.vue (複数)
    |       |
    |       +-- @action -> handleAction()
    |
    +-- CreateCustomToolDialog.vue
    |       |
    |       +-- 作成/編集フォーム
    |       +-- captainCustomTools/create or update
    |
    +-- DeleteDialog.vue
            |
            +-- 削除確認
            +-- captainCustomTools/delete
```

### データフロー図

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

URLアクセス ──────────▶ onMounted
                              │
                              └── fetchCustomTools()
                                      │
                                      ▼
                        GET /api/v1/.../captain/custom_tools
                              │
                              ▼
                        Vuex State更新
                              │
                              ▼
                        CustomToolCard描画 ────────▶ ツール一覧

作成ボタン ────────────▶ openCreateDialog()
                              │
                              ▼
                        CreateCustomToolDialog
                              │
                              ▼
                        captainCustomTools/create
                              │
                              ▼
                        POST /api/v1/.../captain/custom_tools
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Index.vue | `app/javascript/dashboard/routes/dashboard/captain/tools/Index.vue` | ソース | メイン画面コンポーネント |
| captain.routes.js | `app/javascript/dashboard/routes/dashboard/captain/captain.routes.js` | 設定 | ルーティング定義 |
| customTools.js (store) | `app/javascript/dashboard/store/captain/customTools.js` | ソース | Vuexストアモジュール |
| customTools.js (api) | `app/javascript/dashboard/api/captain/customTools.js` | ソース | APIクライアント |
| CustomToolCard.vue | `app/javascript/dashboard/components-next/captain/pageComponents/customTool/CustomToolCard.vue` | ソース | ツールカード |
| CreateCustomToolDialog.vue | `app/javascript/dashboard/components-next/captain/pageComponents/customTool/CreateCustomToolDialog.vue` | ソース | 作成/編集ダイアログ |
| CustomToolsPageEmptyState.vue | `app/javascript/dashboard/components-next/captain/pageComponents/emptyStates/CustomToolsPageEmptyState.vue` | ソース | 空状態表示 |
| DeleteDialog.vue | `app/javascript/dashboard/components-next/captain/pageComponents/DeleteDialog.vue` | ソース | 削除確認ダイアログ |
