# 機能設計書 12-パーツパラメータ表示

## 概要

本ドキュメントは、InvenTreeモバイルアプリにおけるパーツパラメータ表示機能の設計仕様を定義する。

### 本機能の処理概要

本機能は、パーツのパラメータ（仕様値）を表示・編集する機能である。パーツパラメータは、部品の電気的特性（抵抗値、容量等）、物理的特性（重量、寸法等）、その他の技術仕様を体系的に管理するために使用される。

**業務上の目的・背景**：電子部品や機械部品を管理する際、各パーツには多様なパラメータ（仕様値）が存在する。例えば、コンデンサには容量値、耐圧、温度特性などのパラメータがある。これらのパラメータを一元管理することで、部品選定時の仕様比較や、設計要件との適合確認が容易になる。また、パラメータテンプレートを使用することで、同種部品間でのデータ整合性を確保できる。

**機能の利用シーン**：
- パーツの詳細仕様を確認する場合
- パーツの仕様値を更新する場合
- チェックボックス型パラメータのON/OFF切替
- 複数パーツの仕様を比較する場合

**主要な処理内容**：
1. 指定されたモデルタイプとIDに基づいてパラメータ一覧を取得
2. 各パラメータの名前、説明、値、単位を表示
3. チェックボックス型パラメータはSwitchウィジェットで表示
4. 編集可能な場合、パラメータ値の更新を実行
5. ページネーション対応による大量パラメータの効率的な表示

**関連システム・外部連携**：InvenTree APIの `parameter/` エンドポイントを使用してパラメータデータを取得・更新する。APIバージョン429以降の「モダンパラメータAPI」に対応。

**権限による制御**：モデルタイプに応じた権限が必要。editableフラグにより編集可否を制御。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | 部品詳細画面 | 主画面 | パラメータ項目押下時にパラメータ一覧表示 |

## 機能種別

データ参照（READ）/ データ更新（UPDATE）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| modelType | String | Yes | モデルタイプ（例："part"） | 空文字不可 |
| modelId | int | Yes | モデルID | 正の整数 |
| editable | bool | Yes | 編集可否フラグ | true/false |
| limit | int | No | 1ページあたりの取得件数（デフォルト25） | 正の整数 |
| offset | int | No | 取得開始位置 | 0以上の整数 |

### 入力データソース

- パーツ詳細画面から渡されるモデルタイプとID
- ユーザーによるパラメータ値の入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| pk | int | パラメータの主キー |
| name | String | パラメータ名（テンプレートから取得） |
| description | String | パラメータの説明（テンプレートから取得） |
| data | String | パラメータ値 |
| units | String | 単位（テンプレートから取得） |
| checkbox | bool | チェックボックス型か否か |
| model_type | String | 関連モデルタイプ |
| model_id | int | 関連モデルID |

### 出力先

- ListView形式の画面表示
- ListTileウィジェットによる各パラメータ情報の表示
- チェックボックス型はSwitchウィジェットで表示

## 処理フロー

### 処理シーケンス

```
1. パーツ詳細画面からパラメータ表示を呼び出し
   └─ ParameterWidget(modelType, modelId, editable)を生成
2. APIリクエストの構築
   └─ parameter/ エンドポイントにmodel_type, model_idフィルタを設定
3. ページネーション付きでパラメータ一覧を取得
   └─ InvenTreeParameter().listPaginated()を呼び出し
4. 取得データをListViewで表示
   └─ 各項目をListTile（または Switch）として構築
5. ユーザーがパラメータを編集（編集可能な場合）
   └─ チェックボックス型：Switch操作で即時更新
   └─ その他：editForm()でダイアログ表示後に更新
6. APIで値を更新
   └─ parameter.update()を呼び出し
```

### フローチャート

