# 機能設計書 5-パーツ詳細表示

## 概要

本ドキュメントは、InvenTreeモバイルアプリにおけるパーツ詳細表示機能の設計を記載する。個々のパーツの詳細情報（在庫数、価格、BOM、サプライヤー等）を表示する機能を提供する。

### 本機能の処理概要

特定のパーツに関する包括的な情報を表示する機能である。基本情報（名前、説明、IPN、カテゴリ）に加え、在庫状況、価格情報、BOM（部品表）、サプライヤー情報、パラメータ、添付ファイル、ノートなど、パーツに関連するあらゆる情報を集約して表示する。

**業務上の目的・背景**：在庫管理業務において、特定のパーツの詳細情報を把握することは発注判断、在庫調整、製造計画などの意思決定に不可欠である。パーツに紐づく様々な情報を一箇所で確認でき、関連画面への素早いナビゲーションが可能であることが求められる。

**機能の利用シーン**：パーツ一覧からの詳細確認、バーコードスキャンによるパーツ特定後の詳細表示、在庫アイテムからの関連パーツ確認、BOMからの構成パーツ確認などで利用される。

**主要な処理内容**：
1. パーツ基本情報の表示（名前、説明、IPN、リビジョン、カテゴリ）
2. 在庫情報の表示（利用可能在庫、総在庫、デフォルトロケーション）
3. 要件情報の表示（ビルド中、発注中、引当状況）
4. 価格情報の表示（価格レンジ、価格詳細画面へのリンク）
5. BOM情報の表示（アセンブリの場合）
6. バリアント一覧の表示（テンプレートパーツの場合）
7. サプライヤー情報の表示（購入可能パーツの場合）
8. 関連在庫アイテムの一覧表示
9. 添付ファイル・ノート・パラメータへのアクセス

**関連システム・外部連携**：InvenTree REST API（part/{pk}/、part/{pk}/pricing/、part/{pk}/requirements/）

**権限による制御**：partロールのview権限が必要。編集権限がない場合は編集ボタンが非表示。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | バーコードスキャン画面 | 遷移元画面 | パーツバーコード照合成功時にパーツ詳細画面へ遷移 |
| 20 | 部品カテゴリ画面 | 遷移元画面 | パーツ選択時にパーツ詳細画面へ遷移 |
| 21 | 部品一覧画面 | 遷移元画面 | パーツ選択時にパーツ詳細画面へ遷移 |
| 22 | 部品詳細画面 | 主画面 | パーツの詳細情報表示、各種操作 |
| 25 | 在庫アイテム詳細画面 | 遷移元画面 | パーツ項目押下時にパーツ詳細画面へ遷移 |

## 機能種別

データ参照 / 詳細表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| part | InvenTreePart | Yes | 表示対象のパーツオブジェクト | null不可、pk必須 |

### 入力データソース

- パーツ一覧からの遷移時に渡されるパーツオブジェクト
- バーコードスキャン結果からのパーツ取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| part | InvenTreePart | パーツオブジェクト（リロード後） |
| parentPart | InvenTreePart? | テンプレートパーツ（バリアントの場合） |
| defaultLocation | InvenTreeStockLocation? | デフォルトロケーション |
| partPricing | InvenTreePartPricing? | 価格情報 |
| partRequirements | InvenTreePartRequirements? | 要件情報 |
| parameterCount | int | パラメータ件数 |
| attachmentCount | int | 添付ファイル件数 |
| bomCount | int | BOMアイテム件数 |
| usedInCount | int | 使用先パーツ件数 |
| variantCount | int | バリアント件数 |

### 出力先

- UI（詳細画面の各タイル・タブ）

## 処理フロー

### 処理シーケンス

```
1. 詳細画面表示
   └─ パーツのリロード（最新データ取得）

2. 設定読み込み
   └─ showRequirements設定
   └─ showPricing設定
   └─ showBom設定
   └─ allowLabelPrinting設定

3. 関連データ取得（並行処理）
   └─ テンプレートパーツ取得（バリアントの場合）
   └─ デフォルトロケーション取得
   └─ テストテンプレート取得（テスト可能の場合）
   └─ 添付ファイル件数取得
   └─ パラメータ件数取得
   └─ 要件情報取得
   └─ 価格情報取得
   └─ BOMアイテム件数取得
   └─ 使用先件数取得
   └─ バリアント件数取得

4. UI構築
   └─ 詳細タブ（partTiles）
   └─ 在庫タブ（PaginatedStockItemList）

5. ユーザーアクション
   └─ 編集ボタン → 編集ダイアログ
   └─ 各タイルタップ → 関連画面遷移
   └─ アクションボタン → 在庫作成、ラベル印刷
```

