# 画面設計書 35-システム設定画面

## 概要

本ドキュメントはInvenTreeシステムにおけるシステム設定画面（SystemSettings）の設計仕様を記載したものである。本画面はシステム全体の動作に影響するグローバル設定を管理するための画面である。

### 本画面の処理概要

本画面はスタッフ権限を持つユーザーが、InvenTreeシステム全体の設定を参照・変更するための画面である。サーバー設定、認証設定、バーコード設定、価格設定、レポート設定、部品設定、在庫設定など、システムの各機能領域に関する設定を一括管理できる。

**業務上の目的・背景**：在庫管理システムの運用においては、組織の業務フローや規則に合わせてシステムの動作をカスタマイズする必要がある。例えば、部品番号の形式（IPN正規表現）、在庫の有効期限管理の有効化、発注書・販売注文の番号パターンなどである。本画面は、これらの設定を体系的に整理し、管理者が容易に設定変更できるインターフェースを提供する。

**画面へのアクセス方法**：ログイン後、ナビゲーションメニューから「設定」→「システム設定」を選択、またはURL `/settings/system/` に直接アクセスする。

**主要な操作・処理内容**：
1. サーバー基本設定（URL、インスタンス名、バックアップ等）を確認・変更する
2. 認証設定（パスワードリセット、MFA強制、SSO等）を確認・変更する
3. バーコード設定（有効化、Webカメラサポート等）を確認・変更する
4. 価格設定（デフォルト通貨、小数点桁数、自動更新等）を確認・変更する
5. レポート/ラベル設定を確認・変更する
6. 部品設定（IPN形式、リビジョン管理等）を確認・変更する
7. 在庫設定（シリアル番号、有効期限、所有権制御等）を確認・変更する
8. 製造/購買/販売オーダー設定を確認・変更する
9. プラグイン固有の設定を確認・変更する

**画面遷移**：
- 遷移元：ホーム画面、ナビゲーションメニュー、管理センター画面
- 遷移先：各設定項目固有の詳細画面（存在する場合）

**権限による表示制御**：本画面はスタッフ権限（is_staff=true）を持つユーザーのみアクセス可能。非スタッフユーザーには「PermissionDenied」が表示される。未ログイン状態ではSkeletonが表示される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 36 | グローバル設定管理 | 主機能 | サーバー・認証・バーコード・価格等のシステム設定 |
| 41 | バーコード生成 | 補助機能 | バーコード設定 |
| 27 | レポートテンプレート管理 | 補助機能 | レポート設定 |
| 28 | ラベルテンプレート管理 | 補助機能 | ラベル設定 |

## 画面種別

設定画面（パネル構成）

## URL/ルーティング

| パス | 説明 |
|------|------|
| `/settings/system/` | システム設定画面（デフォルトパネル） |
| `/settings/system/{panel}` | 特定パネルを選択した状態 |

## 入出力項目

各パネルで多数の設定項目を持つ。主要な設定キーを以下に示す。

### サーバー設定パネル (server)

| 設定キー | 説明 |
|----------|------|
| INVENTREE_BASE_URL | ベースURL |
| INVENTREE_COMPANY_NAME | 会社名 |
| INVENTREE_INSTANCE_ID | インスタンスID |
| INVENTREE_INSTANCE | インスタンス名 |
| INVENTREE_INSTANCE_TITLE | インスタンスタイトル表示 |
| DISPLAY_FULL_NAMES | フルネーム表示 |
| DISPLAY_PROFILE_INFO | プロファイル情報表示 |
| INVENTREE_BACKUP_ENABLE | バックアップ有効化 |
| INVENTREE_BACKUP_DAYS | バックアップ保持日数 |
| INVENTREE_DELETE_TASKS_DAYS | タスク削除日数 |
| INVENTREE_DELETE_ERRORS_DAYS | エラー削除日数 |
| INVENTREE_DELETE_NOTIFICATIONS_DAYS | 通知削除日数 |

### 認証設定パネル (authentication)

| 設定キー | 説明 |
|----------|------|
| LOGIN_ENABLE_PWD_FORGOT | パスワードリセット有効化 |
| LOGIN_MAIL_REQUIRED | メール必須 |
| LOGIN_ENFORCE_MFA | MFA強制 |
| LOGIN_ENABLE_REG | 登録有効化 |
| LOGIN_ENABLE_SSO | SSO有効化 |
| LOGIN_ENABLE_SSO_REG | SSO登録有効化 |
| LOGIN_ENABLE_SSO_GROUP_SYNC | SSOグループ同期 |
| SSO_GROUP_MAP | SSOグループマッピング |

