# 機能設計書 84-AIアシスタント

## 概要

本ドキュメントは、Chatwoot Captain AIアシスタント機能の設計を記載する。LLMを活用した会話支援アシスタントの作成・管理・運用を行うEnterprise機能である。

### 本機能の処理概要

AIアシスタント機能は、顧客対応を自動化するAIエージェントの作成・管理を行う機能である。

**業務上の目的・背景**：カスタマーサポート業務において、頻出する質問への自動回答、FAQに基づく情報提供、会話のハンドオフなどを自動化することで、エージェントの負担軽減と24時間対応を実現する必要がある。

**機能の利用シーン**：
- 管理者がAIアシスタントを新規作成する際
- アシスタントの名前、説明、設定を編集する際
- アシスタントをインボックスに配置する際
- レスポンスガイドラインやガードレールを設定する際

**主要な処理内容**：
1. AIアシスタントの作成（名前、説明、設定）
2. アシスタントの設定更新（温度、FAQモード、メモリ機能等）
3. レスポンスガイドライン・ガードレールの設定
4. ドキュメント・シナリオとの関連付け
5. インボックスへの配置管理

**関連システム・外部連携**：LLMプロバイダー（OpenAI等）、Captain Documents、Captain Scenarios、Inboxとの連携。

**権限による制御**：Captain::Assistantポリシーによる権限チェック。通常はadministrator権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 102 | Captainアシスタント一覧 | 主画面 | アシスタント一覧表示 |
| 103 | アシスタント作成画面 | 主画面 | 新規アシスタント作成 |
| 111 | アシスタント設定画面 | 主画面 | アシスタント詳細設定 |
| 112 | ガードレール設定画面 | 参照画面 | ガードレール設定 |
| 113 | ガイドライン設定画面 | 参照画面 | レスポンスガイドライン設定 |

## 機能種別

CRUD操作 / AI連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | String | Yes | アシスタント名 | presence: true |
| description | String | Yes | アシスタント説明 | presence: true |
| config.product_name | String | No | 製品名 | - |
| config.feature_faq | Boolean | No | FAQ機能有効化 | - |
| config.feature_memory | Boolean | No | メモリ機能有効化 | - |
| config.feature_citation | Boolean | No | 引用機能有効化 | - |
| config.welcome_message | String | No | ウェルカムメッセージ | - |
| config.handoff_message | String | No | ハンドオフ時メッセージ | - |
| config.resolution_message | String | No | 解決時メッセージ | - |
| config.instructions | String | No | AIへの指示 | - |
| config.temperature | Float | No | 応答の温度パラメータ | 0.0-1.0 |
| response_guidelines | Array | No | レスポンスガイドライン | - |
| guardrails | Array | No | ガードレール設定 | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | BigInt | アシスタントID |
| name | String | アシスタント名 |
| description | String | アシスタント説明 |
| config | JSONB | 設定情報 |
| response_guidelines | JSONB | レスポンスガイドライン |
| guardrails | JSONB | ガードレール設定 |
| avatar_url | String | アバター画像URL |
| created_at | DateTime | 作成日時 |
| updated_at | DateTime | 更新日時 |

### 出力先

- JSON APIレスポンス
- WebSocket経由でフロントエンドに配信（変更時）

## 処理フロー

### 処理シーケンス

```
1. アシスタント一覧取得（index）
   └─ アカウントに紐付くアシスタントを作成日時降順で取得
2. アシスタント作成（create）
   └─ パラメータ検証
   └─ captain_assistantsテーブルにINSERT
3. アシスタント更新（update）
   └─ パラメータ検証
   └─ レコード更新
4. アシスタント削除（destroy）
   └─ 関連レコード（documents, scenarios等）も削除
```

### フローチャート

