# 画面設計書 16-在庫アイテム詳細画面

## 概要

本ドキュメントは、InvenTreeフロントエンドアプリケーションの「在庫アイテム詳細画面」に関する設計仕様を記載する。

### 本画面の処理概要

本画面は、個別の在庫アイテム（StockItem）の詳細情報を表示し、在庫操作（移動、数量調整、シリアライズ等）や関連情報（割当、テスト結果、インストール済みアイテム等）を管理するための画面である。

**業務上の目的・背景**：在庫管理システムにおいて、在庫アイテムは物理的な在庫の最小管理単位である。この画面では、個別在庫アイテムの状態（数量、ロケーション、ステータス、有効期限等）を詳細に把握し、在庫操作を実行することで、正確な在庫管理と在庫追跡を実現する。

**画面へのアクセス方法**：在庫アイテム一覧からの行クリック、部品詳細画面の在庫タブからの遷移、バーコードスキャン結果からの遷移、またはURL `/stock/item/:id/*` に直接アクセスする。

**主要な操作・処理内容**：
1. 在庫アイテム基本情報の表示・編集
2. 在庫追跡履歴の表示
3. 製造オーダー・販売オーダーへの割当表示
4. テスト結果の表示
5. インストール済みアイテム（組立部品内のコンポーネント）の管理
6. 子アイテム（分割された在庫）の表示
7. 在庫操作（カウント、移動、追加、削除、割当解除、返却、シリアライズ）
8. 在庫アイテムの複製・削除
9. バーコードによるロケーションへのスキャン移動
10. ラベル・レポートの印刷

**画面遷移**：
- 遷移元：在庫アイテム一覧、部品詳細画面、発注書詳細画面、製造オーダー詳細画面、バーコードスキャン画面
- 遷移先：部品詳細画面、在庫ロケーション詳細画面、発注書詳細画面、製造オーダー詳細画面、販売注文詳細画面

**権限による表示制御**：`stock`ロールに基づき表示・編集・削除の可否が制御。各パネルは関連ロール（build, sales_order等）でも制御される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | 在庫アイテム管理 | 主機能 | 在庫アイテム情報の表示・編集・削除 |
| 9 | 在庫移動・調整 | 主機能 | 在庫カウント、移動、追加、削除、シリアライズ処理 |
| 10 | 在庫アイテムパラメータ管理 | 補助機能 | 在庫アイテムパラメータの表示（継承） |
| 11 | 在庫追跡管理 | 補助機能 | 在庫追跡履歴の表示 |
| 19 | 製造オーダー管理 | 遷移先機能 | 製造オーダー割当の表示・遷移 |
| 15 | 販売注文管理 | 遷移先機能 | 販売注文割当の表示・遷移 |
| 42 | バーコードスキャン | API連携 | バーコードによるロケーション移動 |
| 47 | 添付ファイル管理 | 補助機能 | 添付ファイルの表示・管理 |
| 48 | メモ・ノート管理 | 補助機能 | 在庫アイテムメモの表示・編集 |

## 画面種別

詳細

## URL/ルーティング

`/stock/item/:id/*`

## 入出力項目

### 入力項目（在庫アイテム編集モーダル）

| 項目名 | 項目種別 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| 部品（Part） | セレクト | 数値 | ○ | 部品ID |
| ロケーション（Location） | セレクト | 数値 | - | 在庫ロケーションID |
| 数量（Quantity） | 数値入力 | 数値 | ○ | 在庫数量 |
| シリアル番号（Serial Number） | テキスト入力 | 文字列 | - | シリアル番号 |
| バッチコード（Batch） | テキスト入力 | 文字列 | - | バッチコード |
| パッケージ（Packaging） | テキスト入力 | 文字列 | - | パッケージ情報 |
| ステータス（Status） | セレクト | 数値 | - | 在庫ステータス |
| 有効期限（Expiry Date） | 日付入力 | 日付 | - | 有効期限日 |
| 購入価格（Purchase Price） | 数値入力 | 数値 | - | 単価 |
| リンク（Link） | URL入力 | 文字列 | - | 外部リンク |

## 表示項目

