# 画面設計書 145-配送プロファイルメタデータ編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における配送プロファイルメタデータ編集画面の設計仕様を記述したものである。

### 本画面の処理概要

**業務上の目的・背景**：メタデータは、標準的なフィールドでは表現できないカスタム情報を配送プロファイルに付与するための機能である。例えば、外部システムとの連携ID、カスタム属性、運用上の注記など、任意のキーと値のペアを保存できる。本画面は、配送プロファイルのメタデータを追加・編集・削除するためのフォームを提供する。

**画面へのアクセス方法**：配送プロファイル詳細画面のメタデータセクションから「編集」をクリックしてアクセスする。URLパスは `/settings/locations/shipping-profiles/:shipping_profile_id/metadata` である。

**主要な操作・処理内容**：
1. 既存のメタデータを表示する
2. 新しいメタデータ（キー・値ペア）を追加する
3. 既存のメタデータを編集する
4. メタデータを削除する
5. 変更を保存する

**画面遷移**：
- 遷移元: 配送プロファイル詳細画面
- 遷移先: 配送プロファイル詳細画面（保存・キャンセル後）

**権限による表示制御**：管理者権限を持つユーザーのみアクセス可能。配送プロファイル編集権限がない場合は表示されない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 44 | 配送プロファイル管理 | 主機能 | プロファイルメタデータの編集 |

## 画面種別

編集（モーダル形式）

## URL/ルーティング

```
/settings/locations/shipping-profiles/:shipping_profile_id/metadata
```

## 入出力項目

### URLパラメータ

| 項目名 | 項目ID | データ型 | 必須 | 説明 |
|--------|--------|----------|------|------|
| 配送プロファイルID | shipping_profile_id | string | 必須 | 編集対象の配送プロファイルID |

### 入力項目

| 項目名 | 項目ID | データ型 | 必須 | 説明 |
|--------|--------|----------|------|------|
| メタデータ | metadata | Record<string, unknown> | - | キー・値ペアの配列 |

## 表示項目

| 項目名 | データソース | 説明 |
|--------|-------------|------|
| メタデータリスト | shipping_profile.metadata | 既存のメタデータ一覧 |
| キー入力フィールド | - | メタデータのキーを入力 |
| 値入力フィールド | - | メタデータの値を入力 |
| 追加ボタン | - | 新しいメタデータ行を追加 |
| 削除ボタン | - | メタデータ行を削除 |
| キャンセルボタン | - | モーダルを閉じる |
| 保存ボタン | - | 変更を保存 |

## イベント仕様

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

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

**処理フロー**：
1. フォームのバリデーションを実行
2. `useUpdateShippingProfile` フックを使用してメタデータを更新
3. 成功時: 成功トーストを表示し、モーダルを閉じる
4. 失敗時: エラートーストを表示

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

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

**処理フロー**：
1. モーダルを閉じる
2. 配送プロファイル詳細画面に戻る

### 3-メタデータ行追加

**トリガー**：追加ボタンをクリック

**処理フロー**：
1. 新しい空のキー・値ペア行をフォームに追加
2. キー入力フィールドにフォーカス

### 4-メタデータ行削除

**トリガー**：行の削除ボタンをクリック

**処理フロー**：
1. 指定された行をフォームから削除

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

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

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

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

#### shipping_profile

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | metadata | フォーム入力値（JSON形式） | メタデータ全体を置換 |
| UPDATE | updated_at | 現在日時 | 更新日時 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| general.success | 成功 | 保存に成功しました | 保存成功時 |
| - | エラー | {APIエラーメッセージ} | API呼び出し失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 配送プロファイル取得失敗 | エラーをthrowし、エラーページを表示 |
| 更新処理失敗 | エラートーストを表示し、モーダルは閉じない |
| 無効なJSON形式 | バリデーションエラーを表示 |

## 備考

- MetadataFormコンポーネントを使用した共通メタデータ編集UI
- メタデータは任意のキー・値ペアを保存可能
- 値にはJSON対応の任意のデータ型（文字列、数値、オブジェクト、配列など）を設定可能
- 既存のメタデータは全件置換方式で更新

---

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

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

### 推奨読解順序

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

メタデータのデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | HttpTypes | `packages/core/types/src/http/shipping-profile/` | metadataフィールドの型定義（Record<string, unknown>） |

**読解のコツ**: メタデータはJSONB型で保存され、任意のキー・値ペアを格納できる。

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

画面のルートコンポーネントを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | shipping-profile-metadata.tsx | `packages/admin/dashboard/src/routes/shipping-profiles/shipping-profile-metadata/shipping-profile-metadata.tsx` | ルートコンポーネント |

**主要処理フロー**:
1. **9行目**: useParamsでshipping_profile_idを取得
2. **11-13行目**: useShippingProfileでデータ取得
3. **15-17行目**: useUpdateShippingProfileで更新フック取得
4. **19-21行目**: エラー時はerrorをthrow
5. **23-30行目**: MetadataFormコンポーネントを表示

#### Step 3: 共通メタデータフォームを理解する

MetadataFormコンポーネントの実装を読み解く。

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

**読解のコツ**: MetadataFormは汎用的なメタデータ編集コンポーネントで、各エンティティのメタデータ編集画面で再利用される。

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

データ取得・更新のAPIフック実装を読み解く。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | shipping-profiles.tsx | `packages/admin/dashboard/src/hooks/api/shipping-profiles.tsx` | useShippingProfile, useUpdateShippingProfile |

**主要処理フロー**:
- **40-60行目**: useShippingProfileでの詳細取得
- **83-107行目**: useUpdateShippingProfileでの更新処理

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

```
ShippingProfileMetadata
    │
    ├─ useParams (URLパラメータ取得)
    │
    ├─ useShippingProfile (配送プロファイル詳細取得)
    │      └─ sdk.admin.shippingProfile.retrieve
    │
    ├─ useUpdateShippingProfile (更新処理)
    │      └─ sdk.admin.shippingProfile.update
    │
    └─ MetadataForm (共通メタデータフォーム)
           │
           ├─ メタデータリスト表示
           │
           ├─ 行追加/削除処理
           │
           └─ 保存処理 (hookに委譲)
```

### データフロー図

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

URLパラメータ              ───▶ useParams                       ───▶ shipping_profile_id
(shipping_profile_id)

shipping_profile_id        ───▶ useShippingProfile              ───▶ shipping_profile.metadata
                                (APIコール)

メタデータ編集             ───▶ MetadataForm                    ───▶ 編集済みメタデータ
                                (フォーム状態管理)

編集済みメタデータ         ───▶ useUpdateShippingProfile        ───▶ 更新結果
                                (APIコール)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| shipping-profile-metadata.tsx | `packages/admin/dashboard/src/routes/shipping-profiles/shipping-profile-metadata/` | ソース | ルートコンポーネント |
| metadata-form.tsx | `packages/admin/dashboard/src/components/forms/metadata-form/` | ソース | 共通メタデータフォーム |
| shipping-profiles.tsx | `packages/admin/dashboard/src/hooks/api/` | ソース | APIフック |
| index.ts | `packages/admin/dashboard/src/routes/shipping-profiles/shipping-profile-metadata/` | ソース | エクスポート定義 |
