# 画面設計書 118-リージョンメタデータ編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboardにおけるリージョンのメタデータ編集画面に関する設計書です。この画面により、リージョンに紐づくカスタムメタデータをキー・バリュー形式で管理することができます。

### 本画面の処理概要

**業務上の目的・背景**：リージョン固有のカスタム情報を保持する必要がある場合に、メタデータ機能を活用します。外部システムとの連携や、カスタマイズされたビジネスロジックの実装に不可欠な機能です。

**画面へのアクセス方法**：リージョン詳細画面（/settings/regions/:id）のメタデータセクションの「編集」ボタン、またはJSON表示エリアの編集アクションからアクセスできます。URL直接アクセスも可能（/settings/regions/:id/metadata）。

**主要な操作・処理内容**：
1. 既存のメタデータをキー・バリュー形式のグリッドで表示
2. 新規メタデータ行の追加（上または下に挿入）
3. 既存メタデータの編集（キーと値の変更）
4. メタデータ行の削除
5. 複雑な値（オブジェクト・配列）は読み取り専用で表示
6. 変更内容の保存

**画面遷移**：
- 遷移元：リージョン詳細画面（/settings/regions/:id）
- 遷移先：保存成功時・キャンセル時ともにリージョン詳細画面に戻る

**権限による表示制御**：管理者権限を持つユーザーのみがアクセス可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 65 | 地域CRUD | 主機能 | リージョンメタデータの編集 |

## 画面種別

ドロワー形式（RouteDrawer）の編集画面

## URL/ルーティング

`/settings/regions/:id/metadata`

## 入出力項目

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|------|------|------|
| メタデータ配列 | metadata | MetadataField[] | - | キー・値・disabled状態の配列 |
| メタデータキー | metadata[].key | string | - | メタデータのキー名 |
| メタデータ値 | metadata[].value | any | - | メタデータの値 |
| 編集不可フラグ | metadata[].disabled | boolean | - | 複雑な値の場合true |

## 表示項目

### メタデータグリッド

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|------|------|
| キー | key | string | メタデータのキー |
| 値 | value | string/any | メタデータの値（複雑な値は{ ... }や[ ... ]で表示） |
| 行アクションメニュー | actions | - | 上に挿入/下に挿入/削除 |

## イベント仕様

### 1-行の追加（上に挿入）

**トリガー**：行のアクションメニューから「上に行を挿入」を選択

**処理内容**：
1. useFieldArrayのinsertを使用
2. 指定インデックスの位置に空の行を挿入
3. 新しい行はkey: "", value: "", disabled: falseで初期化

### 2-行の追加（下に挿入）

**トリガー**：行のアクションメニューから「下に行を挿入」を選択

**処理内容**：
1. useFieldArrayのinsertを使用
2. 指定インデックス+1の位置に空の行を挿入

### 3-行の削除

**トリガー**：行のアクションメニューから「行を削除」を選択

**処理内容**：
1. useFieldArrayのremoveを使用
2. 指定インデックスの行を削除
3. 最後の1行を削除した場合は、自動的に空の行を追加

### 4-保存

**トリガー**：「保存」ボタンをクリック

**処理内容**：
1. フォーム値をパース（parseValues関数）
2. useUpdateRegionフックでリージョン更新APIを呼び出し
3. 成功時：トースト通知を表示し、ドロワーを閉じる
4. 失敗時：エラートースト通知を表示

### 5-キャンセル

**トリガー**：「キャンセル」ボタンをクリック

**処理内容**：
1. ドロワーを閉じてリージョン詳細画面に戻る

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | region | UPDATE | リージョンのmetadataフィールドを更新 |

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

#### region

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

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|---------|
| metadata.edit.successToast | 成功 | メタデータが更新されました | 保存成功時 |
| - | エラー | {エラーメッセージ} | API呼び出し失敗時 |
| metadata.edit.complexRow.tooltip | 情報 | この行は編集できません | 複雑な値の行にホバー時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| リージョン情報取得エラー | エラーをスローしてエラーバウンダリで処理 |
| 更新API失敗 | エラートーストを表示、フォームは維持 |
| 複雑な値（オブジェクト/配列） | 編集不可として表示、削除も不可 |

## 備考

- 本画面は汎用のMetadataFormコンポーネントを使用
- オブジェクトや配列などの複雑な値は編集不可（読み取り専用）
- 複雑な値がある場合は警告メッセージ（InlineTip）を表示
- 値の型は自動判定される（true/false->boolean、数値文字列->number）

---

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

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

### 推奨読解順序

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

メタデータのデータ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | metadata-form.tsx | `packages/admin/dashboard/src/components/forms/metadata-form/metadata-form.tsx` | MetadataFieldSchemaの定義（42-46行目） |

**読解のコツ**: メタデータはkey, value, disabledの3フィールドを持つオブジェクトの配列として管理されます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | region-metadata.tsx | `packages/admin/dashboard/src/routes/regions/region-metadata/region-metadata.tsx` | コンポーネントのエントリーポイント |

**主要処理フロー**:
1. **8行目**: URLパラメータからリージョンIDを取得
2. **10行目**: useRegionでリージョン情報を取得
3. **11行目**: useUpdateRegionでリージョン更新フックを取得
4. **17-26行目**: RouteDrawerでMetadataFormをラップ

#### Step 3: フォームロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | metadata-form.tsx | `packages/admin/dashboard/src/components/forms/metadata-form/metadata-form.tsx` | 汎用メタデータフォームコンポーネント |

**主要処理フロー**:
- 112番「ストアメタデータ編集画面」と同じMetadataFormを使用
- hookプロップにuseUpdateRegionのmutateAsyncを渡す

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | regions.tsx | `packages/admin/dashboard/src/hooks/api/regions.tsx` | リージョンAPIフック |

**主要処理フロー**:
- **18-38行目**: useRegion - リージョン情報取得
- **86-111行目**: useUpdateRegion - metadataを含むリージョン更新

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

```
RegionMetadata (region-metadata.tsx)
    │
    ├─ useParams()
    │      └─ リージョンID取得
    │
    ├─ useRegion()
    │      └─ sdk.admin.region.retrieve()
    │
    ├─ useUpdateRegion()
    │      └─ sdk.admin.region.update()
    │
    └─ MetadataForm
           │
           ├─ useForm() + useFieldArray()
           │      └─ フォーム状態管理
           │
           ├─ getDefaultValues()
           │      └─ 既存メタデータの変換
           │
           └─ parseValues()
                  └─ 保存用データ変換
```

### データフロー図

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

region.metadata ────▶ getDefaultValues() ─────▶ フォーム初期値
                           │
                           ▼
キー/値の編集 ────▶ フォーム状態管理 ────────▶ fields配列
                           │
                           ▼
保存ボタン押下 ──▶ parseValues() ───────────▶ 更新用metadata
                           │                    (型変換済み)
                           ▼
                 useUpdateRegion API呼び出し
                           │
                           ▼
                  [Region APIサーバー]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| region-metadata.tsx | `packages/admin/dashboard/src/routes/regions/region-metadata/region-metadata.tsx` | ソース | エントリーポイント |
| metadata-form.tsx | `packages/admin/dashboard/src/components/forms/metadata-form/metadata-form.tsx` | ソース | 汎用メタデータフォーム |
| regions.tsx | `packages/admin/dashboard/src/hooks/api/regions.tsx` | ソース | リージョンAPIフック |
| route-drawer.tsx | `packages/admin/dashboard/src/components/modals/route-drawer/` | ソース | ドロワーコンポーネント |
