# 画面設計書 57-注文メタデータ編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における「注文メタデータ編集画面」の設計仕様を定義するものである。

### 本画面の処理概要

**業務上の目的・背景**：EC運営において、注文に対して追加のカスタムデータ（メタデータ）を付与・管理する必要がある場合がある（例：特別な配送指示、社内管理用情報、外部システム連携用ID等）。本画面は、管理者が注文のメタデータをキー・バリュー形式で編集するためのインターフェースを提供する。

**画面へのアクセス方法**：注文詳細画面から「メタデータ編集」アクションを選択することでアクセスする。

**主要な操作・処理内容**：
1. 現在のメタデータ一覧を確認する
2. 新しいキー・バリューペアを追加する
3. 既存のキー・バリューを編集する
4. 不要なキー・バリューを削除する
5. 保存ボタンを押下してメタデータを更新する

**画面遷移**：
- 遷移元：注文詳細画面（`/orders/:id`）
- 遷移先：更新完了後、注文詳細画面に戻る

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | 注文情報更新 | 主機能 | メタデータの更新 |

## 画面種別

編集（ドロワー形式）

## URL/ルーティング

```
/orders/:id/metadata
```

## 入出力項目

| 項目名 | 項目ID | データ型 | 必須 | 入力形式 | バリデーション | 説明 |
|--------|--------|----------|------|----------|----------------|------|
| メタデータ配列 | metadata | Array<{key, value, disabled}> | - | 動的フォーム | - | キー・バリューペアの配列 |
| キー | key | string | - | テキスト | - | メタデータのキー |
| 値 | value | any | - | テキスト | - | メタデータの値 |
| 無効フラグ | disabled | boolean | - | - | - | 複雑な値の編集無効化フラグ |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| ヘッダータイトル | テキスト | 「メタデータ編集」 |
| キー列ヘッダー | テキスト | 「キー」 |
| 値列ヘッダー | テキスト | 「値」 |
| 複雑な値の警告 | InlineTip | オブジェクト・配列値がある場合の警告表示 |
| 行アクションメニュー | DropdownMenu | 行の追加・削除メニュー |

## イベント仕様

### 1-キー入力

キーフィールドに入力があった場合：
- 入力値をフォーム状態に保存
- 複雑な値（オブジェクト・配列）を持つ行は編集不可（disabled）

### 2-値入力

値フィールドに入力があった場合：
- 入力値をフォーム状態に保存
- 文字列として保存（保存時に型変換）

### 3-行追加

行アクションメニューから「上に追加」または「下に追加」を選択した場合：
- 指定位置に新しい空の行を挿入
- useFieldArrayのinsert関数を使用

### 4-行削除

行アクションメニューから「削除」を選択した場合：
- 指定位置の行を削除
- 最後の1行を削除した場合、自動的に空の行を追加

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

保存ボタンが押下された場合：
1. フォームデータをパース（空の行を除外、型変換を実行）
2. `useUpdateOrder`フックを使用してAPI呼び出し
3. APIエンドポイント：`POST /admin/orders/:id`
4. リクエストボディ：`{ metadata: { key1: value1, key2: value2, ... } }`
5. 成功時：トースト通知を表示し、ドロワーを閉じる
6. 失敗時：エラーメッセージをトーストで表示

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

キャンセルボタンが押下された場合：
- フォームの変更を破棄
- ドロワーを閉じて注文詳細画面に戻る

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

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

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

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

#### order

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | metadata | パースされたメタデータオブジェクト | JSON形式 |
| UPDATE | updated_at | 現在日時 | 自動更新 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| successToast | 成功 | 「メタデータを更新しました」 | 更新成功時 |
| error | エラー | APIから返されたエラーメッセージ | 更新失敗時 |
| complexRow.label | 警告 | 「編集不可の値があります」 | 複雑な値がある場合 |
| complexRow.description | 警告 | 「オブジェクトまたは配列の値は編集できません」 | 複雑な値がある場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 注文が見つからない | エラーをスローし、エラーページを表示 |
| 読み込み中 | スケルトンを表示 |
| ネットワークエラー | エラートーストを表示 |

## 備考

- メタデータの値は以下の型変換ルールに従う
  - "true" / "false" -> boolean
  - 数値形式の文字列 -> number
  - その他 -> string
- オブジェクトや配列の値は編集不可（disabledフラグがtrue）
- 削除されたキーは空文字で更新される（API側でnull処理）
- 共通コンポーネント（MetadataForm）を使用しており、他のエンティティでも再利用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | OrderMetadata | `packages/admin/dashboard/src/routes/orders/order-metadata/order-metadata.tsx` | 画面コンポーネント |

**主要処理フロー**:
1. **6行目**: useParamsでIDを取得
2. **8-10行目**: useOrderフックで注文データを取得（metadataフィールド）
3. **12行目**: useUpdateOrderフックの取得
4. **19-24行目**: MetadataFormコンポーネントをレンダリング

#### Step 2: メタデータフォームコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | MetadataForm | `packages/admin/dashboard/src/components/forms/metadata-form/metadata-form.tsx` | 共通フォームコンポーネント |

**主要処理フロー**:
- **42-50行目**: Zodスキーマ定義
- **84-89行目**: useFormによるフォーム初期化
- **91-108行目**: フォーム送信ハンドラ
- **110-113行目**: useFieldArrayによる動的フィールド管理
- **115-126行目**: 行削除ロジック
- **128-134行目**: 行追加ロジック
- **333-367行目**: デフォルト値の生成（型判定含む）
- **369-428行目**: 値のパース・型変換ロジック

#### Step 3: APIフックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | useUpdateOrder | `packages/admin/dashboard/src/hooks/api/orders.tsx` | 注文更新APIフック |

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

```
OrderMetadata (order-metadata.tsx)
    │
    ├─ useOrder (注文データ取得、metadataフィールド)
    │
    ├─ useUpdateOrder (注文更新フック)
    │
    └─ MetadataForm (metadata-form.tsx)
           │
           ├─ useFieldArray (動的フィールド管理)
           │
           ├─ getDefaultValues (初期値生成)
           │
           ├─ parseValues (値のパース・型変換)
           │
           └─ hook（useUpdateOrder.mutateAsync）
                  └─ sdk.admin.order.update
                         └─ POST /admin/orders/:id
```

### データフロー図

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

既存メタデータ ────▶ getDefaultValues ────▶ フォーム初期値
                              │
                              ▼
キー入力 ─────────────┐
                      │
値入力 ──────────────┼───▶ useFieldArray ───▶ フォーム状態管理
                      │
行追加/削除 ─────────┘
                              │
                              ▼
                        parseValues
                              │
                              ▼
                    型変換（boolean/number/string）
                              │
                              ▼
                        useUpdateOrder
                              │
                              ▼
                     order.metadata (DB)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order-metadata.tsx | `packages/admin/dashboard/src/routes/orders/order-metadata/order-metadata.tsx` | ソース | 画面コンポーネント |
| metadata-form.tsx | `packages/admin/dashboard/src/components/forms/metadata-form/metadata-form.tsx` | ソース | 共通フォームコンポーネント |
| orders.tsx | `packages/admin/dashboard/src/hooks/api/orders.tsx` | ソース | 注文APIフック |
