# 画面設計書 104-予約メタデータ編集画面

## 概要

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

### 本画面の処理概要

予約メタデータ編集画面は、在庫予約に関連するカスタムメタデータを編集するためのドロワー形式の画面である。

**業務上の目的・背景**：メタデータはキーバリュー形式の拡張データを格納するための仕組みであり、標準の予約フィールドでは表現できない追加情報（例：予約理由コード、参照番号、カスタム属性など）を管理できる。システム連携や業務固有の情報を予約に紐付けることで、柔軟な在庫管理を実現する。

**画面へのアクセス方法**：予約詳細画面（/reservations/{id}）のメタデータセクションから「編集」操作でアクセスする。

**主要な操作・処理内容**：
1. 既存メタデータの表示
2. メタデータのキーと値の追加
3. 既存メタデータの値の編集
4. メタデータの削除
5. 変更の保存

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

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

## 関連機能

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

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

| 項目名 | 項目ID | 入力/出力 | 必須 | データ型 | バリデーション | 備考 |
|--------|--------|----------|------|---------|---------------|------|
| メタデータ | metadata | 入力 | 任意 | Record<string, any> | - | キーバリュー形式で複数入力可能 |

## 表示項目

| 項目名 | データソース | 表示形式 | 備考 |
|--------|-------------|---------|------|
| 既存メタデータ一覧 | reservation.metadata | キーバリューリスト | 編集・削除可能 |

## イベント仕様

### 1-メタデータ追加

- トリガー：MetadataFormの追加操作
- 処理内容：新しいキーバリューペアをフォームに追加
- 状態変化：フォームに新しい入力行が追加される

### 2-メタデータ編集

- トリガー：既存メタデータの値を変更
- 処理内容：フォーム状態を更新
- 状態変化：該当行の値が更新される

### 3-メタデータ削除

- トリガー：メタデータ行の削除操作
- 処理内容：該当キーバリューペアをフォームから削除
- 状態変化：該当行がフォームから削除される

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

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

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

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

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | reservation | UPDATE | メタデータフィールドを更新 |

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

#### reservation

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | metadata | フォーム入力値（JSON形式） | キーバリューペアのオブジェクト |

## メッセージ仕様

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

## 例外処理

| 例外条件 | 処理内容 | ユーザーへの通知 |
|---------|---------|----------------|
| 予約が見つからない | エラーをスロー | エラー画面表示 |
| API通信エラー | 処理を中断 | エラートースト表示 |

## 備考

- ドロワー（RouteDrawer）形式でサイドパネルとして表示
- MetadataFormコンポーネント（共通コンポーネント）を使用
- メタデータはJSONB型でデータベースに格納
- 空のメタデータも保存可能

---

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

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

### 推奨読解順序

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

画面のエントリーポイントと全体構造を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | reservation-metadata.tsx | `packages/admin/dashboard/src/routes/reservations/reservation-metadata/reservation-metadata.tsx` | シンプルな構造で、データ取得とMetadataFormの連携を確認 |

**主要処理フロー**:
1. **11行目**: useParamsでURLパラメータからidを取得
2. **13行目**: useReservationItemで予約データを取得
3. **14行目**: useUpdateReservationItemで更新mutation取得
4. **16-18行目**: エラー処理
5. **20-28行目**: RouteDrawerでドロワー表示、MetadataFormをレンダリング

**読解のコツ**: この画面は非常にシンプルな構造で、MetadataFormコンポーネントに処理を委譲している。isPending（ローディング状態）、isMutating（更新処理中）、hook（更新関数）、metadata（既存データ）を渡すだけ。

#### Step 2: 共通コンポーネントを理解する

MetadataFormコンポーネントの実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | metadata-form | `packages/admin/dashboard/src/components/forms/metadata-form/` | メタデータ編集の共通UIと処理ロジックを確認 |

**読解のコツ**: MetadataFormは複数のエンティティ（予約、商品、顧客など）で共通利用される汎用コンポーネント。hook propとして渡されたmutateAsync関数を呼び出すことで、各エンティティのAPIを抽象化している。

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

予約更新APIの呼び出し方法を確認。

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

**主要処理フロー**:
- **75-76行目**: sdk.admin.reservation.updateでAPI呼び出し（metadataもpayloadに含まれる）
- **77-90行目**: 成功時のキャッシュ無効化

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

```
ReservationMetadata (reservation-metadata.tsx)
    │
    ├─ useReservationItem (reservations.tsx)
    │      └─ sdk.admin.reservation.retrieve
    │
    ├─ useUpdateReservationItem (reservations.tsx)
    │
    └─ MetadataForm (components/forms/metadata-form)
           │
           └─ hook (mutateAsync)
                  └─ sdk.admin.reservation.update
```

### データフロー図

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

URL params (id) ───▶ useReservationItem ───▶ 既存メタデータ
         │                                        │
         │                                        ▼
         │                              MetadataForm ───▶ 編集UI
         │
         ▼
保存ボタン ─────────▶ hook (mutateAsync) ───▶ 予約詳細画面に戻る
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| reservation-metadata.tsx | `packages/admin/dashboard/src/routes/reservations/reservation-metadata/reservation-metadata.tsx` | ソース | 画面エントリーポイント |
| reservations.tsx | `packages/admin/dashboard/src/hooks/api/reservations.tsx` | ソース | 予約関連API hooks |
| metadata-form | `packages/admin/dashboard/src/components/forms/metadata-form/` | ソース | メタデータ編集共通コンポーネント |
| index.ts | `packages/admin/dashboard/src/routes/reservations/reservation-metadata/index.ts` | ソース | エクスポート定義 |
