# 機能設計書 201-Super Adminダッシュボード

## 概要

本ドキュメントは、Chatwootのスーパー管理者向けダッシュボード機能について記載する。

### 本機能の処理概要

Super Adminダッシュボードは、Chatwootインスタンス全体の統計情報を表示する管理者専用のダッシュボード機能である。システム全体のアカウント数、ユーザー数、インボックス数、会話数をリアルタイムで把握し、過去30日間の会話作成推移をグラフで視覚化する。

**業務上の目的・背景**：Chatwootをマルチテナント形式で運用する際、システム管理者はインスタンス全体の利用状況を把握する必要がある。この機能により、システムの成長状況、負荷状態、利用トレンドを一目で確認できるため、リソース計画やキャパシティプランニングに活用できる。

**機能の利用シーン**：
- システム管理者が日次・週次でシステム全体の利用状況を確認する場面
- 新規顧客の増加傾向を把握してインフラ増強を検討する場面
- 会話トラフィックの変動パターンを分析してサポート体制を最適化する場面

**主要な処理内容**：
1. システム全体のアカウント総数を取得して表示
2. システム全体のユーザー総数を取得して表示
3. システム全体のインボックス総数を取得して表示
4. システム全体の会話総数を取得して表示
5. 過去30日間の会話作成数を日別に集計してチャートデータとして提供

**関連システム・外部連携**：本機能は外部システムとの連携はなく、内部データベースのみを参照する。Administrate gemを使用した管理画面フレームワーク上で動作する。

**権限による制御**：本機能はSuper Admin権限を持つユーザーのみがアクセス可能である。通常のエージェントや管理者はアクセスできない。Deviseによる認証とSuper Adminモデルによる認可で制御される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Super Admin Dashboard | 主画面 | システム統計の一覧表示 |

## 機能種別

参照処理（READ）/ 統計計算処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | 本機能は入力パラメータを受け取らない | - |

### 入力データソース

データベースから直接取得：
- `accounts`テーブル - アカウント総数
- `users`テーブル - ユーザー総数
- `inboxes`テーブル - インボックス総数
- `conversations`テーブル - 会話総数および日別集計

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| @accounts_count | String | フォーマット済みアカウント総数 |
| @users_count | String | フォーマット済みユーザー総数 |
| @inboxes_count | String | フォーマット済みインボックス総数 |
| @conversations_count | String | フォーマット済み会話総数 |
| @data | Array | 過去30日間の日別会話数配列 [日付, 件数] |

### 出力先

Super Admin管理画面のダッシュボードビュー

## 処理フロー

### 処理シーケンス

```
1. 認証チェック
   └─ Super Adminとしてログインしているか確認
2. 日別会話データ集計
   └─ 過去30日間の会話を日別にグループ化して件数を取得
3. アカウント総数取得
   └─ Account.countを実行し、区切り文字付きでフォーマット
4. ユーザー総数取得
   └─ User.countを実行し、区切り文字付きでフォーマット
5. インボックス総数取得
   └─ Inbox.countを実行し、区切り文字付きでフォーマット
6. 会話総数取得
   └─ Conversation.countを実行し、区切り文字付きでフォーマット
7. ビューレンダリング
   └─ 取得したデータをダッシュボードビューに渡す
```

### フローチャート

