# 画面設計書 74-価格表編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboardにおける「価格表編集画面」の画面設計書です。既存の価格表（Price List）の基本情報を編集するためのドロワー形式の画面について記述します。

### 本画面の処理概要

この画面では、価格表のタイプ、タイトル、ステータス、説明を編集します。開始日・終了日・顧客グループの編集は別画面（価格表設定画面）で行います。

**業務上の目的・背景**：価格表の基本情報は、その価格表の性質や用途を定義する重要な設定です。セール価格表をオーバーライド価格表に変更したり、公開状態を切り替えたり、説明文を更新したりする際に使用されます。設定項目を2画面に分割することで、頻繁に更新する項目と初期設定後は変更が少ない項目を区別し、操作性を向上させています。

**画面へのアクセス方法**：価格表詳細画面の基本情報セクションの「Edit」ボタンをクリック、またはURL `/price-lists/{id}/edit` に直接アクセスすることで表示されます。

**主要な操作・処理内容**：
1. 価格表タイプ（Sale/Override）の変更
2. タイトルの変更
3. ステータス（Active/Draft）の変更
4. 説明文の変更
5. 変更内容の保存

**画面遷移**：
- 遷移元：価格表詳細画面
- 遷移先：保存成功時・キャンセル時に価格表詳細画面に戻る

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 53 | 価格リスト管理 | 主機能 | 価格表基本情報の更新 |

## 画面種別

ドロワー形式（RouteDrawer）

## URL/ルーティング

`/price-lists/:id/edit`

## 入出力項目

### パスパラメータ（入力）

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| id | string | Yes | 価格表のID |

### フォーム項目

| 項目名 | フィールド名 | 型 | 必須 | バリデーション | 説明 |
|--------|-------------|-----|------|---------------|------|
| タイプ | type | enum | Yes | "sale" または "override" | 価格表のタイプ |
| タイトル | title | string | Yes | 1文字以上 | 価格表の名称 |
| ステータス | status | enum | Yes | "draft" または "active" | 公開ステータス |
| 説明 | description | string | Yes | 1文字以上 | 価格表の説明 |

## 表示項目

### ヘッダー部

| 項目名 | コンポーネント | 説明 |
|--------|--------------|------|
| タイトル | Heading | "Edit Price List" |

### フォーム部

| 項目名 | コンポーネント | 説明 |
|--------|--------------|------|
| タイプ選択 | RadioGroup.ChoiceBox | Sale/Overrideの選択 |
| タイトル入力 | Input | テキスト入力 |
| ステータス選択 | Select | Active/Draftの選択 |
| 説明入力 | Textarea | 複数行テキスト入力 |

### フッター部

| 項目名 | コンポーネント | 説明 |
|--------|--------------|------|
| キャンセルボタン | Button (secondary) | ドロワーを閉じる |
| 保存ボタン | Button (primary) | 変更を保存 |

## イベント仕様

### 1-タイプ変更

RadioGroup.ChoiceBoxでSaleまたはOverrideを選択します。選択変更時にフォーム状態が更新されます。

### 2-タイトル変更

Inputフィールドにタイトルを入力します。1文字以上必須です。

### 3-ステータス変更

SelectコンポーネントでActiveまたはDraftを選択します。

### 4-説明変更

Textareaフィールドに説明文を入力します。1文字以上必須です。

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

フォームをバリデーションし、成功すれば`useUpdatePriceList`フックを使用してAPIを呼び出します。成功時はトーストを表示し、ドロワーを閉じて詳細画面に戻ります。

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

変更を破棄し、ドロワーを閉じて詳細画面に戻ります。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | price_list | SELECT | 価格表詳細の取得 |
| 保存押下 | price_list | UPDATE | 価格表基本情報の更新 |

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

#### price_list

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | type | フォーム入力値（"sale" or "override"） | |
| UPDATE | title | フォーム入力値 | |
| UPDATE | status | フォーム入力値（"draft" or "active"） | |
| UPDATE | description | フォーム入力値 | |

## メッセージ仕様

| 種別 | 条件 | メッセージ |
|------|------|-----------|
| 成功 | 更新成功時 | Price list "{title}" was successfully updated. |
| エラー | バリデーション失敗時 | 各フィールドにエラーメッセージ表示 |
| エラー | API呼び出し失敗時 | エラーメッセージをトースト表示 |