### 詳細パネル

#### 基本情報（左上）

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| 部品（Base Part） | リンク | 部品詳細へのリンク |
| IPN | 文字列 | 内部部品番号 |
| リビジョン（Revision） | 文字列 | 部品リビジョン |
| ステータス（Status） | バッジ | 在庫ステータス |
| カスタムステータス | バッジ | カスタムステータス（設定時のみ） |
| リンク（Link） | URL | 外部リンク |

#### 数量情報（右上）

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| シリアル番号（Serial Number） | 文字列 | シリアル番号（前後ナビゲーション付き） |
| 数量（Quantity） | 数値 | 在庫数量（単位付き） |
| 利用可能数（Available） | 数値 | 未割当数量 |
| 割当済み（Allocated to Orders） | 数値 | オーダー割当済み数量 |
| バッチコード（Batch Code） | 文字列 | バッチコード |

#### 関連情報（左下）

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| サプライヤー部品（Supplier Part） | リンク | サプライヤー部品へのリンク |
| ロケーション（Location） | リンク | 在庫ロケーションへのリンク |
| インストール先（Installed In） | リンク | インストール先在庫アイテムへのリンク |
| 親アイテム（Parent Item） | リンク | 親在庫アイテムへのリンク |
| 消費元（Consumed By） | リンク | 消費した製造オーダーへのリンク |
| 製造オーダー（Build Order） | リンク | 製造元オーダーへのリンク |
| 発注書（Purchase Order） | リンク | 購入元発注書へのリンク |
| 販売注文（Sales Order） | リンク | 販売先注文へのリンク |
| 顧客（Customer） | リンク | 出荷先顧客へのリンク |

#### その他情報（右下）

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| 有効期限（Expiry Date） | 日付 | 有効期限日 |
| 単価（Unit Price） | 通貨 | 購入単価 |
| 在庫価値（Stock Value） | 通貨 | 数量×単価 |
| パッケージ（Packaging） | 文字列 | パッケージ情報 |
| 最終更新（Last Updated） | 日付 | 最終更新日 |
| 最終棚卸（Last Stocktake） | 日付 | 最終棚卸日 |

### バッジ表示

| バッジ | 表示条件 | 色 |
|--------|---------|-----|
| In Production | is_building=true | 黄 |
| Serial Number | シリアル番号あり | 青 |
| Quantity | シリアル番号なし | 青 |
| Available | 在庫あり&割当あり | 黄 |
| Batch Code | バッチコードあり | 青 |
| Status | 常時 | ステータス依存 |
| Stale | 有効期限有効&stale=true | 黄 |
| Expired | 有効期限有効&expired=true | オレンジ |
| Unavailable | in_stock=false | 赤 |

### パネル一覧

| パネル名 | 表示条件 | 内容 |
|---------|----------|------|
| 在庫詳細（Stock Details） | 常時 | 上記詳細項目 |
| 在庫追跡（Stock Tracking） | 常時 | 在庫追跡履歴テーブル |
| 割当（Allocations） | in_stock & (component or salable) | 製造・販売オーダー割当 |
| テスト結果（Test Results） | testable=true | テスト結果テーブル |
| インストール済み（Installed Items） | assembly or インストール済みあり | インストール済みアイテムテーブル |
| 子アイテム（Child Items） | child_items > 0 | 子在庫アイテムテーブル |
| 添付ファイル（Attachments） | 常時 | 添付ファイルパネル |
| メモ（Notes） | 常時 | メモ表示・編集パネル |

## イベント仕様

### 1-在庫アイテム編集

アクションメニューの「Edit」選択時の処理。

**処理フロー**：
1. 編集モーダルを表示（useStockFieldsでフィールド定義）
2. 送信時に `PUT /api/stock/{id}/` を呼び出し
3. 成功後、インスタンスをリフレッシュ

### 2-在庫アイテム複製

アクションメニューの「Duplicate」選択時の処理。

**処理フロー**：
1. 複製モーダルを表示（現在の在庫アイテムデータをinitialDataに設定）
2. serial_numbersフィールドに現在のserialを設定、serialフィールドは削除
3. 送信時に `POST /api/stock/` を呼び出し
4. 成功後、新しい在庫アイテム詳細画面に遷移（複数作成時は通知表示）