### バーコード設定パネル (barcode)

| 設定キー | 説明 |
|----------|------|
| BARCODE_ENABLE | バーコード機能有効化 |
| BARCODE_INPUT_DELAY | 入力遅延 |
| BARCODE_WEBCAM_SUPPORT | Webカメラサポート |
| BARCODE_SHOW_TEXT | テキスト表示 |
| BARCODE_GENERATION_PLUGIN | 生成プラグイン |

### 価格設定パネル (pricing)

| 設定キー | 説明 |
|----------|------|
| INVENTREE_DEFAULT_CURRENCY | デフォルト通貨 |
| CURRENCY_CODES | 利用可能通貨コード |
| PART_INTERNAL_PRICE | 内部価格使用 |
| PRICING_DECIMAL_PLACES | 小数点桁数 |
| PRICING_AUTO_UPDATE | 自動更新 |
| CURRENCY_UPDATE_PLUGIN | 為替更新プラグイン |

### 部品設定パネル (parts)

| 設定キー | 説明 |
|----------|------|
| PART_IPN_REGEX | IPN正規表現 |
| PART_ALLOW_DUPLICATE_IPN | 重複IPN許可 |
| PART_ENABLE_REVISION | リビジョン管理有効化 |
| PART_NAME_FORMAT | 名前フォーマット |
| PART_TEMPLATE | テンプレートデフォルト |
| PART_ASSEMBLY | アセンブリデフォルト |

### 在庫設定パネル (stock)

| 設定キー | 説明 |
|----------|------|
| SERIAL_NUMBER_GLOBALLY_UNIQUE | シリアル番号グローバルユニーク |
| STOCK_ENABLE_EXPIRY | 有効期限有効化 |
| STOCK_STALE_DAYS | 滞留日数 |
| STOCK_OWNERSHIP_CONTROL | 所有権制御 |

### 製造オーダー設定パネル (buildorders)

| 設定キー | 説明 |
|----------|------|
| BUILDORDER_REFERENCE_PATTERN | 参照番号パターン |
| BUILDORDER_REQUIRE_RESPONSIBLE | 責任者必須 |
| BUILDORDER_REQUIRE_VALID_BOM | 有効BOM必須 |

### 購買オーダー設定パネル (purchaseorders)

| 設定キー | 説明 |
|----------|------|
| PURCHASEORDER_REFERENCE_PATTERN | 参照番号パターン |
| PURCHASEORDER_REQUIRE_RESPONSIBLE | 責任者必須 |
| PURCHASEORDER_AUTO_COMPLETE | 自動完了 |

### 販売オーダー設定パネル (salesorders)

| 設定キー | 説明 |
|----------|------|
| SALESORDER_REFERENCE_PATTERN | 参照番号パターン |
| SALESORDER_REQUIRE_RESPONSIBLE | 責任者必須 |
| SALESORDER_DEFAULT_SHIPMENT | デフォルト出荷 |

### 返品オーダー設定パネル (returnorders)

| 設定キー | 説明 |
|----------|------|
| RETURNORDER_ENABLED | 返品オーダー有効化 |
| RETURNORDER_REFERENCE_PATTERN | 参照番号パターン |

## 表示項目

### パネル一覧

| パネル名 | ラベル | アイコン | 説明 |
|---------|--------|---------|------|
| server | Server | IconServerCog | サーバー基本設定 |
| authentication | Authentication | IconFingerprint | 認証設定 |
| barcode | Barcodes | IconQrcode | バーコード設定 |
| notifications | Notifications | IconBellCog | 通知設定（プラグイン固有） |
| pricing | Pricing | IconCurrencyDollar | 価格・通貨設定 |
| labels | Labels | IconTag | ラベル設定 |
| reporting | Reporting | IconFileAnalytics | レポート設定 |
| parameters | Parameters | IconList | パラメータ設定 |
| parts | Parts | IconCategory | 部品設定 |
| stock | Stock | IconPackages | 在庫設定 |
| stock-history | Stock History | IconClipboardList | 在庫履歴・棚卸設定 |
| buildorders | Build Orders | IconTools | 製造オーダー設定 |
| purchaseorders | Purchase Orders | IconShoppingCart | 購買オーダー設定 |
| salesorders | Sales Orders | IconTruckDelivery | 販売オーダー設定 |
| returnorders | Return Orders | IconTruckReturn | 返品オーダー設定 |
| plugins | Plugin Settings | IconPlugConnected | プラグイン固有設定 |

