# 機能設計書 202-インストール設定

## 概要

本ドキュメントは、Chatwootインスタンスのインストール設定（Installation Configs）を管理するSuper Admin機能について記載する。

### 本機能の処理概要

インストール設定機能は、Chatwootインスタンス全体に適用されるシステム設定を管理する機能である。環境変数では設定できない動的な設定値や、管理画面から変更可能な設定項目をデータベースで管理し、Super Adminが編集可能な形で提供する。

**業務上の目的・背景**：Chatwootをデプロイした後、運用中にシステム設定を変更したい場合がある。環境変数の変更はサーバー再起動が必要だが、本機能を使用することでサーバーを再起動せずに設定変更が可能となる。また、マルチテナント環境での共通設定を一元管理できる。

**機能の利用シーン**：
- システム管理者がサインアップ機能の有効/無効を切り替える場面
- Firebase設定やWebhookタイムアウトなどの運用パラメータを調整する場面
- 環境変数で設定できない動的設定を管理する場面

**主要な処理内容**：
1. 編集可能なインストール設定の一覧表示
2. 設定値の新規作成
3. 設定値の編集・更新
4. 設定値の削除
5. 設定変更時のキャッシュクリア

**関連システム・外部連携**：本機能はシステム全体の設定を管理するため、設定変更は即座にグローバルキャッシュ（GlobalConfig）に反映される。他の機能からはGlobalConfigを通じて設定値を参照する。

**権限による制御**：本機能はSuper Admin権限を持つユーザーのみがアクセス可能である。また、`locked: true`の設定項目は一覧に表示されず、編集対象外となる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Installation Configs一覧 | 主画面 | 設定項目の一覧表示 |
| - | Installation Config編集 | 編集画面 | 設定値の編集 |
| - | Installation Config新規作成 | 作成画面 | 新規設定の追加 |

## 機能種別

CRUD操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | String | Yes | 設定項目名 | 存在性チェック |
| value | Any | No | 設定値（シリアライズ対応） | - |

### 入力データソース

Super Admin管理画面のフォーム入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | Integer | 設定ID |
| name | String | 設定項目名 |
| value | Any | 設定値 |
| created_at | DateTime | 作成日時 |
| updated_at | DateTime | 更新日時 |

### 出力先

- Super Admin管理画面の一覧ビュー
- Super Admin管理画面の詳細ビュー

## 処理フロー

### 処理シーケンス

```
1. 認証チェック
   └─ Super Adminとしてログインしているか確認
2. 設定一覧取得（indexアクション）
   └─ locked: falseの設定のみを取得
3. 設定値の参照（showアクション）
   └─ 個別の設定詳細を表示
4. 設定値の編集（updateアクション）
   └─ 設定値を更新し、キャッシュをクリア
5. 設定値の作成（createアクション）
   └─ 新規設定を追加（locked: falseで固定）
```

### フローチャート

```mermaid
flowchart TD
    A[Super Admin アクセス] --> B{認証済み?}
    B -->|No| C[ログイン画面へリダイレクト]
    B -->|Yes| D{アクション種別}
    D -->|index| E[編集可能設定一覧取得]
    D -->|show| F[設定詳細表示]
    D -->|create| G{重複チェック}
    G -->|重複あり| H[エラー表示]
    G -->|重複なし| I[設定作成]
    D -->|update| J[設定更新]
    I --> K[キャッシュクリア]
    J --> K
    K --> L[画面更新]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 編集可能フィルタ | locked: falseの設定のみ表示 | 一覧表示時 |
| BR-002 | 自動locked設定 | 新規作成時はlocked: falseで固定 | 作成時 |
| BR-003 | 一意性制約 | 設定名は一意でなければならない | 作成・更新時 |
| BR-004 | SAML無効化制限 | SAML認証ユーザーが存在する場合、SAML SSO設定を無効化できない | ENABLE_SAML_SSO_LOGIN更新時 |

### 計算ロジック

設定値はJSONB形式でシリアライズされ、`serialized_value`カラムに保存される。値の取得時はデシリアライズされる。

```ruby
# 値の保存
self.serialized_value = { value: value_to_assigned }.with_indifferent_access

