# 機能設計書 205-インスタンスステータス

## 概要

本ドキュメントは、Chatwootインスタンスのシステムステータス確認機能について記載する。Super Admin管理画面から、Chatwootインスタンスの稼働状況やインフラの健全性を確認できる機能である。

### 本機能の処理概要

インスタンスステータス機能は、Chatwootインスタンスの現在の状態を表示する診断機能である。Chatwootのバージョン情報、Gitコミットハッシュ、PostgreSQL接続状態、Redis接続状態およびメモリ使用状況、データベースマイグレーション状態、エディション情報などを一覧表示する。

**業務上の目的・背景**：システム管理者がChatwootインスタンスの健全性を診断し、問題発生時の原因特定やキャパシティプランニングに活用する。特にRedisのメモリ使用状況やクライアント接続数は、パフォーマンス問題の早期発見に役立つ。

**機能の利用シーン**：
- システム管理者がインスタンスの現在のバージョンを確認する場面
- インフラ担当者がPostgreSQL/Redisの接続状態を確認する場面
- デプロイ後にマイグレーション実行状態を確認する場面
- トラブルシューティング時にシステム情報を収集する場面

**主要な処理内容**：
1. Chatwootバージョン情報の取得
2. GitコミットSHAの取得
3. PostgreSQL接続状態の確認
4. Redis接続状態とメトリクスの取得
5. エディション情報（Community/Enterprise/Custom）の判定
6. データベースマイグレーション状態の確認

**関連システム・外部連携**：PostgreSQLとRedisの接続状態を直接確認するため、これらのインフラストラクチャへの接続が必要。

**権限による制御**：本機能はSuper Admin権限を持つユーザーのみがアクセス可能である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Instance Status画面 | 主画面 | システムステータスの一覧表示 |

## 機能種別

システム診断 / 参照処理（READ）

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- システム設定ファイル（バージョン情報）
- PostgreSQLデータベース接続
- Redisサーバー接続
- GitコミットハッシュGIT_HASH定数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Chatwoot version | String | Chatwootのバージョン番号 |
| Git SHA | String | 現在のGitコミットハッシュ |
| Postgres alive | String | PostgreSQL接続状態（true/false） |
| Redis alive | String | Redis接続状態（true/false） |
| Redis version | String | Redisサーバーバージョン |
| Redis connected clients | String | 接続中のクライアント数 |
| Redis maxclients setting | String | 最大クライアント数設定 |
| Redis memory used | String | 使用中メモリ量 |
| Redis memory peak | String | ピーク時メモリ使用量 |
| Redis total memory available | String | システム総メモリ量 |
| Redis maxmemory setting | String | 最大メモリ設定 |
| Redis maxmemory_policy setting | String | メモリポリシー設定 |
| Chatwoot edition | String | エディション（Enterprise/Custom/Community） |
| Database Migrations | String | マイグレーション状態（pending/completed） |

### 出力先

Super Admin管理画面のInstance Statusビュー

## 処理フロー

### 処理シーケンス

```
1. 認証チェック
   └─ Super Adminとしてログインしているか確認
2. バージョン情報取得
   └─ Chatwoot.config[:version]から取得
3. Git SHA取得
   └─ GIT_HASH定数から取得
4. PostgreSQL状態確認
   └─ ActiveRecord::Base.connection.active?でチェック
5. Redis状態確認
   └─ Redis.new.ping → PONG応答確認
6. Redisメトリクス取得
   └─ redis.infoコマンドで詳細情報取得
7. エディション判定
   └─ ChatwootApp.enterprise?/custom?で判定
8. マイグレーション状態確認
   └─ migration_context.needs_migration?でチェック
9. 結果表示
   └─ @metricsハッシュをビューに渡す
```

### フローチャート

```mermaid
flowchart TD
    A[Super Admin アクセス] --> B{認証済み?}
    B -->|No| C[ログイン画面へリダイレクト]
    B -->|Yes| D[@metrics初期化]
    D --> E[バージョン情報取得]
    E --> F[Git SHA取得]
    F --> G[PostgreSQL接続確認]
    G --> H{Redis接続}
    H -->|成功| I[Redisメトリクス取得]
    H -->|失敗| J[Redis alive = false]
    I --> K[エディション判定]
    J --> K
    K --> L[マイグレーション状態確認]
    L --> M[ビュー表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Redis接続失敗時 | Redis接続失敗時はメトリクスを取得せずalive=falseのみ表示 | Redis接続エラー時 |
| BR-002 | エディション判定順序 | Enterprise → Custom → Communityの順で判定 | 常時 |
| BR-003 | マイグレーション状態 | pending/completedの2状態で表示 | 常時 |

### 計算ロジック

エディション判定ロジック：
```ruby
if ChatwootApp.enterprise?
  'Enterprise'