### フローチャート

```mermaid
flowchart TD
    A[詳細画面表示] --> B[パーツリロード]
    B --> C{リロード成功?}
    C -->|No| D[前画面に戻る]
    C -->|Yes| E[設定読み込み]
    E --> F[関連データ取得]
    F --> G[UI構築]
    G --> H[詳細タブ表示]
    H --> I{ユーザー操作}
    I -->|編集| J[編集ダイアログ]
    I -->|カテゴリタップ| K[カテゴリ画面遷移]
    I -->|価格タップ| L[価格詳細画面遷移]
    I -->|BOMタップ| M[BOM一覧画面遷移]
    I -->|サプライヤータップ| N[サプライヤー一覧遷移]
    I -->|在庫作成| O[在庫作成フォーム]
    I -->|ラベル印刷| P[ラベル印刷処理]
    I -->|バーコード| Q[バーコード操作]
    I -->|在庫タブ| R[在庫一覧表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 非アクティブ警告 | アクティブでないパーツは警告表示 | isActive=false |
| BR-02 | BOM表示条件 | アセンブリパーツのみBOMセクション表示 | isAssembly=true |
| BR-03 | 使用先表示条件 | コンポーネントパーツのみ使用先表示 | isComponent=true |
| BR-04 | サプライヤー表示条件 | 購入可能パーツのみサプライヤー表示 | isPurchaseable=true |
| BR-05 | 要件表示条件 | 設定ONかつAPI対応時のみ要件表示 | showRequirements=true && apiVersion>=350 |
| BR-06 | 価格表示条件 | 設定ONの場合のみ価格セクション表示 | showPricing=true |

### 計算ロジック

**在庫数表示**:
- 利用可能在庫と総在庫が異なる場合: `{unallocatedStock} / {inStock}`
- 同じ場合: `{inStock}`
- 単位がある場合は末尾に単位を追加

**価格レンジ表示**:
- `formatPriceRange(overallMin, overallMax, currency)`を使用

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 設定読み込み | settings | SELECT | 表示設定の取得 |

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

#### settings（ローカル設定）

| 操作 | 項目（キー） | 取得条件 | 備考 |
|-----|-------------|---------|------|
| SELECT | INV_PART_SHOW_REQUIREMENTS | - | 要件表示設定 |
| SELECT | INV_PART_SHOW_PRICING | - | 価格表示設定 |
| SELECT | INV_PART_SHOW_BOM | - | BOM表示設定 |
| SELECT | INV_ENABLE_LABEL_PRINTING | - | ラベル印刷設定 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | リロード失敗 | パーツが削除されている等 | 前画面に戻る |
| 401/403 | 認証/権限エラー | partロールなし | エラーメッセージ表示 |
| 404 | 未検出エラー | パーツが存在しない | 前画面に戻る |

### リトライ仕様

- プルリフレッシュによる手動リトライ

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

- 読み取り専用（トランザクションなし）

## パフォーマンス要件

- 関連データは非同期で並行取得
- サムネイル画像はキャッシュ利用

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

- partロールのview権限が必要
- 編集ボタンはpart.canEditの場合のみ表示

## 備考

- 2つのタブ構成：詳細タブ、在庫タブ
- アクションボタン：在庫作成、ラベル印刷（条件付き）
- バーコードボタン：カスタムバーコード割当/解除

---

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

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

### 推奨読解順序

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

まず、パーツとその関連データモデルを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | part.dart | `lib/inventree/part.dart` | InvenTreePartクラス（138-459行目） |
| 1-2 | part.dart | `lib/inventree/part.dart` | InvenTreePartPricingクラス（498-545行目） |
| 1-3 | part.dart | `lib/inventree/part.dart` | InvenTreePartRequirementsクラス（464-493行目） |

**読解のコツ**:
- **355-372行目**: 各種フラグ（isAssembly, isComponent, isPurchaseable等）
- **296-341行目**: 在庫関連プロパティ
- **239-255行目**: getPricingメソッド
- **217-236行目**: getRequirementsメソッド

#### Step 2: 詳細画面ウィジェットを理解する

詳細画面の全体構造を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | part_detail.dart | `lib/widget/part/part_detail.dart` | PartDetailWidgetクラス（36-856行目） |

**主要処理フロー**:
- **45-67行目**: 状態変数の定義（各種カウント、関連オブジェクト）
- **148-310行目**: `request`メソッド - データ取得処理
- **347-750行目**: `partTiles`メソッド - 詳細タブのタイル構築
- **838-855行目**: `getTabs`メソッド - 2タブ構成

#### Step 3: アクションボタンを理解する

利用可能なアクションを追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | part_detail.dart | `lib/widget/part/part_detail.dart` | appBarActionsメソッド（72-87行目） |
| 3-2 | part_detail.dart | `lib/widget/part/part_detail.dart` | actionButtonsメソッド（109-137行目） |
| 3-3 | part_detail.dart | `lib/widget/part/part_detail.dart` | barcodeButtonsメソッド（90-106行目） |

**主要処理フロー**:
- **72-87行目**: 編集ボタン（canEdit時のみ）
- **109-137行目**: 在庫作成、ラベル印刷
- **90-106行目**: バーコード割当/解除

#### Step 4: 在庫作成処理を理解する

新規在庫作成フォームの処理を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | part_detail.dart | `lib/widget/part/part_detail.dart` | _newStockItemメソッド（779-836行目） |

**主要処理フロー**:
- **780-786行目**: フォームフィールド設定
- **788-795行目**: 初期値設定（パーツ、デフォルトロケーション）
- **796-815行目**: シリアル番号取得（追跡可能パーツの場合）

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

```
PartDetailWidget
    │
    ├─ request(context)
    │      ├─ part.reload()
    │      ├─ InvenTreePart().get(templatePartId) [バリアント時]
    │      ├─ InvenTreeStockLocation().get(defaultLocationId)
    │      ├─ part.getTestTemplates() [テスト可能時]
    │      ├─ InvenTreeAttachment().countAttachments()
    │      ├─ InvenTreeParameter().countParameters()
    │      ├─ part.getRequirements() [設定ON時]
    │      ├─ part.getPricing() [設定ON時]
    │      ├─ InvenTreePart().count(in_bom_for)
    │      ├─ InvenTreeBomItem().count(uses)
    │      └─ InvenTreePart().count(variant_of)
    │
    ├─ partTiles()
    │      ├─ headerTile()
    │      ├─ [非アクティブ警告]
    │      ├─ [テンプレートパーツタイル]
    │      ├─ [カテゴリタイル]
    │      ├─ [バリアントタイル]
    │      ├─ [在庫タイル]
    │      ├─ [デフォルトロケーションタイル]
    │      ├─ [要件タイル群]
    │      ├─ [価格タイル]
    │      ├─ [BOMタイル]
    │      ├─ [使用先タイル]
    │      ├─ [サプライヤータイル]
    │      ├─ [ノートタイル]
    │      ├─ [パラメータタイル]
    │      └─ [添付ファイルタイル]
    │
    └─ getTabs()
           ├─ 詳細タブ → partTiles()
           └─ 在庫タブ → PaginatedStockItemList
