# 画面設計書 28-レポート概要画面

## 概要

本ドキュメントは、Chatwootのレポート概要（Overview Reports）画面の設計仕様を記述したものである。

### 本画面の処理概要

レポート概要画面は、カスタマーサポート業務のリアルタイム統計情報を表示するダッシュボード画面である。

**業務上の目的・背景**：カスタマーサポートのマネージャーやスーパーバイザーにとって、チームの現在の状況をリアルタイムで把握することは重要である。本画面により、現在の会話数、対応状況、エージェントの稼働状況、会話の発生パターンなどを一目で確認でき、リソース配分やチーム運営の意思決定に活用できる。

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

**主要な操作・処理内容**：
1. ライブ統計情報の表示（オープン会話数、未対応数など）
2. 会話ヒートマップの表示（時間帯別の会話発生パターン）
3. 解決ヒートマップの表示（時間帯別の解決パターン）
4. エージェント別のライブレポート表示
5. チーム別のライブレポート表示

**画面遷移**：ダッシュボードホーム、他のレポート画面から遷移可能。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 118 | ライブレポート | 主機能 | リアルタイム統計の表示 |

## 画面種別

ダッシュボード / レポート

## URL/ルーティング

| パス | ルート名 | 説明 |
|------|----------|------|
| `/app/accounts/:accountId/reports/overview` | reports_overview | レポート概要画面 |

## 入出力項目

### 入力項目

なし（自動でリアルタイムデータを取得）

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| liveStats | Object | リアルタイム統計データ |
| conversationHeatmap | Array | 会話ヒートマップデータ |
| resolutionHeatmap | Array | 解決ヒートマップデータ |
| agentLiveReport | Array | エージェント別ライブレポート |
| teamLiveReport | Array | チーム別ライブレポート |

## 表示項目

### ヘッダー

| 項目名 | 説明 |
|--------|------|
| タイトル | 「概要レポート」（i18nキー: OVERVIEW_REPORTS.HEADER） |

### ライブ統計カード

| 項目名 | 説明 |
|--------|------|
| オープン会話数 | 現在オープンな会話の数 |
| 未対応会話数 | 未割り当ての会話数 |
| 対応中会話数 | エージェントが対応中の会話数 |
| 解決済み会話数 | 解決済みの会話数 |

### 会話ヒートマップ

| 項目名 | 説明 |
|--------|------|
| 時間帯 | 0-23時 |
| 曜日 | 月-日 |
| 会話数 | 各セルの会話発生数（色の濃さで表現） |

### 解決ヒートマップ

| 項目名 | 説明 |
|--------|------|
| 時間帯 | 0-23時 |
| 曜日 | 月-日 |
| 解決数 | 各セルの解決数（色の濃さで表現） |

### エージェントライブレポート

| 項目名 | 説明 |
|--------|------|
| エージェント名 | エージェントの表示名 |
| オンライン状態 | Online/Offline/Away |
| オープン会話数 | 担当中のオープン会話数 |

### チームライブレポート

| 項目名 | 説明 |
|--------|------|
| チーム名 | チームの表示名 |
| オープン会話数 | チームのオープン会話数 |

## イベント仕様

### 1-画面初期表示

画面マウント時、各種ライブデータを取得する。

**処理フロー**:
1. 各コンテナコンポーネントが個別にデータ取得
2. `StatsLiveReportsContainer`でライブ統計取得
3. `ConversationHeatmapContainer`で会話ヒートマップ取得
4. `ResolutionHeatmapContainer`で解決ヒートマップ取得
5. `AgentLiveReportContainer`でエージェント別レポート取得
6. `TeamLiveReportContainer`でチーム別レポート取得

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面初期表示 | conversations, agents, teams | SELECT | 各種集計クエリ実行 |

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

本画面は参照のみで更新処理なし。

#### conversations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | status, created_at, resolved_at | アカウント内のデータを集計 | ライブ統計、ヒートマップ用 |

## メッセージ仕様

| 種別 | コード | メッセージ | 表示条件 |
|------|--------|-----------|----------|
| 情報 | - | ローディング状態 | データ取得中 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|---------|
| API通信エラー | ローディング状態を解除、コンポーネント個別にエラーハンドリング |
| 権限不足 | 画面へのアクセスがブロック |