### 3-在庫アイテム削除

アクションメニューの「Delete」選択時の処理。

**処理フロー**：
1. 削除確認モーダルを表示
2. 送信時に `DELETE /api/stock/{id}/` を呼び出し
3. 成功後、部品詳細画面に遷移

### 4-在庫操作

Stock Operationsドロップダウンからの操作。

**処理フロー**（useStockAdjustActionsフックで実装）：
1. Count（カウント）：在庫数量の確認・修正
2. Transfer（移動）：在庫ロケーション間の移動
3. Add（追加）：在庫の追加
4. Remove（削除）：在庫の削除

特殊操作：
- Assign（割当）：顧客への割当（salable=trueの場合）
- Return（返却）：消費元からの返却（consumed_by or customerがある場合）

### 5-シリアライズ

Stock Operationsの「Serialize」選択時の処理（trackable=true、数量>1の場合）。

**処理フロー**：
1. シリアライズモーダルを表示（useStockItemSerializeFieldsでフィールド定義）
2. 数量と目的地、シリアル番号を入力
3. 送信時に `POST /api/stock/{id}/serialize/` を呼び出し
4. 全量シリアライズの場合、最初のシリアライズ済みアイテムに遷移

### 6-発注

Stock Operationsの「Order」選択時の処理（purchaseable=true、アクティブ部品の場合）。

**処理フロー**：
1. OrderPartsWizardを開く
2. 発注ウィザードで発注書作成

### 7-シリアル番号検索

シリアル番号表示横の検索アイコン押下時の処理。

**処理フロー**：
1. シリアル番号検索モーダルを表示（useFindSerialNumberForm）
2. 入力されたシリアル番号で同一部品の在庫アイテムを検索
3. 該当アイテムの詳細画面に遷移

### 8-前後シリアル番号ナビゲーション

シリアル番号表示横の前後ボタン押下時の処理。

**処理フロー**：
1. serialNumbers.previous.pk または serialNumbers.next.pk を取得
2. 該当シリアル番号の在庫アイテム詳細画面に遷移

### 9-バーコードスキャンでロケーション移動

バーコードアクションの「Scan into location」選択時の処理。

**処理フロー**：
1. バーコードスキャンダイアログを表示
2. スキャンしたバーコードからロケーションを識別
3. `POST /api/stock/transfer/` でこの在庫アイテムをスキャンしたロケーションに移動
4. 成功/失敗メッセージを表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 在庫アイテム編集 | stock_stockitem | UPDATE | 在庫アイテム情報を更新 |
| 在庫アイテム複製 | stock_stockitem | INSERT | 新規在庫アイテムを作成 |
| 在庫アイテム削除 | stock_stockitem | DELETE | 在庫アイテムを削除 |
| 在庫カウント | stock_stockitem, stock_stockitemtracking | UPDATE, INSERT | 数量更新、追跡履歴追加 |
| 在庫移動 | stock_stockitem, stock_stockitemtracking | UPDATE, INSERT | ロケーション更新、追跡履歴追加 |
| シリアライズ | stock_stockitem | INSERT | 複数のシリアライズ済み在庫アイテム作成 |
| バーコードスキャン移動 | stock_stockitem, stock_stockitemtracking | UPDATE, INSERT | ロケーション更新、追跡履歴追加 |

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

#### stock_stockitem

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | location | フォーム選択値 | ロケーションID |
| UPDATE | quantity | フォーム入力値 | 在庫数量 |
| UPDATE | batch | フォーム入力値 | バッチコード |
| UPDATE | status | フォーム選択値 | ステータスコード |
| UPDATE | expiry_date | フォーム入力値 | 有効期限 |
| UPDATE | purchase_price | フォーム入力値 | 購入単価 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|---------------|------|---------------|
| 成功 | シリアライズ成功 | Stock item serialized |
| 成功 | バーコードスキャン成功 | Scanned stock item into location |
| エラー | バーコードスキャン失敗 | Error scanning stock item |
| 情報 | 複数アイテム作成 | Created {n} stock items |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| 在庫アイテムが見つからない | InstanceDetailコンポーネントが404処理 |
| 権限不足 | 対応するボタン/パネルが非表示 |
| API通信エラー | エラー通知を表示 |
| 在庫枯渇後のリフレッシュ | ロケーションまたは部品概要画面に遷移 |

