# 画面設計書 102-Captainアシスタント一覧

## 概要

Captain AIアシスタントの一覧を表示し、最後にアクティブだったアシスタントまたは最初のアシスタントへ自動的にルーティングするインデックス画面の設計書です。この画面はCaptain機能へのエントリーポイントとして機能します。

### 本画面の処理概要

**業務上の目的・背景**：Captain AIは顧客対応を自動化するためのAIアシスタント機能です。この画面は、ユーザーがCaptain機能にアクセスした際に、適切なアシスタントの管理画面へスムーズに誘導することを目的としています。UISettings に保存された最後にアクティブだったアシスタントIDを参照して、ユーザーの作業継続性を担保します。

**画面へのアクセス方法**：サイドバーのナビゲーションから「Captain」を選択してアクセスします。URLパスは `/app/accounts/:accountId/captain/:navigationPath` です。初回アクセス時はFAQ一覧画面にリダイレクトされます。

**主要な操作・処理内容**：
1. アシスタント一覧データの取得
2. 最後にアクティブだったアシスタントIDの確認
3. 適切な子画面へのルーティング（FAQ、ドキュメント、シナリオ、プレイグラウンドなど）
4. アシスタントが存在しない場合は作成画面へリダイレクト

**画面遷移**：
- 遷移元：サイドバーナビゲーション、ダッシュボード
- 遷移先：FAQ一覧画面、ドキュメント一覧画面、シナリオ一覧画面、プレイグラウンド画面、インボックス設定画面、ツール一覧画面、設定画面、アシスタント作成画面

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 84 | AIアシスタント | 主機能 | Captain AIアシスタントの一覧表示とルーティング |

## 画面種別

インデックス / ルーティング

## URL/ルーティング

| パス | ルート名 |
|------|----------|
| `/app/accounts/:accountId/captain/:navigationPath` | `captain_assistants_index` |

## 入出力項目

### 入力パラメータ

| 項目名 | 物理名 | 型 | 必須 | 備考 |
|--------|--------|-----|------|------|
| アカウントID | accountId | number | Yes | URLパラメータ |
| ナビゲーションパス | navigationPath | string | No | リダイレクト先のルート名 |

### 出力項目

この画面は中継的な役割のため、表示要素はSpinnerのみです。

| 項目名 | 物理名 | 型 | 備考 |
|--------|--------|-----|------|
| ローディング状態 | - | component | Spinnerコンポーネント表示 |

## 表示項目

### ローディング表示

| 項目名 | 表示形式 | 備考 |
|--------|----------|------|
| Spinner | ローディングインジケータ | 画面中央に表示 |

## イベント仕様

### 1-マウント時の自動ルーティング

1. コンポーネントがマウントされる
2. `performRouting()` が呼び出される
3. `captainAssistants/get` アクションでアシスタント一覧を取得
4. `nextTick` で `routeToLastActiveAssistant()` を呼び出し
5. 以下のロジックでリダイレクト先を決定：
   - UISettingsの `last_active_assistant_id` を確認
   - 該当アシスタントが存在すればそのIDを使用
   - 存在しなければ最初のアシスタントIDを使用
   - アシスタントが0件の場合は作成画面へリダイレクト
6. 有効なルート（FAQ、ドキュメント、シナリオ、プレイグラウンド、インボックス、ツール、設定）の場合はそのルートへ
7. 無効なルートの場合はデフォルトでFAQ一覧へリダイレクト

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| アシスタント一覧取得 | captain_assistants | SELECT | アカウントに紐づくアシスタント取得 |

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

#### captain_assistants

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, name, etc. | `account_id = current_account.id` | 全アシスタント取得 |

## メッセージ仕様

この画面では直接的なユーザーメッセージは表示されません。

## 例外処理

| 例外条件 | 処理内容 | 表示 |
|----------|----------|------|
| データ取得中 | Spinnerコンポーネント表示 | ローディングインジケータ |
| アシスタント0件 | 作成画面へリダイレクト | captain_assistants_create_indexへ遷移 |
| 無効なナビゲーションパス | FAQ一覧へリダイレクト | captain_assistants_responses_indexへ遷移 |

## 備考