## 備考

- ライブレポートはリアルタイム性が高いため、ページ遷移のたびに最新データを取得
- ヒートマップは過去7日間のデータを表示
- 各セクションは独立したコンテナコンポーネントで実装されている
- 管理者権限が必要

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | reports.js (api) | `app/javascript/dashboard/api/reports.js` | APIレスポンスの構造を確認 |

**読解のコツ**: APIメソッドのパラメータとレスポンス形式を見ることで、どのようなデータが取得されるか把握できる。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | LiveReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/LiveReports.vue` | 画面のメインコンポーネント、構成を確認 |

**主要処理フロー**:
1. **行2-6**: 各コンテナコンポーネントをインポート
2. **行11**: ヘッダーにタイトル表示
3. **行12-17**: 各コンテナコンポーネントを縦に配置

#### Step 3: 各コンテナコンポーネントを理解する

個別のレポートセクションを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | StatsLiveReportsContainer.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/StatsLiveReportsContainer.vue` | ライブ統計の取得・表示 |
| 3-2 | ConversationHeatmapContainer.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/heatmaps/ConversationHeatmapContainer.vue` | 会話ヒートマップ |
| 3-3 | ResolutionHeatmapContainer.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/heatmaps/ResolutionHeatmapContainer.vue` | 解決ヒートマップ |
| 3-4 | AgentLiveReportContainer.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/AgentLiveReportContainer.vue` | エージェント別レポート |
| 3-5 | TeamLiveReportContainer.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/TeamLiveReportContainer.vue` | チーム別レポート |

#### Step 4: APIレイヤーを理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | reports.js | `app/javascript/dashboard/api/reports.js` | getConversationMetric等のメソッド |

**主要処理フロー**:
- **行49-56**: `getConversationMetric`でライブ統計取得
- **行70-74**: `getConversationTrafficCSV`でヒートマップデータ取得

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

```
LiveReports.vue (View層)
    │
    ├─ ReportHeader
    │      └─ 「概要レポート」タイトル表示
    │
    ├─ StatsLiveReportsContainer
    │      └─ API呼び出し（ライブ統計）
    │
    ├─ ConversationHeatmapContainer
    │      └─ ReportsAPI.getConversationTrafficCSV()
    │
    ├─ ResolutionHeatmapContainer
    │      └─ API呼び出し（解決ヒートマップ）
    │
    ├─ AgentLiveReportContainer
    │      └─ API呼び出し（エージェント別）
    │
    └─ TeamLiveReportContainer
           └─ API呼び出し（チーム別）
```

### データフロー図

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

なし ───────────────────▶ 各コンテナコンポーネント
                                │
                                ├─ StatsLiveReportsContainer ───▶ ライブ統計カード
                                │
                                ├─ ConversationHeatmapContainer ───▶ 会話ヒートマップ
                                │
                                ├─ ResolutionHeatmapContainer ───▶ 解決ヒートマップ
                                │
                                ├─ AgentLiveReportContainer ───▶ エージェント別テーブル
                                │
                                └─ TeamLiveReportContainer ───▶ チーム別テーブル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| LiveReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/LiveReports.vue` | ソース | メイン画面コンポーネント |
| ReportHeader.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/ReportHeader.vue` | ソース | レポートヘッダー |
| StatsLiveReportsContainer.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/StatsLiveReportsContainer.vue` | ソース | ライブ統計コンテナ |
| ConversationHeatmapContainer.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/heatmaps/ConversationHeatmapContainer.vue` | ソース | 会話ヒートマップコンテナ |
| ResolutionHeatmapContainer.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/heatmaps/ResolutionHeatmapContainer.vue` | ソース | 解決ヒートマップコンテナ |
| AgentLiveReportContainer.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/AgentLiveReportContainer.vue` | ソース | エージェント別レポートコンテナ |
| TeamLiveReportContainer.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/TeamLiveReportContainer.vue` | ソース | チーム別レポートコンテナ |
| reports.js | `app/javascript/dashboard/api/reports.js` | ソース | レポートAPI |