## 備考

- シリアル番号付き在庫アイテムでは前後シリアル番号へのナビゲーションが可能
- 有効期限機能はグローバル設定 `STOCK_ENABLE_EXPIRY` で有効/無効を制御
- インストール済みアイテムパネルは、在庫アイテムがassemblyの場合またはインストール済みアイテムがある場合に表示
- 在庫枯渇（数量が0になった等）後にページ更新すると、元のロケーションまたは部品概要画面に遷移

---

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

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

### 推奨読解順序

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

在庫アイテムデータの構造と関連APIを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ApiEndpoints.ts | `src/frontend/lib/enums/ApiEndpoints.ts` | stock_item_list, stock_transfer, stock_serialize等のエンドポイント |
| 1-2 | ModelType.ts | `src/frontend/lib/enums/ModelType.ts` | ModelType.stockitem の定義 |

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

画面のメインコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | StockDetail.tsx | `src/frontend/src/pages/stock/StockDetail.tsx` | メイン画面コンポーネント（約1047行） |

**主要処理フロー**:
1. **91-121行**: コンポーネント定義、useInstance群の初期化
2. **99-102行**: enableExpiry（有効期限設定）の判定
3. **108-121行**: useInstanceで在庫アイテムデータを取得
4. **123-128行**: useInstanceでシリアル番号情報を取得
5. **133-463行**: detailsPanel定義（4領域の詳細表示）
6. **465-520行**: showBuildAllocations, showSalesAllocations, showInstalledItemsの判定
7. **522-629行**: stockPanels定義（タブパネル構成）
8. **652-728行**: editStockItem, duplicateStockItem, deleteStockItem（各種モーダル）
9. **730-760行**: stockOperationProps, stockAdjustActions（在庫操作）
10. **762-788行**: serializeStockItem（シリアライズモーダル）
11. **790-792行**: orderPartsWizard（発注ウィザード）
12. **794-823行**: scanIntoLocation（バーコードスキャン）
13. **825-915行**: stockActions（アクションボタン群）
14. **917-985行**: stockBadges（バッジ表示）
15. **987-1046行**: レンダリング部分

#### Step 3: テーブルコンポーネントを理解する

各パネルで使用されるテーブルコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | StockTrackingTable.tsx | `src/frontend/src/tables/stock/StockTrackingTable.tsx` | 在庫追跡履歴テーブル |
| 3-2 | BuildAllocatedStockTable.tsx | `src/frontend/src/tables/build/BuildAllocatedStockTable.tsx` | 製造オーダー割当テーブル |
| 3-3 | SalesOrderAllocationTable.tsx | `src/frontend/src/tables/sales/SalesOrderAllocationTable.tsx` | 販売オーダー割当テーブル |
| 3-4 | StockItemTestResultTable.tsx | `src/frontend/src/tables/stock/StockItemTestResultTable.tsx` | テスト結果テーブル |
| 3-5 | InstalledItemsTable.tsx | `src/frontend/src/tables/stock/InstalledItemsTable.tsx` | インストール済みアイテムテーブル |

#### Step 4: フォームとフックを理解する

在庫操作に関連するフォームとフックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | StockForms.tsx | `src/frontend/src/forms/StockForms.tsx` | useStockFields, useStockItemSerializeFields, useFindSerialNumberForm |
| 4-2 | UseStockAdjustActions.ts | `src/frontend/src/hooks/UseStockAdjustActions.ts` | 在庫操作アクションフック |

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

