# 画面設計書 103-アシスタント作成画面

## 概要

新しいCaptain AIアシスタントを作成するための画面設計書です。アシスタントが存在しない場合のエントリーポイントとして機能し、空状態表示と作成ダイアログを提供します。

### 本画面の処理概要

**業務上の目的・背景**：Captain AI機能を初めて使用するユーザーや、新しいAIアシスタントを追加したいユーザーのために、アシスタント作成のエントリーポイントを提供します。アシスタントは顧客対応を自動化するためのAIエージェントであり、FAQ、ドキュメント、シナリオなどのナレッジベースと連携して動作します。

**画面へのアクセス方法**：アシスタントが1つも存在しない場合、Captain機能へのアクセス時に自動的にリダイレクトされます。URLパスは `/app/accounts/:accountId/captain/assistants` です。

**主要な操作・処理内容**：
1. 空状態の表示（アシスタント未作成時）
2. 「Create a new assistant」ボタンによる作成ダイアログ表示
3. アシスタント情報の入力と作成
4. 作成完了後のFAQ一覧画面への自動遷移

**画面遷移**：
- 遷移元：Captainアシスタント一覧画面（アシスタント0件時のリダイレクト）
- 遷移先：FAQ一覧画面（作成完了後）

**権限による表示制御**：administrator および agent ロールがアクセス可能です。CloudまたはEnterpriseインストールタイプでのみ利用可能です（フィーチャーフラグなしで直接アクセス可能）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 84 | AIアシスタント | 主機能 | 新しいアシスタントの作成 |

## 画面種別

登録（ダイアログ）

## URL/ルーティング

| パス | ルート名 |
|------|----------|
| `/app/accounts/:accountId/captain/assistants` | `captain_assistants_create_index` |

## 入出力項目

### 作成フォーム入力項目

| 項目名 | 物理名 | 型 | 必須 | バリデーション | 備考 |
|--------|--------|-----|------|---------------|------|
| 名前 | name | string | Yes | 必須 | アシスタント名 |
| 説明 | description | string | Yes | 必須 | アシスタントの説明 |
| 製品名 | product_name | string | Yes | 必須 | サポート対象製品名 |

### 出力項目

| 項目名 | 物理名 | 型 | 備考 |
|--------|--------|-----|------|
| 作成されたアシスタント | assistant | object | id, name, descriptionなど |

## 表示項目

### 空状態表示（AssistantPageEmptyState）

| 項目名 | 表示形式 | 備考 |
|--------|----------|------|
| タイトル | "No assistants available" | 空状態メッセージ |
| サブタイトル | 説明テキスト | 機能説明 |
| 作成ボタン | プライマリボタン | アシスタント作成ダイアログを開く |

### Feature Spotlightポップオーバー

| 項目名 | 表示形式 | 備考 |
|--------|----------|------|
| Know moreボタン | テキストリンク | ポップオーバー表示 |
| タイトル | "Captain Assistant" | 機能紹介 |
| 説明文 | 機能説明テキスト | Captain Assistantの説明 |
| サムネイル | 画像 | ライト/ダークモード対応 |
| Learn moreリンク | 外部リンク | https://chwt.app/captain-assistant |

## イベント仕様

### 1-作成ボタン押下

1. 「Create a new assistant」ボタンまたは空状態の作成ボタンをクリック
2. `handleCreate()` が呼び出される
3. `dialogType` を 'create' に設定
4. `nextTick` で `createAssistantDialog.value.dialogRef.open()` を実行
5. `CreateAssistantDialog` コンポーネントがモーダル表示される

### 2-アシスタント作成完了

1. フォーム入力後、Submit時に `captainAssistants/create` アクションが dispatch される
2. API成功時：
   - 成功メッセージ表示
   - `handleAfterCreate(newAssistant)` が呼び出される
   - 新しいアシスタントIDでFAQ一覧画面（captain_assistants_responses_index）へ遷移
3. API失敗時：エラーメッセージ表示

### 3-ダイアログクローズ

1. キャンセルボタンまたは外部クリックでダイアログクローズ
2. `handleCreateClose()` が呼び出される
3. `dialogType` と `selectedAssistant` をリセット

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| アシスタント作成 | captain_assistants | INSERT | 新規アシスタントレコード作成 |
| UIフラグ取得 | - | - | Vuexストアのフラグ確認 |

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

#### captain_assistants

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | フォーム入力値 | アシスタント名 |
| INSERT | description | フォーム入力値 | 説明 |
| INSERT | product_name | フォーム入力値 | 製品名 |
| INSERT | account_id | current_account.id | 自動設定 |

## メッセージ仕様

| 種別 | メッセージキー | メッセージ内容 |
|------|---------------|---------------|
| 成功 | CAPTAIN.ASSISTANTS.CREATE.SUCCESS_MESSAGE | "The assistant has been successfully created" |
| エラー | CAPTAIN.ASSISTANTS.CREATE.ERROR_MESSAGE | "There was an error creating the assistant, please try again." |

## 例外処理