# 値の取得
serialized_value[:value]
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 一覧表示 | installation_configs | SELECT | 編集可能な設定を取得 |
| 詳細表示 | installation_configs | SELECT | 個別設定を取得 |
| 新規作成 | installation_configs | INSERT | 新規設定を追加 |
| 更新 | installation_configs | UPDATE | 設定値を更新 |
| 削除 | installation_configs | DELETE | 設定を削除 |

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

#### installation_configs

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | locked = false | 編集可能設定のみ |
| INSERT | name, serialized_value, locked | 入力値、false | locked固定 |
| UPDATE | serialized_value | 入力値 | 空文字はnilに変換 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 401 | 認証エラー | Super Admin未ログイン | ログイン画面へリダイレクト |
| 422 | バリデーションエラー | 設定名重複 | エラーメッセージ表示、元画面へ戻る |
| 422 | バリデーションエラー | SAMLユーザー存在時のSSO無効化 | エラーメッセージ表示 |

### リトライ仕様

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

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

設定の作成・更新は単一レコードの操作のため、明示的なトランザクション制御は不要。after_commitコールバックでキャッシュクリアを実行。

## パフォーマンス要件

- 設定変更時にGlobalConfigキャッシュがクリアされる
- 次回アクセス時にキャッシュが再構築される

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

- Super Admin権限のみアクセス可能
- locked設定は管理画面から編集不可
- 機密情報を含む設定は環境変数で管理することを推奨

## 備考

- Administrate gemによる管理画面フレームワークを使用
- YAML形式でシリアライズされる設定値
- default_scopeにより作成日時の降順でソート

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | installation_config.rb | `app/models/installation_config.rb` | テーブル構造、シリアライズ、バリデーション |

**読解のコツ**:
- `serialize :serialized_value`によりYAML形式でJSONBカラムに保存される
- `value`と`value=`メソッドでシリアライズ/デシリアライズを抽象化
- `editable`スコープで編集可能設定をフィルタリング

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | installation_configs_controller.rb | `app/controllers/super_admin/installation_configs_controller.rb` | CRUDアクションの制御 |

**主要処理フロー**:
1. **2行目**: ActiveRecord::RecordNotUniqueをrescue
2. **24-26行目**: scoped_resourceでeditable設定のみを対象
3. **39-43行目**: resource_paramsで空文字をnilに変換し、locked: falseを強制

#### Step 3: ダッシュボード定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | installation_config_dashboard.rb | `app/dashboards/installation_config_dashboard.rb` | 管理画面の表示項目定義 |

**主要処理フロー**:
- **10-16行目**: 表示属性の型定義
- **23-28行目**: 一覧表示項目
- **43-46行目**: フォーム項目（name, value）

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

```
SuperAdmin::InstallationConfigsController
    │
    ├─ scoped_resource
    │      └─ InstallationConfig.editable
    │
    ├─ resource_params
    │      └─ permit(:name, :value)
    │             └─ merge(locked: false)
    │
    └─ Administrate CRUD
           │
           └─ InstallationConfig
                  ├─ before_validation :set_lock
                  ├─ validate :saml_sso_users_check
                  └─ after_commit :clear_cache
                         └─ GlobalConfig.clear_cache
```

### データフロー図

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

フォーム入力 ────▶ InstallationConfigsController ───▶ 一覧/詳細ビュー
(name, value)            │
                    ┌────┴────┐
                    ▼         ▼
              バリデーション  キャッシュクリア
                    │              │
                    └────┬─────────┘
                         ▼
                    installation_configs
                    テーブル更新
                         │
                         ▼
                    GlobalConfig
                    キャッシュクリア
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| installation_configs_controller.rb | `app/controllers/super_admin/installation_configs_controller.rb` | コントローラー | CRUD操作の制御 |
| installation_config.rb | `app/models/installation_config.rb` | モデル | 設定データの管理 |
| installation_config_dashboard.rb | `app/dashboards/installation_config_dashboard.rb` | ダッシュボード | 管理画面の表示定義 |
| application_controller.rb | `app/controllers/super_admin/application_controller.rb` | コントローラー | Super Admin共通処理 |
