# 画面設計書 36-チームレポート画面

## 概要

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

### 本画面の処理概要

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

**業務上の目的・背景**：顧客サポートでは、エージェントをチームにグループ化して業務を分担することが一般的です。本画面では、特定のチームを選択し、そのチームにおける会話数、受信メッセージ数、送信メッセージ数、平均初回応答時間、平均解決時間、解決数などの指標を時系列グラフで可視化します。これにより、チームごとのパフォーマンスを把握し、チーム間のリソース配分やパフォーマンス比較、改善施策の立案に役立てることができます。

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

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

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 113 | チーム別レポート | 主機能 | チーム別統計の表示 |

## 画面種別

詳細

## URL/ルーティング

- パス: `/app/accounts/:accountId/reports/teams`
- ルート名: `team_reports`
- コンポーネント: `TeamReports.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-日付範囲変更

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

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

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

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

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

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

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

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

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

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

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

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

#### teams

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

#### conversations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, team_id, created_at | team_id = 選択チーム、期間内 | 会話数算出用 |

#### reporting_events

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, value, value_in_business_hours, timestamp | team_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.37）が推奨されます
- WootReports コンポーネントを再利用し、type='team' として表示
- チームタイプでは `INCOMING_MESSAGES` メトリクスも表示される

---

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

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

### 推奨読解順序

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

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

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

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | WootReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/WootReports.vue` | チームタイプでの reportKeys 定義 |

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

```
TeamReports.vue
    │
    └─ WootReports.vue
           │
           ├─ store.dispatch('teams/get')
           │
           ├─ $store.getters['teams/getTeams']
           │
           ├─ ReportHeader.vue
           │      └─ V4Button (Download)
           │             └─ downloadTeamReports()
           │
           ├─ ReportFilters.vue (type='team')
           │      ├─ team selector
           │      ├─ dateRange selector
           │      ├─ groupBy selector
           │      └─ businessHours toggle
           │
           └─ ReportContainer.vue
                  ├─ ChartStats.vue
                  └─ BarChart.vue
```

### データフロー図

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

チーム選択 ─────────────▶ WootReports.onFilterChange()
       │                        │
       │                        ▼
       │                  selectedFilter 更新
       │                        │
日付範囲フィルタ ───────▶ fetchAllData()
       │                        │
       │                        ├─▶ fetchAccountSummary
       │                        │         │
       │                        │         ▼
       │                        │   ChartStats表示
       │                        │
       │                        └─▶ fetchChartData
       │                                  │
       │                                  ▼
       │                            BarChart表示
       │
グループ化フィルタ ─────────▶ groupBy 更新 → 再フェッチ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TeamReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/TeamReports.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` | 設定 | 翻訳ファイル |
