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

## 概要

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

### 本画面の処理概要

本画面は、特定のインボックスのパフォーマンス指標を詳細に分析するためのレポート画面です。

**業務上の目的・背景**：インボックスレポート概要画面（No.34）から特定のインボックスを選択した際に、そのインボックスの詳細なパフォーマンス分析を行うことができます。会話数、受信メッセージ数、送信メッセージ数、平均初回応答時間、平均解決時間、解決数などの指標を時系列グラフで可視化し、パフォーマンスの推移を把握することで、チャネル運用の改善やリソース配分の最適化を行うことができます。

**画面へのアクセス方法**：インボックスレポート概要画面（No.34）のテーブルでインボックス名をクリックすることでアクセスできます。URLは `/app/accounts/:accountId/reports/inboxes/:id` です。

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

**画面遷移**：
- 遷移元：インボックスレポート概要画面（No.34）
- 遷移先：インボックスレポート概要画面（戻るボタン）

**権限による表示制御**：本画面は `administrator` または `report_manage` 権限を持つユーザーのみがアクセス可能です。権限がない場合はアクセスが拒否されます。

## 関連機能

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

## 画面種別

詳細

## URL/ルーティング

- パス: `/app/accounts/:accountId/reports/inboxes/:id`
- ルート名: `inbox_reports_show`
- コンポーネント: `InboxReportsShow.vue`
- パラメータ: `id` - インボックスのID

## 入出力項目

### フィルタ入力項目

| 項目名 | 項目ID | データ型 | 必須 | 初期値 | 説明 |
|--------|--------|----------|------|--------|------|
| 日付範囲 | 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. URLパラメータからインボックスIDを取得
2. `useFunctionGetter` で `inboxes/getInboxById` を使用して該当インボックスの情報を取得
3. インボックス情報が取得できたら `WootReports` コンポーネントを表示

### 2-日付範囲変更

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

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

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

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

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

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

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

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

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

### 6-戻るボタン

戻るボタンをクリックすると、前の画面に戻ります。

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

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

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

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

#### inboxes

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, name | id = URLパラメータのID | インボックス情報取得 |

#### conversations

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

#### reporting_events

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, value, value_in_business_hours, timestamp | inbox_id = 対象インボックス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」メッセージを表示 |

## 備考

- インボックスタイプのレポートでは `INCOMING_MESSAGES` メトリクスも表示される
- 時間値は `formatTime` ユーティリティ関数で人間が読みやすい形式に変換される
- グループ化オプションは選択された日付範囲に応じて動的に変更される

---

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

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

### 推奨読解順序

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | InboxReportsShow.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/InboxReportsShow.vue` | インボックス取得ロジック（8-9行目）、WootReportsへのprops（13-26行目） |

**主要処理フロー**:
1. **8行目**: ルートパラメータからインボックスIDを取得
2. **9行目**: `useFunctionGetter` でインボックス情報をリアクティブに取得
3. **13-26行目**: インボックス情報がある場合に `WootReports` を表示

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | WootReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/WootReports.vue` | type='inbox' での reportKeys 定義（84-96行目、INCOMING_MESSAGESを含む） |

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

```
InboxReportsShow.vue
    │
    ├─ useFunctionGetter('inboxes/getInboxById', id)
    │
    └─ WootReports.vue (type='inbox')
           │
           ├─ store.dispatch('inboxes/get')
           │
           ├─ ReportHeader.vue (has-back-button)
           │      └─ V4Button (Download)
           │
           ├─ ReportFilters.vue
           │
           └─ ReportContainer.vue
                  ├─ ChartStats.vue (includes INCOMING_MESSAGES)
                  └─ BarChart.vue
```

### データフロー図

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

URLパラメータ (:id) ───────▶ useFunctionGetter ──────────────▶ inbox オブジェクト
       │                        │
       ▼                        ▼
日付範囲フィルタ ───────▶ WootReports.fetchAllData()
       │                        │
       │                        ├─▶ fetchAccountSummary
       │                        │         │
       │                        │         ▼
       │                        │   ChartStats表示
       │                        │
       │                        └─▶ fetchChartData
       │                                  │
       │                                  ▼
       │                            BarChart表示
       │
グループ化フィルタ ─────────▶ groupBy 更新 → 再フェッチ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| InboxReportsShow.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/InboxReportsShow.vue` | ソース | 画面エントリーポイント |
| WootReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/WootReports.vue` | ソース | 詳細レポートコンポーネント |
| ReportHeader.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/ReportHeader.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` | 設定 | 翻訳ファイル |
