# 機能設計書 36-グローバル設定管理

## 概要

本ドキュメントは、InvenTreeシステムにおけるグローバル設定管理機能の設計を定義する。システム全体に適用される設定項目の管理・参照・更新を行う機能を提供する。

### 本機能の処理概要

グローバル設定管理機能は、InvenTreeシステム全体の動作を制御する設定値を一元管理する。InvenTreeSettingモデルを通じて、キー・バリュー形式で様々な設定を保存・取得する。

**業務上の目的・背景**：在庫管理システムは企業ごとに運用方法が異なるため、システムの動作をカスタマイズできる設定機能が必要。インスタンス名、デフォルト通貨、バーコード設定など、システム全体に影響する設定を管理者が変更できるようにする。

**機能の利用シーン**：
- システム初期導入時の基本設定
- 運用開始後の設定変更（通貨、言語等）
- プラグイン関連設定の変更
- バーコード・ラベル印刷設定
- セキュリティ関連設定の調整

**主要な処理内容**：
1. 設定値の取得（キャッシュ対応）
2. 設定値の更新（バリデーション付き）
3. 設定定義の参照（名前、説明、デフォルト値、選択肢）
4. 設定カテゴリ別の管理
5. 設定変更後のコールバック処理

**関連システム・外部連携**：
- Redis/Memcachedキャッシュ（設定値キャッシュ）
- プラグインレジストリ（プラグイン関連設定の連携）

**権限による制御**：設定の変更はスタッフ権限が必要。読み取りは認証済みユーザーが可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 35 | システム設定画面 | 主画面 | グローバル設定の表示・編集 |
| 34 | 管理センター画面 | 参照画面 | システム設定パネル |

## 機能種別

設定管理 / 構成管理

## 入力仕様

### 設定更新入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| key | str | Yes | 設定キー | 既知のキーであること |
| value | str | Yes | 設定値 | 設定ごとのバリデーション |

### 入力データソース

- システム設定画面からのフォーム入力
- REST API経由のJSON入力
- 環境変数からの初期化

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| key | str | 設定キー |
| value | str | 設定値 |
| name | str | 設定名（表示用） |
| description | str | 設定の説明 |
| units | str | 単位（該当する場合） |
| type | str | 設定タイプ（boolean, integer等） |
| choices | list | 選択肢（該当する場合） |

### 出力先

- REST APIレスポンス（JSON）
- システム設定画面への表示
- データベース（common_inventreesetting）

## 処理フロー

### 処理シーケンス

```
1. 設定取得リクエスト
   └─ キャッシュ確認
2. キャッシュヒット時
   └─ キャッシュから値を返却
3. キャッシュミス時
   └─ データベースから取得
4. 設定が存在しない場合
   └─ デフォルト値で作成
5. キャッシュ更新
   └─ 取得した値をキャッシュに保存
```

### フローチャート

```mermaid
flowchart TD
    A[設定取得リクエスト] --> B{セッションキャッシュ?}
    B -->|Hit| C[値を返却]
    B -->|Miss| D{グローバルキャッシュ?}
    D -->|Hit| E[セッションキャッシュ更新]
    E --> C
    D -->|Miss| F[データベース検索]
    F --> G{設定存在?}
    G -->|Yes| H[キャッシュ更新]
    G -->|No| I[デフォルト値で作成]
    I --> H
    H --> C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-36-01 | 設定キー大文字化 | 設定キーは自動的に大文字に正規化 | 設定アクセス時 |
| BR-36-02 | スタッフ権限要求 | 設定変更はスタッフユーザーのみ可能 | 設定更新時 |
| BR-36-03 | バリデーション必須 | 各設定に定義されたバリデータを適用 | 設定保存時 |
| BR-36-04 | コールバック実行 | after_save定義がある設定は保存後にコールバック実行 | 設定保存後 |
| BR-36-05 | キャッシュ無効化 | 設定更新時にキャッシュを無効化 | 設定更新時 |

### 計算ロジック

設定値の型変換:
```python
if setting.is_bool():
    value = str2bool(value)
elif setting.is_int():
    value = int(value)
elif setting.is_float():
    value = float(value)
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 設定取得 | common_inventreesetting | SELECT | 設定値取得 |
| 設定作成 | common_inventreesetting | INSERT | 新規設定作成 |
| 設定更新 | common_inventreesetting | UPDATE | 設定値更新 |

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

#### common_inventreesetting

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | key | 大文字正規化されたキー | key__iexactで検索 |
| INSERT | key, value | 設定キーとデフォルト値 | 存在しない設定の初期化 |
| UPDATE | value | 新しい設定値 | バリデーション通過後 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 400 | ValidationError | 設定値がバリデーションに失敗 | 有効な値を入力 |
| 403 | PermissionDenied | スタッフ権限なしで更新試行 | スタッフ権限を付与 |

