# 画面設計書 42-SLAレポート画面

## 概要

本ドキュメントは、ChatwootのSLA（Service Level Agreement）レポート画面の設計仕様を定義するものである。

### 本画面の処理概要

SLAポリシーの達成状況を分析・可視化する画面。SLAヒット率、違反数、対象会話数などのメトリクスを表示し、SLA適用済み会話の一覧をテーブル形式で確認できる。

**業務上の目的・背景**：SLA（サービスレベル契約）はカスタマーサポートの品質基準を定義する重要な機能である。初回応答時間や解決時間の目標を設定し、その達成状況を監視することで、サービス品質の維持・向上を図る。本画面は、SLAポリシーがどの程度守られているか、どこで違反が発生しているかを把握し、改善アクションにつなげるために使用される。

**画面へのアクセス方法**：サイドメニューの「レポート」から「SLA」を選択することでアクセスする。管理者またはレポート管理権限を持つユーザーのみがアクセス可能。

**主要な操作・処理内容**：
1. 期間フィルタによるレポート期間の選択
2. エージェント、インボックス、チーム、SLAポリシー、ラベルによるフィルタリング
3. SLAメトリクス（ヒット率、違反数、会話数）の確認
4. SLA適用済み会話一覧のページング閲覧
5. CSVレポートのダウンロード

**画面遷移**：
- 遷移元：レポートメニュー
- 遷移先：各会話詳細画面（テーブルの会話リンクから）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 42 | SLAポリシー適用 | 主機能 | SLAに関するレポート表示 |

## 画面種別

一覧

## URL/ルーティング

```
/app/accounts/:accountId/reports/sla
```

- ルート名: `sla_reports`
- パラメータ:
  - `accountId`: アカウントID

## 入出力項目

### フィルタ入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| 期間（from/to） | Date | ○ | レポート対象期間 |
| エージェント | Select | - | 担当エージェントでフィルタ |
| インボックス | Select | - | インボックスでフィルタ |
| チーム | Select | - | チームでフィルタ |
| SLAポリシー | Select | - | SLAポリシーでフィルタ |
| ラベル | MultiSelect | - | ラベルでフィルタ |

## 表示項目

### レポートヘッダー

| 項目名 | 型 | 説明 |
|--------|-----|------|
| レポートタイトル | String | 「SLAレポート」 |
| ダウンロードボタン | Button | CSVレポートをダウンロード |

### SLAメトリクス

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ヒット率 | Percentage | SLA達成率（%） |
| 違反数 | Number | SLA違反（ミス）の件数 |
| 会話数 | Number | SLA適用済み会話の総数 |

### SLA会話テーブル

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 会話ID | Number | 会話の識別子（リンク） |
| エージェント | String | 担当エージェント名 |
| インボックス | String | インボックス名 |
| SLAポリシー | String | 適用されたSLAポリシー名 |
| ステータス | Badge | 達成/違反のステータス |
| 初回応答時間 | Duration | 実際の初回応答時間 |
| 解決時間 | Duration | 実際の解決時間 |
| 作成日時 | DateTime | 会話作成日時 |

### ページネーション

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 現在のページ | Number | 現在表示中のページ番号 |
| 総件数 | Number | フィルタ適用後の総レコード数 |
| ページ切り替え | Pagination | ページ遷移UI |

## イベント仕様

### 1-フィルタ変更イベント

**トリガー**: 任意のフィルタ条件変更時

**処理フロー**:
1. ユーザーがフィルタ条件を変更
2. `onFilterChange`メソッドが呼び出される
3. `activeFilter`状態が更新される
4. `fetchSLAReports`と`fetchSLAMetrics`メソッドが呼び出される
5. Vuexストアに`slaReports/get`と`slaReports/getMetrics`がディスパッチされる
6. APIからデータ取得後、画面が更新される

### 2-ページ変更イベント

**トリガー**: ページネーションのページ変更時

**処理フロー**:
1. ユーザーがページを切り替え
2. `onPageChange`メソッドが呼び出される
3. `fetchSLAReports`メソッドで新しいページのデータを取得
4. テーブルが更新される

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

**トリガー**: ダウンロードボタンクリック

**処理フロー**:
1. `downloadReports`メソッドが呼び出される
2. `slaReports/download`アクションがディスパッチされる
3. APIエンドポイント`/api/v1/accounts/:accountId/applied_slas/download`にリクエスト
4. レスポンスをCSVファイルとしてダウンロード

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| フィルタ変更 | applied_slas | SELECT | SLA適用データの取得 |
| メトリクス取得 | applied_slas | SELECT | SLAメトリクスの集計 |

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

#### applied_slas

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | account_id | 現在のアカウントID | フィルタ条件 |
| SELECT | created_at | since〜until期間 | 期間フィルタ |
| SELECT | assigned_agent_id | 指定エージェントID | エージェントフィルタ |
| SELECT | inbox_id | 指定インボックスID | インボックスフィルタ |
| SELECT | team_id | 指定チームID | チームフィルタ |
| SELECT | sla_policy_id | 指定SLAポリシーID | SLAフィルタ |

## メッセージ仕様

| 種別 | メッセージキー | メッセージ内容 |
|------|---------------|---------------|
| エラー | SLA_REPORTS.DOWNLOAD_FAILED | ダウンロードに失敗しました |

