# 画面設計書 93-在庫詳細画面

## 概要

本ドキュメントは、Medusa Admin Dashboardの在庫詳細画面の設計仕様を定義するものです。

### 本画面の処理概要

在庫詳細画面は、個別の在庫アイテム（Inventory Item）の詳細情報を表示し、関連する在庫レベル、予約状況、バリアント紐付けなどを確認・管理するための画面です。2カラムレイアウトで、メインエリアに主要情報、サイドバーに関連情報を表示します。

**業務上の目的・背景**：在庫管理担当者が特定の在庫アイテムの状況を詳細に把握するための画面です。各ロケーションでの在庫数量、予約状況、関連する商品バリアントなどの情報を一元的に確認でき、在庫調整やロケーション管理などの操作への導線も提供します。

**画面へのアクセス方法**：在庫一覧画面から特定の在庫アイテム行をクリックするか、URL `/inventory/{id}` に直接アクセスすることで表示されます。

**主要な操作・処理内容**：
1. 在庫アイテム基本情報の表示（タイトル、SKU）
2. ロケーション別在庫レベルの表示と管理
3. 予約一覧の表示と管理
4. 関連バリアント一覧の表示
5. 属性情報（サイズ・重量など）の表示
6. 各種編集画面への遷移
7. メタデータの表示・編集
8. JSON形式での生データ表示

**画面遷移**：
- 遷移元：在庫一覧画面
- 遷移先：
  - 在庫編集画面（基本情報編集）
  - 在庫属性編集画面（属性情報編集）
  - 在庫ロケーション管理画面（ロケーション追加・削除）
  - 在庫調整画面（在庫数量調整）
  - バリアント詳細画面（関連バリアント選択時）
  - メタデータ編集画面

**権限による表示制御**：認証済みユーザーであれば全機能を利用可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 48 | 在庫アイテム管理 | 主機能 | 在庫アイテム詳細の表示 |
| 49 | 在庫レベル管理 | 補助機能 | ロケーション別在庫の表示 |
| 50 | 在庫予約管理 | 補助機能 | 予約状況の表示 |

## 画面種別

詳細

## URL/ルーティング

`/inventory/{id}`

## 入出力項目

本画面は詳細表示が主目的のため、直接の入力項目はありません。

## 表示項目

### メインエリア

#### 基本情報セクション（InventoryItemGeneralSection）

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|-----|------|
| タイトル | title | string | 在庫アイテムのタイトル |
| SKU | sku | string | 在庫管理単位コード |

#### ロケーション別在庫セクション（InventoryItemLocationLevelsSection）

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|-----|------|
| ロケーション名 | location.name | string | 在庫ロケーションの名前 |
| 在庫数 | stocked_quantity | number | 現在の在庫数量 |
| 予約数 | reserved_quantity | number | 予約済み数量 |
| 利用可能数 | available_quantity | number | 利用可能数量（在庫数 - 予約数） |
| 入荷予定数 | incoming_quantity | number | 入荷予定数量 |

#### 予約セクション（InventoryItemReservationsSection）

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|-----|------|
| 予約ID | id | string | 予約アイテムのID |
| 数量 | quantity | number | 予約数量 |
| 説明 | description | string | 予約の説明 |
| 作成日時 | created_at | datetime | 予約作成日時 |

### サイドバー

#### 関連バリアントセクション（InventoryItemVariantsSection）

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|-----|------|
| バリアントタイトル | variant.title | string | 関連バリアントのタイトル |
| 商品タイトル | variant.product.title | string | 関連商品のタイトル |

#### 属性セクション（InventoryItemAttributeSection）

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|-----|------|
| 高さ | height | number | 製品の高さ |
| 幅 | width | number | 製品の幅 |
| 奥行き | length | number | 製品の奥行き |
| 重量 | weight | number | 製品の重量 |
| MIDコード | mid_code | string | 製造者識別コード |
| HSコード | hs_code | string | 関税分類コード |
| 原産国 | origin_country | string | 原産国 |
| 素材 | material | string | 製品の素材 |

## イベント仕様

### 1-基本情報編集ボタン押下

在庫編集画面（ドロワー）を開きます。

**遷移先**: `/inventory/{id}/edit`

### 2-属性編集ボタン押下

在庫属性編集画面（ドロワー）を開きます。

**遷移先**: `/inventory/{id}/attributes`

### 3-ロケーション管理ボタン押下

在庫ロケーション管理画面（ドロワー）を開きます。

**遷移先**: `/inventory/{id}/locations`

### 4-在庫調整ボタン押下

特定ロケーションの在庫調整画面（ドロワー）を開きます。

**遷移先**: `/inventory/{id}/locations/{location_id}/adjust`

### 5-メタデータ編集ボタン押下

メタデータ編集画面（ドロワー）を開きます。

**遷移先**: `/inventory/{id}/metadata`

### 6-バリアント選択

関連バリアントの詳細画面に遷移します。