## イベント仕様

### 1-ページ読み込み

**トリガー**：画面アクセス時

**処理内容**：
- useUserState()でユーザー認証状態を確認
- 未ログイン時はSkeletonを表示
- スタッフ権限チェック（isStaff()）
- 権限がない場合はPermissionDeniedを表示
- 権限がある場合はパネル一覧をレンダリング

### 2-パネル選択

**トリガー**：サイドバーまたはタブからパネルを選択

**処理内容**：
- URLが更新される
- 選択されたパネルのGlobalSettingListまたはPluginSettingsGroupがレンダリング

### 3-設定値変更

**トリガー**：設定項目の値を変更

**処理内容**：
- GlobalSettingListまたはUserSettingListコンポーネントが変更を検知
- `PATCH /api/settings/global/{key}/`でサーバーに設定値を送信
- 成功時は自動保存、エラー時はエラーメッセージ表示

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 設定一覧表示 | common_inventreesetting | SELECT | グローバル設定の取得 |
| 設定値変更 | common_inventreesetting | UPDATE | グローバル設定の更新 |

### テーブル別更新項目詳細

#### common_inventreesetting

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | key, value | 全レコードまたはkeys[]指定 | GlobalSettingListのkeysパラメータ |
| UPDATE | value | フォーム入力値 | key指定でPATCH |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|-----------|----------|
| 成功 | Setting updated | 設定更新成功時 |
| エラー | Error updating setting | 設定更新失敗時 |

## 例外処理

| 例外状況 | 表示内容 | 対応処理 |
|---------|---------|---------|
| 未ログイン | Skeleton | ローディング表示 |
| 非スタッフユーザー | PermissionDeniedコンポーネント | アクセス拒否表示 |
| API通信エラー | エラーメッセージ | 通知表示 |

## 備考

- 設定変更は即座にサーバーに反映される（自動保存）
- 一部の設定はサーバー再起動が必要な場合がある
- プラグイン設定パネル（plugins）は、インストールされたプラグインの設定を動的に表示する
- 通知設定パネル（notifications）は、通知プラグインの設定を表示する
- 設定項目の表示はGlobalSettingListコンポーネントが担当し、keysプロパティで表示する設定キーを指定する

---

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

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

### 推奨読解順序

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

まず、設定データの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SettingList.tsx | `src/frontend/src/components/settings/SettingList.tsx` | GlobalSettingListコンポーネントの動作 |

**読解のコツ**: keysプロパティに指定された設定キーのみが表示される

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

処理の起点となるページコンポーネントを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | SystemSettings.tsx | `src/frontend/src/pages/Index/Settings/SystemSettings.tsx` | メインコンポーネント全体（41-374行目） |

**主要処理フロー**:
1. **42-342行目**: systemSettingsPanelsのuseMemoで全パネル定義
2. **344行目**: useUserState()でユーザー認証状態を取得
3. **346行目**: useServerApiState()でサーバー情報を取得
4. **348-350行目**: 未ログイン時はSkeletonを表示
5. **352-373行目**: スタッフ権限判定とレンダリング

#### Step 3: パネル定義を理解する

各設定パネルの内容を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | SystemSettings.tsx | `src/frontend/src/pages/Index/Settings/SystemSettings.tsx` | serverパネル（44-75行目）の設定キー一覧 |
| 3-2 | SystemSettings.tsx | `src/frontend/src/pages/Index/Settings/SystemSettings.tsx` | authenticationパネル（76-101行目）の設定キー一覧 |
| 3-3 | SystemSettings.tsx | `src/frontend/src/pages/Index/Settings/SystemSettings.tsx` | partsパネル（195-227行目）の設定キー一覧 |

**主要処理フロー**:
- 各パネルはGlobalSettingListコンポーネントでkeys配列を指定
- PluginSettingsGroupはプラグイン固有設定を動的表示

#### Step 4: 設定コンポーネントを理解する

