# 画面設計書 44-ボットレポート画面

## 概要

本ドキュメントは、Chatwootのボットレポート画面の設計仕様を定義するものである。

### 本画面の処理概要

エージェントボット（チャットボット）のパフォーマンスを分析・可視化する画面。ボットによる自動解決数、ハンドオフ（人間のエージェントへの引き継ぎ）数などのメトリクスをチャートとサマリーで表示する。

**業務上の目的・背景**：エージェントボットは、顧客からの問い合わせに対して自動応答を行う機能である。ボットがどの程度の会話を自動で解決できているか、どの程度が人間のエージェントに引き継がれているかを把握することで、ボットの有効性を評価し、改善ポイントを特定できる。ボットの解決率が高ければサポートコストの削減につながり、低ければボットの学習データや応答ロジックの見直しが必要となる。

**画面へのアクセス方法**：サイドメニューの「レポート」から「ボット」を選択することでアクセスする。管理者またはレポート管理権限を持つユーザーのみがアクセス可能。

**主要な操作・処理内容**：
1. 期間フィルタによるレポート期間の選択
2. グループ化オプションによる集計単位の変更
3. ボットメトリクス（解決数、ハンドオフ数、解決率）の確認
4. 時系列チャートによる推移の可視化

**画面遷移**：
- 遷移元：レポートメニュー
- 遷移先：特になし（単独表示画面）

**権限による表示制御**：管理者（administrator）およびレポート管理権限（report_manage）を持つユーザーのみがアクセス可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 117 | ボット分析 | 主機能 | ボットパフォーマンス分析 |

## 画面種別

詳細

## URL/ルーティング

```
/app/accounts/:accountId/reports/bot
```

- ルート名: `bot_reports`
- パラメータ:
  - `accountId`: アカウントID

## 入出力項目

### フィルタ入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| 期間（from/to） | Date | ○ | レポート対象期間 |
| グループ化 | Select | ○ | 日/週/月による集計単位 |

## 表示項目

### レポートヘッダー

| 項目名 | 型 | 説明 |
|--------|-----|------|
| レポートタイトル | String | 「ボットレポート」 |

### ボットメトリクス

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ボット解決数 | Number | ボットが自動解決した会話数 |
| ハンドオフ数 | Number | 人間のエージェントに引き継がれた会話数 |
| ボット解決率 | Percentage | 解決数 / (解決数 + ハンドオフ数) * 100 |

### チャート表示

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ボット解決数チャート | LineChart | 期間別のボット解決数推移 |
| ハンドオフ数チャート | LineChart | 期間別のハンドオフ数推移 |

## イベント仕様

### 1-フィルタ変更イベント

**トリガー**: 期間フィルタまたはグループ化オプションの変更時

**処理フロー**:
1. ユーザーがフィルタ条件を変更
2. `onFilterChange`メソッドが呼び出される
3. from, to, groupBy, businessHours状態が更新される
4. `fetchAllData`メソッドが呼び出される
5. `fetchBotSummary`でサマリーデータ取得
6. `fetchChartData`で各メトリクスのチャートデータ取得
7. 画面が更新される

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| フィルタ変更 | reporting_events | SELECT | ボットメトリクスの集計 |
| フィルタ変更 | conversations | SELECT | ボット関連会話の集計 |

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

#### reporting_events

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | account_id | 現在のアカウントID | フィルタ条件 |
| SELECT | name | bot_resolutions_count / bot_handoffs_count | メトリクスタイプ |
| SELECT | created_at | フィルタ期間内 | 期間フィルタ |

## メッセージ仕様

| 種別 | メッセージキー | メッセージ内容 |
|------|---------------|---------------|
| エラー | REPORT.SUMMARY_FETCHING_FAILED | サマリーの取得に失敗しました |
| エラー | REPORT.DATA_FETCHING_FAILED | データの取得に失敗しました |

## 例外処理

| 例外状態 | 処理内容 |
|----------|---------|
| API通信エラー | エラートースト表示 |
| 権限不足 | 403エラー、アクセス拒否画面表示 |
| データなし | ゼロ値のメトリクスと空のチャート表示 |

## 備考