```mermaid
flowchart TD
    A[Super Admin アクセス] --> B{認証済み?}
    B -->|No| C[ログイン画面へリダイレクト]
    B -->|Yes| D[日別会話データ集計]
    D --> E[アカウント総数取得]
    E --> F[ユーザー総数取得]
    F --> G[インボックス総数取得]
    G --> H[会話総数取得]
    H --> I[数値フォーマット処理]
    I --> J[ダッシュボードビュー表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 日別集計期間 | 過去30日間を集計対象とする | 常時 |
| BR-002 | 数値フォーマット | 1000以上の数値は桁区切りを表示 | 数値表示時 |
| BR-003 | スコープ除外 | 会話集計時はdefault_scopeを無視 | 会話データ取得時 |

### 計算ロジック

日別会話件数の集計：
```ruby
Conversation.unscoped.group_by_day(:created_at, range: 30.days.ago..2.seconds.ago).count
```
- `unscoped`により全会話を対象
- `group_by_day`はGroupdateメソッドで日別グループ化
- 2秒前までを対象とするのはキャッシュ整合性のため

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 統計表示 | accounts | SELECT | 総件数取得 |
| 統計表示 | users | SELECT | 総件数取得 |
| 統計表示 | inboxes | SELECT | 総件数取得 |
| 統計表示 | conversations | SELECT | 総件数取得および日別集計 |

### テーブル別操作詳細

#### accounts

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | COUNT(*) | 全レコード対象 | 総件数のみ取得 |

#### users

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | COUNT(*) | 全レコード対象 | 総件数のみ取得 |

#### inboxes

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | COUNT(*) | 全レコード対象 | 総件数のみ取得 |

#### conversations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | COUNT(*) | 全レコード対象 | 総件数取得 |
| SELECT | created_at, COUNT(*) | 過去30日間 | 日別グループ集計 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 401 | 認証エラー | Super Adminとして未ログイン | ログイン画面へリダイレクト |
| 500 | サーバーエラー | DB接続エラー | エラーページ表示 |

### リトライ仕様

本機能にリトライ処理は実装されていない。

## トランザクション仕様

本機能は参照のみのためトランザクション制御は不要。

## パフォーマンス要件

- レスポンス時間：1秒以内を目標
- 大規模インスタンスでは会話数集計がボトルネックになる可能性あり

## セキュリティ考慮事項

- Super Admin権限を持つユーザーのみアクセス可能
- Devise認証による保護
- 管理画面は本番環境ではIP制限等の追加保護を推奨

## 備考

- Administrate gemを使用した管理画面フレームワーク上で動作
- Groupdate gemを使用して日別集計を実現
- number_with_delimiterヘルパーで数値フォーマットを適用

---

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

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

### 推奨読解順序

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

Super Adminダッシュボードはシンプルな統計表示機能のため、特別なデータ構造はない。各モデルのレコード件数を取得するのみ。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | super_admin.rb | `app/models/super_admin.rb` | Super AdminがUserを継承していることを確認 |

**読解のコツ**: Super AdminはUserのSTI（Single Table Inheritance）実装である。typeカラムで判別される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | dashboard_controller.rb | `app/controllers/super_admin/dashboard_controller.rb` | indexアクションが本機能のエントリーポイント |

**主要処理フロー**:
1. **5行目**: 過去30日間の会話を日別にグループ化して集計
2. **6行目**: アカウント総数を取得してフォーマット
3. **7行目**: ユーザー総数を取得してフォーマット
4. **8行目**: インボックス総数を取得してフォーマット
5. **9行目**: 会話総数を取得してフォーマット

#### Step 3: 認証・認可を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | application_controller.rb | `app/controllers/super_admin/application_controller.rb` | before_action :authenticate_super_admin!による認証制御 |

**主要処理フロー**:
- **14行目**: Deviseのauthenticate_super_admin!メソッドで認証を強制

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

```
SuperAdmin::DashboardController#index
    │
    ├─ Conversation.unscoped.group_by_day (Groupdate)
    │      └─ 日別会話データ集計
    │
    ├─ Account.count
    │      └─ number_with_delimiter (ActionView Helper)
    │
    ├─ User.count
    │      └─ number_with_delimiter (ActionView Helper)
    │
    ├─ Inbox.count
    │      └─ number_with_delimiter (ActionView Helper)
    │
    └─ Conversation.count
           └─ number_with_delimiter (ActionView Helper)
```

### データフロー図

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

なし ─────────────▶ DashboardController  ───▶ ダッシュボードビュー
                         │                        │
                    ┌────┴────┐                   │
                    ▼         ▼                   │
              DB集計クエリ   数値フォーマット       │
                    │         │                   │
                    └────┬────┘                   │
                         ▼                        │
                    @data, @accounts_count,       │
                    @users_count, @inboxes_count, │
                    @conversations_count ────────▶│
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| dashboard_controller.rb | `app/controllers/super_admin/dashboard_controller.rb` | コントローラー | ダッシュボード表示の制御 |
| application_controller.rb | `app/controllers/super_admin/application_controller.rb` | コントローラー | Super Admin共通の認証処理 |
| super_admin.rb | `app/models/super_admin.rb` | モデル | Super Adminユーザーモデル |
| account.rb | `app/models/account.rb` | モデル | アカウントモデル |
| user.rb | `app/models/user.rb` | モデル | ユーザーモデル |
| inbox.rb | `app/models/inbox.rb` | モデル | インボックスモデル |
| conversation.rb | `app/models/conversation.rb` | モデル | 会話モデル |