GlobalSettingListの動作を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | SettingList.tsx | `src/frontend/src/components/settings/SettingList.tsx` | GlobalSettingList関数コンポーネント |

**主要処理フロー**:
- keysプロパティで表示する設定キーを指定
- 各設定項目はフォームコントロールとして表示
- 値変更時にAPIを呼び出して保存

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

```
SystemSettings
    │
    ├─ useUserState() ─── ユーザー認証状態確認
    │      ├─ isLoggedIn() = false ───▶ Skeleton表示
    │      └─ isStaff() = false ───▶ PermissionDenied表示
    │
    ├─ useServerApiState()
    │      └─ server.instance ─── ヘッダーサブタイトル
    │
    ├─ useMemo(systemSettingsPanels)
    │      │
    │      ├─ server: GlobalSettingList(keys=[...])
    │      │
    │      ├─ authentication: GlobalSettingList(keys=[...])
    │      │
    │      ├─ barcode: GlobalSettingList(keys=[...])
    │      │
    │      ├─ notifications: PluginSettingsGroup(mixin='notification')
    │      │
    │      ├─ pricing: GlobalSettingList(keys=[...]) x3
    │      │
    │      ├─ labels: GlobalSettingList(keys=[...])
    │      │
    │      ├─ reporting: GlobalSettingList(keys=[...])
    │      │
    │      ├─ parameters: GlobalSettingList(keys=[...])
    │      │
    │      ├─ parts: GlobalSettingList(keys=[...])
    │      │
    │      ├─ stock: GlobalSettingList(keys=[...])
    │      │
    │      ├─ stock-history: GlobalSettingList(keys=[...])
    │      │
    │      ├─ buildorders: GlobalSettingList(keys=[...])
    │      │
    │      ├─ purchaseorders: GlobalSettingList(keys=[...])
    │      │
    │      ├─ salesorders: GlobalSettingList(keys=[...])
    │      │
    │      ├─ returnorders: GlobalSettingList(keys=[...])
    │      │
    │      └─ plugins: PluginSettingsGroup(global=true)
    │
    ├─ PageTitle ─── ブラウザタイトル設定
    ├─ SettingsHeader ─── 画面ヘッダー
    └─ PanelGroup
           └─ (各パネルコンテンツ)
```

### データフロー図

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

ログイン状態    ───▶ useUserState()           ───▶ 認証チェック結果
                      │
                      ├─ isLoggedIn() = false  ───▶ Skeleton
                      │
                      ├─ isStaff() = false     ───▶ PermissionDenied
                      │
                      └─ isStaff() = true      ───▶ 設定画面表示
                            │
                            ▼
                     useMemo(systemSettingsPanels)
                            │
                            ▼
パネル選択      ───▶ PanelGroup               ───▶ URL更新
                      │                              + パネルコンテンツ表示
                      ▼
設定キー配列   ───▶ GlobalSettingList
                      │
                      ├─ GET /api/settings/global/ ───▶ 設定値取得
                      │
                      └─ フォームコントロール   ───▶ 設定項目表示

設定値変更     ───▶ PATCH /api/settings/global/{key}/
                      │
                      └─ 成功/エラー           ───▶ 通知表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| SystemSettings.tsx | `src/frontend/src/pages/Index/Settings/SystemSettings.tsx` | ソース | メインページコンポーネント |
| router.tsx | `src/frontend/src/router.tsx` | ソース | ルーティング定義（160行目） |
| SettingList.tsx | `src/frontend/src/components/settings/SettingList.tsx` | ソース | GlobalSettingListコンポーネント |
| PluginSettingsGroup.tsx | `src/frontend/src/pages/Index/Settings/PluginSettingsGroup.tsx` | ソース | プラグイン設定グループ |
| PanelGroup.tsx | `src/frontend/src/components/panels/PanelGroup.tsx` | ソース | パネルグループコンポーネント |
| SettingsHeader.tsx | `src/frontend/src/components/nav/SettingsHeader.tsx` | ソース | 設定ヘッダーコンポーネント |
| PermissionDenied.tsx | `src/frontend/src/components/errors/PermissionDenied.tsx` | ソース | アクセス拒否コンポーネント |
| UserState.ts | `src/frontend/src/states/UserState.ts` | ソース | ユーザー状態管理 |
| ServerApiState.ts | `src/frontend/src/states/ServerApiState.ts` | ソース | サーバー状態管理 |
