# 画面設計書 113-ガイドライン設定画面

## 概要

本ドキュメントは、ChatwootのCaptain AIアシスタントの応答ガイドライン（回答指針）を設定・管理する画面の設計書です。

### 本画面の処理概要

**業務上の目的・背景**：AIアシスタントがより適切で一貫性のある応答を生成するよう、応答ガイドラインを設定します。ガードレールが「禁止事項」を定義するのに対し、ガイドラインは「推奨事項」や「応答スタイル」を定義します。これにより、企業のトーン&マナーやカスタマーサービス品質基準に沿ったAI応答を実現します。Captain V2機能としてCloud/Enterprise版で提供される高度な制御機能です。

**画面へのアクセス方法**：アシスタント設定画面の制御項目セクションから「Response Guidelines」リンクをクリック、または直接URLパス `/accounts/:accountId/captain/:assistantId/settings/guidelines` にアクセスします。

**主要な操作・処理内容**：
1. 既存応答ガイドラインの一覧表示
2. 新規ガイドラインの追加（インライン入力またはダイアログ）
3. 既存ガイドラインの編集・削除
4. 推奨ガイドラインの一括追加
5. 複数ガイドラインの一括選択・削除
6. ガイドラインの検索・フィルタリング

**画面遷移**：
- 遷移元：アシスタント設定画面
- 遷移先：アシスタント設定画面（戻るボタン）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 84 | AIアシスタント | 主機能 | ガイドラインの設定・管理 |

## 画面種別

設定・一覧画面

## URL/ルーティング

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

## 入出力項目

### ガイドライン入力

| 項目名 | 項目ID | 型 | 必須 | 入力/出力 | 説明 |
|--------|--------|-----|------|-----------|------|
| ガイドライン内容 | content | string | Yes | 入力 | 応答ガイドラインのテキスト |

### 検索入力

| 項目名 | 項目ID | 型 | 必須 | 入力/出力 | 説明 |
|--------|--------|-----|------|-----------|------|
| 検索クエリ | searchQuery | string | No | 入力 | ガイドライン検索用テキスト |

## 表示項目

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

| 項目名 | 説明 |
|--------|------|
| ページタイトル | 「Response Guidelines」 |
| 戻るリンク | アシスタント設定画面へ戻る |
| 説明文 | ガイドライン機能の説明 |

### 推奨ガイドラインセクション（初回表示時）

| 項目名 | 説明 |
|--------|------|
| セクションタイトル | 推奨ガイドラインのタイトル |
| 推奨ガイドライン一覧 | 3つのサンプルガイドライン |
| 個別追加ボタン | 各ガイドラインを個別に追加 |
| 全件追加ボタン | すべての推奨ガイドラインを追加 |
| 閉じるボタン | 推奨セクションを非表示 |

### ガイドライン一覧セクション

| 項目名 | 説明 |
|--------|------|
| 一括選択バー | 全選択/選択解除、一括削除 |
| 新規追加ダイアログ | ダイアログ形式でガイドライン追加 |
| 検索入力 | ガイドライン検索用入力欄 |
| ガイドラインカード | 各ガイドラインの表示 |
| インライン追加入力 | テキストエリア形式でガイドライン追加 |

### ガイドラインカード

| 項目名 | 説明 |
|--------|------|
| 選択チェックボックス | 一括操作用選択 |
| ガイドライン内容 | ガイドラインテキストの表示 |
| 編集ボタン | ガイドラインの編集モード |
| 削除ボタン | ガイドラインの個別削除 |

## イベント仕様

### 1-ガイドライン追加（インライン）

**トリガー**: インライン入力で入力後、保存ボタンクリック

**処理フロー**:
1. 入力値の検証
2. 既存response_guidelines配列に新規ガイドラインを追加
3. `captainAssistants/update` アクションを dispatch
4. 成功時: 成功メッセージをアラート表示、入力欄をクリア
5. 失敗時: エラーメッセージをアラート表示

### 2-ガイドライン追加（ダイアログ）

**トリガー**: 新規追加ダイアログで確認ボタンクリック

**処理フロー**:
1. ダイアログ入力値の検証
2. 既存response_guidelines配列に新規ガイドラインを追加
3. `captainAssistants/update` アクションを dispatch
4. 成功時: 成功メッセージ、ダイアログを閉じる
5. 失敗時: エラーメッセージをアラート表示

### 3-ガイドライン編集

**トリガー**: カードの編集操作完了

**処理フロー**:
1. 編集内容の検証
2. response_guidelines配列の該当インデックスを更新
3. `captainAssistants/update` アクションを dispatch
4. 成功/失敗メッセージの表示

