# 機能設計書 37-ユーザー設定管理

## 概要

本ドキュメントは、InvenTreeシステムにおけるユーザー設定管理機能の設計を定義する。個々のユーザーに対する個人設定の管理・参照・更新を行う機能を提供する。

### 本機能の処理概要

ユーザー設定管理機能は、InvenTreeシステムを利用する各ユーザー固有の設定を管理する。InvenTreeUserSettingモデルを通じて、言語、テーマ、表示オプションなどユーザーごとにカスタマイズ可能な設定を保存・取得する。

**業務上の目的・背景**：同じ在庫管理システムを使用するユーザーでも、言語や表示設定の好みは異なる。各ユーザーが自分の使いやすいように設定をカスタマイズできることで、作業効率が向上する。

**機能の利用シーン**：
- ユーザーの言語設定変更
- ダッシュボードウィジェットのカスタマイズ
- テーブル表示オプションの設定
- 検索のデフォルト設定
- 通知設定のカスタマイズ

**主要な処理内容**：
1. ユーザー設定値の取得（ユーザーとキーで特定）
2. ユーザー設定値の更新
3. 設定定義の参照（デフォルト値、選択肢）
4. ユーザーごとの設定一覧管理
5. 設定のリセット（デフォルト値に戻す）

**関連システム・外部連携**：
- グローバル設定（デフォルト値の参照）
- プラグインユーザー設定（プラグインごとの個人設定）

**権限による制御**：ユーザーは自身の設定のみ変更可能。他ユーザーの設定へのアクセスは不可。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 36 | ユーザー設定画面 | 主画面 | ユーザー個人設定の表示・編集 |
| 37 | ホーム画面 | 参照画面 | ダッシュボードウィジェット設定の適用 |

## 機能種別

設定管理 / パーソナライゼーション

## 入力仕様

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

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

### 入力データソース

- ユーザー設定画面からのフォーム入力
- REST API経由のJSON入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| pk | int | 設定ID |
| key | str | 設定キー |
| value | str | 設定値 |
| user | int | ユーザーID |
| name | str | 設定名（表示用） |
| description | str | 設定の説明 |
| type | str | 設定タイプ（boolean, integer等） |

### 出力先

- REST APIレスポンス（JSON）
- ユーザー設定画面への表示
- データベース（common_inventreeusersetting）

## 処理フロー

### 処理シーケンス

```
1. ユーザー設定取得リクエスト
   └─ ユーザー認証確認
2. キャッシュ確認
   └─ user:keyでキャッシュ検索
3. データベース検索
   └─ user_id, keyで検索
4. 設定が存在しない場合
   └─ デフォルト値を返却（または作成）
5. 結果返却
   └─ 設定値を返却
```

### フローチャート

```mermaid
flowchart TD
    A[ユーザー設定取得リクエスト] --> B{ユーザー認証?}
    B -->|No| C[401エラー]
    B -->|Yes| D{キャッシュ存在?}
    D -->|Yes| E[キャッシュ値返却]
    D -->|No| F[データベース検索]
    F --> G{設定存在?}
    G -->|Yes| H[キャッシュ更新して返却]
    G -->|No| I[デフォルト値返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-37-01 | ユーザースコープ | ユーザーは自身の設定のみアクセス可能 | 全操作 |
| BR-37-02 | デフォルト値継承 | 設定が未設定の場合はグローバル設定またはデフォルト値を使用 | 設定取得時 |
| BR-37-03 | 設定キー正規化 | 設定キーは大文字に正規化 | 設定アクセス時 |
| BR-37-04 | 型変換 | 設定値は定義された型に自動変換 | 設定取得時 |

### 計算ロジック

設定値の取得優先順位:
1. ユーザー設定（common_inventreeusersetting）
2. グローバルデフォルト（設定定義のdefault）
3. システムデフォルト（空文字等）

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

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

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

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

#### common_inventreeusersetting

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | key, user_id | 大文字正規化キーとユーザーID | |
| INSERT | key, user_id, value | 設定キー、ユーザーID、値 | |
| UPDATE | value | 新しい設定値 | |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 401 | Unauthorized | 未認証でアクセス | ログインする |
| 400 | ValidationError | 設定値が不正 | 有効な値を入力 |

### リトライ仕様

特別なリトライ仕様は不要。

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

- 設定の取得・更新は個別のトランザクションで処理

## パフォーマンス要件

- ユーザー設定取得：10ms以内
- 設定キャッシュ対応

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

- ユーザーは自身の設定のみアクセス可能
- 他ユーザーの設定へのアクセスは403エラー
- プライバシーに関する設定は暗号化を検討

## 備考

USER_SETTINGS（主要な設定項目）:
- HOMEPAGE_WIDGETS: ダッシュボードウィジェット設定
- LANGUAGE: 言語設定
- SEARCH_*: 各種検索デフォルト設定
- TABLE_*: テーブル表示設定

---

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

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

### 推奨読解順序

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

ユーザー設定モデルの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.py | `src/backend/InvenTree/common/models.py` | InvenTreeUserSettingクラスの定義 |

**読解のコツ**:
- InvenTreeUserSettingはBaseInvenTreeSettingを継承
- userフィールドでユーザーと関連付け
- extra_unique_fields = ['user']でユーザーごとに一意

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

ユーザー設定の定義ファイルを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | user.py | `src/backend/InvenTree/common/setting/user.py` | USER_SETTINGSの定義 |

**主要処理フロー**:
- 各設定には name, description, default, validator, choices 等を指定
- HOMEPAGE_*、SEARCH_*、TABLE_*などのカテゴリ別設定

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

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

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

**主要処理フロー**:
- UserSettingsList: ユーザー設定一覧取得
- UserSettingsDetail: 個別設定の取得・更新
- get_queryset()でuser=request.userフィルタリング

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

```
InvenTreeUserSetting.get_setting(key, user=user)
    │
    ├─ get_filters()
    │      └─ {'user': user}
    │
    ├─ get_setting_object(key, user=user)
    │      ├─ キャッシュ確認（user:key）
    │      └─ データベース検索
    │
    └─ 値の型変換
           └─ is_bool(), is_int(), is_float()

UserSettingsDetail API
    │
    ├─ GET: 設定値取得
    │      └─ user=request.userでフィルタ
    │
    └─ PATCH: 設定値更新
           └─ バリデーション → 保存
```

### データフロー図

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

設定取得要求 ───▶ ユーザー認証 ───▶ 認証OK
  + user                   │
  + key                    ▼
                    キャッシュ検索 ───▶ ヒット → 値返却
                           │
                     キャッシュミス
                           │
                           ▼
                    DB検索(user, key) ───▶ 存在 → 値返却
                           │
                        存在しない
                           │
                           ▼
                    デフォルト値返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| models.py | `src/backend/InvenTree/common/models.py` | ソース | InvenTreeUserSettingモデル |
| 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` | ソース | 設定シリアライザ |
| UserSettings.tsx | `src/frontend/src/pages/Index/Settings/UserSettings/` | フロントエンド | ユーザー設定画面 |