```

### データフロー図

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

InvenTreePart ───▶ PartDetailWidget ───▶ UI表示
    │                    │                     │
    └─ pk               ├─ reload()            ├─ 詳細タブ
                        ├─ getPricing()        │    ├─ ヘッダー
                        ├─ getRequirements()   │    ├─ 各種タイル
                        └─ 関連データ取得        │    └─ リンク
                                               │
                                               └─ 在庫タブ
                                                    └─ 在庫一覧
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| part_detail.dart | `lib/widget/part/part_detail.dart` | ソース | パーツ詳細画面ウィジェット |
| part.dart | `lib/inventree/part.dart` | ソース | InvenTreePartモデル、価格・要件モデル |
| stock.dart | `lib/inventree/stock.dart` | ソース | InvenTreeStockItem、StockLocationモデル |
| part_image_widget.dart | `lib/widget/part/part_image_widget.dart` | ソース | パーツ画像表示・変更画面 |
| part_pricing.dart | `lib/widget/part/part_pricing.dart` | ソース | 価格詳細画面 |
| bom_list.dart | `lib/widget/part/bom_list.dart` | ソース | BOM一覧画面 |
| part_list.dart | `lib/widget/part/part_list.dart` | ソース | バリアント一覧表示 |
| stock_list.dart | `lib/widget/stock/stock_list.dart` | ソース | 在庫タブの一覧 |
| supplier_part_list.dart | `lib/widget/company/supplier_part_list.dart` | ソース | サプライヤーパーツ一覧 |
| notes_widget.dart | `lib/widget/notes_widget.dart` | ソース | ノート表示・編集 |
| parameter_widget.dart | `lib/widget/parameter_widget.dart` | ソース | パラメータ表示 |
| attachment_widget.dart | `lib/widget/attachment_widget.dart` | ソース | 添付ファイル表示 |
| labels.dart | `lib/labels.dart` | ソース | ラベル印刷処理 |
| barcode.dart | `lib/barcode/barcode.dart` | ソース | バーコード操作 |