### 4-ガイドライン削除（個別）

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

**処理フロー**:
1. response_guidelines配列から該当インデックスを削除
2. `captainAssistants/update` アクションを dispatch
3. 成功/失敗メッセージの表示

### 5-ガイドライン一括削除

**トリガー**: 一括選択バーの削除ボタンクリック

**処理フロー**:
1. 選択されたIDのガイドラインをfilterで除外
2. `captainAssistants/update` アクションを dispatch
3. 選択状態をクリア
4. 成功/失敗メッセージの表示

### 6-推奨ガイドライン一括追加

**トリガー**: 推奨セクションの「全件追加」ボタンクリック

**処理フロー**:
1. UI設定を更新（推奨表示フラグをfalse）
2. 3つの推奨ガイドラインを既存配列に追加
3. `captainAssistants/update` アクションを dispatch
4. 成功/失敗メッセージの表示

### 7-検索フィルタリング

**トリガー**: 検索入力欄への入力

**処理フロー**:
1. searchQuery値を更新
2. picoSearchライブラリでコンテンツをフィルタリング
3. filteredGuidelinesを更新して表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ガイドライン追加 | captain_assistants | UPDATE | response_guidelinesフィールドを更新 |
| ガイドライン編集 | captain_assistants | UPDATE | response_guidelinesフィールドを更新 |
| ガイドライン削除 | captain_assistants | UPDATE | response_guidelinesフィールドを更新 |
| 一括追加/削除 | captain_assistants | UPDATE | response_guidelinesフィールドを更新 |

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

#### captain_assistants

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | response_guidelines | JSON配列（ガイドライン文字列の配列） | 追加・編集・削除時 |
| UPDATE | updated_at | 現在時刻 | 更新日時 |

## メッセージ仕様

| 種別 | キー | メッセージ内容 | 表示タイミング |
|------|-----|---------------|---------------|
| 成功 | CAPTAIN.ASSISTANTS.RESPONSE_GUIDELINES.API.ADD.SUCCESS | ガイドラインが追加されました | 追加成功時 |
| エラー | CAPTAIN.ASSISTANTS.RESPONSE_GUIDELINES.API.ADD.ERROR | ガイドラインの追加に失敗しました | 追加失敗時 |
| 成功 | CAPTAIN.ASSISTANTS.RESPONSE_GUIDELINES.API.UPDATE.SUCCESS | ガイドラインが更新されました | 編集成功時 |
| エラー | CAPTAIN.ASSISTANTS.RESPONSE_GUIDELINES.API.UPDATE.ERROR | ガイドラインの更新に失敗しました | 編集失敗時 |
| 成功 | CAPTAIN.ASSISTANTS.RESPONSE_GUIDELINES.API.DELETE.SUCCESS | ガイドラインが削除されました | 削除成功時 |
| エラー | CAPTAIN.ASSISTANTS.RESPONSE_GUIDELINES.API.DELETE.ERROR | ガイドラインの削除に失敗しました | 削除失敗時 |
| 情報 | CAPTAIN.ASSISTANTS.RESPONSE_GUIDELINES.EMPTY_MESSAGE | ガイドラインがありません | 0件時 |
| 情報 | CAPTAIN.ASSISTANTS.RESPONSE_GUIDELINES.SEARCH_EMPTY_MESSAGE | 検索結果がありません | 検索結果0件時 |

## 例外処理

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

## 備考

- ガードレール画面と同一のUIパターンを使用
- Captain V2フィーチャーフラグが有効な場合のみアクセス可能
- 推奨ガイドラインの表示/非表示はUI設定で永続化
- response_guidelinesは文字列配列としてアシスタントのJSONフィールドに保存
- ガードレールとの違い: ガードレールは「禁止事項」、ガイドラインは「推奨事項」

---

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

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

### 推奨読解順序

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

ガイドラインデータの構造とアシスタントモデルとの関係を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Index.vue | `app/javascript/dashboard/routes/dashboard/captain/assistants/guidelines/Index.vue` | L37-39: guidelinesContent computed - データ構造の理解 |
| 1-2 | assistant.js | `app/javascript/dashboard/store/captain/assistant.js` | ストアモジュールの定義 |

**読解のコツ**: guidelinesはassistant.response_guidelinesプロパティとして配列形式で保存される（guardrailsとは別のフィールド）。

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

ルーティングとメインコンポーネントの構成を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | captain.routes.js | `app/javascript/dashboard/routes/dashboard/captain/captain.routes.js` | L90-97: guidelinesルート定義、metaV2 |
| 2-2 | Index.vue | `app/javascript/dashboard/routes/dashboard/captain/assistants/guidelines/Index.vue` | メインコンポーネント全体 |

