# 画面設計書 102-予約詳細画面

## 概要

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

### 本画面の処理概要

予約詳細画面は、在庫予約の詳細情報を表示するためのフルページ形式の画面である。

**業務上の目的・背景**：在庫予約の詳細情報を確認することで、どの在庫アイテムがどのロケーションで予約されているか、予約数量や説明などを把握できる。これにより、在庫管理者は予約状況を正確に把握し、在庫の割当や調整の判断材料とすることができる。

**画面へのアクセス方法**：予約一覧画面（/reservations）から予約を選択、または予約作成後の自動遷移でアクセスする。

**主要な操作・処理内容**：
1. 予約の基本情報（ライン商品ID、説明、ロケーション）の表示
2. ロケーションでの在庫状況（在庫数、利用可能数、予約数）の表示
3. 関連する在庫アイテム情報のサイドバー表示
4. 予約情報の編集画面への遷移
5. メタデータおよびJSON生データの表示

**画面遷移**：
- 遷移元：予約一覧画面、予約作成画面
- 遷移先：予約編集画面（/reservations/{id}/edit）、メタデータ編集画面

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 50 | 在庫予約管理 | 主機能 | 予約詳細の表示 |

## 画面種別

詳細（TwoColumnPage形式）

## URL/ルーティング

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

## 入出力項目

本画面は表示専用のため、入力項目は存在しない。

## 表示項目

### メインエリア（ReservationGeneralSection）

| 項目名 | データソース | 表示形式 | 備考 |
|--------|-------------|---------|------|
| ヘッダータイトル | inventoryItem.title / inventoryItem.sku | テキスト | 「{アイテム名}の予約」形式 |
| ライン商品ID | reservation.line_item_id | テキスト | 注文明細との紐付け |
| 説明 | reservation.description | テキスト | 予約の用途・理由 |
| ロケーション | location.name | テキスト | 在庫ロケーション名 |
| ロケーション在庫数 | locationLevel.stocked_quantity | 数値 | 当該ロケーションの総在庫数 |
| ロケーション利用可能数 | locationLevel.available_quantity | 数値 | 予約可能な在庫数 |
| ロケーション予約数 | locationLevel.reserved_quantity | 数値 | 予約済みの在庫数 |

### サイドバーエリア（InventoryItemGeneralSection）

| 項目名 | データソース | 表示形式 | 備考 |
|--------|-------------|---------|------|
| 在庫アイテム情報 | inventory_item | コンポーネント | InventoryItemGeneralSectionで表示 |

### 共通エリア

| 項目名 | データソース | 表示形式 | 備考 |
|--------|-------------|---------|------|
| メタデータ | reservation.metadata | JSON形式 | TwoColumnPageコンポーネントで表示 |
| JSON生データ | reservation | JSON形式 | TwoColumnPageコンポーネントで表示 |

## イベント仕様

### 1-編集ボタン押下

- トリガー：ActionMenuの「編集」をクリック
- 処理内容：予約編集画面へ遷移
- 画面遷移：/reservations/{id}/edit

### 2-メタデータ表示

- トリガー：画面ロード時
- 処理内容：TwoColumnPageコンポーネントがshowMetadata=trueの設定に基づきメタデータセクションを表示
- 画面遷移：なし

### 3-JSON表示

- トリガー：画面ロード時
- 処理内容：TwoColumnPageコンポーネントがshowJSON=trueの設定に基づきJSON生データセクションを表示
- 画面遷移：なし

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | reservation | SELECT | 予約情報の取得 |
| 画面表示 | inventory_item | SELECT | 在庫アイテム情報の取得 |
| 画面表示 | stock_location | SELECT | ロケーション情報の取得 |

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

本画面では参照のみのため、更新処理は発生しない。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| - | エラー | APIエラーメッセージ | データ取得失敗時 |

## 例外処理

| 例外条件 | 処理内容 | ユーザーへの通知 |
|---------|---------|----------------|
| 予約が見つからない | エラーをスロー | エラー画面表示 |
| 在庫アイテムが見つからない | サイドバーを非表示 | - |
| ロケーションが見つからない | ローディング表示継続 | - |

## 備考

- TwoColumnPage形式でメイン領域とサイドバーに情報を分割表示
- ローダー（reservationItemLoader）によるデータプリフェッチを実装
- 拡張ポイント（widgets）が複数設定されており、プラグインによる画面拡張が可能
  - reservation.details.before
  - reservation.details.after
  - reservation.details.side.before
  - reservation.details.side.after