```mermaid
flowchart TD
    A[アシスタント一覧画面] --> B[GET /captain/assistants]
    B --> C[AssistantsController#index]
    C --> D[account_assistants.ordered取得]
    D --> E[JSON応答]

    F[アシスタント作成] --> G[POST /captain/assistants]
    G --> H[AssistantsController#create]
    H --> I{権限チェック}
    I -->|OK| J[assistant_params検証]
    I -->|NG| K[403 Forbidden]
    J --> L[Captain::Assistant.create!]
    L --> M[JSON応答]

    N[アシスタント削除] --> O[DELETE /captain/assistants/:id]
    O --> P[AssistantsController#destroy]
    P --> Q[assistant.destroy]
    Q --> R[関連レコード非同期削除]
    R --> S[204 No Content]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-84-01 | 名前必須 | アシスタント名は必須 | 作成・更新時 |
| BR-84-02 | 説明必須 | アシスタント説明は必須 | 作成・更新時 |
| BR-84-03 | アカウント紐付け | アシスタントは必ずアカウントに紐付く | 作成時 |
| BR-84-04 | 配列パラメータ | response_guidelines/guardrailsは部分更新対応 | 更新時 |
| BR-84-05 | 非同期削除 | 関連レコードは非同期で削除 | 削除時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 一覧取得 | captain_assistants | SELECT | アカウント紐付けで取得 |
| 作成 | captain_assistants | INSERT | 新規レコード作成 |
| 更新 | captain_assistants | UPDATE | レコード更新 |
| 削除 | captain_assistants | DELETE | レコード削除 |
| 削除 | captain_documents | DELETE | 関連ドキュメント削除（非同期） |
| 削除 | captain_scenarios | DELETE | 関連シナリオ削除（非同期） |
| 削除 | captain_inboxes | DELETE | インボックス関連削除（非同期） |

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

#### captain_assistants

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | account_id | Current.account.id | アカウント条件 |
| INSERT | name | ユーザー入力 | 必須 |
| INSERT | description | ユーザー入力 | 必須 |
| INSERT | config | JSONB | 設定情報 |
| INSERT | response_guidelines | JSONB | 配列 |
| INSERT | guardrails | JSONB | 配列 |
| INSERT | account_id | Current.account.id | 自動設定 |
| UPDATE | config, response_guidelines, guardrails | 更新値 | 部分更新対応 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 403 | Forbidden | 権限がない | 管理者に連絡 |
| 404 | NotFound | アシスタントが存在しない | IDを確認 |
| 422 | ValidationError | バリデーションエラー | 入力内容を確認 |

### リトライ仕様

該当なし

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

単一レコード操作のため、暗黙的トランザクション。削除時の関連レコードは非同期ジョブで処理。

## パフォーマンス要件

- 一覧取得はページネーションなしで全件取得（アシスタント数は限定的想定）
- orderedスコープで作成日時降順ソート

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

- Captain::Assistantポリシーによる権限制御
- アカウント境界による分離
- config内の機密情報は制限

## 備考

- Enterprise版機能
- Avatarableによるアバター管理対応
- 関連レコードはdestroy_asyncで非同期削除

---

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

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

### 推奨読解順序

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

まず、AIアシスタントのデータモデルを理解する。

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

**読解のコツ**:
- **19-37行目**: 関連定義（documents, responses, inboxes, scenarios等）
- **39行目**: store_accessorでconfigカラムのアクセサ定義
- **41-43行目**: バリデーション（name, description必須）
- **45-47行目**: スコープ定義（ordered, for_account）
- **53-64行目**: available_agent_toolsで利用可能なツール取得

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

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

**主要処理フロー**:
1. **7-9行目**: indexアクションでorderedスコープ使用
2. **13-15行目**: createアクションでassistant_params使用
3. **17-19行目**: updateアクションでパラメータ更新
4. **21-24行目**: destroyアクションで削除
5. **26-33行目**: playgroundアクションでテスト実行
6. **35-38行目**: toolsアクションで利用可能ツール取得
7. **50-64行目**: assistant_paramsでpermit処理（配列パラメータの特別処理）

#### Step 3: AIサービスとの連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | assistant_chat_service.rb | `enterprise/app/services/captain/llm/assistant_chat_service.rb` | LLM連携 |

**主要処理フロー**:
- **4-12行目**: initializeでシステムメッセージとツール初期化
- **22-26行目**: generate_responseでLLM呼び出し
- **30-32行目**: build_toolsでSearchDocumentationService設定
- **34-39行目**: system_messageでシステムプロンプト生成

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

```
AssistantsController
    │
    ├─ index
    │      └─ Captain::Assistant.for_account.ordered
    │
    ├─ create
    │      └─ account_assistants.create!(assistant_params)
    │
    ├─ update
    │      └─ @assistant.update!(assistant_params)
    │
    ├─ destroy
    │      └─ @assistant.destroy
    │              └─ dependent: :destroy_async
    │                      ├─ documents
    │                      ├─ responses
    │                      ├─ captain_inboxes
    │                      └─ scenarios
    │
    ├─ playground
    │      └─ Captain::Llm::AssistantChatService.new
    │              └─ generate_response
    │
    └─ tools
           └─ assistant.available_agent_tools
                   ├─ built_in_agent_tools
                   └─ account.captain_custom_tools
```

### データフロー図

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

assistant_params ───▶ AssistantsController ───▶ Captain::Assistant
                              │                        │
                              ├─ バリデーション          ├─ DB保存
                              │                        │
                              └─ 権限チェック            └─ JSON応答

playground request ───▶ AssistantChatService ───▶ LLM応答
                              │
                              └─ LLM API呼び出し
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| assistants_controller.rb | `enterprise/app/controllers/api/v1/accounts/captain/assistants_controller.rb` | コントローラー | CRUD API |
| assistant.rb | `enterprise/app/models/captain/assistant.rb` | モデル | データモデル定義 |
| assistant_chat_service.rb | `enterprise/app/services/captain/llm/assistant_chat_service.rb` | サービス | LLM連携 |
| assistant_policy.rb | `enterprise/app/policies/captain/assistant_policy.rb` | ポリシー | 権限制御 |
| captain_tools_helpers.rb | `app/models/concerns/captain_tools_helpers.rb` | Concern | ツール管理ヘルパー |
| agentable.rb | `app/models/concerns/agentable.rb` | Concern | エージェント機能 |