**遷移先**: `/products/{product_id}/variants/{variant_id}`

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 詳細表示 | inventory_item | SELECT | 在庫アイテム詳細の取得 |
| 詳細表示 | inventory_level | SELECT | ロケーション別在庫レベルの取得 |
| 詳細表示 | reservation_item | SELECT | 予約一覧の取得 |
| 詳細表示 | product_variant | SELECT | 関連バリアントの取得 |

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

本画面は詳細表示のみのため、データベース更新は発生しません。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| - | エラー | エラーメッセージ（API エラー内容） | API 呼び出しエラー時 |

## 例外処理

| 例外条件 | 対応 | 画面表示 |
|---------|------|----------|
| 在庫アイテムが存在しない | エラーをスロー | エラー画面を表示 |
| APIエラー | エラーをスロー | エラー画面を表示 |
| ローディング中 | スケルトン表示 | TwoColumnPageSkeletonを表示 |

## 備考

- TwoColumnPageレイアウトを使用
- JSON表示機能あり（showJSON: true）
- メタデータ表示・編集機能あり（showMetadata: true）
- ウィジェット拡張ポイントあり（before/after/sideBefore/sideAfter）
- loaderでデータをプリフェッチ

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | inventory-item.ts | `packages/modules/inventory/src/models/inventory-item.ts` | InventoryItemエンティティ。location_levels, reservation_itemsとの関連を確認 |
| 1-2 | inventory-level.ts | `packages/modules/inventory/src/models/inventory-level.ts` | InventoryLevelエンティティ。stocked_quantity, reserved_quantity, available_quantityを確認 |
| 1-3 | reservation-item.ts | `packages/modules/inventory/src/models/reservation-item.ts` | ReservationItemエンティティ |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | inventory-detail.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/inventory-detail.tsx` | ページコンポーネント。TwoColumnPageレイアウト、各セクションコンポーネントの配置を確認 |
| 2-2 | loader.ts | `packages/admin/dashboard/src/routes/inventory/inventory-detail/loader.ts` | データローダー。プリフェッチの実装を確認 |
| 2-3 | constants.ts | `packages/admin/dashboard/src/routes/inventory/inventory-detail/constants.ts` | 取得フィールドの定義 |

**主要処理フロー**:
1. **17行目**: `useParams` でIDを取得
2. **19-36行目**: `useInventoryItem` でデータ取得
3. **40-49行目**: ローディング中はスケルトン表示
4. **55-79行目**: TwoColumnPageで各セクションを配置

#### Step 3: 各セクションコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | inventory-item-general-section.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/inventory-item-general-section.tsx` | 基本情報セクション |
| 3-2 | inventory-item-location-levels.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/inventory-item-location-levels.tsx` | ロケーション別在庫セクション |
| 3-3 | inventory-item-reservations.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/inventory-item-reservations.tsx` | 予約セクション |
| 3-4 | variants-section.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/inventory-item-variants/variants-section.tsx` | 関連バリアントセクション |
| 3-5 | attributes-section.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/inventory-item-attributes/attributes-section.tsx` | 属性セクション |

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

```
InventoryDetail (inventory-detail.tsx)
    │
    ├─ useInventoryItem (inventory.tsx)
    │      └─ sdk.admin.inventoryItem.retrieve()
    │
    ├─ TwoColumnPage.Main
    │      ├─ InventoryItemGeneralSection
    │      ├─ InventoryItemLocationLevelsSection
    │      │      └─ LocationListTable
    │      └─ InventoryItemReservationsSection
    │             └─ ReservationListTable
    │
    └─ TwoColumnPage.Sidebar
           ├─ InventoryItemVariantsSection
           └─ InventoryItemAttributeSection
```

### データフロー図

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

URL パラメータ (id) ──▶ useInventoryItem ──▶ API呼び出し
                              │
                              ▼
                         inventory_item データ
                              │
           ┌──────────────────┼──────────────────┐
           ▼                  ▼                  ▼
    GeneralSection    LocationLevelsSection  ReservationsSection
           │                  │                  │
           ▼                  ▼                  ▼
    基本情報表示      ロケーション別在庫表示   予約一覧表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| inventory-detail.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/inventory-detail.tsx` | ソース | ページコンポーネント |
| loader.ts | `packages/admin/dashboard/src/routes/inventory/inventory-detail/loader.ts` | ソース | データローダー |
| constants.ts | `packages/admin/dashboard/src/routes/inventory/inventory-detail/constants.ts` | ソース | 定数定義 |
| inventory-item-general-section.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/inventory-item-general-section.tsx` | ソース | 基本情報セクション |
| inventory-item-location-levels.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/inventory-item-location-levels.tsx` | ソース | ロケーション別在庫セクション |
| inventory-item-reservations.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/inventory-item-reservations.tsx` | ソース | 予約セクション |
| variants-section.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/inventory-item-variants/variants-section.tsx` | ソース | 関連バリアントセクション |
| attributes-section.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/inventory-item-attributes/attributes-section.tsx` | ソース | 属性セクション |
| inventory.tsx | `packages/admin/dashboard/src/hooks/api/inventory.tsx` | ソース | API フック |
