# 機能設計書 83-キャプテン設定

## 概要

本ドキュメントは、Chatwoot Captain（AI機能）の設定管理機能の設計を記載する。LLMプロバイダー、モデル選択、各種AI機能の有効/無効を管理する機能である。

### 本機能の処理概要

キャプテン設定機能は、Chatwootに統合されたAI機能（Captain）の全体的な設定を管理する機能である。

**業務上の目的・背景**：企業がAI機能を活用してカスタマーサポートを効率化する際、利用するLLMプロバイダーやモデルを選択し、各AI機能（エディター補助、アシスタント、Copilot、ラベル提案、音声文字起こし、ヘルプセンター検索）の有効/無効を制御する必要がある。

**機能の利用シーン**：
- 管理者がアカウントでAI機能を有効化する際
- 使用するLLMモデルを変更する際
- 特定のAI機能のみを有効/無効化する際
- AI機能の利用状況を確認する際

**主要な処理内容**：
1. 利用可能なLLMプロバイダー・モデル一覧の取得
2. 各AI機能の現在の設定状態の取得
3. アカウント固有のモデル選択の保存
4. 各AI機能の有効/無効設定の保存

**関連システム・外部連携**：LLMプロバイダー（OpenAI等）との連携設定、config/llm.yml設定ファイルとの連携が行われる。

**権限による制御**：アカウント更新権限（administrator）を持つユーザーのみが設定変更可能。設定閲覧は認証済みユーザーが可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 88 | Captain設定画面 | 主画面 | Captain AIの設定管理 |

## 機能種別

設定管理 / CRUD操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| captain_models | Hash | No | 機能別モデル選択 | 有効なモデル名 |
| captain_models.editor | String | No | エディター用モデル | llm.ymlで定義済みモデル |
| captain_models.assistant | String | No | アシスタント用モデル | llm.ymlで定義済みモデル |
| captain_models.copilot | String | No | Copilot用モデル | llm.ymlで定義済みモデル |
| captain_models.label_suggestion | String | No | ラベル提案用モデル | llm.ymlで定義済みモデル |
| captain_models.audio_transcription | String | No | 音声文字起こし用モデル | llm.ymlで定義済みモデル |
| captain_models.help_center_search | String | No | ヘルプセンター検索用モデル | llm.ymlで定義済みモデル |
| captain_features | Hash | No | 機能別有効/無効 | boolean値 |
| captain_features.editor | Boolean | No | エディター有効/無効 | true/false |
| captain_features.assistant | Boolean | No | アシスタント有効/無効 | true/false |
| captain_features.copilot | Boolean | No | Copilot有効/無効 | true/false |
| captain_features.label_suggestion | Boolean | No | ラベル提案有効/無効 | true/false |
| captain_features.audio_transcription | Boolean | No | 音声文字起こし有効/無効 | true/false |
| captain_features.help_center_search | Boolean | No | ヘルプセンター検索有効/無効 | true/false |

### 入力データソース

- 設定画面からのAPI呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| providers | Array | 利用可能なLLMプロバイダー一覧 |
| models | Hash | 利用可能なモデル情報 |
| features | Hash | 機能別設定情報（有効状態、選択モデル、デフォルト等） |

### 出力先

- JSON APIレスポンス

## 処理フロー

### 処理シーケンス

```
1. 設定取得リクエスト（show）
   └─ Llm::Modelsからプロバイダー・モデル情報取得
   └─ アカウント設定とマージした機能設定取得
2. 設定更新リクエスト（update）
   └─ パラメータのpermit処理
   └─ 既存設定とマージ
   └─ アカウントレコード更新
   └─ 更新後の設定情報返却
```

### フローチャート