## 例外処理

| 状態 | 処理 |
|------|------|
| 価格表が存在しない場合 | エラーをスローし、エラーバウンダリーで捕捉 |
| データ取得中 | フォームを表示しない（ready判定） |
| バリデーションエラー | フォームフィールドにエラー表示 |
| API エラー発生時 | エラーメッセージをトースト表示 |

## 備考

- RouteDrawerを使用したスライドインUI
- フォームはreact-hook-formとzodを使用したバリデーションを実装
- 現在の値をデフォルト値として設定
- KeyboundFormでキーボードショートカット対応

---

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

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

### 推奨読解順序

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

ページコンポーネントとデータ取得処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | price-list-edit.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-edit/price-list-edit.tsx` | RouteDrawer構成、usePriceListでのデータ取得 |

**主要処理フロー**:
1. **10行目**: useParamsでURLからid取得
2. **12行目**: usePriceListで価格表データ取得
3. **14行目**: readyフラグでデータ取得完了判定
4. **20-27行目**: RouteDrawerでドロワー構成

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

編集フォームの実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | edit-price-list-form.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-edit/components/price-list-edit-form/edit-price-list-form.tsx` | フォーム構成、バリデーション、API呼び出し |

**主要処理フロー**:
- **26-31行目**: PriceListEditSchema - zodスキーマ定義
- **37-45行目**: useFormでフォーム初期化（現在値をdefaultValues）
- **47行目**: useUpdatePriceListでミューテーション
- **49-64行目**: handleSubmit - バリデーションとAPI呼び出し
- **73-111行目**: RadioGroupでタイプ選択
- **128-160行目**: Selectでステータス選択

#### Step 3: API呼び出しを理解する

更新APIフックの実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | price-lists.tsx | `packages/admin/dashboard/src/hooks/api/price-lists.tsx` | useUpdatePriceListフック |

**主要処理フロー**:
- **88-111行目**: useUpdatePriceList - ミューテーション定義、キャッシュ無効化

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

```
PriceListEdit (price-list-edit.tsx)
    │
    ├─ usePriceList() - 価格表詳細取得
    │
    └─ RouteDrawer
           │
           ├─ RouteDrawer.Header
           │      └─ Heading ("Edit Price List")
           │
           └─ PriceListEditForm (edit-price-list-form.tsx)
                  │
                  ├─ useForm()
                  │      └─ zodResolver(PriceListEditSchema)
                  │
                  ├─ useUpdatePriceList()
                  │
                  ├─ KeyboundForm
                  │      │
                  │      ├─ RadioGroup.ChoiceBox (type)
                  │      │
                  │      ├─ Input (title)
                  │      │
                  │      ├─ Select (status)
                  │      │
                  │      └─ Textarea (description)
                  │
                  └─ RouteDrawer.Footer
                         ├─ Cancel Button
                         └─ Save Button
```

### データフロー図

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

URL param (id) ──────▶ usePriceList() ──────▶ price_list
                                                   │
                                                   ▼
                              ┌────────────────────────────────┐
                              │ useForm() defaultValues        │
                              │   type: price_list.type        │
                              │   title: price_list.title      │
                              │   status: price_list.status    │
                              │   description: price_list.desc │
                              └────────────────────────────────┘

フォーム入力 ──────▶ form.handleSubmit()
                        │
                        └─▶ zodResolver validation
                               │
                               └─▶ useUpdatePriceList()
                                      │
                                      └─▶ sdk.admin.priceList.update()
                                             │
                                             └─▶ 成功: toast.success() + handleSuccess()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| price-list-edit.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-edit/price-list-edit.tsx` | ソース | ページコンポーネント |
| edit-price-list-form.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-edit/components/price-list-edit-form/edit-price-list-form.tsx` | ソース | 編集フォーム |
| price-lists.tsx | `packages/admin/dashboard/src/hooks/api/price-lists.tsx` | ソース | API呼び出しフック |
| constants.ts | `packages/admin/dashboard/src/routes/price-lists/common/constants.ts` | ソース | PriceListStatus, PriceListType定数 |
