# 画面設計書 106-ドキュメント一覧画面

## 概要

Captain AIアシスタントの学習ドキュメントを管理するための一覧画面設計書です。AIアシスタントの回答精度を向上させるためのナレッジベースとなるドキュメントの表示、追加、削除、関連FAQの確認機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：Captain AIは企業のドキュメント（ヘルプ記事、FAQ、マニュアルなど）を学習し、顧客からの問い合わせに対して適切な回答を生成します。この画面では、AIが参照するドキュメントを管理し、ナレッジベースの品質と網羅性を維持します。ドキュメントを追加することで、AIの回答精度が向上します。

**画面へのアクセス方法**：Captain機能のサイドナビゲーションから「Documents」を選択してアクセスします。URLパスは `/app/accounts/:accountId/captain/:assistantId/documents` です。

**主要な操作・処理内容**：
1. ドキュメント一覧の表示（ページネーション対応）
2. 新規ドキュメントの追加（URL指定）
3. ドキュメントの削除
4. ドキュメントに関連するFAQの表示

**画面遷移**：
- 遷移元：Captainアシスタント一覧画面、サイドナビゲーション
- 遷移先：関連FAQ表示ダイアログ（モーダル）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 92 | ドキュメント管理 | 主機能 | 学習ドキュメントの一覧表示、追加、削除 |

## 画面種別

一覧 / 登録（ダイアログ）

## URL/ルーティング

| パス | ルート名 |
|------|----------|
| `/app/accounts/:accountId/captain/:assistantId/documents` | `captain_assistants_documents_index` |

## 入出力項目

### ドキュメント追加フォーム

| 項目名 | 物理名 | 型 | 必須 | バリデーション | 備考 |
|--------|--------|-----|------|---------------|------|
| 外部リンク | external_link | string | Yes | URL形式 | ドキュメントURL |
| 名前 | name | string | No | - | 表示名（未指定時はURL使用） |

### 出力項目（一覧）

| 項目名 | 物理名 | 型 | 備考 |
|--------|--------|-----|------|
| ドキュメントID | id | number | 内部識別子 |
| 名前 | name | string | ドキュメント名 |
| 外部リンク | external_link | string | ドキュメントURL |
| アシスタント | assistant | object | 関連アシスタント情報 |
| 作成日時 | created_at | datetime | 作成日時 |

## 表示項目

### ヘッダー領域

| 項目名 | 表示形式 | 備考 |
|--------|----------|------|
| タイトル | "Documents" | ヘッダータイトル |
| Add newボタン | プライマリボタン | administratorのみ表示 |

### バナー表示

| 項目名 | 表示形式 | 条件 | 備考 |
|--------|----------|------|------|
| 制限バナー | LimitBanner | 制限超過時 | 使用量警告 |

### ドキュメントカード

| 項目名 | 表示形式 | 備考 |
|--------|----------|------|
| ドキュメント名 | テキスト（太字） | 名前またはURL |
| 外部リンク | リンクテキスト | 新しいタブで開く |
| アシスタント情報 | バッジ | 関連アシスタント |
| 作成日時 | 相対日時 | フォーマット済み |
| アクションメニュー | ドロップダウン | 関連FAQ表示/削除 |

### ページネーション

| 項目名 | 表示形式 | 備考 |
|--------|----------|------|
| 現在ページ | テキスト | ページ番号表示 |
| 総件数 | テキスト | 総レコード数 |
| ページ送りボタン | ボタン群 | 前後ナビゲーション |

## イベント仕様

### 1-ドキュメント追加

1. 「Add new」ボタンをクリック
2. `handleCreateDocument()` が呼び出される
3. `CreateDocumentDialog` がモーダル表示される
4. URL入力後、Submit時に `captainDocuments/create` アクションが dispatch される
5. API成功時：成功メッセージ表示、ダイアログクローズ、一覧更新
6. API失敗時：エラーメッセージ表示

### 2-ドキュメント削除

1. ドキュメントカードのメニューから「Delete」を選択
2. `handleAction({action: 'delete', id})` が呼び出される
3. `DeleteDialog` が表示される
4. 確認後、`captainDocuments/delete` アクションが dispatch される
5. API成功時：成功メッセージ表示、一覧更新

### 3-関連FAQ表示

1. ドキュメントカードのメニューから「View related questions」を選択
2. `handleAction({action: 'viewRelatedQuestions', id})` が呼び出される
3. `RelatedResponses` ダイアログが表示される
4. 該当ドキュメントから生成されたFAQ一覧を表示

### 4-ページ遷移

1. ページネーションボタンをクリック
2. `onPageChange(page)` が呼び出される
3. `fetchDocuments(page)` でデータ取得

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ドキュメント一覧取得 | captain_documents | SELECT | アシスタントのドキュメント取得 |
| ドキュメント追加 | captain_documents | INSERT | 新規ドキュメント作成 |
| ドキュメント削除 | captain_documents | DELETE | ドキュメント削除 |

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

#### captain_documents

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | - | `assistant_id = :assistantId` | 一覧取得条件 |
| INSERT | name | フォーム入力値 | ドキュメント名 |
| INSERT | external_link | フォーム入力値 | ドキュメントURL |
| INSERT | assistant_id | URLパラメータ | アシスタントID |
| DELETE | - | `id = :documentId` | 指定ID削除 |

## メッセージ仕様