| 例外条件 | 処理内容 | 表示 |
|----------|----------|------|
| データ取得中 | isFetchingフラグでローディング表示 | PageLayoutのローディング状態 |
| 権限不足 | 画面アクセス不可 | ルートガードによりリダイレクト |
| API通信エラー | アラート表示 | エラーメッセージ |
| バリデーションエラー | フォームフィールドにエラー表示 | 各項目下にエラーテキスト |
| Captain未有効（Cloud版） | Paywallコンポーネント表示 | アップグレード案内 |

## 備考

- この画面はアシスタントが0件の場合のみ表示される
- アシスタント作成後は自動的にFAQ一覧画面に遷移
- Cloud版の場合、Feature Spotlightにアクションボタンが表示される
- フィーチャーフラグなしで直接アクセス可能（インストールタイプのみチェック）

---

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

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

### 推奨読解順序

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

まず、アシスタントデータの構造とUIフラグの管理を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | assistant.js (store) | `app/javascript/dashboard/store/captain/assistant.js` | ストア定義、createStoreによる自動生成 |
| 1-2 | storeFactory.js | `app/javascript/dashboard/store/storeFactory.js` | UIFlags（fetchingListなど）の定義を確認 |

**読解のコツ**: `createStore` でUIFlagsが自動生成されます。`getUIFlags` ゲッターで `fetchingList` フラグを取得できます。

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

処理の起点となるVueコンポーネントを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Index.vue (assistants) | `app/javascript/dashboard/routes/dashboard/captain/assistants/Index.vue` | メインコンポーネントの構造、イベントハンドラを確認 |
| 2-2 | captain.routes.js | `app/javascript/dashboard/routes/dashboard/captain/captain.routes.js` | ルーティング定義を確認（99-109行目） |

**主要処理フロー**:
1. **17行目**: `uiFlags` でローディング状態取得
2. **18行目**: `isFetching` computed
3. **24-27行目**: `handleCreate()` でダイアログ表示
4. **34-44行目**: `handleAfterCreate()` で作成後のナビゲーション

#### Step 3: ダイアログコンポーネントを理解する

アシスタント作成ダイアログの構造を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CreateAssistantDialog.vue | `app/javascript/dashboard/components-next/captain/pageComponents/assistant/CreateAssistantDialog.vue` | ダイアログコンポーネント、フォーム構造を確認 |

#### Step 4: API通信層を理解する

バックエンドとの通信処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | assistant.js (api) | `app/javascript/dashboard/api/captain/assistant.js` | APIクライアント、createメソッドを確認 |

**主要処理フロー**:
- ApiClientのcreateメソッドを継承使用

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

```
Index.vue (captain/assistants)
    |
    +-- PageLayout.vue
    |       |
    |       +-- ヘッダー、ボタン、ローディング状態
    |
    +-- FeatureSpotlightPopover.vue
    |       |
    |       +-- Know moreポップオーバー
    |
    +-- AssistantPageEmptyState.vue
    |       |
    |       +-- 空状態表示、作成ボタン
    |
    +-- CaptainPaywall.vue
    |       |
    |       +-- アップグレード案内（有料プラン未加入時）
    |
    +-- CreateAssistantDialog.vue
            |
            +-- フォーム入力
            +-- captainAssistants/create (Vuex Action)
                    |
                    +-- CaptainAssistantAPI.create()
                            |
                            +-- POST /api/v1/.../captain/assistants
```

### データフロー図

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

作成ボタン押下 ────────▶ handleCreate()
                              │
                              ▼
                        ダイアログ表示
                              │
                              ▼
フォーム入力 ──────────▶ CreateAssistantDialog
                              │
                              ▼
                        バリデーション
                              │
                              ▼
                        captainAssistants/create
                              │
                              ▼
                        POST /api/v1/.../captain/assistants
                              │
                              ▼
                        handleAfterCreate()
                              │
                              ▼
                        router.push() ──────────▶ FAQ一覧画面
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Index.vue | `app/javascript/dashboard/routes/dashboard/captain/assistants/Index.vue` | ソース | メイン画面コンポーネント |
| captain.routes.js | `app/javascript/dashboard/routes/dashboard/captain/captain.routes.js` | 設定 | ルーティング定義 |
| assistant.js (store) | `app/javascript/dashboard/store/captain/assistant.js` | ソース | Vuexストアモジュール |
| assistant.js (api) | `app/javascript/dashboard/api/captain/assistant.js` | ソース | APIクライアント |
| CreateAssistantDialog.vue | `app/javascript/dashboard/components-next/captain/pageComponents/assistant/CreateAssistantDialog.vue` | ソース | 作成ダイアログ |
| AssistantPageEmptyState.vue | `app/javascript/dashboard/components-next/captain/pageComponents/emptyStates/AssistantPageEmptyState.vue` | ソース | 空状態表示 |
| PageLayout.vue | `app/javascript/dashboard/components-next/captain/PageLayout.vue` | ソース | ページレイアウト |
| CaptainPaywall.vue | `app/javascript/dashboard/components-next/captain/pageComponents/Paywall.vue` | ソース | 有料プラン案内 |
| FeatureSpotlightPopover.vue | `app/javascript/dashboard/components-next/feature-spotlight/FeatureSpotlightPopover.vue` | ソース | 機能紹介ポップオーバー |
| integrations.json | `app/javascript/dashboard/i18n/locale/en/integrations.json` | 設定 | 多言語リソース（CAPTAIN.ASSISTANTS） |