- ボットレポートはエージェントボット機能が有効な場合に意味を持つ
- エージェントフィルタは非表示（show-agents-filter="false"）
- 営業時間ベースの計算は非表示（show-business-hours-switch="false"）
- reportKeysにはBOT_RESOLUTION_COUNTとBOT_HANDOFF_COUNTの2種類を定義

---

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

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

### 推奨読解順序

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

まず、ボットレポートデータの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | reports.js | `app/javascript/dashboard/store/modules/reports.js` | getBotSummary getter |

**読解のコツ**:
- ボットレポート専用のsummaryKeyとして`getBotSummary`を使用
- fetchingStatusとして`getBotSummaryFetchingStatus`を使用

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | BotReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/BotReports.vue` | メインコンポーネント |

**主要処理フロー**:
1. **L19-28**: data定義 - from, to, groupBy, reportKeys, businessHours
2. **L23-26**: reportKeys - BOT_RESOLUTION_COUNT, BOT_HANDOFF_COUNT定義
3. **L38-77**: methods - fetchAllData, fetchBotSummary, fetchChartData

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

メトリクスとチャートを担当するコンポーネント。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | BotMetrics.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/BotMetrics.vue` | メトリクス表示 |
| 3-2 | ReportFilterSelector.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/FilterSelector.vue` | フィルタUI |
| 3-3 | ReportContainer.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/ReportContainer.vue` | チャート表示コンテナ |

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

バックエンドとの通信。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | reports.js | `app/javascript/dashboard/api/reports.js` | レポートAPI |

#### Step 5: バックエンドを理解する

Rails側のコントローラとビルダー。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | reports_controller.rb | `app/controllers/api/v2/accounts/reports_controller.rb` | bot_summary, bot_metricsエンドポイント |

**主要処理フロー**:
- **L17-19**: bot_summary - ボットサマリー取得
- **L60-63**: bot_metrics - ボットメトリクス取得

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

```
BotReports.vue
    │
    ├─ ReportFilterSelector (子コンポーネント)
    │      └─ @filter-change → onFilterChange()
    │             └─ fetchAllData()
    │                    ├─ fetchBotSummary()
    │                    │      └─ fetchBotSummary dispatch
    │                    │             └─ GET /api/v2/.../reports/bot_summary
    │                    │
    │                    └─ fetchChartData()
    │                           └─ fetchAccountReport dispatch (各メトリクス)
    │                                  └─ GET /api/v2/.../reports
    │
    ├─ BotMetrics (子コンポーネント)
    │      └─ props: filters
    │             └─ 内部でbot_metrics APIを呼び出し
    │
    └─ ReportContainer (子コンポーネント)
           └─ props: account-summary-key="getBotSummary"
                     summary-fetching-key="getBotSummaryFetchingStatus"
                     report-keys={BOT_RESOLUTION_COUNT, BOT_HANDOFF_COUNT}
```

### データフロー図

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

期間フィルタ   ───▶  fetchBotSummary()       ───▶  サマリーメトリクス
                            │                        (解決数、ハンドオフ数)
グループ化     ───▶  fetchChartData()        ───▶  時系列チャート
                            │
                     BotMetrics内部           ───▶  解決率計算
                            │
                     bot_metrics API         ───▶  詳細メトリクス
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| BotReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/BotReports.vue` | ソース | メイン画面コンポーネント |
| BotMetrics.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/BotMetrics.vue` | ソース | メトリクス表示コンポーネント |
| FilterSelector.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/FilterSelector.vue` | ソース | フィルタコンポーネント |
| ReportContainer.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/ReportContainer.vue` | ソース | チャート表示コンテナ |
| ReportHeader.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/ReportHeader.vue` | ソース | ヘッダーコンポーネント |
| reports.routes.js | `app/javascript/dashboard/routes/dashboard/settings/reports/reports.routes.js` | 設定 | ルーティング定義 |
| reports.js (store) | `app/javascript/dashboard/store/modules/reports.js` | ソース | Vuexストアモジュール |
| reports.js (api) | `app/javascript/dashboard/api/reports.js` | ソース | APIクライアント |
| reports_controller.rb | `app/controllers/api/v2/accounts/reports_controller.rb` | ソース | Railsコントローラ |
| BotMetricsBuilder | `app/builders/v2/reports/bot_metrics_builder.rb` | ソース | メトリクス計算ロジック |