---

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

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

### 推奨読解順序

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

予約データと関連エンティティの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | reservations.tsx | `packages/admin/dashboard/src/hooks/api/reservations.tsx` | 23-43行目のuseReservationItemで取得するデータ構造（AdminReservationResponse）を確認 |

**読解のコツ**: HttpTypes.AdminReservationResponseの型定義を参照することで、reservationオブジェクトが持つプロパティ（id, inventory_item_id, location_id, quantity, description, metadata等）を把握できる。

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

画面全体の構造と表示ロジックを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | reservation-detail.tsx | `packages/admin/dashboard/src/routes/reservations/reservation-detail/reservation-detail.tsx` | 画面全体の構成、データ取得、条件分岐を確認 |

**主要処理フロー**:
1. **13行目**: useParamsでURLパラメータからidを取得
2. **15-17行目**: useLoaderDataでプリフェッチデータを取得
3. **19-25行目**: useReservationItemで予約データを取得
4. **28-32行目**: useInventoryItemで在庫アイテムデータを取得
5. **34行目**: useExtensionでウィジェット取得関数を取得
6. **36-49行目**: ローディング・エラー状態の処理
7. **51-72行目**: TwoColumnPageでメイン・サイドバー構成をレンダリング

#### Step 3: 予約情報表示コンポーネントを理解する

メインエリアの表示ロジックを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | reservation-general-section.tsx | `packages/admin/dashboard/src/routes/reservations/reservation-detail/components/reservation-general-section/reservation-general-section.tsx` | 予約詳細の表示項目とレイアウトを確認 |

**主要処理フロー**:
- **22-26行目**: useInventoryItemで在庫アイテム情報を取得
- **25-26行目**: useStockLocationでロケーション情報を取得
- **37-40行目**: 在庫アイテムのlocation_levelsから該当ロケーションのレベル情報を取得
- **42-88行目**: Container内でSectionRowを使って各情報を表示

#### Step 4: データローダーを理解する

初期データのプリフェッチ処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | loader.ts | `packages/admin/dashboard/src/routes/reservations/reservation-detail/loader.ts` | ルートローダーでのデータプリフェッチ方法を確認 |

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

```
ReservationDetail (reservation-detail.tsx)
    │
    ├─ useLoaderData (loader.ts)
    │      └─ reservationItemLoader
    │             └─ sdk.admin.reservation.retrieve
    │
    ├─ useReservationItem (reservations.tsx)
    │      └─ sdk.admin.reservation.retrieve
    │
    ├─ useInventoryItem (inventory.tsx)
    │      └─ sdk.admin.inventoryItem.retrieve
    │
    ├─ ReservationGeneralSection (reservation-general-section.tsx)
    │      ├─ useInventoryItem
    │      └─ useStockLocation (stock-locations.tsx)
    │             └─ sdk.admin.stockLocation.retrieve
    │
    └─ InventoryItemGeneralSection (inventory-item-general-section.tsx)
```

### データフロー図

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

URL params (id) ───▶ useReservationItem ───▶ 予約基本情報
         │
         ▼
reservation.inventory_item_id ───▶ useInventoryItem ───▶ 在庫アイテム情報
         │                                                    │
         │                                                    ▼
         │                                         location_levels
         │                                                    │
         ▼                                                    ▼
reservation.location_id ───▶ useStockLocation ───▶ ロケーション情報
                                                             │
                                                             ▼
                                                    在庫状況（stocked/available/reserved）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| reservation-detail.tsx | `packages/admin/dashboard/src/routes/reservations/reservation-detail/reservation-detail.tsx` | ソース | 画面エントリーポイント、レイアウト構成 |
| reservation-general-section.tsx | `packages/admin/dashboard/src/routes/reservations/reservation-detail/components/reservation-general-section/reservation-general-section.tsx` | ソース | 予約詳細表示コンポーネント |
| loader.ts | `packages/admin/dashboard/src/routes/reservations/reservation-detail/loader.ts` | ソース | データプリフェッチローダー |
| breadcrumb.tsx | `packages/admin/dashboard/src/routes/reservations/reservation-detail/breadcrumb.tsx` | ソース | パンくずリスト生成 |
| 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/index.ts` | ソース | エクスポート定義 |
