# 画面設計書 33-インボックスレポート画面

## 概要

本ドキュメントは、Chatwootのインボックスレポート画面（旧バージョン）の設計仕様を定義するものです。

### 本画面の処理概要

本画面は、特定のインボックスを選択してパフォーマンス指標を詳細に分析するためのレポート画面です。旧版のレポートUIを提供しています。

**業務上の目的・背景**：顧客サポートでは複数のチャネル（メール、チャット、SNSなど）からの問い合わせを「インボックス」として管理します。本画面では、特定のインボックスを選択し、そのインボックスにおける会話数、受信メッセージ数、送信メッセージ数、平均初回応答時間、平均解決時間、解決数などの指標を時系列グラフで可視化します。これにより、チャネルごとのパフォーマンスを把握し、リソース配分やサービス改善の意思決定を行うことができます。

**画面へのアクセス方法**：ダッシュボードのサイドメニューから「レポート」を選択し、サブメニューから「Inbox」を選択することでアクセスできます。URLは `/app/accounts/:accountId/reports/inboxes` です。

**主要な操作・処理内容**：
1. インボックス選択ドロップダウンで分析対象のインボックスを選択
2. 日付範囲フィルタで集計期間を指定（過去7日、30日、3ヶ月、6ヶ月、1年、カスタム期間）
3. グループ化フィルタで集計単位を変更（日/週/月/年）
4. ビジネスアワートグルで営業時間内のみの統計に切り替え
5. 各メトリクスのバーチャートでパフォーマンス推移を確認
6. レポートダウンロードボタンでCSV形式のレポートをエクスポート

**画面遷移**：
- 遷移元：レポートホーム画面、サイドメニュー
- 遷移先：なし（単独画面）

**権限による表示制御**：本画面は `administrator` または `report_manage` 権限を持つユーザーのみがアクセス可能です。また、FEATURE_FLAGS.REPORTS 機能フラグが有効である必要があります。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 111 | インボックス別レポート | 主機能 | インボックス別統計の表示 |

## 画面種別

詳細

## URL/ルーティング

- パス: `/app/accounts/:accountId/reports/inboxes`
- ルート名: `inbox_reports`
- コンポーネント: `InboxReports.vue`

## 入出力項目

### フィルタ入力項目

| 項目名 | 項目ID | データ型 | 必須 | 初期値 | 説明 |
|--------|--------|----------|------|--------|------|
| インボックス | selectedFilter | Object | Yes | 最初のインボックス | 分析対象のインボックス |
| 日付範囲 | dateRange | Object | Yes | 過去7日 | 集計対象期間 |
| グループ化 | groupBy | Object | No | Day | 集計単位（日/週/月/年） |
| ビジネスアワー | businessHours | Boolean | No | false | 営業時間内のみで集計 |

## 表示項目

### メトリクスカード

| 項目名 | 項目ID | データ型 | 説明 |
|--------|--------|----------|------|
| 会話数 | conversations_count | Number | 期間内の会話総数 |
| 受信メッセージ数 | incoming_messages_count | Number | 期間内に受信したメッセージ数 |
| 送信メッセージ数 | outgoing_messages_count | Number | 期間内に送信したメッセージ数 |
| 平均初回応答時間 | avg_first_response_time | Number | 平均初回応答時間（秒） |
| 平均解決時間 | avg_resolution_time | Number | 平均解決時間（秒） |
| 解決数 | resolutions_count | Number | 解決した会話の総数 |
| 顧客待機時間 | reply_time | Number | 平均顧客待機時間（秒） |

### 各メトリクスの時系列チャート

各メトリクスについて、選択された期間とグループ化単位に応じたバーチャートが表示されます。

## イベント仕様

### 1-インボックス選択変更

インボックスを選択すると、そのインボックスのレポートデータが取得されます。

**処理フロー**:
1. ドロップダウンからインボックスを選択
2. `onFilterChange` イベントハンドラが発火
3. `selectedFilter` を更新
4. `fetchAllData` が呼び出される
5. Vuex Actions `fetchAccountSummary` と `fetchAccountReport` をディスパッチ

### 2-日付範囲変更

日付範囲フィルタを変更すると、選択された期間に基づいてレポートが再取得されます。

**処理フロー**:
1. ユーザーが日付範囲ドロップダウンから期間を選択
2. `onDateRangeChange` イベントハンドラが発火
3. `from`（開始Unix時間）と`to`（終了Unix時間）を計算
4. `fetchAllData` が呼び出される

### 3-グループ化フィルタ変更

グループ化フィルタを変更すると、集計単位が変更されてレポートが再取得されます。

**処理フロー**:
1. ユーザーがグループ化ドロップダウンから単位を選択
2. `onGroupByFilterChange` イベントハンドラが発火
3. `groupBy` を更新して `fetchAllData` を呼び出し

### 4-ビジネスアワートグル変更

営業時間フラグを切り替えると、営業時間内のみの統計が表示されます。

