# 画面設計書 116-リージョン編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboardにおけるリージョン編集画面に関する設計書です。この画面により、既存のリージョン情報を編集することができます。

### 本画面の処理概要

**業務上の目的・背景**：リージョン設定の変更が必要な場合（通貨変更、税金設定変更、決済プロバイダーの追加・削除など）に、既存のリージョン情報を更新するために使用します。

**画面へのアクセス方法**：リージョン詳細画面（/settings/regions/:id）の編集ボタンをクリック、またはURL直接アクセス（/settings/regions/:id/edit）。

**主要な操作・処理内容**：
1. リージョン名の編集
2. 通貨の変更
3. 自動税金計算の有効/無効切替
4. 税込価格の有効/無効切替
5. 決済プロバイダーの変更
6. 変更内容の保存

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

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

## 関連機能

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

## 画面種別

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

## URL/ルーティング

`/settings/regions/:id/edit`

## 入出力項目

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|------|------|------|
| リージョン名 | name | string | 必須 | リージョンの名称 |
| 通貨 | currency_code | string | - | 通貨コード |
| 自動税金計算 | automatic_taxes | boolean | - | 自動税金計算の有効/無効 |
| 税込価格 | is_tax_inclusive | boolean | - | 税込価格の有効/無効 |
| 決済プロバイダー | payment_providers | string[] | - | 決済プロバイダーID配列 |

## 表示項目

### 基本情報セクション

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|------|------|
| リージョン名入力 | name | Input | テキスト入力フィールド |
| 通貨選択 | currency_code | Select | ストアサポート通貨のドロップダウン |

### 税金設定セクション

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|------|------|
| 自動税金計算 | automatic_taxes | Switch | トグルスイッチ |
| 税込価格 | is_tax_inclusive | Switch | トグルスイッチ |

### 決済プロバイダーセクション

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|------|------|
| 決済プロバイダー | payment_providers | Combobox | 有効なプロバイダーの複数選択 |

## イベント仕様

### 1-データ初期化

**トリガー**：画面読み込み時

**処理内容**：
1. URLパラメータからリージョンIDを取得
2. useRegionでリージョン情報を取得（payment_providers, countries, automatic_taxes展開）
3. useStoreでストア情報を取得（サポート通貨用）
4. usePricePreferencesで税込価格設定を取得
5. フォームに現在の値を設定

### 2-保存

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

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

### 3-キャンセル

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

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

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | region | UPDATE | リージョン情報の更新 |
| 保存ボタン押下 | price_preference | UPDATE | 税込価格設定の更新 |

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

#### region

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | name | フォーム入力値 | リージョン名 |
| UPDATE | currency_code | フォーム選択値（小文字変換） | 通貨コード |
| UPDATE | automatic_taxes | フォーム選択値 | 自動税金計算フラグ |
| UPDATE | updated_at | 現在日時 | 自動更新 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|---------|
| regions.toast.edit | 成功 | リージョンが更新されました | 更新成功時 |
| - | エラー | {エラーメッセージ} | API呼び出し失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| リージョン情報取得エラー | エラーをスローしてエラーバウンダリで処理 |
| ストア情報取得エラー | エラーをスローしてエラーバウンダリで処理 |
| price_preferences取得エラー | エラーをスローしてエラーバウンダリで処理 |
| 更新API失敗 | エラートーストを表示、フォームは維持 |

## 備考

- 国の編集はこの画面では行わない（詳細画面の国一覧セクションで管理）
- 通貨コードは大文字で表示するが、API送信時は小文字に変換
- 決済プロバイダーはComboboxでインクリメンタル検索・ページネーション対応
- フォームはKeybound対応（キーボードショートカットでの操作可能）

---

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

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

### 推奨読解順序

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

リージョン編集時のデータ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | edit-region-form.tsx | `packages/admin/dashboard/src/routes/regions/region-edit/components/edit-region-form/edit-region-form.tsx` | EditRegionSchemaの定義（27-33行目） |

**読解のコツ**: 編集時のバリデーションはnameのみ必須です。payment_providersは任意となっています。

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

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

**主要処理フロー**:
1. **16-24行目**: useRegionでリージョン情報を取得（展開フィールド指定）
2. **26-31行目**: useStoreでストア情報を取得
3. **33-44行目**: usePricePreferencesで税込設定を取得
4. **64-76行目**: RouteDrawerでEditRegionFormをラップ

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | edit-region-form.tsx | `packages/admin/dashboard/src/routes/regions/region-edit/components/edit-region-form/edit-region-form.tsx` | メインフォームロジック |

**主要処理フロー**:
- **27-33行目**: Zodバリデーションスキーマ
- **40-45行目**: pricePreferencesから税込設定を取得
- **47-55行目**: useFormでフォーム初期化（既存値を設定）
- **57-66行目**: useComboboxDataで決済プロバイダー取得
- **68-69行目**: useUpdateRegionでリージョン更新フック取得
- **71-90行目**: handleSubmit - 更新API呼び出し

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

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

**主要処理フロー**:
- **86-111行目**: useUpdateRegion - リージョン更新、成功時にキャッシュ無効化

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

```
RegionEdit (region-edit.tsx)
    │
    ├─ useRegion()
    │      └─ sdk.admin.region.retrieve()
    │
    ├─ useStore()
    │      └─ sdk.admin.store.list()
    │
    ├─ usePricePreferences()
    │      └─ price_preferences API
    │
    └─ EditRegionForm
           │
           ├─ useForm()
           │      └─ フォーム状態管理
           │
           ├─ useComboboxData()
           │      └─ sdk.admin.payment.listPaymentProviders()
           │
           └─ useUpdateRegion()
                  └─ sdk.admin.region.update()
```

### データフロー図

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

既存region ──────────▶ useForm初期化 ────────────────▶ フォーム表示
既存pricePreferences ─▶ is_tax_inclusive初期値 ─────▶
                           │
name編集 ───────────────▶ フォーム状態 ─────────────▶
currency選択 ──────────▶ フォーム状態 ─────────────▶  保存ボタン
automatic_taxes ───────▶ フォーム状態 ─────────────▶     │
is_tax_inclusive ──────▶ フォーム状態 ─────────────▶     │
payment_providers ─────▶ フォーム状態 ─────────────▶     │
                                                        ▼
                                              useUpdateRegion()
                                                        │
                                              (currency小文字変換)
                                                        │
                                                        ▼
                                              [Region APIサーバー]
                                                        │
                                                        ▼
                                              ドロワーを閉じる
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| region-edit.tsx | `packages/admin/dashboard/src/routes/regions/region-edit/region-edit.tsx` | ソース | エントリーポイント |
| edit-region-form.tsx | `packages/admin/dashboard/src/routes/regions/region-edit/components/edit-region-form/edit-region-form.tsx` | ソース | メインフォームコンポーネント |
| regions.tsx | `packages/admin/dashboard/src/hooks/api/regions.tsx` | ソース | リージョンAPIフック |
| store.tsx | `packages/admin/dashboard/src/hooks/api/store.tsx` | ソース | ストアAPIフック |
| price-preferences.tsx | `packages/admin/dashboard/src/hooks/api/price-preferences.tsx` | ソース | 価格設定APIフック |
| currencies.ts | `packages/admin/dashboard/src/lib/data/currencies.ts` | データ | 通貨データ |
| use-combobox-data.tsx | `packages/admin/dashboard/src/hooks/use-combobox-data.tsx` | ソース | コンボボックスデータフック |
| route-drawer.tsx | `packages/admin/dashboard/src/components/modals/route-drawer/` | ソース | ドロワーコンポーネント |
