# 画面設計書 15-在庫ロケーション一覧・詳細画面

## 概要

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

### 本画面の処理概要

本画面は、在庫ロケーション（保管場所）の階層構造を一覧表示し、個別ロケーションの詳細情報を表示・編集するための画面である。ロケーションIDが指定されない場合はトップレベルロケーションページとして機能する。

**業務上の目的・背景**：在庫管理システムにおいて、在庫アイテムの物理的な保管場所を体系的に管理することは、効率的な入出庫作業、棚卸し作業、ピッキング作業の基盤となる。ロケーションの階層構造（倉庫→棚→段→列等）により、数万点の在庫アイテムを効率的に管理・追跡できる。

**画面へのアクセス方法**：メインナビゲーションの「在庫（Stock）」メニューをクリック、またはURL `/stock/location/:id?/*` に直接アクセスする。パンくずリストからも階層をたどってアクセス可能。

**主要な操作・処理内容**：
1. ロケーション一覧の表示（テーブル形式/パラメトリック表示切替）
2. サブロケーションの表示と選択
3. ロケーション内の在庫アイテム一覧表示
4. デフォルト部品（このロケーションをデフォルトとする部品）の表示
5. ロケーションパラメータの表示・設定
6. ロケーション情報の編集
7. ロケーションの削除（在庫アイテム・サブロケーションの処理オプション付き）
8. バーコードスキャンによる在庫アイテム/ロケーションの移動
9. 在庫操作（カウント、移動）
10. ラベル・レポートの印刷

**画面遷移**：
- 遷移元：ホームダッシュボード、他の在庫ロケーション画面、在庫アイテム詳細画面
- 遷移先：在庫アイテム詳細画面、サブロケーション画面、部品詳細画面

**権限による表示制御**：`stock_location`ロールに基づき、表示・編集・削除の可否が制御される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | 在庫ロケーション管理 | 主機能 | ロケーションの一覧表示、編集、削除処理 |
| 8 | 在庫アイテム管理 | 遷移先機能 | ロケーション内在庫アイテム一覧から在庫詳細への遷移 |
| 9 | 在庫移動・調整 | API連携 | 在庫カウント、移動処理 |
| 10 | 在庫アイテムパラメータ管理 | 補助機能 | ロケーションパラメータの表示・設定 |
| 42 | バーコードスキャン | API連携 | バーコードスキャンによる在庫移動 |

## 画面種別

一覧・詳細（複合）

## URL/ルーティング

`/stock/location/:id?/*`

- `:id?` はオプションのロケーションID
- IDなしの場合はトップレベルロケーションページ（URL: `/stock/`）

## 入出力項目

### 入力項目（ロケーション編集モーダル）

| 項目名 | 項目種別 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| 名前（Name） | テキスト入力 | 文字列 | ○ | ロケーション名 |
| 説明（Description） | テキスト入力 | 文字列 | - | ロケーションの説明 |
| 親ロケーション（Parent） | セレクト | 数値 | - | 親ロケーションのID |
| アイコン（Icon） | アイコン選択 | 文字列 | - | ロケーションアイコン |
| ロケーションタイプ | セレクト | 数値 | - | ロケーションタイプのID |
| 構造的（Structural） | チェックボックス | 真偽値 | - | 構造的ロケーションフラグ |
| 外部（External） | チェックボックス | 真偽値 | - | 外部ロケーションフラグ |

### 削除確認モーダル

| 項目名 | 項目種別 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| 在庫アイテムアクション | ラジオ選択 | 文字列 | ○ | 親ロケーションに移動/削除 |
| サブロケーションアクション | ラジオ選択 | 文字列 | ○ | 親ロケーションに移動/削除 |

## 表示項目

### 詳細パネル（ロケーション詳細）

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| 名前（Name） | 文字列 | ロケーション名（アイコン付き） |
| パス（Path） | 文字列 | ロケーションの階層パス |
| 説明（Description） | 文字列 | ロケーションの説明 |
| 親ロケーション（Parent Location） | リンク | 親ロケーションへのリンク |
| 在庫アイテム数（Stock Items） | 数値 | このロケーション内の在庫アイテム数 |
| サブロケーション数（Sublocations） | 数値 | サブロケーションの数 |
| 構造的（Structural） | 真偽値 | 構造的ロケーションフラグ |
| 外部（External） | 真偽値 | 外部ロケーションフラグ |
| ロケーションタイプ（Location Type） | 文字列 | ロケーションタイプ名 |

### パネル一覧

| パネル名 | 表示条件 | 内容 |
|---------|----------|------|
| ロケーション詳細（Location Details） | 常時 | 上記詳細項目 |
| サブロケーション（Sublocations/Stock Locations） | 常時 | サブロケーション一覧（テーブル/パラメトリック切替） |
| 在庫アイテム（Stock Items） | 常時 | 在庫アイテム一覧テーブル |
| デフォルト部品（Default Parts） | ロケーションID指定時 | このロケーションをデフォルトとする部品一覧 |
| パラメータ（Parameters） | ロケーションID指定時 | ロケーションパラメータ一覧 |

