# 画面設計書 112-ガードレール設定画面

## 概要

本ドキュメントは、ChatwootのCaptain AIアシスタントのガードレール（安全制御ルール）を設定・管理する画面の設計書です。

### 本画面の処理概要

**業務上の目的・背景**：AIアシスタントが不適切な応答を生成しないよう、ガードレール（制限ルール）を設定することで、AIの振る舞いを制御します。例えば、個人情報の共有を禁止したり、攻撃的な言語を拒否したりするルールを定義できます。これにより、企業のコンプライアンス要件やブランドガイドラインに沿ったAI応答を実現します。Captain V2機能としてCloud/Enterprise版で提供される高度な制御機能です。

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

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

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

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

## 関連機能

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

## 画面種別

設定・一覧画面

## URL/ルーティング

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

## 入出力項目

### ガードレールルール入力

| 項目名 | 項目ID | 型 | 必須 | 入力/出力 | 説明 |
|--------|--------|-----|------|-----------|------|
| ルール内容 | content | string | Yes | 入力 | ガードレールルールのテキスト |

### 検索入力

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

## 表示項目

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

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

### 推奨ルールセクション（初回表示時）

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

### ルール一覧セクション

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

### ルールカード

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

## イベント仕様

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

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

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

### 2-ガードレール追加（ダイアログ）

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

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

### 3-ガードレール編集

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

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

### 4-ガードレール削除（個別）

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

**処理フロー**:
1. guardrails配列から該当インデックスを削除
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

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

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

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

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

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

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

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

#### captain_assistants

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

## メッセージ仕様

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

## 例外処理

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

## 備考

- Captain V2フィーチャーフラグが有効な場合のみアクセス可能
- 推奨ルールの表示/非表示はUI設定（uiSettings）で永続化
- guardrailsは文字列配列としてアシスタントのJSONフィールドに保存
- picoSearchライブラリを使用した軽量な検索機能を提供

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: guardrailsはアシスタントオブジェクトのプロパティとして配列形式で保存される。

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

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

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

**主要処理フロー**:
1. **L26-31**: UIフラグとアシスタントデータの取得
2. **L37**: guardrailsContentの取得（assistant.guardrails）
3. **L47-49**: displayGuardrails - IDとcontentのマッピング
4. **L111-116**: saveGuardrails - 保存処理の共通化
5. **L118-126**: addGuardrail - ルール追加
6. **L128-137**: editGuardrail - ルール編集
7. **L139-147**: deleteGuardrail - ルール削除

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

各機能コンポーネントの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | SuggestedRules.vue | `app/javascript/dashboard/components-next/captain/assistant/SuggestedRules.vue` | 推奨ルール表示 |
| 3-2 | AddNewRulesInput.vue | `app/javascript/dashboard/components-next/captain/assistant/AddNewRulesInput.vue` | インライン入力 |
| 3-3 | AddNewRulesDialog.vue | `app/javascript/dashboard/components-next/captain/assistant/AddNewRulesDialog.vue` | ダイアログ入力 |
| 3-4 | RuleCard.vue | `app/javascript/dashboard/components-next/captain/assistant/RuleCard.vue` | ルールカード表示 |
| 3-5 | BulkSelectBar.vue | `app/javascript/dashboard/components-next/captain/assistant/BulkSelectBar.vue` | 一括選択操作 |

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

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

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

### データフロー図

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

推奨ルール追加 -------> addAllExample() -----------> API更新
                           |
インライン入力 -------> addGuardrail() -----------> guardrails配列更新
                           |                           |
ダイアログ入力 -------> addGuardrail() -----------> saveGuardrails()
                                                       |
ルール編集 -----------> editGuardrail() ---------->    |
                                                       v
ルール削除 -----------> deleteGuardrail() -------> captainAssistants/update
                                                       |
一括削除 ------------> bulkDeleteGuardrails() --->     |
                                                       v
検索入力 ------------> picoSearch() -------------> filteredGuardrails
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Index.vue | `app/javascript/dashboard/routes/dashboard/captain/assistants/guardrails/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 |
