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

## 概要

本ドキュメントは、Medusa Admin Dashboardの税リージョン編集画面の設計仕様を定義したものである。

### 本画面の処理概要

税リージョン編集画面は、既存の税リージョンの設定を変更するためのドロワー形式の画面である。主に税プロバイダーの変更を行う。

**業務上の目的・背景**：税リージョンに紐づく税プロバイダーを変更することで、税金計算のロジックを切り替えることができる。例えば、外部の税計算サービスに切り替える際などに使用する。

**画面へのアクセス方法**：税リージョン詳細画面から編集アクション（編集ボタンまたはドロップダウンメニュー）を選択することでドロワーが開く。

**主要な操作・処理内容**：
1. 現在の税プロバイダーの確認
2. 新しい税プロバイダーの選択
3. 保存ボタンで変更を適用

**画面遷移**：
- 遷移元：税リージョン詳細画面
- 遷移先：保存成功時は税リージョン詳細画面に戻る

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

## 関連機能

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

## 画面種別

編集（ドロワー形式）

## URL/ルーティング

`/settings/tax-regions/:id/edit`

## 入出力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| provider_id | string | 必須 | 税プロバイダーID |

## 表示項目

| セクション | 項目 | 説明 |
|-----------|------|------|
| ヘッダー | 画面タイトル | 「税リージョンを編集」 |
| フォーム | 税プロバイダー | コンボボックスで税プロバイダーを選択 |
| フッター | キャンセルボタン | ドロワーを閉じる |
| フッター | 保存ボタン | 変更を保存 |

## イベント仕様

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

保存ボタンを押下すると、以下の処理が実行される：

1. フォームのバリデーションを実行（税プロバイダーが選択されているか）
2. バリデーション成功時、`useUpdateTaxRegion` フックを使用してAPI呼び出し
3. リクエストペイロードに新しい税プロバイダーIDを含める
4. 成功時：成功トーストを表示し、ドロワーを閉じる
5. 失敗時：エラートーストを表示

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

ドロワーを閉じて税リージョン詳細画面に戻る。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | tax_region | UPDATE | 税プロバイダーIDの更新 |

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

#### tax_region

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | provider_id | フォーム入力値 | 新しい税プロバイダーID |
| UPDATE | updated_at | 現在日時 | 自動更新 |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|--------------|--------------|---------|
| 成功 | 税リージョンが更新されました | 更新成功時 |
| エラー | 税プロバイダーを選択してください | 未選択時 |
| エラー | {エラーメッセージ} | API呼び出し失敗時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| 必須項目未入力 | バリデーションエラーを表示 |
| 税リージョンが存在しない | エラーをスローしてエラー画面へ |
| ネットワークエラー | エラートーストを表示 |
| セッション切れ | ログイン画面へリダイレクト |

## 備考

- 税プロバイダーの変更は即座に反映される
- 国コードは変更不可（税リージョン作成時に決定）
- デフォルト税率の編集は別画面で行う

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | tax-region-edit-form.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-edit/components/tax-region-edit/tax-region-edit-form.tsx` | TaxRegionEditSchema（21-23行目）でフォームのデータ構造を確認 |

**読解のコツ**: シンプルなスキーマで、provider_idのみが必須項目であることを確認。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tax-region-edit.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-edit/tax-region-edit.tsx` | RouteDrawerでドロワー表示を行うエントリーポイント |

**主要処理フロー**:
1. **10行目**: useParamsでURLからidを取得
2. **12行目**: useTaxRegionで現在の税リージョンデータを取得
3. **14行目**: readyフラグでデータ取得完了を判定
4. **20-31行目**: RouteDrawer内にヘッダーとフォームをレンダリング

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | tax-region-edit-form.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-edit/components/tax-region-edit/tax-region-edit-form.tsx` | フォームの実装とAPI呼び出しロジック |

**主要処理フロー**:
- **29-37行目**: useComboboxDataで税プロバイダー一覧を取得
- **39-44行目**: useFormでフォーム状態を初期化（現在値をデフォルト値として設定）
- **46行目**: useUpdateTaxRegionフックでAPIミューテーション取得
- **48-63行目**: handleSubmitでフォーム送信処理

#### Step 4: API連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | tax-regions.tsx | `packages/admin/dashboard/src/hooks/api/tax-regions.tsx` | useUpdateTaxRegionフックの実装 |

**主要処理フロー**:
- **77-99行目**: useUpdateTaxRegionの実装、sdk.admin.taxRegion.updateを呼び出し
- **90-93行目**: 成功時にdetailとlistsのクエリを無効化

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

```
TaxRegionEdit (tax-region-edit.tsx)
    │
    ├─ useParams (React Router)
    │      └─ id取得
    │
    ├─ useTaxRegion (tax-regions.tsx)
    │      └─ sdk.admin.taxRegion.retrieve
    │
    └─ TaxRegionEditForm (tax-region-edit-form.tsx)
           │
           ├─ useComboboxData (税プロバイダー一覧取得)
           │      └─ sdk.admin.taxProvider.list
           │
           ├─ useForm (react-hook-form)
           │      └─ zodResolver (バリデーション)
           │
           └─ useUpdateTaxRegion (tax-regions.tsx)
                  └─ sdk.admin.taxRegion.update (API呼び出し)
```

### データフロー図

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

URLパラメータ (id) ───────▶ TaxRegionEdit
                                │
現在の税リージョン ◀─────── useTaxRegion
                                │
税プロバイダー選択 ───────┐    │
                        │    ▼
                        └─▶ TaxRegionEditForm ───▶ 税リージョン詳細画面
                                │
                                └─▶ useUpdateTaxRegion
                                        │
                                        └─▶ PATCH /admin/tax-regions/:id
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| tax-region-edit.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-edit/tax-region-edit.tsx` | ソース | エントリーポイント |
| tax-region-edit-form.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-edit/components/tax-region-edit/tax-region-edit-form.tsx` | ソース | フォームコンポーネント |
| tax-regions.tsx | `packages/admin/dashboard/src/hooks/api/tax-regions.tsx` | ソース | API連携フック |
| index.ts | `packages/admin/dashboard/src/routes/tax-regions/tax-region-edit/index.ts` | ソース | エクスポート定義 |
| RouteDrawer | `packages/admin/dashboard/src/components/modals` | ソース | ドロワーコンポーネント |
| Combobox | `packages/admin/dashboard/src/components/inputs/combobox` | ソース | コンボボックスコンポーネント |