## イベント仕様

### 1-ロケーション選択

サブロケーション一覧から行をクリックした時の処理。

**処理フロー**：
1. 選択されたロケーションのPKを取得
2. `/stock/location/{pk}/` に遷移

### 2-ロケーション編集

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

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

### 3-ロケーション削除

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

**処理フロー**：
1. 削除確認モーダルを表示（在庫アイテム・サブロケーションの処理方法を選択）
2. 送信時に `DELETE /api/stock/location/{id}/` を呼び出し
3. 成功後、親ロケーションまたは `/stock/` に遷移

### 4-在庫アイテムスキャン

バーコードアクションの「Scan in stock items」選択時の処理。

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

### 5-コンテナスキャン

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

**処理フロー**：
1. バーコードスキャンダイアログを表示（scanInStockLocation）
2. スキャンしたバーコードからロケーションを識別
3. `PATCH /api/stock/location/{pk}/` でスキャンしたロケーションの親をこのロケーションに設定
4. 成功/失敗メッセージを表示

### 6-在庫操作

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

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

### 7-ナビゲーションツリー表示

パンくずリストのアクション押下時の処理。

**処理フロー**：
1. `NavigationTree` コンポーネントを表示
2. ロケーションツリーを `/api/stock/location/tree/` から取得
3. 選択したロケーションに遷移

### 8-サブロケーション表示切替

サブロケーションパネルのセグメントコントロールでテーブル/パラメトリック切替。

**処理フロー**：
1. sublocationView状態を更新
2. 選択に応じて `StockLocationTable` または `StockLocationParametricTable` を表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ロケーション編集 | stock_stocklocation | UPDATE | ロケーション情報を更新 |
| ロケーション削除 | stock_stocklocation | DELETE | ロケーションを削除（関連処理あり） |
| 在庫アイテムスキャン | stock_stockitem, stock_stockitemtracking | UPDATE, INSERT | 在庫アイテムのロケーションを更新、追跡履歴追加 |
| コンテナスキャン | stock_stocklocation | UPDATE | スキャンしたロケーションの親を更新 |
| 在庫カウント | stock_stockitem, stock_stockitemtracking | UPDATE, INSERT | 在庫数量更新、追跡履歴追加 |
| 在庫移動 | stock_stockitem, stock_stockitemtracking | UPDATE, INSERT | 在庫ロケーション更新、追跡履歴追加 |

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

#### stock_stocklocation

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | name | フォーム入力値 | ロケーション名 |
| UPDATE | description | フォーム入力値 | 説明 |
| UPDATE | parent | フォーム選択値 | 親ロケーションID |
| UPDATE | icon | フォーム選択値 | アイコン名 |
| UPDATE | location_type | フォーム選択値 | ロケーションタイプID |
| UPDATE | structural | フォーム入力値 | 構造的フラグ |
| UPDATE | external | フォーム入力値 | 外部フラグ |
| DELETE | - | pk = 指定値 | ロケーション削除 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|---------------|------|---------------|
| 確認 | ロケーション削除時 | Delete Stock Location（モーダルタイトル） |
| 選択 | 在庫アイテムアクション | Move items to parent location / Delete items |
| 選択 | サブロケーションアクション | Move items to parent location / Delete items |
| 成功 | バーコードスキャン成功 | Scanned stock item into location / Scanned stock location into location |
| エラー | バーコードスキャン失敗 | Error scanning stock item / Error scanning stock location |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| ロケーションが見つからない | InstanceDetailコンポーネントが404処理 |
| 権限不足 | 編集/削除ボタンが非表示 |
| API通信エラー | エラー通知を表示 |
| バーコードスキャンエラー | エラーメッセージを返却し表示 |

## 備考

- ロケーションIDが指定されない場合（`/stock/`）はトップレベルロケーションとして動作
- パンくずリストでロケーション階層をナビゲート可能
- ロケーションアイコンは `ApiIcon` コンポーネントで表示
- サブロケーション表示は `StockLocationTable`（テーブル）と `StockLocationParametricTable`（パラメトリック）で切替可能
- バーコードスキャン機能では、スキャンしたアイテム/ロケーションをこのロケーションに移動する

---

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

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

### 推奨読解順序

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

ロケーションデータの構造とAPIレスポンスを確認する。

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

**読解のコツ**: ロケーションは階層構造を持ち、`path_detail`パラメータで親ロケーションのパス情報を含めて取得できる。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | LocationDetail.tsx | `src/frontend/src/pages/stock/LocationDetail.tsx` | メイン画面コンポーネント。useInstance, パネル構成を確認 |

