# 画面設計書 111-アシスタント設定画面

## 概要

本ドキュメントは、ChatwootのCaptain AIアシスタントの詳細設定を行う画面の設計書です。

### 本画面の処理概要

**業務上の目的・背景**：Captain AIはChatwootのAIアシスタント機能であり、顧客対応の自動化や効率化を実現します。本画面は、作成されたAIアシスタントの基本情報（名前、説明、システム設定など）を編集・管理するために必要です。また、アシスタントの削除機能も提供し、不要になったアシスタントのライフサイクル管理を行います。Cloud版およびEnterprise版でのみ利用可能な機能であり、AI活用による業務効率化を推進する重要な設定画面です。

**画面へのアクセス方法**：サイドバーのCaptainメニューからアシスタント一覧を開き、対象アシスタントの設定アイコンをクリック、または直接URLパス `/accounts/:accountId/captain/:assistantId/settings` にアクセスします。

**主要な操作・処理内容**：
1. アシスタント基本情報（名前、説明）の表示・編集
2. システム設定（AIの振る舞いに関する設定）の表示・編集
3. Captain V2有効時のガードレール・ガイドライン設定へのナビゲーション
4. アシスタントの削除処理

**画面遷移**：
- 遷移元：アシスタント一覧画面、サイドバーナビゲーション
- 遷移先：ガードレール設定画面、ガイドライン設定画面、アシスタント作成画面（削除後）、他のアシスタント設定画面（削除後に別アシスタントがある場合）

**権限による表示制御**：管理者およびエージェントロールを持つユーザーのみアクセス可能です。Captain V2機能フラグが有効な場合、ガードレールとガイドラインの設定リンクが表示されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 84 | AIアシスタント | 主機能 | アシスタントの詳細設定、削除処理 |

## 画面種別

設定・編集画面

## URL/ルーティング

- パス: `/accounts/:accountId/captain/:assistantId/settings`
- ルート名: `captain_assistants_settings_index`
- パラメータ:
  - `accountId`: アカウントID
  - `assistantId`: アシスタントID

## 入出力項目

### 基本設定フォーム

| 項目名 | 項目ID | 型 | 必須 | 入力/出力 | 説明 |
|--------|--------|-----|------|-----------|------|
| アシスタント名 | name | string | Yes | 入出力 | アシスタントの表示名 |
| 説明 | description | string | No | 入出力 | アシスタントの説明文 |

### システム設定フォーム

| 項目名 | 項目ID | 型 | 必須 | 入力/出力 | 説明 |
|--------|--------|-----|------|-----------|------|
| システムプロンプト | system_prompt | text | No | 入出力 | AIの基本的な振る舞いを定義するプロンプト |
| 応答設定 | response_settings | object | No | 入出力 | 応答に関する各種設定 |

## 表示項目

### ヘッダーセクション

| 項目名 | 説明 |
|--------|------|
| ページタイトル | アシスタント設定画面のタイトル |
| 戻るリンク | 前の画面へ戻るナビゲーション |

### 基本設定セクション

| 項目名 | 説明 |
|--------|------|
| セクションタイトル | 「Basic Settings」 |
| セクション説明 | 基本設定の説明文 |
| フォームコンポーネント | AssistantBasicSettingsForm |

### システム設定セクション

| 項目名 | 説明 |
|--------|------|
| セクションタイトル | 「System Settings」 |
| セクション説明 | システム設定の説明文 |
| フォームコンポーネント | AssistantSystemSettingsForm |

### 削除セクション

| 項目名 | 説明 |
|--------|------|
| セクションタイトル | 「Delete」 |
| セクション説明 | 削除操作の説明 |
| 削除ボタン | アシスタント名を含む削除ボタン |

### 制御項目セクション（Captain V2有効時のみ）

| 項目名 | 説明 |
|--------|------|
| セクションタイトル | 「Control Items」 |
| ガードレール設定リンク | ガードレール設定画面へのナビゲーション |
| ガイドライン設定リンク | ガイドライン設定画面へのナビゲーション |

## イベント仕様

### 1-基本設定保存

**トリガー**: 基本設定フォームのsubmitイベント

