# 機能設計書 43-マシン設定管理

## 概要

本ドキュメントは、InvenTreeシステムにおけるマシン設定管理機能の設計仕様を定義する。この機能は、ラベルプリンターなどの外部機械の設定を管理し、ドライバーと接続設定のカスタマイズを可能にする。

### 本機能の処理概要

**業務上の目的・背景**：
製造業・倉庫管理において、ラベルプリンターやバーコードスキャナーなどの外部機器との連携は不可欠である。本機能は、これらの外部機械をInvenTreeシステムに登録し、ドライバー設定や接続パラメータを一元管理することで、機器の追加・変更・メンテナンスを容易にする。プラグインシステムと連携し、様々な種類の機器に対応できる拡張性を提供する。

**機能の利用シーン**：
- 新しいラベルプリンターをシステムに登録する
- 既存の機械のドライバー設定を変更する
- 機械の有効/無効を切り替える
- 機械の接続状態やエラーを確認する

**主要な処理内容**：
1. マシン設定の登録・編集・削除（MachineConfig CRUD操作）
2. マシンドライバーの設定管理（MachineSetting）
3. マシンレジストリへの登録・更新通知
4. マシンの初期化・ステータス管理

**関連システム・外部連携**：
- プラグインシステム（MachineType, MachineDriver）
- ラベル印刷機能との連携
- 外部ハードウェア（プリンター等）

**権限による制御**：
- マシン設定の管理はスタッフ権限が必要
- マシンステータスの参照は認証済みユーザーで可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 34 | 管理センター画面 | 補助機能 | マシン設定パネル |

## 機能種別

CRUD操作 / 設定管理 / データ連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | マシン名（一意） | 最大255文字、重複不可 |
| machine_type | string | Yes | マシンタイプ | 登録済みのマシンタイプのみ |
| driver | string | Yes | ドライバー名 | 登録済みのドライバーのみ |
| active | boolean | No | 有効フラグ（デフォルト: true） | |

### 入力データソース

- 管理画面のフォーム入力
- APIリクエスト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | UUID | マシンの一意識別子 |
| name | string | マシン名 |
| machine_type | string | マシンタイプ |
| driver | string | ドライバー名 |
| active | boolean | 有効フラグ |
| errors | array | エラーリスト |
| initialized | boolean | 初期化済みフラグ |
| status | object | マシンステータス |

### 出力先

- APIレスポンス（JSON形式）
- 管理画面表示

## 処理フロー

### 処理シーケンス

```
1. マシン設定の作成/更新リクエスト
   └─ MachineConfig.save()
2. バリデーション実行
   └─ name, machine_type, driverの検証
3. データベースへの保存
   └─ MachineConfigテーブルへINSERT/UPDATE
4. レジストリへの通知
   └─ registry.add_machine()またはregistry.update_machine()
5. マシンの初期化（作成時）
   └─ machine.initialize()
```

### フローチャート

