# 機能設計書 4-部品パラメータ管理

## 概要

本ドキュメントは、InvenTreeシステムにおける部品パラメータ管理機能の設計を記述する。部品パラメータは、部品の技術仕様や特性値を構造化されたフォーマットで管理し、検索・比較・フィルタリングを可能にする。

### 本機能の処理概要

**業務上の目的・背景**：
電子部品や機械部品などでは、電圧定格、抵抗値、寸法、重量などの技術パラメータが重要である。部品パラメータ管理機能は、これらのパラメータをテンプレート化して一貫性のある形式で管理し、パラメータ値による部品検索・フィルタリングを実現する。物理単位（SI単位系）への対応により、異なる単位での値比較も可能となる。カテゴリごとにデフォルトパラメータを設定することで、新規部品登録時のパラメータ入力を効率化できる。

**機能の利用シーン**：
- 部品の技術仕様（電圧、電流、抵抗値、容量、寸法等）を登録する場面
- パラメータ値による部品検索・フィルタリングを行う場面
- 類似パラメータを持つ部品を比較する場面
- カテゴリにデフォルトパラメータを設定し、新規部品登録を効率化する場面
- パラメータテンプレートを新規作成・編集する場面

**主要な処理内容**：
1. パラメータテンプレートの作成・編集・削除
2. 部品へのパラメータ値の設定
3. カテゴリへのデフォルトパラメータテンプレート設定
4. 物理単位への変換と数値化
5. パラメータ値による検索・フィルタリング
6. 選択肢（choices）によるバリデーション

**関連システム・外部連携**：
- Part（部品）との連携（パラメータ値の保持）
- PartCategory（カテゴリ）との連携（デフォルトテンプレート）
- StockLocation（ロケーション）との連携（パラメータ対応）
- プラグインシステムとの連携（カスタムバリデーション）

**権限による制御**：
- パラメータの閲覧は一般ユーザーでも可能
- パラメータテンプレートの作成・編集にはpart.change_parametertemplate権限が必要
- パラメータ値の編集には対象オブジェクトの編集権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | 部品詳細画面 | 主機能 | パラメータタブでのパラメータ値表示・編集 |
| 13 | 部品カテゴリ一覧・詳細画面 | 参照画面 | カテゴリパラメータテンプレートの設定 |

## 機能種別

CRUD操作 / マスタ管理 / データ変換

## 入力仕様

### パラメータテンプレート

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | テンプレート名 | 最大100文字、空文字不可 |
| units | string | No | 単位 | 物理単位形式（例：mA, V, mm） |
| description | string | No | 説明 | 最大250文字 |
| checkbox | boolean | No | チェックボックス型 | |
| choices | string | No | 選択肢（カンマ区切り） | |
| enabled | boolean | No | 有効フラグ | デフォルトTrue |

### パラメータ値

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| template | integer | Yes | テンプレートID | 有効なParameterTemplateのID |
| model_type | string | Yes | 対象モデル種別 | 'part', 'stocklocation'等 |
| model_id | integer | Yes | 対象モデルID | 有効なモデルインスタンスのID |
| data | string | Yes | パラメータ値 | 選択肢がある場合はその中から選択 |
| note | string | No | 備考 | 最大500文字 |

### 入力データソース

- 画面入力（パラメータ編集フォーム）
- REST API（api-parameter-template-list, api-parameter-list）
- カテゴリデフォルト値からの自動設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| pk | integer | パラメータの主キー |
| template | integer | テンプレートID |
| template_detail | object | テンプレート詳細情報 |
| model_type | string | 対象モデル種別 |
| model_id | integer | 対象モデルID |
| data | string | パラメータ値 |
| data_numeric | float | 数値化された値（単位変換後） |
| note | string | 備考 |
| updated | datetime | 更新日時 |
| updated_by | integer | 更新者ID |

### 出力先

- 画面表示（パラメータ一覧、パラメータ詳細）
- REST API レスポンス
- レポート出力

## 処理フロー

### 処理シーケンス