**処理フロー**:
1. トグルスイッチを切り替え
2. `onBusinessHoursToggle` イベントハンドラが発火
3. `businessHours` パラメータを更新
4. `fetchAllData` を呼び出してデータを再取得

### 5-レポートダウンロード

「Download inbox reports」ボタンをクリックすると、CSVファイルがダウンロードされます。

**処理フロー**:
1. ダウンロードボタンをクリック
2. `downloadReports` メソッドが呼び出される
3. Vuex Action `downloadInboxReports` をディスパッチ
4. API `GET /api/v2/accounts/:accountId/reports/inboxes` を呼び出し
5. レスポンスをCSVファイルとしてダウンロード

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示時 | inboxes | SELECT | インボックス一覧取得 |
| インボックス選択時 | conversations, reporting_events, messages | SELECT | インボックス別レポートデータ取得 |
| フィルタ変更時 | conversations, reporting_events, messages | SELECT | 条件に基づくデータ再取得 |

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

#### inboxes

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, name | account_id = 現在のアカウント | フィルタドロップダウン用 |

#### conversations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, inbox_id, created_at | inbox_id = 選択インボックス、期間内 | 会話数算出用 |

#### reporting_events

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, value, value_in_business_hours, timestamp | inbox_id = 選択インボックス、期間内 | 各種メトリクス算出用 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 表示条件 |
|-------------|------|-----------|----------|
| LOADING_CHART | 情報 | Loading chart data... | データ取得中 |
| NO_ENOUGH_DATA | 警告 | We've not received enough data points to generate report, Please try again later. | データ不足時 |
| DATA_FETCHING_FAILED | エラー | Failed to fetch data, please try again later. | API呼び出し失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| インボックスが存在しない | 空のドロップダウンを表示 |
| API呼び出し失敗 | エラーメッセージを表示 |
| 権限不足 | 画面アクセス拒否（ルートガードで制御） |
| データなし | 「We've not received enough data points」メッセージを表示 |

## 備考

- この画面は旧バージョンのUIです。新しいUI（インボックスレポート概要画面 No.34）が推奨されます
- WootReports コンポーネントを再利用し、type='inbox' として表示
- インボックスタイプでは `INCOMING_MESSAGES` メトリクスも表示される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | reports.js (store) | `app/javascript/dashboard/store/modules/reports.js` | accountReport と accountSummary の状態定義 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | InboxReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/InboxReports.vue` | WootReportsへのprops（6-13行目） |

**主要処理フロー**:
1. **7行目**: key="inbox-reports" でコンポーネントをユニークに識別
2. **8行目**: type="inbox" でインボックスレポートとして設定
3. **9行目**: getter-key="inboxes/getInboxes" でインボックス一覧を取得
4. **10行目**: action-key="inboxes/get" でインボックス一覧をフェッチ

#### Step 3: WootReportsコンポーネントの理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | WootReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/WootReports.vue` | インボックスタイプでの reportKeys 定義（84-96行目） |

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

```
InboxReports.vue
    │
    └─ WootReports.vue
           │
           ├─ store.dispatch('inboxes/get')
           │
           ├─ $store.getters['inboxes/getInboxes']
           │
           ├─ ReportHeader.vue
           │      └─ V4Button (Download)
           │             └─ downloadInboxReports()
           │
           ├─ ReportFilters.vue (type='inbox')
           │      ├─ inbox selector
           │      ├─ dateRange selector
           │      ├─ groupBy selector
           │      └─ businessHours toggle
           │
           └─ ReportContainer.vue
                  ├─ ChartStats.vue
                  └─ BarChart.vue
```

### データフロー図

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

インボックス選択 ───────▶ WootReports.onFilterChange()
       │                        │
       │                        ▼
       │                  selectedFilter 更新
       │                        │
日付範囲フィルタ ───────▶ fetchAllData()
       │                        │
       │                        ├─▶ fetchAccountSummary
       │                        │         │
       │                        │         ▼
       │                        │   GET /api/v2/.../reports/summary
       │                        │         │
       │                        │         ▼
       │                        │   ChartStats表示
       │                        │
       │                        └─▶ fetchChartData
       │                                  │
       │                                  ▼
       │                            GET /api/v2/.../reports
       │                                  │
       │                                  ▼
       │                            BarChart表示
       │
グループ化フィルタ ─────────▶ groupBy 更新 → 再フェッチ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| InboxReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/InboxReports.vue` | ソース | 画面エントリーポイント |
| WootReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/WootReports.vue` | ソース | 詳細レポートコンポーネント |
| ReportFilters.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/ReportFilters.vue` | ソース | フィルタコンポーネント |
| ReportContainer.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/ReportContainer.vue` | ソース | チャートコンテナ |
| reports.js (store) | `app/javascript/dashboard/store/modules/reports.js` | ソース | Vuex Store モジュール |
| reports.routes.js | `app/javascript/dashboard/routes/dashboard/settings/reports/reports.routes.js` | ソース | ルート定義 |
| report.json | `app/javascript/dashboard/i18n/locale/en/report.json` | 設定 | 翻訳ファイル |