## 例外処理

| 例外状態 | 処理内容 |
|----------|---------|
| API通信エラー | エラートースト表示 |
| 権限不足 | 403エラー、アクセス拒否画面表示 |
| データなし | 空のテーブルとゼロ値のメトリクス表示 |
| ダウンロードエラー | エラーメッセージ表示 |

## 備考

- SLAレポートはCloud/Enterprise版でのみ利用可能
- ヒット率は「達成数 / 総適用数 * 100」で算出
- テーブルは作成日時の降順でソートされる

---

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

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

### 推奨読解順序

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

まず、SLAレポートデータの構造とVuexストアの状態管理を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | slaReports.js | `app/javascript/dashboard/store/modules/slaReports.js` | state構造（records, metrics, meta, uiFlags） |

**読解のコツ**:
- `state.metrics`にヒット率、違反数、会話数が格納される
- `state.records`にSLA適用済み会話のリストが格納される
- `state.meta`にページネーション情報が格納される

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | SLAReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/SLAReports.vue` | メインコンポーネント |

**主要処理フロー**:
1. **L19-31**: data定義 - pageNumber、activeFilterの初期状態
2. **L34-39**: computed - Vuex gettersのマッピング
3. **L41-48**: mounted - 初期データ（agents, inboxes等）とSLAデータの取得
4. **L51-78**: methods - データ取得とフィルタ処理

#### Step 3: フィルタコンポーネントを理解する

フィルタUIを担当するコンポーネント。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | SLAReportFilters.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/SLA/SLAReportFilters.vue` | フィルタUI |

#### Step 4: API層を理解する

バックエンドとの通信を担当するAPI層。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | slaReports.js | `app/javascript/dashboard/api/slaReports.js` | API定義（get, download, getMetrics） |

**主要処理フロー**:
- **L9-31**: get - SLA適用済み会話の取得（ページング対応）
- **L33-53**: download - CSVダウンロード
- **L55-75**: getMetrics - メトリクス取得

#### Step 5: バックエンドを理解する

Rails側のコントローラとモデル。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | applied_slas_controller.rb | `app/controllers/api/v1/accounts/applied_slas_controller.rb` | コントローラ |
| 5-2 | applied_sla.rb | `app/models/applied_sla.rb` | モデル定義 |

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

```
SLAReports.vue
    │
    ├─ mounted()
    │      ├─ store.dispatch('agents/get')
    │      ├─ store.dispatch('inboxes/get')
    │      ├─ store.dispatch('teams/get')
    │      ├─ store.dispatch('labels/get')
    │      ├─ store.dispatch('sla/get')
    │      ├─ fetchSLAMetrics()
    │      │      └─ slaReports/getMetrics
    │      │             └─ SLAReportsAPI.getMetrics()
    │      │                    └─ GET /api/v1/.../applied_slas/metrics
    │      │
    │      └─ fetchSLAReports()
    │             └─ slaReports/get
    │                    └─ SLAReportsAPI.get()
    │                           └─ GET /api/v1/.../applied_slas
    │
    ├─ SLAReportFilters (子コンポーネント)
    │      └─ @filter-change → onFilterChange()
    │
    ├─ SLAMetrics (子コンポーネント)
    │      └─ props: hitRate, noOfBreaches, noOfConversations
    │
    ├─ SLATable (子コンポーネント)
    │      └─ @page-change → onPageChange()
    │
    └─ downloadReports()
           └─ slaReports/download
                  └─ SLAReportsAPI.download()
                         └─ GET /api/v1/.../applied_slas/download
```

### データフロー図

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

期間フィルタ   ───▶  SLAReportsAPI.get()     ───▶  SLA会話テーブル
                            │
フィルタ条件   ───▶  SLAReportsAPI.getMetrics ───▶  SLAメトリクス
(agent,inbox等)             │                        (hitRate,breaches)
                            │
ページ番号     ───▶  fetchSLAReports()       ───▶  ページング更新
                            │
ダウンロード   ───▶  SLAReportsAPI.download  ───▶  CSVファイル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| SLAReports.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/SLAReports.vue` | ソース | メイン画面コンポーネント |
| SLAMetrics.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/SLA/SLAMetrics.vue` | ソース | メトリクス表示コンポーネント |
| SLATable.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/SLA/SLATable.vue` | ソース | テーブル表示コンポーネント |
| SLAReportFilters.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/SLA/SLAReportFilters.vue` | ソース | フィルタコンポーネント |
| ReportHeader.vue | `app/javascript/dashboard/routes/dashboard/settings/reports/components/ReportHeader.vue` | ソース | ヘッダーコンポーネント |
| reports.routes.js | `app/javascript/dashboard/routes/dashboard/settings/reports/reports.routes.js` | 設定 | ルーティング定義 |
| slaReports.js (store) | `app/javascript/dashboard/store/modules/slaReports.js` | ソース | Vuexストアモジュール |
| slaReports.js (api) | `app/javascript/dashboard/api/slaReports.js` | ソース | APIクライアント |
| applied_slas_controller.rb | `app/controllers/api/v1/accounts/applied_slas_controller.rb` | ソース | Railsコントローラ |
| applied_sla.rb | `app/models/applied_sla.rb` | ソース | モデル定義 |