```
StockDetail (StockDetail.tsx:91)
    │
    ├─ useParams() - URLから在庫アイテムID取得
    │
    ├─ useInstance(ApiEndpoints.stock_item_list)
    │      └─ GET /api/stock/{id}/ - 在庫アイテム詳細取得
    │
    ├─ useInstance(ApiEndpoints.stock_serial_info)
    │      └─ GET /api/stock/{id}/serial-info/ - シリアル番号情報
    │
    ├─ useFindSerialNumberForm
    │      └─ シリアル番号検索モーダル
    │
    ├─ useEditApiFormModal (659-666行)
    │      └─ PUT /api/stock/{id}/ - 在庫アイテム編集
    │
    ├─ useCreateApiFormModal (duplicateStockItem) (685-711行)
    │      └─ POST /api/stock/ - 在庫アイテム複製
    │
    ├─ useDeleteApiFormModal (719-728行)
    │      └─ DELETE /api/stock/{id}/ - 在庫アイテム削除
    │
    ├─ useStockAdjustActions (754-760行)
    │      ├─ Count modal
    │      ├─ Transfer modal
    │      ├─ Add modal
    │      ├─ Remove modal
    │      ├─ Assign modal
    │      └─ Return modal
    │
    ├─ useCreateApiFormModal (serializeStockItem) (768-788行)
    │      └─ POST /api/stock/{id}/serialize/ - シリアライズ
    │
    ├─ useBarcodeScanDialog (scanIntoLocation) (794-823行)
    │      └─ POST /api/stock/transfer/ - ロケーション移動
    │
    ├─ OrderPartsWizard - 発注ウィザード
    │
    └─ PanelGroup
           ├─ detailsPanel
           ├─ StockTrackingTable
           ├─ Allocations (Accordion)
           │      ├─ BuildAllocatedStockTable
           │      └─ SalesOrderAllocationTable
           ├─ StockItemTestResultTable
           ├─ InstalledItemsTable
           ├─ StockItemTable (子アイテム)
           ├─ AttachmentPanel
           └─ NotesPanel
```

### データフロー図

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

URL パラメータ ───▶ StockDetail ───▶ 画面表示
(:id)                    │
                         ├─▶ stock詳細取得
                         │         │
                         │         ▼
                         │   GET /api/stock/{id}/
                         │
                         ├─▶ serial-info取得
                         │         │
                         │         ▼
                         │   GET /api/stock/{id}/serial-info/
                         │
                         └─▶ 在庫操作（Transfer等）
                                   │
                                   ▼
                            POST /api/stock/transfer/
                                   │
                                   ▼
                            stock_stockitem, stock_stockitemtracking
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| StockDetail.tsx | `src/frontend/src/pages/stock/StockDetail.tsx` | ソース | 在庫アイテム詳細画面メインコンポーネント |
| StockTrackingTable.tsx | `src/frontend/src/tables/stock/StockTrackingTable.tsx` | ソース | 在庫追跡履歴テーブル |
| BuildAllocatedStockTable.tsx | `src/frontend/src/tables/build/BuildAllocatedStockTable.tsx` | ソース | 製造オーダー割当テーブル |
| SalesOrderAllocationTable.tsx | `src/frontend/src/tables/sales/SalesOrderAllocationTable.tsx` | ソース | 販売オーダー割当テーブル |
| StockItemTestResultTable.tsx | `src/frontend/src/tables/stock/StockItemTestResultTable.tsx` | ソース | テスト結果テーブル |
| InstalledItemsTable.tsx | `src/frontend/src/tables/stock/InstalledItemsTable.tsx` | ソース | インストール済みアイテムテーブル |
| StockForms.tsx | `src/frontend/src/forms/StockForms.tsx` | ソース | 在庫関連フォームフィールド定義 |
| UseStockAdjustActions.ts | `src/frontend/src/hooks/UseStockAdjustActions.ts` | ソース | 在庫操作フック |
| BarcodeScanDialog.tsx | `src/frontend/src/components/barcodes/BarcodeScanDialog.tsx` | ソース | バーコードスキャンダイアログ |
| OrderPartsWizard.tsx | `src/frontend/src/components/wizards/OrderPartsWizard.tsx` | ソース | 発注ウィザード |
| formatters.ts | `src/frontend/src/defaults/formatters.ts` | ソース | formatCurrency, formatDecimal関数 |