**主要処理フロー**:
1. **L26-31**: UIフラグとアシスタントデータの取得
2. **L37-39**: guidelinesContentの取得（assistant.response_guidelines）
3. **L49-51**: displayGuidelines - IDとcontentのマッピング
4. **L117-122**: saveGuidelines - 保存処理の共通化
5. **L124-132**: addGuideline - ガイドライン追加
6. **L134-143**: editGuideline - ガイドライン編集
7. **L145-153**: deleteGuideline - ガイドライン削除

#### Step 3: ガードレール画面との比較

両画面は同一UIパターンを使用しているため、差分を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | guardrails/Index.vue | `app/javascript/dashboard/routes/dashboard/captain/assistants/guardrails/Index.vue` | ガードレール版との比較 |

**主要な差分**:
- データフィールド: `guardrails` vs `response_guidelines`
- UI設定キー: `show_guardrails_suggestions` vs `show_response_guidelines_suggestions`
- i18nキー: `GUARDRAILS.*` vs `RESPONSE_GUIDELINES.*`

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

```
Index.vue (guidelines)
    |
    +-- PageLayout.vue (レイアウト、戻るリンク)
    |
    +-- SettingsHeader.vue (タイトル・説明)
    |
    +-- SuggestedRules.vue (推奨ガイドライン)
    |       |
    |       +-- @add -> addAllExample()
    |       +-- @close -> closeSuggestedRules()
    |
    +-- BulkSelectBar.vue (一括操作)
    |       |
    |       +-- @bulk-delete -> bulkDeleteGuidelines()
    |
    +-- AddNewRulesDialog.vue
    |       |
    |       +-- @add -> addGuideline()
    |
    +-- RuleCard.vue (各ガイドライン)
    |       |
    |       +-- @select -> handleRuleSelect()
    |       +-- @edit -> editGuideline()
    |       +-- @delete -> deleteGuideline()
    |
    +-- AddNewRulesInput.vue (インライン入力)
            |
            +-- @add -> addGuideline()

saveGuidelines()
    |
    +-- store.dispatch('captainAssistants/update')
            |
            +-- CaptainAssistantAPI.update()
```

### データフロー図

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

推奨一括追加 ---------> addAllExample() -----------> API更新
                           |
インライン入力 -------> addGuideline() -----------> response_guidelines配列更新
                           |                           |
ダイアログ入力 -------> addGuideline() -----------> saveGuidelines()
                                                       |
編集 ----------------> editGuideline() ---------->     |
                                                       v
削除 ----------------> deleteGuideline() -------> captainAssistants/update
                                                       |
一括削除 ------------> bulkDeleteGuidelines() -->      |
                                                       v
検索入力 ------------> picoSearch() -------------> filteredGuidelines
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Index.vue | `app/javascript/dashboard/routes/dashboard/captain/assistants/guidelines/Index.vue` | ソース | メイン画面コンポーネント |
| captain.routes.js | `app/javascript/dashboard/routes/dashboard/captain/captain.routes.js` | ソース | ルーティング定義 |
| assistant.js | `app/javascript/dashboard/store/captain/assistant.js` | ソース | Vuexストアモジュール |
| PageLayout.vue | `app/javascript/dashboard/components-next/captain/PageLayout.vue` | ソース | レイアウトコンポーネント |
| SettingsHeader.vue | `app/javascript/dashboard/components-next/captain/pageComponents/settings/SettingsHeader.vue` | ソース | ヘッダーコンポーネント |
| SuggestedRules.vue | `app/javascript/dashboard/components-next/captain/assistant/SuggestedRules.vue` | ソース | 推奨ルール表示（共通） |
| AddNewRulesInput.vue | `app/javascript/dashboard/components-next/captain/assistant/AddNewRulesInput.vue` | ソース | インライン入力（共通） |
| AddNewRulesDialog.vue | `app/javascript/dashboard/components-next/captain/assistant/AddNewRulesDialog.vue` | ソース | ダイアログ入力（共通） |
| RuleCard.vue | `app/javascript/dashboard/components-next/captain/assistant/RuleCard.vue` | ソース | ルールカード（共通） |
| BulkSelectBar.vue | `app/javascript/dashboard/components-next/captain/assistant/BulkSelectBar.vue` | ソース | 一括選択バー（共通） |
| useUISettings.js | `app/javascript/dashboard/composables/useUISettings.js` | ソース | UI設定composable |