```
1. パラメータテンプレート作成
   └─ バリデーション実行 → DB保存

2. パラメータ値設定
   └─ テンプレート検証 → 選択肢バリデーション → 単位バリデーション → 数値化 → DB保存

3. カテゴリデフォルト設定
   └─ テンプレート関連付け → デフォルト値設定 → 新規部品への自動適用

4. 数値化処理
   └─ 単位がある場合: SI単位への変換 → 数値格納
   └─ 単位がない場合: float変換試行 → 成功時は数値格納
```

### フローチャート

```mermaid
flowchart TD
    A[パラメータ操作開始] --> B{操作種別}
    B -->|テンプレート作成| C[バリデーション実行]
    C --> D[DB保存]

    B -->|値設定| E[テンプレート検証]
    E --> F{選択肢あり?}
    F -->|Yes| G{選択肢に含まれる?}
    G -->|No| H[ValidationError]
    G -->|Yes| I[単位バリデーション]
    F -->|No| I
    I --> J{単位変換成功?}
    J -->|No| H
    J -->|Yes| K[数値化処理]
    K --> L[プラグインバリデーション]
    L --> M{バリデーション通過?}
    M -->|No| H
    M -->|Yes| D

    D --> N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 選択肢制約 | 選択肢が定義されている場合、値はその中から選択 | template.choices が設定時 |
| BR-002 | 単位強制 | PARAMETER_ENFORCE_UNITS設定時、単位検証が必須 | 設定有効かつtemplate.units設定時 |
| BR-003 | チェックボックス変換 | checkbox=Trueの場合、値はTrue/Falseに正規化 | template.checkbox=True |
| BR-004 | 一意性制約 | 同一モデル・テンプレートの組み合わせは一意 | Parameter保存時 |
| BR-005 | カテゴリデフォルト | カテゴリにデフォルトテンプレートを設定可能 | PartCategoryParameterTemplate |
| BR-006 | テンプレート更新時の再計算 | テンプレート変更時、関連パラメータを再計算 | ParameterTemplate保存時 |

### 計算ロジック

```python
# 数値化処理
def calculate_numeric_value(self):
    if self.template.units:
        try:
            self.data_numeric = InvenTree.conversion.convert_physical_value(
                self.data, self.template.units
            )
        except (ValidationError, ValueError):
            self.data_numeric = None
    else:
        try:
            self.data_numeric = float(self.data)
        except ValueError:
            self.data_numeric = None

# チェックボックス値の正規化
if self.template.checkbox:
    self.data = InvenTree.helpers.str2bool(self.data)
    self.data_numeric = 1 if self.data else 0

# 単位変換の例
# "10mA" -> 0.01 (アンペアに変換)
# "100kOhm" -> 100000 (オームに変換)
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| テンプレート作成 | common_parametertemplate | INSERT | 新規テンプレートレコード挿入 |
| テンプレート編集 | common_parametertemplate | UPDATE | テンプレート情報更新 |
| テンプレート削除 | common_parametertemplate | DELETE | テンプレートレコード削除 |
| パラメータ値設定 | part_partparameter | INSERT/UPDATE | パラメータ値レコード操作 |
| パラメータ値削除 | part_partparameter | DELETE | パラメータ値レコード削除 |
| カテゴリデフォルト | part_partcategoryparametertemplate | INSERT/UPDATE/DELETE | カテゴリ関連操作 |

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

#### part_partparameter

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | model_type, model_id, template_id, data, data_numeric, note, updated, updated_by_id | 入力値、計算値 | 一意性制約あり |
| UPDATE | data, data_numeric, note, updated, updated_by_id | 入力値、計算値 | |
| DELETE | - | pk指定 | |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ValidationError | バリデーションエラー | 選択肢に含まれない値 | 有効な選択肢から選択 |
| ValidationError | バリデーションエラー | 単位変換失敗 | 正しい単位形式で入力 |
| ValidationError | バリデーションエラー | プラグインバリデーション失敗 | プラグイン要件を確認 |
| IntegrityError | 整合性エラー | 同一モデル・テンプレートの重複 | 既存パラメータを編集 |

### リトライ仕様

特になし

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

- パラメータの作成・更新・削除は単一トランザクション内で実行
- テンプレート変更時の再計算はバックグラウンドタスクで実行