elsif ChatwootApp.custom?
  'Custom'
else
  'Community'
end
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 接続確認 | - | SELECT | ActiveRecord接続状態確認 |
| マイグレーション確認 | schema_migrations | SELECT | マイグレーション状態確認 |

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

本機能はシステム状態の確認のみで、データベースへの書き込みは行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 401 | 認証エラー | Super Admin未ログイン | ログイン画面へリダイレクト |
| - | Redis接続エラー | Redis::CannotConnectError | Redis alive = falseとして表示継続 |

### リトライ仕様

本機能にリトライ処理は実装されていない。Redis接続エラーはrescueされ、画面表示は継続される。

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

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

## パフォーマンス要件

- レスポンス時間：1秒以内を目標
- Redis接続タイムアウト時は遅延が発生する可能性あり

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

- Super Admin権限のみアクセス可能
- システム情報を表示するため、公開環境では特に注意
- Git SHAやバージョン情報は脆弱性攻撃の手がかりになる可能性あり

## 備考

- Redis::Config.appから設定を読み込み
- GIT_HASHはビルド時に設定される定数
- Chatwoot.config[:version]は設定ファイルから読み込み

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | instance_statuses_controller.rb | `app/controllers/super_admin/instance_statuses_controller.rb` | showアクションと各メトリクス取得メソッド |

**読解のコツ**: showアクションから順に各プライベートメソッドを呼び出し、@metricsハッシュを構築している。

**主要処理フロー**:
1. **3-10行目**: showアクションで各メトリクス取得メソッドを呼び出し
2. **12-19行目**: chatwoot_editionでエディション判定
3. **21-23行目**: instance_metaでマイグレーション状態確認
4. **25-27行目**: chatwoot_versionでバージョン取得
5. **29-31行目**: shaでGitハッシュ取得
6. **33-39行目**: postgres_statusでPostgreSQL接続確認
7. **41-58行目**: redis_metricsでRedis情報取得

#### Step 2: Redis接続処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | instance_statuses_controller.rb | `app/controllers/super_admin/instance_statuses_controller.rb` | redis_metricsメソッドのRedis::CannotConnectErrorハンドリング |

**主要処理フロー**:
- **43行目**: Redis::Config.appから設定を取得して接続
- **44行目**: pingコマンドでPONG応答を確認
- **45-54行目**: redis.infoから各種メトリクスを取得
- **56-58行目**: 接続エラー時はalive=falseを設定

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

```
SuperAdmin::InstanceStatusesController#show
    │
    ├─ chatwoot_version
    │      └─ Chatwoot.config[:version]
    │
    ├─ sha
    │      └─ GIT_HASH定数
    │
    ├─ postgres_status
    │      └─ ActiveRecord::Base.connection.active?
    │
    ├─ redis_metrics
    │      ├─ Redis.new(Redis::Config.app)
    │      ├─ redis.ping
    │      └─ redis.info
    │
    ├─ chatwoot_edition
    │      ├─ ChatwootApp.enterprise?
    │      └─ ChatwootApp.custom?
    │
    └─ instance_meta
           └─ migration_context.needs_migration?
```

### データフロー図

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

なし ─────────────▶ InstanceStatusesController ───▶ @metrics
                         │
                    ┌────┼────┐
                    ▼    ▼    ▼
              バージョン  DB接続  Redis接続
                    │    │    │
                    └────┴────┘
                         │
                         ▼
                    @metrics = {
                      'Chatwoot version' => ...,
                      'Git SHA' => ...,
                      'Postgres alive' => ...,
                      'Redis alive' => ...,
                      ...
                    }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| instance_statuses_controller.rb | `app/controllers/super_admin/instance_statuses_controller.rb` | コントローラー | ステータス取得処理 |
| application_controller.rb | `app/controllers/super_admin/application_controller.rb` | コントローラー | Super Admin共通処理 |
| redis.rb | `config/initializers/redis.rb` | 設定 | Redis接続設定 |
| chatwoot.rb | `lib/chatwoot.rb` | ライブラリ | バージョン情報管理 |
