# 画面設計書 103-予約編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における予約編集画面の設計仕様を定義する。

### 本画面の処理概要

予約編集画面は、既存の在庫予約情報を編集するためのドロワー（サイドパネル）形式の画面である。

**業務上の目的・背景**：在庫予約の作成後、予約数量の変更やロケーションの変更、説明の追加・修正が必要になる場合がある。この画面により、在庫管理者は既存の予約を柔軟に調整でき、注文処理や在庫調整の変更に対応できる。

**画面へのアクセス方法**：予約詳細画面（/reservations/{id}）のアクションメニューから「編集」を選択してアクセスする。

**主要な操作・処理内容**：
1. ロケーション（倉庫）の変更
2. 予約数量の変更
3. 説明の編集
4. 在庫状況（タイトル、SKU、在庫数、利用可能数）の確認
5. 変更の保存

**画面遷移**：
- 遷移元：予約詳細画面
- 遷移先：保存成功時は予約詳細画面に戻る

**権限による表示制御**：認証済みの管理者ユーザーのみアクセス可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 50 | 在庫予約管理 | 主機能 | 予約情報の編集 |

## 画面種別

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

## URL/ルーティング

- パス: `/reservations/:id/edit`
- パラメータ: `id` - 予約ID

## 入出力項目

| 項目名 | 項目ID | 入力/出力 | 必須 | データ型 | バリデーション | 備考 |
|--------|--------|----------|------|---------|---------------|------|
| ロケーション | location_id | 入力 | 必須 | string | - | Selectで選択 |
| 数量 | quantity | 入力 | 必須 | number | 1以上 | 利用可能数量+現在予約数量が上限 |
| 説明 | description | 入力 | 任意 | string | - | Textareaで入力 |

## 表示項目

| 項目名 | データソース | 表示形式 | 備考 |
|--------|-------------|---------|------|
| タイトル | item.title / item.sku | テキスト | 在庫アイテム名 |
| SKU | item.sku | テキスト | 在庫アイテムSKU |
| 在庫数 | level.stocked_quantity | 数値 | 選択ロケーションの総在庫数 |
| 利用可能数 | 計算値 | 数値 | stocked_quantity - (reserved_quantity - 現在予約数) - 入力数量 |

## イベント仕様

### 1-ロケーション変更

- トリガー：ロケーションSelectで値を変更
- 処理内容：
  1. 選択したロケーションに対応する在庫レベル情報を取得
  2. 在庫数・利用可能数の表示を更新
- 状態変化：在庫情報表示エリアが更新される

### 2-数量入力

- トリガー：数量フィールドへの入力
- 処理内容：
  1. 入力値をリアルタイムで監視
  2. 利用可能数を動的に再計算
- 状態変化：利用可能数の表示が更新される

### 3-保存ボタン押下

- トリガー：「保存」ボタンをクリック
- 処理内容：
  1. フォームバリデーション実行
  2. 予約更新APIを呼び出し（useUpdateReservationItem）
  3. 成功時：トースト通知を表示し、ドロワーを閉じる
  4. 失敗時：エラートースト通知を表示
- 画面遷移：保存成功時は予約詳細画面に戻る

### 4-キャンセルボタン押下

- トリガー：「キャンセル」ボタンをクリック
- 処理内容：ドロワーを閉じる
- 画面遷移：予約詳細画面に戻る

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | reservation | UPDATE | 予約情報を更新 |
| 保存ボタン押下 | inventory_level | UPDATE | ロケーション変更時、両ロケーションのreserved_quantityを更新 |

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

#### reservation

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | location_id | フォーム入力値 | ロケーションID |
| UPDATE | quantity | フォーム入力値 | 予約数量 |
| UPDATE | description | フォーム入力値（オプション） | 説明 |

#### inventory_level

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | reserved_quantity | 数量変更分を加減算 | ロケーション変更時は元ロケーションから減算、新ロケーションに加算 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| inventory.reservation.updateSuccessToast | 成功 | 予約が正常に更新されました | 予約更新成功時 |
| (APIエラー) | エラー | エラーメッセージ（API応答） | API呼び出し失敗時 |

## 例外処理

| 例外条件 | 処理内容 | ユーザーへの通知 |
|---------|---------|----------------|
| 予約が見つからない | エラーをスロー | エラー画面表示 |
| 在庫アイテムが見つからない | データ取得待機 | ローディング表示 |
| ロケーションが見つからない | データ取得待機 | ローディング表示 |
| API通信エラー | 処理を中断 | エラートースト表示 |

## 備考

- ドロワー（RouteDrawer）形式でサイドパネルとして表示
- zodによるスキーマバリデーション（EditReservationSchema）を実装
- react-hook-formによるフォーム管理
- 利用可能数の計算：stocked_quantity - (reserved_quantity - 現在の予約数) - 新しい予約数
- 数量の最大値は (available_quantity + 現在の予約数) に設定