```mermaid
flowchart TD
    A[マシン設定リクエスト] --> B{新規作成?}
    B -->|Yes| C[バリデーション]
    B -->|No| D[既存設定取得]
    D --> C
    C --> E{検証OK?}
    E -->|No| F[エラーレスポンス]
    E -->|Yes| G[DB保存]
    G --> H{新規作成?}
    H -->|Yes| I[registry.add_machine]
    H -->|No| J[registry.update_machine]
    I --> K[初期化実行]
    J --> L[更新フック実行]
    K --> M[レスポンス返却]
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-43-01 | マシン名一意性 | マシン名はシステム内で一意でなければならない | マシン作成・更新時 |
| BR-43-02 | レジストリ同期 | マシン設定変更時は必ずレジストリに通知 | 全ての保存・削除操作 |
| BR-43-03 | ドライバー有効性 | 指定されたドライバーが利用可能である必要がある | マシン作成・更新時 |
| BR-43-04 | 削除前レジストリ解除 | マシン削除前にレジストリから解除 | マシン削除時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| マシン登録 | machine_machineconfig | INSERT | 新規マシン設定の作成 |
| マシン更新 | machine_machineconfig | UPDATE | 既存マシン設定の更新 |
| マシン削除 | machine_machineconfig | DELETE | マシン設定の削除 |
| 設定取得 | machine_machinesetting | SELECT | マシン設定値の取得 |
| 設定更新 | machine_machinesetting | INSERT/UPDATE | マシン設定値の保存 |

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

#### machine_machineconfig

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | UUID自動生成 | プライマリキー |
| INSERT | name | ユーザー入力値 | 一意制約あり |
| INSERT | machine_type | ユーザー選択値 | |
| INSERT | driver | ユーザー選択値 | |
| INSERT | active | true（デフォルト） | |

#### machine_machinesetting

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | machine_config | ForeignKey | MachineConfigへの参照 |
| INSERT/UPDATE | config_type | 'M' or 'D' | Machine or Driver |
| INSERT/UPDATE | key | 設定キー | |
| INSERT/UPDATE | value | 設定値 | |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 400 | ValidationError | マシン名が重複 | 別のマシン名を指定 |
| 400 | ValidationError | 無効なマシンタイプ | 有効なマシンタイプを選択 |
| 400 | ValidationError | 無効なドライバー | 有効なドライバーを選択 |
| 403 | PermissionDenied | スタッフ権限なし | 管理者に権限付与を依頼 |

### リトライ仕様

設定操作は冪等であり、エラー時は再試行が可能。

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

マシン設定の保存とレジストリへの通知は同一トランザクション内で実行されない。レジストリへの通知は保存後のコールバックで実行される。

## パフォーマンス要件

- マシン設定のCRUD操作：500ms以内
- レジストリ同期：即座に実行

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

- マシン設定の変更はスタッフ権限が必要
- 機器接続情報（IPアドレス等）は適切に保護

## 備考

- マシンインスタンスはregistry.get_machine(pk)で取得可能
- マシンのエラー状態はerrorsプロパティで確認可能

---

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

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

### 推奨読解順序

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

マシン設定のデータモデルを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.py | `src/backend/InvenTree/machine/models.py` | MachineConfigクラス（17-130行目）、MachineSettingクラス（132-205行目） |

**読解のコツ**:
- `id`フィールドがUUIDであることに注意
- `save()`メソッドでレジストリへの通知を行っている（47-68行目）
- `delete()`メソッドで先にレジストリから削除（70-75行目）
- `machine`プロパティでレジストリからインスタンスを取得

#### Step 2: マシンレジストリを理解する

マシンの登録・管理を行うレジストリの動作を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | registry.py | `src/backend/InvenTree/machine/registry.py` | マシンレジストリの実装（ファイル全体） |

**主要処理フロー**:
- `add_machine()`: 新規マシンの登録と初期化
- `update_machine()`: 既存マシンの更新通知
- `remove_machine()`: マシンの削除
- `get_machine()`: PKによるマシン取得

#### Step 3: マシンタイプとドライバーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | machine_type.py | `src/backend/InvenTree/machine/machine_type.py` | BaseMachineTypeクラス |

**主要処理フロー**:
- マシンタイプの基底クラス
- ドライバーとの連携インターフェース

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

```
MachineConfig.save()
    │
    ├─ super().save()
    │      └─ DBへの保存
    │
    └─ {created: true}
           │
           ├─ registry.add_machine(self, initialize=True)
           │      │
           │      └─ machine.initialize()
           │
           └─ {created: false}
                  │
                  └─ registry.update_machine(old_machine, self)

MachineConfig.delete()
    │
    ├─ registry.remove_machine(self.machine)
    │
    └─ super().delete()
```

### データフロー図

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

管理画面        ───▶ MachineConfig       ───▶ DB保存
フォーム入力           モデル操作               machine_machineconfig
                        │
                        ▼
                 レジストリ通知
                        │
                        ▼                    [副作用]
                 マシン初期化        ───▶ 外部機器との接続
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| models.py | `src/backend/InvenTree/machine/models.py` | ソース | MachineConfig, MachineSettingモデル |
| registry.py | `src/backend/InvenTree/machine/registry.py` | ソース | マシンレジストリ |
| machine_type.py | `src/backend/InvenTree/machine/machine_type.py` | ソース | マシンタイプ基底クラス |
| api.py | `src/backend/InvenTree/machine/api.py` | ソース | マシンAPI エンドポイント |
| serializers.py | `src/backend/InvenTree/machine/serializers.py` | ソース | マシンシリアライザ |
