# 画面設計書 37-チームレポート概要

## 概要

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

### 本画面の処理概要

本画面は、アカウント内の全チームのパフォーマンス指標を一覧形式で表示するレポート画面です。

**業務上の目的・背景**：顧客サポート業務では、エージェントをチームにグループ化して業務を分担することが一般的です。本画面では、各チームの会話数、平均初回応答時間、平均解決時間、平均顧客待機時間、解決数といった主要KPIを一覧で確認でき、チーム全体のパフォーマンス状況を俯瞰的に把握することができます。これにより、どのチームが効率的に運用されているか、どのチームに改善が必要かを一目で判断し、チーム間の比較やリソース配分の最適化を行うことができます。

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

**主要な操作・処理内容**：
1. 日付範囲フィルタで集計期間を指定（過去7日、30日、3ヶ月、6ヶ月、1年、カスタム期間）
2. ビジネスアワートグルで営業時間内のみの統計に切り替え
3. レポートダウンロードボタンでCSV形式のレポートをエクスポート
4. チーム名クリックで詳細レポート画面（No.38）へ遷移

**画面遷移**：
- 遷移元：レポートホーム画面、サイドメニュー
- 遷移先：チームレポート詳細画面（No.38）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 113 | チーム別レポート | 主機能 | チームレポート概要一覧表示 |

## 画面種別

一覧

## URL/ルーティング

- パス: `/app/accounts/:accountId/reports/teams_overview`
- ルート名: `team_reports_index`
- コンポーネント: `TeamReportsIndex.vue`

## 入出力項目

### フィルタ入力項目

| 項目名 | 項目ID | データ型 | 必須 | 初期値 | 説明 |
|--------|--------|----------|------|--------|------|
| 日付範囲 | dateRange | Object | Yes | 過去7日 | 集計対象期間 |
| ビジネスアワー | businessHours | Boolean | No | false | 営業時間内のみで集計 |

## 表示項目

### サマリーテーブル

| 項目名 | 項目ID | データ型 | 説明 |
|--------|--------|----------|------|
| チーム名 | name | String | チームの名前（リンク） |
| 会話数 | conversationsCount | Number | 期間内の会話総数 |
| 平均初回応答時間 | avgFirstResponseTime | String | 平均初回応答時間（フォーマット済み） |
| 平均解決時間 | avgResolutionTime | String | 平均解決時間（フォーマット済み） |
| 平均顧客待機時間 | avgReplyTime | String | 平均顧客待機時間（フォーマット済み） |
| 解決数 | resolutionsCount | Number | 解決した会話の総数 |

## イベント仕様

### 1-日付範囲変更

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

**処理フロー**:
1. ユーザーが日付範囲ドロップダウンから期間を選択
2. `onFilterChange` イベントハンドラが発火
3. `from`（開始Unix時間）と`to`（終了Unix時間）を計算
4. Vuex Action `summaryReports/fetchTeamSummaryReports` をディスパッチ
5. API `GET /api/v2/accounts/:accountId/summary_reports/team` を呼び出し
6. レスポンスデータでテーブルを更新

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

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

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

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

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

### 4-チーム名クリック

チーム名をクリックすると、そのチームの詳細レポート画面に遷移します。

**処理フロー**:
1. テーブル内のチーム名リンクをクリック
2. Vue Routerで `team_reports_show` ルートに遷移
3. パラメータとしてチームIDを渡す

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示時 | teams, conversations, reporting_events | SELECT | チーム別サマリーデータ取得 |
| フィルタ変更時 | teams, conversations, reporting_events | SELECT | 条件に基づくサマリーデータ再取得 |

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

#### teams

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, name | account_id = 現在のアカウント | チーム一覧取得 |

#### conversations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | team_id, created_at | 期間内の会話をteam_idでグループ化してカウント | conversations_count算出用 |

#### reporting_events

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | team_id, name, value, value_in_business_hours, created_at | イベント種別ごとの平均値を計算 | 解決時間、初回応答時間等の算出 |

## メッセージ仕様

| メッセージ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呼び出し失敗 | エラーメッセージを表示し、UIFlags更新で読み込み状態を解除 |
| 権限不足 | 画面アクセス拒否（ルートガードで制御） |
| データなし | 空のテーブルを表示（「--」でプレースホルダー表示） |

## 備考