**処理フロー**:
1. フォームデータの検証
2. `captainAssistants/update` アクションを dispatch
3. API呼び出し（PUT `/api/v1/accounts/:accountId/captain/assistants/:id`）
4. 成功時: 成功メッセージをアラート表示
5. 失敗時: エラーメッセージをアラート表示

### 2-システム設定保存

**トリガー**: システム設定フォームのsubmitイベント

**処理フロー**:
1. フォームデータの検証
2. `captainAssistants/update` アクションを dispatch
3. API呼び出し（PUT `/api/v1/accounts/:accountId/captain/assistants/:id`）
4. 成功時: 成功メッセージをアラート表示
5. 失敗時: エラーメッセージをアラート表示

### 3-アシスタント削除

**トリガー**: 削除ボタンクリック

**処理フロー**:
1. DeleteDialogを開く
2. 確認ダイアログでユーザーの確認を取得
3. 確認後、削除APIを呼び出し
4. 成功時:
   - 他のアシスタントが存在する場合: 最初のアシスタントの設定画面へ遷移
   - アシスタントが0件の場合: アシスタント作成画面へ遷移
5. 失敗時: エラーメッセージを表示

### 4-制御項目ナビゲーション

**トリガー**: ガードレール/ガイドラインリンクのクリック

**処理フロー**:
1. 対応するルートへ router.push
2. ガードレール: `captain_assistants_guardrails_index` へ遷移
3. ガイドライン: `captain_assistants_guidelines_index` へ遷移

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 基本設定保存 | captain_assistants | UPDATE | アシスタントの基本情報を更新 |
| システム設定保存 | captain_assistants | UPDATE | アシスタントのシステム設定を更新 |
| アシスタント削除 | captain_assistants | DELETE | アシスタントレコードを削除 |

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

#### captain_assistants

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | name | フォーム入力値 | アシスタント名 |
| UPDATE | description | フォーム入力値 | 説明 |
| UPDATE | system_prompt | フォーム入力値 | システムプロンプト |
| UPDATE | config | フォーム入力値 | 設定JSON |
| UPDATE | updated_at | 現在時刻 | 更新日時 |
| DELETE | - | id = assistantId | 削除対象レコード |

## メッセージ仕様

| 種別 | キー | メッセージ内容 | 表示タイミング |
|------|-----|---------------|---------------|
| 成功 | CAPTAIN.ASSISTANTS.EDIT.SUCCESS_MESSAGE | アシスタントが更新されました | 設定保存成功時 |
| エラー | CAPTAIN.ASSISTANTS.EDIT.ERROR_MESSAGE | アシスタントの更新に失敗しました | 設定保存失敗時 |
| 確認 | CAPTAIN.ASSISTANTS.SETTINGS.DELETE.TITLE | アシスタントを削除 | 削除セクションタイトル |
| 確認 | CAPTAIN.ASSISTANTS.SETTINGS.DELETE.DESCRIPTION | この操作は取り消せません | 削除説明 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| アシスタントが見つからない | 404エラー、アシスタント一覧へリダイレクト |
| 権限不足 | 403エラー、アクセス拒否メッセージ表示 |
| API通信エラー | エラーメッセージ表示、フォーム状態を維持 |
| フィーチャーフラグ無効 | Captain機能未対応のメッセージ表示 |

## 備考

- Cloud版およびEnterprise版でのみ利用可能
- Captain V2フィーチャーフラグが有効な場合、制御項目セクションが表示される
- 削除操作は確認ダイアログを経由し、誤操作を防止

---

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

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

### 推奨読解順序

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

アシスタントデータの構造とストア管理を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | assistant.js | `app/javascript/dashboard/store/captain/assistant.js` | ストアモジュールの定義、createStoreファクトリの使用 |
| 1-2 | assistant.js | `app/javascript/dashboard/api/captain/assistant.js` | APIクライアントの定義、エンドポイント構成 |

**読解のコツ**: CaptainAssistantストアはcreateStoreファクトリを使用して生成されており、標準的なCRUD操作が自動的に提供される。

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

ルーティング設定と画面コンポーネントの構成を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | captain.routes.js | `app/javascript/dashboard/routes/dashboard/captain/captain.routes.js` | ルート定義、メタ情報（permissions, featureFlag） |
| 2-2 | Settings.vue | `app/javascript/dashboard/routes/dashboard/captain/assistants/settings/Settings.vue` | メインコンポーネント、Composition APIの使用 |

