# 機能設計書 85-Playground

## 概要

本ドキュメントは、Chatwoot Captain AIアシスタントのPlayground機能の設計を記載する。AIアシスタントの動作をテストするための対話型インターフェースを提供するEnterprise機能である。

### 本機能の処理概要

Playground機能は、作成したAIアシスタントの応答をリアルタイムでテストするための機能である。

**業務上の目的・背景**：AIアシスタントを本番環境に配置する前に、設定した指示やガイドラインが期待通りに動作するかを検証する必要がある。Playgroundを使用することで、実際の顧客対応に影響を与えることなく、AIの応答品質を確認・改善できる。

**機能の利用シーン**：
- 新規作成したアシスタントの動作確認
- 指示やガイドラインの調整後の動作テスト
- 特定のシナリオでのAI応答確認
- 温度パラメータ調整後の応答変化確認

**主要な処理内容**：
1. テストメッセージの送信
2. メッセージ履歴の管理
3. LLMへのリクエスト生成・送信
4. AI応答の取得・表示

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

**権限による制御**：Captain::Assistantポリシーによる権限チェック。アシスタントの閲覧・編集権限を持つユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 109 | プレイグラウンド画面 | 主画面 | アシスタントのテスト実行 |

## 機能種別

AI連携 / テスト機能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| id | Integer | Yes | アシスタントID | 存在するアシスタント |
| message_content | String | No | テストメッセージ本文 | - |
| message_history | Array | No | 過去のメッセージ履歴 | role, content構造 |
| message_history[].role | String | Yes | メッセージのロール | user/assistant |
| message_history[].content | String | Yes | メッセージ内容 | - |

### 入力データソース

- Playground画面からのAPI呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| response | String | AIアシスタントの応答テキスト |

### 出力先

- JSON APIレスポンス
- Playground画面に表示

## 処理フロー

### 処理シーケンス

```
1. Playgroundリクエスト受信
   └─ アシスタントID、メッセージ内容、履歴を取得
2. アシスタント取得
   └─ 権限チェック
3. AssistantChatService初期化
   └─ アシスタント設定読み込み
   └─ システムメッセージ生成
   └─ ツール設定
4. generate_response呼び出し
   └─ メッセージ履歴にテストメッセージ追加
   └─ LLM API呼び出し
5. レスポンス返却
   └─ JSON形式で応答
```

### フローチャート

```mermaid
flowchart TD
    A[Playground画面] --> B[POST /captain/assistants/:id/playground]
    B --> C[AssistantsController#playground]
    C --> D[set_assistant]
    D --> E{権限チェック}
    E -->|OK| F[AssistantChatService.new]
    E -->|NG| G[403 Forbidden]
    F --> H[システムメッセージ生成]
    H --> I[メッセージ履歴構築]
    I --> J[generate_response]
    J --> K[LLM API呼び出し]
    K --> L[応答取得]
    L --> M[JSON応答]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-85-01 | アシスタント存在確認 | 指定IDのアシスタントが存在すること | リクエスト時 |
| BR-85-02 | メッセージ履歴フォーマット | role + content形式のArrayであること | メッセージ履歴指定時 |
| BR-85-03 | 本番影響なし | Playgroundは会話/メッセージDBに保存しない | 常時 |
| BR-85-04 | クレジット消費 | LLM呼び出しでクレジットが消費される可能性 | 呼び出し時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| アシスタント取得 | captain_assistants | SELECT | IDでアシスタント取得 |

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

#### captain_assistants

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id | パラメータのassistant_id | 取得条件 |
| SELECT | config, name, description | - | LLM呼び出しに使用 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 403 | Forbidden | 権限がない | 管理者に連絡 |
| 404 | NotFound | アシスタントが存在しない | IDを確認 |
| 500 | InternalError | LLM API呼び出し失敗 | リトライまたは設定確認 |

### リトライ仕様

LLM API呼び出し失敗時はBaseAiServiceのエラーハンドリングに従う

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

読み取り専用操作のため、明示的なトランザクションなし

## パフォーマンス要件

- LLM APIのレスポンス時間に依存（数秒程度）
- ストリーミング対応の場合はリアルタイム応答

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

- 入力メッセージにプロンプトインジェクション対策
- アカウント境界によるアシスタントアクセス制限

## 備考

- Enterprise版機能
- Playgroundの会話はDBに保存されない（ステートレス）
- メッセージ履歴はクライアント側で管理

---

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

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

### 推奨読解順序

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

Playgroundはステートレスなため、リクエスト/レスポンスの構造を理解する。

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

**読解のコツ**:
- **66-68行目**: playground_paramsでmessage_content, message_history許可
- **70-72行目**: message_historyをrole/content形式に変換

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

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

**主要処理フロー**:
1. **26-33行目**: playgroundアクション定義
2. **27-30行目**: AssistantChatService初期化とgenerate_response呼び出し
3. **32行目**: JSON形式でレスポンス返却

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

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

**主要処理フロー**:
- **4-12行目**: initializeでシステムメッセージ、ツール初期化
- **22-26行目**: generate_responseでメッセージ履歴構築とLLM呼び出し
- **34-39行目**: system_messageでシステムプロンプト生成
- **41-43行目**: persist_messageは空実装（Playground用）

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

```
AssistantsController#playground
    │
    ├─ set_assistant
    │      └─ account_assistants.find(params[:id])
    │
    ├─ message_history (helper)
    │      └─ playground_params[:message_history]
    │              └─ role/content形式に変換
    │
    └─ Captain::Llm::AssistantChatService.new
           │
           ├─ initialize
           │      ├─ system_message生成
           │      └─ build_tools
           │              └─ SearchDocumentationService
           │
           └─ generate_response
                  ├─ メッセージ履歴追加
                  ├─ additional_message追加
                  └─ request_chat_completion
                         └─ LLM API呼び出し
```

### データフロー図

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

message_content ───▶ AssistantsController ───▶ JSON応答
message_history          │
                         └─ AssistantChatService
                                │
                                ├─ システムメッセージ
                                ├─ メッセージ履歴
                                ├─ 追加メッセージ
                                │
                                └─ LLM API ───▶ AI応答
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| assistants_controller.rb | `enterprise/app/controllers/api/v1/accounts/captain/assistants_controller.rb` | コントローラー | playgroundアクション |
| assistant_chat_service.rb | `enterprise/app/services/captain/llm/assistant_chat_service.rb` | サービス | LLM連携 |
| system_prompts_service.rb | `enterprise/app/services/captain/llm/system_prompts_service.rb` | サービス | システムプロンプト生成 |
| base_ai_service.rb | `lib/llm/base_ai_service.rb` | ライブラリ | LLM API基底クラス |
| chat_helper.rb | `enterprise/app/helpers/captain/chat_helper.rb` | ヘルパー | チャット処理ヘルパー |