```mermaid
flowchart TD
    A[パーツ詳細画面] --> B[パラメータ表示を選択]
    B --> C[ParameterWidget生成]
    C --> D[PaginatedParameterList表示]
    D --> E[InvenTreeParameter.listPaginated]
    E --> F[パラメータ一覧表示]
    F --> G{ユーザー操作}
    G -->|チェックボックス切替| H[即時更新API呼び出し]
    G -->|テキスト項目タップ| I{editable?}
    I -->|Yes| J[editForm表示]
    I -->|No| F
    J --> K[値を入力して保存]
    K --> L[parameter.update]
    H --> L
    L --> M[リスト更新]
    M --> F
    G -->|スクロール| N[次ページ取得]
    N --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-12-01 | パラメータテンプレート | パラメータはテンプレートに基づいて定義される | 常時 |
| BR-12-02 | チェックボックス型 | checkbox=trueの場合、Switchウィジェットで表示・操作 | template_detail.checkbox == true |
| BR-12-03 | 編集可否制御 | editableフラグがfalseの場合は表示のみ | 常時 |
| BR-12-04 | モダンパラメータAPI | APIバージョン429以降でのみ利用可能 | supportsModernParameters == true |
| BR-12-05 | パラメータカウント | パラメータが0件の場合は表示項目自体を非表示 | parameterCount == 0 |

### 計算ロジック

- チェックボックス値変換: `as_bool` = value.toLowerCase() == "true"

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| パラメータ取得 | Parameter | SELECT | モデルタイプとIDに関連するパラメータを取得 |
| パラメータ更新 | Parameter | UPDATE | パラメータ値を更新 |

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

#### Parameter（InvenTree API経由）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | model_type, model_id | 指定されたモデルタイプとID | フィルタ条件 |
| SELECT | data, template_detail等 | - | 取得対象カラム |
| UPDATE | data | ユーザー入力値 | パラメータ値の更新 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 401 | 認証エラー | トークン無効または期限切れ | 再ログインを促す |
| 403 | 権限エラー | 編集権限がない | 読み取り専用モードで表示 |
| 404 | Not Found | パラメータが存在しない | エラーメッセージを表示 |
| 500 | サーバーエラー | サーバー内部エラー | リトライまたはエラー表示 |

### リトライ仕様

ネットワークエラー時はプルダウンリフレッシュで再取得可能。更新失敗時はエラー表示後に再試行可能。

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

パラメータ更新は単一レコードの更新のため、明示的なトランザクション管理は不要。

## パフォーマンス要件

- ページサイズ：25件（PaginatedSearchState._pageSize）
- スクロールによる遅延読み込み対応
- 更新時はローディングオーバーレイ表示

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

- API認証トークンによるアクセス制御
- editableフラグによる編集権限の分離
- HTTPS通信によるデータ保護

## 備考

- モダンパラメータAPI（APIバージョン429以降）にのみ対応
- 旧APIバージョンでは本機能は利用不可（ShowParametersItemでnullを返す）
- パラメータ追加機能はモバイルアプリでは未実装

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | parameter.dart | `lib/inventree/parameter.dart` | InvenTreeParameterクラスの定義、プロパティ（name, data, units, checkbox等）を理解する |

**読解のコツ**:
- **3-77行目**: InvenTreeParameterクラスの完全な定義
- **13行目**: APIエンドポイント `parameter/`
- **33-36行目**: name, descriptionはtemplate_detailサブキーから取得
- **38-48行目**: value, valueString, as_boolの実装
- **53-56行目**: units, is_checkboxの実装（template_detailから取得）
- **65-76行目**: countParameters()メソッドでパラメータ数を取得

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | parameter_widget.dart | `lib/widget/parameter_widget.dart` | ParameterWidgetクラスのエントリーポイント、modelType/modelId/editableを受け取る |

**主要処理フロー**:
1. **17-26行目**: ParameterWidgetの定義、modelType, modelId, editableを受け取る
2. **42-53行目**: getBody()でPaginatedParameterListを構築、フィルタを設定
3. **160-192行目**: ShowParametersItem()関数でパーツ詳細画面からの呼び出しを処理

#### Step 3: ページネーション対応リストを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | parameter_widget.dart | `lib/widget/parameter_widget.dart` | PaginatedParameterListクラスによるページネーション対応の一覧表示を理解 |

**主要処理フロー**:
- **59-70行目**: PaginatedParameterListクラスの定義
- **88-100行目**: requestPage()でInvenTreeParameter().listPaginated()を呼び出し
- **102-115行目**: editParameter()でチェックボックス以外のパラメータ編集
- **117-154行目**: buildItem()で各パラメータのListTileを構築

#### Step 4: チェックボックス型パラメータの即時更新を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | parameter_widget.dart | `lib/widget/parameter_widget.dart` | Switchウィジェットによるチェックボックス型パラメータの即時更新処理 |

**主要処理フロー**:
- **130-144行目**: Switchウィジェットの実装
- **133行目**: parameter.as_boolで現在値を取得
- **136-141行目**: onChangedでparameter.update()を呼び出し、data値を更新

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

```
ShowParametersItem (パーツ詳細画面から呼び出し)
    │
    └─ ParameterWidget
           │
           └─ PaginatedParameterList
                  │
                  ├─ PaginatedSearchState (基底クラス)
                  │      └─ requestPage()
                  │              └─ InvenTreeParameter().listPaginated()
                  │                      └─ InvenTreeAPI.get()
                  │
                  ├─ buildItem()
                  │      ├─ ListTile (通常パラメータ)
                  │      │      └─ onTap: editParameter()
                  │      │              └─ parameter.editForm()
                  │      │
                  │      └─ Switch (チェックボックス型)
                  │              └─ onChanged: parameter.update()
                  │
                  └─ editParameter()
                         └─ parameter.editForm()
                                └─ launchApiForm()
```

### データフロー図

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

modelType ─────▶ InvenTreeParameter ───────▶ ListView
modelId             .listPaginated()              (ListTile/Switch)
editable                   │
                           ▼
                 API: parameter/
                           │
                           ▼
                 JSON Response ──────▶ List<InvenTreeParameter>
                                               │
                                               ▼
                                    画面表示（名前, 値, 単位）
                                               │
                                               ▼ (編集時)
                                    parameter.update() ──▶ API PATCH
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| parameter_widget.dart | `lib/widget/parameter_widget.dart` | ソース | パラメータ表示・編集ウィジェット、ShowParametersItem関数 |
| parameter.dart | `lib/inventree/parameter.dart` | ソース | InvenTreeParameterモデルクラス定義 |
| model.dart | `lib/inventree/model.dart` | ソース | 基底モデルクラス、API呼び出し共通処理、editForm()メソッド |
| paginator.dart | `lib/widget/paginator.dart` | ソース | ページネーション対応検索ウィジェット基底クラス |
| refreshable_state.dart | `lib/widget/refreshable_state.dart` | ソース | リフレッシュ可能な状態管理基底クラス |
| api.dart | `lib/api.dart` | ソース | InvenTree API通信クラス、supportsModernParametersプロパティ |
| api_form.dart | `lib/api_form.dart` | ソース | APIフォーム起動、launchApiForm()関数 |
| progress.dart | `lib/widget/progress.dart` | ソース | ローディングオーバーレイ表示 |