| 種別 | メッセージキー | メッセージ内容 |
|------|---------------|---------------|
| 成功 | CAPTAIN.DOCUMENTS.CREATE.SUCCESS_MESSAGE | ドキュメント追加成功 |
| エラー | CAPTAIN.DOCUMENTS.CREATE.ERROR_MESSAGE | ドキュメント追加失敗 |
| 成功 | CAPTAIN.DOCUMENTS.DELETE.SUCCESS_MESSAGE | ドキュメント削除成功 |
| エラー | CAPTAIN.DOCUMENTS.DELETE.ERROR_MESSAGE | ドキュメント削除失敗 |

## 例外処理

| 例外条件 | 処理内容 | 表示 |
|----------|----------|------|
| データ取得中 | isFetchingフラグでローディング表示 | Spinner |
| ドキュメント0件 | 空状態表示 | DocumentPageEmptyState |
| API通信エラー | アラート表示 | エラーメッセージ |
| 最後の1件削除後 | 前のページに遷移 | 自動ページ調整 |
| Captain未有効 | Paywallコンポーネント表示 | アップグレード案内 |

## 備考

- ドキュメントはURL指定で追加（外部Webページ、ヘルプセンター記事など）
- 追加されたドキュメントはバックグラウンドでクロール・インデックス化される
- 関連FAQはドキュメントから自動生成されたQ&Aを表示
- show-know-more=false でKnow moreボタンは非表示

---

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

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

### 推奨読解順序

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

まず、ドキュメントデータの構造とストアの状態管理を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | document.js (store) | `app/javascript/dashboard/store/captain/document.js` | ストア定義、createStoreによる自動生成 |
| 1-2 | document.js (api) | `app/javascript/dashboard/api/captain/document.js` | APIクライアント、getメソッドのパラメータを確認 |

**読解のコツ**: `createStore` ベースで基本CRUDが自動生成されています。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Index.vue (documents) | `app/javascript/dashboard/routes/dashboard/captain/documents/Index.vue` | メインコンポーネントの構造を確認 |

**主要処理フロー**:
1. **22-25行目**: ストアゲッターの取得
2. **27行目**: `selectedAssistantId` をルートパラメータから取得
3. **41-48行目**: `handleCreateDocument()` でダイアログ表示
4. **58-70行目**: `handleAction()` で削除/関連FAQ表示の振り分け
5. **72-79行目**: `fetchDocuments()` でデータ取得
6. **89-91行目**: `onMounted` で初期化

#### Step 3: 関連FAQダイアログを理解する

関連FAQ表示の実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | RelatedResponses.vue | `app/javascript/dashboard/components-next/captain/pageComponents/document/RelatedResponses.vue` | 関連FAQ表示ダイアログの実装 |

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | document.js (api) | `app/javascript/dashboard/api/captain/document.js` | getメソッドでassistant_idパラメータ対応 |

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

```
Index.vue (documents)
    |
    +-- PageLayout.vue
    |       |
    |       +-- ヘッダー、ボタン、ページネーション
    |
    +-- LimitBanner.vue
    |
    +-- DocumentCard.vue (複数)
    |       |
    |       +-- @action -> handleAction()
    |
    +-- RelatedResponses.vue
    |       |
    |       +-- ドキュメント関連FAQモーダル
    |
    +-- CreateDocumentDialog.vue
    |       |
    |       +-- URL入力フォーム
    |       +-- captainDocuments/create
    |
    +-- DeleteDialog.vue
            |
            +-- 削除確認
            +-- captainDocuments/delete
```

### データフロー図

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

URLアクセス ──────────▶ onMounted
                              │
                              └── fetchDocuments()
                                      │
                                      ▼
                        GET /api/v1/.../captain/documents
                        (assistant_id=:assistantId)
                              │
                              ▼
                        Vuex State更新
                              │
                              ▼
                        DocumentCard描画 ────────▶ ドキュメント一覧

追加ボタン ────────────▶ handleCreateDocument()
                              │
                              ▼
                        CreateDocumentDialog
                              │
                              ▼
                        captainDocuments/create
                              │
                              ▼
                        POST /api/v1/.../captain/documents

関連FAQ ──────────────▶ handleAction({viewRelatedQuestions})
                              │
                              ▼
                        RelatedResponses表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Index.vue | `app/javascript/dashboard/routes/dashboard/captain/documents/Index.vue` | ソース | メイン画面コンポーネント |
| captain.routes.js | `app/javascript/dashboard/routes/dashboard/captain/captain.routes.js` | 設定 | ルーティング定義 |
| document.js (store) | `app/javascript/dashboard/store/captain/document.js` | ソース | Vuexストアモジュール |
| document.js (api) | `app/javascript/dashboard/api/captain/document.js` | ソース | APIクライアント |
| DocumentCard.vue | `app/javascript/dashboard/components-next/captain/assistant/DocumentCard.vue` | ソース | ドキュメントカード |
| CreateDocumentDialog.vue | `app/javascript/dashboard/components-next/captain/pageComponents/document/CreateDocumentDialog.vue` | ソース | 作成ダイアログ |
| RelatedResponses.vue | `app/javascript/dashboard/components-next/captain/pageComponents/document/RelatedResponses.vue` | ソース | 関連FAQ表示 |
| DeleteDialog.vue | `app/javascript/dashboard/components-next/captain/pageComponents/DeleteDialog.vue` | ソース | 削除確認ダイアログ |
| DocumentPageEmptyState.vue | `app/javascript/dashboard/components-next/captain/pageComponents/emptyStates/DocumentPageEmptyState.vue` | ソース | 空状態表示 |
| LimitBanner.vue | `app/javascript/dashboard/components-next/captain/pageComponents/document/LimitBanner.vue` | ソース | 制限バナー |