---

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

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

### 推奨読解順序

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

予約編集に関するバリデーションスキーマを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | edit-reservation-form.tsx | `packages/admin/dashboard/src/routes/reservations/reservation-detail/components/edit-reservation/components/edit-reservation-form.tsx` | 21-25行目のEditReservationSchemaでバリデーションルールを確認 |

**読解のコツ**: z.object()でlocation_id（必須文字列）、description（オプション文字列）、quantity（1以上の数値）を定義。

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

画面のエントリーポイントとデータ取得ロジックを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | edit-reservation-modal.tsx | `packages/admin/dashboard/src/routes/reservations/reservation-detail/components/edit-reservation/edit-reservation-modal.tsx` | 予約、在庫アイテム、ロケーション情報の取得フローを確認 |

**主要処理フロー**:
1. **12行目**: useParamsでURLパラメータからidを取得
2. **15行目**: useReservationItemで予約データを取得
3. **16-20行目**: useInventoryItemで在庫アイテムデータを取得
4. **23-32行目**: useStockLocationsでロケーション一覧を取得
5. **34行目**: データ準備完了の判定
6. **39-51行目**: RouteDrawerでドロワー表示、EditReservationFormをレンダリング

#### Step 3: フォームコンポーネントを理解する

フォームの実装詳細を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | edit-reservation-form.tsx | `packages/admin/dashboard/src/routes/reservations/reservation-detail/components/edit-reservation/components/edit-reservation-form.tsx` | フォーム実装、状態管理、利用可能数計算、API呼び出しを確認 |

**主要処理フロー**:
- **46-54行目**: getDefaultValuesで既存予約データからデフォルト値を設定
- **64-67行目**: useFormでフォーム初期化
- **69行目**: useUpdateReservationItemで更新mutation取得
- **71-81行目**: handleSubmitでAPI呼び出しと成功・失敗処理
- **83-88行目**: watchで数量とロケーションIDを監視し、在庫レベル情報を取得
- **130-148行目**: AttributeGridRowで在庫情報を表示（利用可能数は動的計算）

#### Step 4: API hooks を理解する

APIとの通信処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | reservations.tsx | `packages/admin/dashboard/src/hooks/api/reservations.tsx` | 66-94行目のuseUpdateReservationItemで予約更新APIの呼び出し方法とキャッシュ無効化を確認 |

**主要処理フロー**:
- **75-76行目**: sdk.admin.reservation.updateでAPI呼び出し
- **77-90行目**: 成功時のキャッシュ無効化（予約詳細、予約一覧、在庫詳細、在庫レベル）

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

```
ReservationEdit (edit-reservation-modal.tsx)
    │
    ├─ useReservationItem (reservations.tsx)
    │      └─ sdk.admin.reservation.retrieve
    │
    ├─ useInventoryItem (inventory.tsx)
    │      └─ sdk.admin.inventoryItem.retrieve
    │
    ├─ useStockLocations (stock-locations.tsx)
    │      └─ sdk.admin.stockLocation.list
    │
    └─ EditReservationForm (edit-reservation-form.tsx)
           │
           └─ useUpdateReservationItem (reservations.tsx)
                  └─ sdk.admin.reservation.update
```

### データフロー図

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

URL params (id) ───▶ useReservationItem ───▶ 既存予約データ
         │                                        │
         │                                        ▼
         │                              getDefaultValues ───▶ フォーム初期値
         │
         ▼
reservation.inventory_item_id ───▶ useInventoryItem ───▶ 在庫アイテム情報
         │                                                    │
         │                                                    ▼
         │                                         location_levels ───▶ 利用可能数計算
         │
         ▼
inventory_item.location_levels ───▶ useStockLocations ───▶ ロケーション選択肢
         │
         ▼
保存ボタン ─────────▶ useUpdateReservationItem ───▶ 予約詳細画面に戻る
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| edit-reservation-modal.tsx | `packages/admin/dashboard/src/routes/reservations/reservation-detail/components/edit-reservation/edit-reservation-modal.tsx` | ソース | エントリーポイント、データ取得 |
| edit-reservation-form.tsx | `packages/admin/dashboard/src/routes/reservations/reservation-detail/components/edit-reservation/components/edit-reservation-form.tsx` | ソース | フォーム実装、バリデーション、API呼び出し |
| reservations.tsx | `packages/admin/dashboard/src/hooks/api/reservations.tsx` | ソース | 予約関連API hooks |
| inventory.tsx | `packages/admin/dashboard/src/hooks/api/inventory.tsx` | ソース | 在庫アイテムAPI hooks |
| stock-locations.tsx | `packages/admin/dashboard/src/hooks/api/stock-locations.tsx` | ソース | ロケーションAPI hooks |
| index.ts | `packages/admin/dashboard/src/routes/reservations/reservation-detail/components/edit-reservation/index.ts` | ソース | エクスポート定義 |