- この画面は実質的にルーティングコントローラーとして機能
- UISettings の `last_active_assistant_id` を参照してユーザーの作業継続性を担保
- Cloud版またはEnterprise版でのみ利用可能
- フィーチャーフラグ CAPTAIN が必要

---

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

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

### 推奨読解順序

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

まず、アシスタントデータの構造とUISettings の管理方法を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | assistant.js (store) | `app/javascript/dashboard/store/captain/assistant.js` | アシスタントストアの定義を確認 |
| 1-2 | storeFactory.js | `app/javascript/dashboard/store/storeFactory.js` | createStore関数でCRUD操作が自動生成されることを理解 |

**読解のコツ**: `createStore` 関数を使用しており、基本的なCRUD操作（get, create, update, delete）が自動生成されています。

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

処理の起点となるVueコンポーネントとルーティング設定を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | captain.routes.js | `app/javascript/dashboard/routes/dashboard/captain/captain.routes.js` | ルーティング定義、メタ情報を確認 |
| 2-2 | AssistantsIndexPage.vue | `app/javascript/dashboard/routes/dashboard/captain/pages/AssistantsIndexPage.vue` | メインコンポーネントのルーティングロジックを確認 |

**主要処理フロー**:
1. **14-16行目**: `assistants` computed でストアからアシスタント一覧取得
2. **26-42行目**: `generateRouterParams()` でルーティングパラメータ生成
3. **44-73行目**: `routeToLastActiveAssistant()` でリダイレクト先決定
4. **75-78行目**: `performRouting()` でデータ取得後ルーティング実行
5. **80行目**: `onMounted` でルーティング処理開始

#### Step 3: ルーティング設定を理解する

Captain機能全体のルーティング構造を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | captain.routes.js | `app/javascript/dashboard/routes/dashboard/captain/captain.routes.js` | assistantRoutes配列で全子ルート定義を確認 |

**主要処理フロー**:
- **32-116行目**: assistantRoutes配列でFAQ、ドキュメント、ツール、シナリオ、プレイグラウンド、インボックス、設定ルートを定義
- **118-133行目**: メインルートでリダイレクト設定

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

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

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

**主要処理フロー**:
- **4-6行目**: `captain/assistants` エンドポイント使用
- **9-16行目**: `get` メソッドでページネーション、検索キー対応

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

```
AssistantsIndexPage.vue
    |
    +-- onMounted
    |       |
    |       +-- performRouting()
    |               |
    |               +-- captainAssistants/get (Vuex Action)
    |               |       |
    |               |       +-- CaptainAssistantAPI.get()
    |               |               |
    |               |               +-- GET /api/v1/.../captain/assistants
    |               |
    |               +-- routeToLastActiveAssistant()
    |                       |
    |                       +-- generateRouterParams()
    |                       |       |
    |                       |       +-- uiSettings.last_active_assistant_id
    |                       |       +-- assistants[0].id (fallback)
    |                       |
    |                       +-- router.replace()
    |                               |
    |                               +-- captain_assistants_responses_index (default)
    |                               +-- captain_assistants_create_index (no assistants)
```

### データフロー図

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

URLアクセス ──────────▶ AssistantsIndexPage
                              │
                              ▼
                        captainAssistants/get
                              │
                              ▼
                        CaptainAssistantAPI
                              │
                              ▼
                        GET /api/v1/.../captain/assistants
                              │
                              ▼
                        Vuex State更新
                              │
                              ▼
                        generateRouterParams()
                              │
                              ├── assistants存在 ─▶ FAQ画面へリダイレクト
                              │
                              └── assistants空 ──▶ 作成画面へリダイレクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AssistantsIndexPage.vue | `app/javascript/dashboard/routes/dashboard/captain/pages/AssistantsIndexPage.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クライアント |
| storeFactory.js | `app/javascript/dashboard/store/storeFactory.js` | ソース | ストア生成ファクトリー |
| Spinner.vue | `app/javascript/dashboard/components-next/spinner/Spinner.vue` | ソース | ローディングコンポーネント |
| useUISettings.js | `app/javascript/dashboard/composables/useUISettings.js` | ソース | UISettings composable |
