# 画面設計書 91-在庫一覧画面

## 概要

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

### 本画面の処理概要

在庫一覧画面は、システムに登録されているすべての在庫アイテム（Inventory Item）を一覧形式で表示し、在庫状況の把握と在庫アイテムの管理を行うための画面です。

**業務上の目的・背景**：ECサイト運営において、在庫管理は売上機会の最大化と過剰在庫の防止の両面で極めて重要です。本画面は、在庫担当者がすべての在庫アイテムの現在の在庫数量、予約済み数量を一目で把握し、在庫切れリスクのある商品を迅速に特定できるようにすることを目的としています。また、新規在庫アイテムの作成や、複数アイテムの在庫数量一括更新への導線も提供します。

**画面へのアクセス方法**：サイドメニューから「Inventory」をクリックするか、URL `/inventory` に直接アクセスすることで表示されます。認証済みユーザーのみがアクセス可能です。

**主要な操作・処理内容**：
1. 在庫アイテム一覧の表示（ページネーション対応、1ページ20件）
2. 在庫アイテムの検索（タイトル、SKU、説明などで検索可能）
3. フィルタによる絞り込み（ロケーション、素材、SKU、MIDコード、サイズ・重量、配送要否）
4. ソート機能（タイトル、SKU、在庫数、予約数で並び替え）
5. 在庫アイテムの複数選択と一括在庫更新
6. 新規在庫アイテム作成画面への遷移
7. 在庫アイテム詳細画面への遷移

**画面遷移**：
- 遷移元：サイドメニュー、ホーム画面
- 遷移先：在庫詳細画面（行クリック）、在庫作成画面（「Create」ボタン）、在庫一括更新画面（選択後「i」キーまたはコマンド）

**権限による表示制御**：認証済みユーザーであれば全機能を利用可能です。管理者権限による特別な制御はありません。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 48 | 在庫アイテム管理 | 主機能 | 在庫アイテム一覧の取得・表示 |
| 51 | 在庫確認 | 補助機能 | 在庫数量・ステータスの表示 |

## 画面種別

一覧

## URL/ルーティング

`/inventory`

## 入出力項目

### 検索・フィルタ入力項目

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| 検索キーワード | q | string | - | タイトル、SKU、説明などで検索 |
| ロケーション | location_id | string | - | 在庫ロケーションでフィルタ |
| 素材 | material | string | - | 素材でフィルタ |
| SKU | sku | string | - | SKUでフィルタ |
| MIDコード | mid_code | string | - | MIDコードでフィルタ |
| 高さ | height | number | - | 高さでフィルタ |
| 幅 | width | number | - | 幅でフィルタ |
| 奥行き | length | number | - | 奥行きでフィルタ |
| 重量 | weight | number | - | 重量でフィルタ |
| 配送必要 | requires_shipping | boolean | - | 配送要否でフィルタ |

## 表示項目

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|-----|------|
| 選択チェックボックス | select | checkbox | 一括操作用の行選択 |
| タイトル | title | string | 在庫アイテムのタイトル |
| SKU | sku | string | 在庫管理単位コード |
| 予約数 | reserved_quantity | number | 予約済み数量 |
| 在庫数 | stocked_quantity | number | 現在の在庫数量 |
| アクション | actions | menu | 編集・削除などのアクションメニュー |

## イベント仕様

### 1-Createボタン押下

新規在庫アイテム作成画面（モーダル）を開きます。

**遷移先**: `/inventory/create`

### 2-行クリック

選択した在庫アイテムの詳細画面に遷移します。

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

### 3-一括在庫更新コマンド（ショートカット：i）

選択した在庫アイテムの一括更新画面に遷移します。

**処理フロー**:
1. 選択された行のIDを取得
2. クエリパラメータに選択IDを付与して在庫一括更新画面に遷移

**遷移先**: `/inventory/stock?inventory_item_ids={ids}`

### 4-検索実行

入力されたキーワードで在庫アイテムを検索し、一覧を更新します。

**処理フロー**:
1. 検索キーワードをクエリパラメータに設定
2. `useInventoryItems` フックで API を呼び出し
3. 検索結果で一覧を再描画

### 5-フィルタ適用

選択されたフィルタ条件で在庫アイテムを絞り込みます。

**処理フロー**:
1. フィルタ条件をクエリパラメータに設定
2. `useInventoryItems` フックで API を呼び出し
3. フィルタ結果で一覧を再描画

### 6-ソート実行

選択されたカラムで在庫アイテムを並び替えます。

**対応カラム**: title, sku, stocked_quantity, reserved_quantity

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 一覧表示 | inventory_item | SELECT | 在庫アイテムの一覧取得 |
| 一覧表示 | inventory_level | SELECT | 在庫レベル情報の取得（在庫数・予約数の算出） |

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

#### inventory_item

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, title, sku, reserved_quantity, stocked_quantity | クエリパラメータに基づく条件 | reserved_quantity, stocked_quantity は computed field |

## メッセージ仕様

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

## 例外処理

