# 画面設計書 95-在庫属性編集画面

## 概要

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

### 本画面の処理概要

在庫属性編集画面は、既存の在庫アイテム（Inventory Item）の属性情報（サイズ、重量、税関関連コードなど）を編集するためのドロワー形式の画面です。

**業務上の目的・背景**：在庫アイテムの物理属性や税関関連情報を正確に管理することは、配送料金の計算や国際取引における関税処理に不可欠です。本画面では、サイズ・重量などの物理属性、HSコード・MIDコード・原産国などの税関関連情報、素材情報を一括して編集できます。

**画面へのアクセス方法**：在庫詳細画面の属性セクションから編集ボタンをクリックすることでドロワー形式で表示されます。URL `/inventory/{id}/attributes` に直接アクセスすることも可能です。

**主要な操作・処理内容**：
1. 物理属性の編集（高さ、幅、奥行き、重量）
2. 税関関連情報の編集（MIDコード、HSコード、原産国）
3. 素材情報の編集
4. 保存処理の実行

**画面遷移**：
- 遷移元：在庫詳細画面
- 遷移先：保存成功時は在庫詳細画面に戻る（ドロワークローズ）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 48 | 在庫アイテム管理 | 主機能 | 在庫アイテム属性の編集 |

## 画面種別

編集（モーダル形式 / ドロワー）

## URL/ルーティング

`/inventory/{id}/attributes`

## 入出力項目

### 入力項目

| 項目名 | 項目ID | 型 | 必須 | バリデーション | 説明 |
|--------|--------|-----|------|--------------|------|
| 高さ | height | number | - | 正の数値 | 製品の高さ |
| 幅 | width | number | - | 正の数値 | 製品の幅 |
| 奥行き | length | number | - | 正の数値 | 製品の奥行き |
| 重量 | weight | number | - | 正の数値 | 製品の重量 |
| MIDコード | mid_code | string | - | - | 製造者識別コード |
| HSコード | hs_code | string | - | - | 関税分類コード |
| 原産国 | origin_country | string | - | - | 原産国コード（国選択） |
| 素材 | material | string | - | - | 製品の素材 |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| ヘッダー | 「Edit Attributes」 |
| 各入力フィールド | 現在の値がプリセット |

## イベント仕様

### 1-Saveボタン押下

入力内容でバリデーションを実行し、在庫アイテムを更新します。

**処理フロー**:
1. フォームのバリデーション実行
2. バリデーション成功時、`useUpdateInventoryItem` で API 呼び出し
3. 成功時、トースト通知（inventory.toast.updateItem）を表示しドロワーをクローズ
4. エラー時、エラーメッセージをトースト表示

### 2-Cancelボタン押下

入力内容を破棄してドロワーをクローズします。

### 3-数値入力フィールドのクリア

空文字入力時、値をnullとして設定します。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 初期表示 | inventory_item | SELECT | 在庫アイテム情報の取得 |
| Save押下 | inventory_item | UPDATE | 在庫アイテム属性の更新 |

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

#### inventory_item

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | height | フォーム入力値またはnull | 任意 |
| UPDATE | width | フォーム入力値またはnull | 任意 |
| UPDATE | length | フォーム入力値またはnull | 任意 |
| UPDATE | weight | フォーム入力値またはnull | 任意 |
| UPDATE | mid_code | フォーム入力値 | 任意 |
| UPDATE | hs_code | フォーム入力値 | 任意 |
| UPDATE | origin_country | フォーム入力値 | 任意 |
| UPDATE | material | フォーム入力値 | 任意 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| inventory.toast.updateItem | 成功 | 在庫アイテムが正常に更新されました | 更新成功時 |
| - | エラー | エラーメッセージ（API エラー内容） | API 呼び出しエラー時 |

## 例外処理

| 例外条件 | 対応 | 画面表示 |
|---------|------|----------|
| 在庫アイテムが存在しない | エラーをスロー | エラー画面を表示 |
| バリデーションエラー | フォームエラー表示 | 入力フィールドにエラーメッセージを表示 |
| APIエラー | トースト通知 | エラーメッセージを表示 |

## 備考

- RouteDrawer形式で実装
- 数値フィールドは空文字入力時にnullに変換
- 原産国フィールドはCountrySelectコンポーネントを使用
- react-hook-formとzodによるバリデーション

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | edit-item-attributes-form.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/edit-inventory-item-attributes/components/edit-item-attributes-form.tsx` | EditInventoryItemAttributesSchemaのバリデーションルールを確認 |

**読解のコツ**: zodスキーマで各フィールドがoptionalであること、数値フィールドはpositiveバリデーションがあることを確認。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | edit-item-attributes-drawer.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/edit-inventory-item-attributes/edit-item-attributes-drawer.tsx` | ドロワーコンポーネント |
| 2-2 | edit-item-attributes-form.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/edit-inventory-item-attributes/components/edit-item-attributes-form.tsx` | フォームコンポーネント |

**主要処理フロー**:
1. **21-30行目（form）**: EditInventoryItemAttributesSchemaの定義
2. **32-43行目（form）**: getDefaultValuesで初期値設定
3. **75-103行目（form）**: heightフィールド（数値入力とnull変換）
4. **237-253行目（form）**: origin_countryフィールド（CountrySelect使用）

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

```
InventoryItemAttributesEdit (edit-item-attributes-drawer.tsx)
    │
    ├─ useInventoryItem (inventory.tsx)
    │      └─ sdk.admin.inventoryItem.retrieve()
    │
    └─ EditInventoryItemAttributesForm (edit-item-attributes-form.tsx)
           │
           └─ useUpdateInventoryItem (inventory.tsx)
                  └─ sdk.admin.inventoryItem.update()
```

### データフロー図

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

高さ/幅/奥行き/重量入力 ───┐
                            │
MIDコード/HSコード入力 ────┼──▶ useForm (react-hook-form)
                            │         │
原産国/素材入力 ───────────┘         │
                                      ▼
                              zodバリデーション
                                      │
                        (空文字 → null 変換)
                                      │
                                      ▼
                         useUpdateInventoryItem ──▶ inventory_item UPDATE
                                      │
                                      ▼
                                handleSuccess ──▶ ドロワークローズ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| edit-item-attributes-drawer.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/edit-inventory-item-attributes/edit-item-attributes-drawer.tsx` | ソース | ドロワーコンポーネント |
| edit-item-attributes-form.tsx | `packages/admin/dashboard/src/routes/inventory/inventory-detail/components/edit-inventory-item-attributes/components/edit-item-attributes-form.tsx` | ソース | フォームコンポーネント |
| inventory.tsx | `packages/admin/dashboard/src/hooks/api/inventory.tsx` | ソース | API フック |