- 時間値は `formatTime` ユーティリティ関数で人間が読みやすい形式に変換される
- ビジネスアワー計算は、サーバーサイドで `value_in_business_hours` カラムを使用して行われる
- テーブルは @tanstack/vue-table ライブラリを使用して実装されている
- この画面は新しいUIで、旧バージョン（No.36）より推奨される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | summaryReports.js | `app/javascript/dashboard/store/modules/summaryReports.js` | Vuex Storeの状態定義（45行目のteamSummaryReports）、getters（62-64行目） |
| 1-2 | team_summary_builder.rb | `app/builders/v2/reports/team_summary_builder.rb` | APIレスポンスのデータ構造 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TeamReportsIndex.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/TeamReportsIndex.vue` | 画面全体の構造（14-35行目）、propsでSummaryReportsに渡すキー |

**主要処理フロー**:
1. **9-11行目**: ダウンロードボタンのクリックハンドラ定義
2. **29行目**: action-key="summaryReports/fetchTeamSummaryReports"
3. **30行目**: getter-key="teams/getTeams"
4. **32行目**: summary-key="summaryReports/getTeamSummaryReports"

#### Step 3: サマリーレポートコンポーネントの理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | SummaryReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/SummaryReports.vue` | テーブル定義（62-93行目）、データ取得（123-130行目） |

#### Step 4: バックエンドAPIの理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | summary_reports_controller.rb | `app/controllers/api/v2/accounts/summary_reports_controller.rb` | teamエンドポイント定義（9-11行目） |
| 4-2 | team_summary_builder.rb | `app/builders/v2/reports/team_summary_builder.rb` | チーム固有の集計ロジック |

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

```
TeamReportsIndex.vue
    │
    ├─ SummaryReports.vue
    │      ├─ useMapGetter('teams/getTeams')
    │      ├─ useMapGetter('summaryReports/getTeamSummaryReports')
    │      ├─ store.dispatch('teams/get')
    │      └─ store.dispatch('summaryReports/fetchTeamSummaryReports')
    │             └─ SummaryReportsAPI.getTeamReports()
    │                    └─ GET /api/v2/accounts/:id/summary_reports/team
    │                           └─ V2::Reports::TeamSummaryBuilder
    │
    ├─ ReportHeader.vue
    │      └─ V4Button (Download)
    │             └─ downloadReports()
    │                    └─ store.dispatch('downloadTeamReports')
    │
    └─ ReportFilterSelector.vue
           └─ onFilterChange → fetchAllData()
```

### データフロー図

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

日付範囲フィルタ ───────▶ SummaryReports.fetchAllData() ───────▶ テーブル表示
       │                        │
       │                        ▼
       │                 Vuex Action
       │                 summaryReports/fetchTeamSummaryReports
       │                        │
       │                        ▼
       │                 API Request
       │                 GET /summary_reports/team
       │                        │
       │                        ▼
       │                 TeamSummaryBuilder.build()
       │                        │
       │                        ▼
       │                 DB Query
       │                 (conversations + reporting_events)
       │                        │
       │                        ▼
ビジネスアワー ─────────▶ value_in_business_hours 選択
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TeamReportsIndex.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/TeamReportsIndex.vue` | ソース | 画面エントリーポイント |
| SummaryReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/SummaryReports.vue` | ソース | サマリーテーブルコンポーネント |
| ReportHeader.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/ReportHeader.vue` | ソース | ヘッダーコンポーネント |
| SummaryReportLink.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/SummaryReportLink.vue` | ソース | テーブル内リンクコンポーネント |
| summaryReports.js | `app/javascript/dashboard/store/modules/summaryReports.js` | ソース | Vuex Store モジュール |
| summaryReports.js | `app/javascript/dashboard/api/summaryReports.js` | ソース | API クライアント |
| reports.routes.js | `app/javascript/dashboard/routes/dashboard/settings/reports/reports.routes.js` | ソース | ルート定義 |
| summary_reports_controller.rb | `app/controllers/api/v2/accounts/summary_reports_controller.rb` | ソース | APIコントローラ |
| team_summary_builder.rb | `app/builders/v2/reports/team_summary_builder.rb` | ソース | レポートビルダー |
| report.json | `app/javascript/dashboard/i18n/locale/en/report.json` | 設定 | 翻訳ファイル |