| 例外条件 | 対応 | 画面表示 |
|---------|------|----------|
| APIエラー | エラーをスロー | エラー画面を表示 |
| データなし | 空の一覧を表示 | 「No data」メッセージを表示 |

## 備考

- ページサイズは20件固定
- 行選択は複数選択可能
- 在庫数・予約数は inventory_level から集計された computed field

---

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

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

### 推奨読解順序

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

まず、在庫アイテムのデータモデルを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | inventory-item.ts | `packages/modules/inventory/src/models/inventory-item.ts` | InventoryItem エンティティの定義。sku, title, stocked_quantity, reserved_quantity などのフィールドを確認 |
| 1-2 | inventory-level.ts | `packages/modules/inventory/src/models/inventory-level.ts` | InventoryLevel エンティティの定義。location_id, stocked_quantity, reserved_quantity の関係を確認 |

**読解のコツ**: `model.define()` でエンティティを定義し、`model.computed()` で計算フィールドを定義している点に注目。

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

処理の起点となるコンポーネントファイルを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | inventory-list.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-list/inventory-list.tsx` | ページコンポーネントのエントリーポイント。SingleColumnPage レイアウトとウィジェット拡張ポイントを確認 |
| 2-2 | inventory-list-table.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-list/components/inventory-list-table.tsx` | 一覧テーブルの実装。useInventoryItems フックによるデータ取得、DataTable コンポーネントの利用を確認 |

**主要処理フロー**:
1. **5-6行目**: `useExtension` でウィジェット拡張ポイントを取得
2. **8-16行目**: `SingleColumnPage` レイアウトでテーブルをラップ
3. **24-36行目**: `useInventoryItems` でAPIからデータ取得
4. **41-53行目**: `useDataTable` でテーブル状態管理
5. **72-102行目**: `_DataTable` でテーブル描画

#### Step 3: テーブルカラムとフィルタを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | use-inventory-table-columns.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-list/components/use-inventory-table-columns.tsx` | テーブルカラムの定義。select, title, sku, reserved_quantity, stocked_quantity, actions カラムを確認 |
| 3-2 | use-inventory-table-filters.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-list/components/use-inventory-table-filters.tsx` | フィルタ条件の定義。ロケーション、素材、SKU などのフィルタを確認 |

**主要処理フロー**:
- **26-53行目**: 選択チェックボックスカラムの定義
- **54-69行目**: タイトルカラムの定義
- **86-101行目**: 予約数カラムの定義
- **102-117行目**: 在庫数カラムの定義

#### Step 4: API呼び出しを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | inventory.tsx | `packages/admin/dashboard/src/hooks/api/inventory.tsx` | APIフックの実装。useInventoryItems, useCreateInventoryItem などの実装を確認 |

**主要処理フロー**:
- **26-45行目**: `useInventoryItems` - 在庫アイテム一覧取得
- **47-67行目**: `useInventoryItem` - 在庫アイテム詳細取得

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

```
InventoryItemListTable (inventory-list.tsx)
    │
    └─ InventoryListTable (inventory-list-table.tsx)
           │
           ├─ useInventoryItems (inventory.tsx)
           │      └─ sdk.admin.inventoryItem.list()
           │
           ├─ useInventoryTableColumns (use-inventory-table-columns.tsx)
           │
           ├─ useInventoryTableFilters (use-inventory-table-filters.tsx)
           │      └─ useStockLocations (stock-locations.tsx)
           │
           └─ _DataTable (data-table.tsx)
```

### データフロー図

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

検索キーワード ───────┐
                      │
フィルタ条件 ─────────┼──▶ useInventoryItems ──▶ API呼び出し ──▶ 在庫アイテム一覧
                      │         │
ソート条件 ──────────┘         │
                               ▼
                         useDataTable ──▶ テーブル状態管理
                               │
                               ▼
                          _DataTable ──▶ テーブル表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| inventory-list.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-list/inventory-list.tsx` | ソース | ページエントリーポイント |
| inventory-list-table.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-list/components/inventory-list-table.tsx` | ソース | 一覧テーブルコンポーネント |
| use-inventory-table-columns.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-list/components/use-inventory-table-columns.tsx` | ソース | テーブルカラム定義 |
| use-inventory-table-filters.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-list/components/use-inventory-table-filters.tsx` | ソース | フィルタ定義 |
| use-inventory-table-query.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-list/components/use-inventory-table-query.tsx` | ソース | クエリパラメータ管理 |
| inventory-actions.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-list/components/inventory-actions.tsx` | ソース | 行アクションメニュー |
| inventory.tsx | `packages/admin/dashboard/src/hooks/api/inventory.tsx` | ソース | API フック |
| inventory-item.ts | `packages/modules/inventory/src/models/inventory-item.ts` | ソース | エンティティモデル |
| inventory-level.ts | `packages/modules/inventory/src/models/inventory-level.ts` | ソース | エンティティモデル |
| inventory-module.ts | `packages/modules/inventory/src/services/inventory-module.ts` | ソース | モジュールサービス |