### リトライ仕様

データベース接続エラーの場合、標準のDjangoリトライ機構に従う。

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

- 設定の取得・更新は個別のトランザクションで処理
- 設定作成時の重複チェックはアトミック操作

## パフォーマンス要件

- 設定取得：5ms以内（キャッシュヒット時）
- 設定取得：50ms以内（キャッシュミス時）
- 設定更新：100ms以内

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

- 設定変更はスタッフ権限が必要
- 隠し設定（hidden=True）はAPIから直接アクセス不可
- 設定値のサニタイズ処理

## 備考

SYSTEM_SETTINGS（主要な設定項目）:
- INVENTREE_INSTANCE: インスタンス名
- INVENTREE_BASE_URL: ベースURL
- INVENTREE_DEFAULT_CURRENCY: デフォルト通貨
- BARCODE_ENABLE: バーコード機能有効化
- LOGIN_ENABLE_REG: ユーザー登録許可
- LOGIN_ENFORCE_MFA: MFA強制

設定のカテゴリ:
- サーバー設定
- ログイン・認証設定
- バーコード設定
- 在庫設定
- 部品設定
- オーダー設定
- レポート設定

---

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

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

### 推奨読解順序

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

設定モデルの基底クラスを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.py | `src/backend/InvenTree/common/models.py` | BaseInvenTreeSetting（265-900行目）の設定基底クラス |

**読解のコツ**:
- **400-418行目**: all_settings_values()で全設定値を一括取得
- **420-448行目**: check_all_settings()で必須設定の検証
- **536-638行目**: get_setting_object()でキャッシュ対応の設定オブジェクト取得
- **640-678行目**: get_setting()で設定値を取得
- **680-772行目**: set_setting()で設定値を更新

#### Step 2: 設定定義を理解する

システム設定の定義ファイルを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | system.py | `src/backend/InvenTree/common/setting/system.py` | SYSTEM_SETTINGS辞書の構造 |

**主要処理フロー**:
- **184行目〜**: SYSTEM_SETTINGS辞書で全設定項目を定義
- 各設定には name, description, default, validator, choices, after_save 等を指定

#### Step 3: APIエンドポイントを理解する

設定管理のREST APIを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | api.py | `src/backend/InvenTree/common/api.py` | GlobalSettingsList, GlobalSettingsDetail |

**主要処理フロー**:
- GlobalSettingsList: 設定一覧取得
- GlobalSettingsDetail: 個別設定の取得・更新

#### Step 4: コールバック処理を理解する

設定変更後の処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | system.py | `src/backend/InvenTree/common/setting/system.py` | after_save関数（update_instance_name, reload_plugin_registry等） |

**主要処理フロー**:
- **62-76行目**: update_instance_name()でインスタンス名をサイト設定に反映
- **78-92行目**: update_instance_url()でURLをサイト設定に反映
- **99-107行目**: reload_plugin_registry()でプラグイン再読み込み
- **109-121行目**: enforce_mfa()でMFA設定変更時に全セッション終了

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

```
InvenTreeSetting.get_setting(key)
    │
    ├─ get_setting_object(key)
    │      ├─ セッションキャッシュ確認
    │      ├─ グローバルキャッシュ確認
    │      └─ データベース検索/作成
    │
    └─ 値の型変換
           ├─ is_bool() → str2bool()
           ├─ is_int() → int()
           └─ is_float() → float()

InvenTreeSetting.set_setting(key, value)
    │
    ├─ バリデーション
    │      ├─ run_validator()
    │      └─ valid_options()
    │
    ├─ データベース保存
    │      └─ setting.save()
    │
    └─ after_saveコールバック
           └─ 定義された関数を実行
```

### データフロー図

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

設定取得要求 ───▶ セッションキャッシュ ───▶ キャッシュ値
        │                  │
        │            キャッシュミス
        │                  │
        ▼                  ▼
        │         グローバルキャッシュ ───▶ キャッシュ値
        │                  │
        │            キャッシュミス
        │                  │
        ▼                  ▼
        │         データベース検索 ───▶ DB値
        │                  │
        │            存在しない場合
        │                  │
        ▼                  ▼
        │         デフォルト値で作成 ───▶ デフォルト値
        │                  │
        └──────────────────┘
                           │
                           ▼
                    キャッシュ更新 ───▶ 値を返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| models.py | `src/backend/InvenTree/common/models.py` | ソース | 設定基底クラス、InvenTreeSettingモデル |
| system.py | `src/backend/InvenTree/common/setting/system.py` | ソース | システム設定定義 |
| user.py | `src/backend/InvenTree/common/setting/user.py` | ソース | ユーザー設定定義（参考） |
| api.py | `src/backend/InvenTree/common/api.py` | ソース | 設定API |
| serializers.py | `src/backend/InvenTree/common/serializers.py` | ソース | 設定シリアライザ |