**主要処理フロー**:
1. **56-62行**: URLパラメータからロケーションIDを取得（オプション）
2. **69-80行**: useInstanceでロケーションデータを取得
3. **82-171行**: detailsPanel定義（ロケーション詳細表示）
4. **175-244行**: locationPanels定義（タブパネル構成）
5. **246-252行**: editLocation（編集モーダル）
6. **254-294行**: deleteLocation（削除モーダル）
7. **296-313行**: stockOperationProps, stockAdjustActions（在庫操作）
8. **315-369行**: バーコードスキャン処理（scanInStockItem, scanInStockLocation）
9. **371-422行**: locationActions（アクションボタン群）
10. **424-434行**: breadcrumbs（パンくずリスト）
11. **436-488行**: レンダリング部分

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | StockLocationTable.tsx | `src/frontend/src/tables/stock/StockLocationTable.tsx` | サブロケーション一覧テーブル |
| 3-2 | StockLocationParametricTable.tsx | `src/frontend/src/tables/stock/StockLocationParametricTable.tsx` | パラメトリック表示テーブル |
| 3-3 | StockItemTable.tsx | `src/frontend/src/tables/stock/StockItemTable.tsx` | 在庫アイテム一覧テーブル |
| 3-4 | PartTable.tsx | `src/frontend/src/tables/part/PartTable.tsx` | デフォルト部品一覧テーブル |

#### Step 4: バーコードスキャン機能を理解する

バーコードスキャン関連の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | BarcodeScanDialog.tsx | `src/frontend/src/components/barcodes/BarcodeScanDialog.tsx` | useBarcodeScanDialogフック |

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

```
Stock (LocationDetail.tsx:56)
    │
    ├─ useParams() - URLからロケーションID取得
    │
    ├─ useInstance(ApiEndpoints.stock_location_list)
    │      └─ GET /api/stock/location/{id}/ - ロケーション詳細取得
    │
    ├─ useEditApiFormModal (246-252行)
    │      └─ PUT /api/stock/location/{id}/ - ロケーション編集
    │
    ├─ useDeleteApiFormModal (267-294行)
    │      └─ DELETE /api/stock/location/{id}/ - ロケーション削除
    │
    ├─ useStockAdjustActions (307-313行)
    │      ├─ Count modal
    │      ├─ Transfer modal
    │      ├─ Add modal
    │      └─ Remove modal
    │
    ├─ useBarcodeScanDialog(scanInStockItem) (315-344行)
    │      └─ POST /api/stock/transfer/ - 在庫アイテム移動
    │
    ├─ useBarcodeScanDialog(scanInStockLocation) (346-369行)
    │      └─ PATCH /api/stock/location/{pk}/ - ロケーション親変更
    │
    ├─ NavigationTree
    │      └─ GET /api/stock/location/tree/ - ロケーションツリー取得
    │
    └─ PanelGroup
           ├─ detailsPanel (ロケーション詳細)
           │      └─ DetailsTable
           │
           ├─ StockLocationTable / StockLocationParametricTable (サブロケーション)
           │      └─ InvenTreeTable
           │
           ├─ StockItemTable (在庫アイテム)
           │      └─ InvenTreeTable
           │
           ├─ PartListTable (デフォルト部品)
           │      └─ InvenTreeTable
           │
           └─ ParametersPanel (パラメータ)
                  └─ ParameterTable
```

### データフロー図

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

URL パラメータ ───▶ Stock ───▶ 画面表示
(:id)                   │
                        ▼
                 useInstance()
                        │
                        ▼
                 GET /api/stock/location/{id}/
                        │
                        ▼
                 Django Backend
                        │
                        ▼
                 stock_stocklocation テーブル

バーコード ───▶ useBarcodeScanDialog ───▶ API呼び出し ───▶ 在庫移動/ロケーション移動
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| LocationDetail.tsx | `src/frontend/src/pages/stock/LocationDetail.tsx` | ソース | 在庫ロケーション画面メインコンポーネント |
| StockLocationTable.tsx | `src/frontend/src/tables/stock/StockLocationTable.tsx` | ソース | サブロケーション一覧テーブル |
| StockLocationParametricTable.tsx | `src/frontend/src/tables/stock/StockLocationParametricTable.tsx` | ソース | パラメトリックロケーションテーブル |
| StockItemTable.tsx | `src/frontend/src/tables/stock/StockItemTable.tsx` | ソース | 在庫アイテムテーブル |
| PartTable.tsx | `src/frontend/src/tables/part/PartTable.tsx` | ソース | 部品テーブル |
| StockForms.tsx | `src/frontend/src/forms/StockForms.tsx` | ソース | 在庫関連フォームフィールド定義（stockLocationFields） |
| NavigationTree.tsx | `src/frontend/src/components/nav/NavigationTree.tsx` | ソース | ナビゲーションツリーコンポーネント |
| BarcodeScanDialog.tsx | `src/frontend/src/components/barcodes/BarcodeScanDialog.tsx` | ソース | バーコードスキャンダイアログ |
| UseStockAdjustActions.ts | `src/frontend/src/hooks/UseStockAdjustActions.ts` | ソース | 在庫操作フック |
| PanelGroup.tsx | `src/frontend/src/components/panels/PanelGroup.tsx` | ソース | タブパネルグループコンポーネント |
| SegmentedControlPanel.tsx | `src/frontend/src/components/panels/SegmentedControlPanel.tsx` | ソース | セグメント切替パネル |
| ApiIcon.tsx | `src/frontend/src/components/items/ApiIcon.tsx` | ソース | APIアイコン表示コンポーネント |