```mermaid
flowchart TD
    A[設定画面表示] --> B[GET /captain/preferences]
    B --> C[PreferencesController#show]
    C --> D[Llm::Models.providers取得]
    C --> E[Llm::Models.models取得]
    C --> F[features_with_account_preferences取得]
    D --> G[JSON応答]
    E --> G
    F --> G

    H[設定保存] --> I[PATCH /captain/preferences]
    I --> J[PreferencesController#update]
    J --> K{権限チェック}
    K -->|OK| L[既存設定とマージ]
    K -->|NG| M[403 Forbidden]
    L --> N[account.save!]
    N --> O[更新後設定を返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-83-01 | モデル検証 | 選択モデルはllm.ymlで定義されたものに限定 | 設定更新時 |
| BR-83-02 | 設定マージ | 既存設定と新規設定をマージ（部分更新対応） | 設定更新時 |
| BR-83-03 | デフォルト値 | 未設定の機能はllm.ymlのデフォルト値を使用 | 設定取得時 |
| BR-83-04 | 機能有効化 | captain_features[key] == trueの場合のみ有効 | 機能利用時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 設定取得 | accounts | SELECT | captain_models, captain_features取得 |
| 設定更新 | accounts | UPDATE | captain_models, captain_features更新 |

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

#### accounts

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | captain_models | JSONB | モデル選択設定 |
| SELECT | captain_features | JSONB | 機能有効/無効設定 |
| UPDATE | captain_models | マージ後のHash | 既存設定を保持しつつ更新 |
| UPDATE | captain_features | マージ後のHash | 既存設定を保持しつつ更新 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 403 | Forbidden | 更新権限がない | 管理者に連絡 |
| 422 | ValidationError | 無効なモデル名指定 | 有効なモデル名を選択 |

### リトライ仕様

該当なし

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

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

## パフォーマンス要件

- 設定画面表示時に呼び出されるため、高速なレスポンスが必要
- llm.ymlはアプリ起動時にロード済み

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

- 管理者権限によるアクセス制御
- APIキー等の機密情報は本APIでは扱わない

## 備考

- LLM設定はconfig/llm.ymlで一元管理
- Enterprise版機能の可能性あり

---

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

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

### 推奨読解順序

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

まず、LLMモデル設定の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.rb | `lib/llm/models.rb` | LLM設定のモジュール定義 |
| 1-2 | captain_featurable.rb | `app/models/concerns/captain_featurable.rb` | アカウントへのCaptain機能追加 |

**読解のコツ**:
- Llm::ModelsはYAML設定をラップするモジュール
- CaptainFeaturableはAccountモデルにincludeされるconcern
- 動的に定義されるメソッド（captain_#{feature_key}_enabled?等）に注目

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | preferences_controller.rb | `app/controllers/api/v1/accounts/captain/preferences_controller.rb` | API制御ロジック |

**主要処理フロー**:
1. **5-7行目**: showアクションでpreferences_payload返却
2. **9-16行目**: updateアクションで設定保存
3. **20-26行目**: preferences_payloadでプロバイダー・モデル・機能情報を構築
4. **39-47行目**: 既存設定とマージするロジック
5. **63-75行目**: features_with_account_preferencesで各機能の詳細設定を生成

#### Step 3: Accountモデルとの連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | captain_featurable.rb | `app/models/concerns/captain_featurable.rb` | 動的メソッド定義 |

**主要処理フロー**:
- **10-20行目**: feature_keysから動的にenabled?/modelメソッドを定義
- **23-28行目**: captain_preferencesで現在の設定を返却
- **32-42行目**: デフォルト値とのマージロジック
- **51-60行目**: モデル検証ロジック

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

```
PreferencesController
    │
    ├─ show
    │      └─ preferences_payload
    │              ├─ Llm::Models.providers
    │              ├─ Llm::Models.models
    │              └─ features_with_account_preferences
    │                      └─ Current.account.captain_preferences
    │                              └─ CaptainFeaturable#captain_preferences
    │
    └─ update
           ├─ captain_params
           │      ├─ merged_captain_models
           │      └─ merged_captain_features
           └─ @current_account.save!
```

### データフロー図

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

config/llm.yml ───▶ Llm::Models ───▶ providers/models
                         │
Account.captain_* ───▶ CaptainFeaturable ───▶ features
                         │
                         └─ PreferencesController ───▶ JSON Response
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| preferences_controller.rb | `app/controllers/api/v1/accounts/captain/preferences_controller.rb` | コントローラー | API制御 |
| models.rb | `lib/llm/models.rb` | ライブラリ | LLM設定モジュール |
| captain_featurable.rb | `app/models/concerns/captain_featurable.rb` | Concern | アカウントへの機能追加 |
| llm.yml | `config/llm.yml` | 設定 | LLMプロバイダー・モデル定義 |
| account.rb | `app/models/account.rb` | モデル | アカウントデータモデル |