**主要処理フロー**:
1. **L21-23**: Captain V2フィーチャーフラグの確認
2. **L30-36**: アシスタントデータの取得（ストアから）
3. **L61-73**: 保存処理（handleSubmit関数）
4. **L75-102**: 削除処理（handleDelete, handleDeleteSuccess関数）

#### Step 3: サブコンポーネントを理解する

フォームコンポーネントの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AssistantBasicSettingsForm.vue | `app/javascript/dashboard/components-next/captain/pageComponents/assistant/settings/AssistantBasicSettingsForm.vue` | 基本設定フォームの構成 |
| 3-2 | AssistantSystemSettingsForm.vue | `app/javascript/dashboard/components-next/captain/pageComponents/assistant/settings/AssistantSystemSettingsForm.vue` | システム設定フォームの構成 |
| 3-3 | AssistantControlItems.vue | `app/javascript/dashboard/components-next/captain/pageComponents/assistant/settings/AssistantControlItems.vue` | 制御項目リンクの表示 |
| 3-4 | DeleteDialog.vue | `app/javascript/dashboard/components-next/captain/pageComponents/DeleteDialog.vue` | 削除確認ダイアログ |

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

```
Settings.vue
    |
    +-- PageLayout.vue (レイアウト)
    |
    +-- SettingsHeader.vue (セクションヘッダー)
    |
    +-- AssistantBasicSettingsForm.vue
    |       |
    |       +-- @submit -> handleSubmit()
    |                       |
    |                       +-- store.dispatch('captainAssistants/update')
    |                               |
    |                               +-- CaptainAssistantAPI.update()
    |
    +-- AssistantSystemSettingsForm.vue
    |       |
    |       +-- @submit -> handleSubmit()
    |
    +-- AssistantControlItems.vue (V2のみ)
    |       |
    |       +-- router-link -> guardrails/guidelines
    |
    +-- DeleteDialog.vue
            |
            +-- @delete-success -> handleDeleteSuccess()
                                    |
                                    +-- router.push()
```

### データフロー図

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

フォーム入力 ---------> handleSubmit() -----------> API更新
                           |                           |
                           v                           v
                   captainAssistants/update     アラート表示
                           |
                           v
                   CaptainAssistantAPI

削除ボタン ----------> handleDelete() -----------> 削除確認ダイアログ
                           |                           |
                           v                           v
                   DeleteDialog              handleDeleteSuccess()
                                                       |
                                                       v
                                                 router.push()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Settings.vue | `app/javascript/dashboard/routes/dashboard/captain/assistants/settings/Settings.vue` | ソース | メイン画面コンポーネント |
| captain.routes.js | `app/javascript/dashboard/routes/dashboard/captain/captain.routes.js` | ソース | ルーティング定義 |
| assistant.js | `app/javascript/dashboard/store/captain/assistant.js` | ソース | Vuexストアモジュール |
| assistant.js | `app/javascript/dashboard/api/captain/assistant.js` | ソース | APIクライアント |
| PageLayout.vue | `app/javascript/dashboard/components-next/captain/PageLayout.vue` | ソース | レイアウトコンポーネント |
| AssistantBasicSettingsForm.vue | `app/javascript/dashboard/components-next/captain/pageComponents/assistant/settings/AssistantBasicSettingsForm.vue` | ソース | 基本設定フォーム |
| AssistantSystemSettingsForm.vue | `app/javascript/dashboard/components-next/captain/pageComponents/assistant/settings/AssistantSystemSettingsForm.vue` | ソース | システム設定フォーム |
| AssistantControlItems.vue | `app/javascript/dashboard/components-next/captain/pageComponents/assistant/settings/AssistantControlItems.vue` | ソース | 制御項目リンク |
| DeleteDialog.vue | `app/javascript/dashboard/components-next/captain/pageComponents/DeleteDialog.vue` | ソース | 削除確認ダイアログ |
| featureFlags.js | `app/javascript/dashboard/featureFlags.js` | ソース | フィーチャーフラグ定義 |