## パフォーマンス要件

- パラメータ一覧取得: 1000件で1秒以内
- 単位変換: 10ms以内
- パラメータ検索: インデックスを活用した高速検索

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

- ユーザー権限に基づくアクセス制御
- プラグインバリデーションによるカスタム検証
- APIエンドポイントは認証必須

## 備考

- Pint（Python物理単位ライブラリ）を使用した単位変換
- パラメータはPart以外にもStockLocation等に設定可能（汎用設計）
- テンプレート名は大文字小文字を区別

---

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

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

### 推奨読解順序

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

ParameterTemplateとParameterモデルの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.py | `src/backend/InvenTree/common/models.py` | ParameterTemplateクラス（2466-2557行目） |
| 1-2 | models.py | `src/backend/InvenTree/common/models.py` | Parameterクラス（2578-2699行目） |

**読解のコツ**:
- ParameterTemplateはパラメータの「型」を定義（名前、単位、選択肢等）
- Parameterは実際の値を保持し、model_type/model_idでGenericForeignKey的に任意モデルに紐付け
- db_table = 'part_partparameter'で既存テーブルとの互換性を維持

**主要処理フロー**:
- **2578-2606行目**: Parameterクラス定義とMeta設定
- **2617-2630行目**: saveメソッド（数値化、チェックボックス処理）
- **2637-2678行目**: cleanメソッド（選択肢、単位、プラグインバリデーション）
- **2680-2699行目**: calculate_numeric_valueメソッド（単位変換）

#### Step 2: カテゴリデフォルト設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | models.py | `src/backend/InvenTree/part/models.py` | PartCategoryParameterTemplateクラス（351-428行目） |
| 2-2 | models.py | `src/backend/InvenTree/part/models.py` | Part.copy_parameters_from_category（2485-2520行目） |

**主要処理フロー**:
- **351-380行目**: クラス定義とドキュメント
- **384-407行目**: cleanメソッド（デフォルト値のバリデーション）

#### Step 3: 単位変換を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | conversion.py | `src/backend/InvenTree/InvenTree/conversion.py` | convert_physical_value関数 |

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

```
REST API Request
    │
    ├─ ParameterList (api.py)
    │      ├─ ParameterSerializer
    │      │      └─ Parameter.save()
    │      │             ├─ calculate_numeric_value()
    │      │             │      └─ InvenTree.conversion.convert_physical_value()
    │      │             ├─ checkbox処理
    │      │             └─ check_save()
    │      │
    │      └─ Parameter.clean()
    │             ├─ 選択肢バリデーション
    │             ├─ 単位バリデーション
    │             └─ プラグインバリデーション
    │
    └─ ParameterDetail (api.py)
           └─ 同上
```

### データフロー図

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

フォーム入力 ───▶ ParameterSerializer ───▶ JSONレスポンス
                        │
                        ▼
                 Parameter.clean()
                        │
                        ├─ 選択肢チェック
                        │
                        ├─ 単位変換チェック
                        │
                        └─ プラグインチェック
                                │
                                ▼
                        Parameter.save()
                                │
                                ├─ calculate_numeric_value()
                                │      │
                                │      └─ convert_physical_value()
                                │             │
                                │             └─ Pint単位変換
                                │
                                └─▶ part_partparameter テーブル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| models.py | `src/backend/InvenTree/common/models.py` | ソース | ParameterTemplate, Parameterモデル定義 |
| models.py | `src/backend/InvenTree/part/models.py` | ソース | PartCategoryParameterTemplateモデル定義 |
| api.py | `src/backend/InvenTree/common/api.py` | ソース | REST APIビュー定義 |
| serializers.py | `src/backend/InvenTree/common/serializers.py` | ソース | シリアライザ定義 |
| conversion.py | `src/backend/InvenTree/InvenTree/conversion.py` | ソース | 単位変換ロジック |
| validators.py | `src/backend/InvenTree/common/validators.py` | ソース | バリデーション関数 |
| tasks.py | `src/backend/InvenTree/common/tasks.py` | ソース | rebuild_parametersタスク |
