# 画面設計書 161-税リージョン作成画面

## 概要

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

### 本画面の処理概要

税リージョン作成画面は、新規税リージョン（課税対象地域）をシステムに登録するための画面である。

**業務上の目的・背景**：ECサイトでは、販売先の国や地域によって異なる税率を適用する必要がある。この画面では、国を指定して税リージョンを作成し、その地域に適用するデフォルト税率を設定することで、正確な税金計算を実現する。

**画面へのアクセス方法**：設定 > 税リージョン一覧画面から「作成」ボタンをクリックすることでモーダルが表示される。

**主要な操作・処理内容**：
1. 対象国の選択（必須）
2. 税プロバイダーの選択（必須）
3. デフォルト税率名の入力（任意）
4. デフォルト税率の設定（任意）
5. 税コードの入力（任意）
6. 保存ボタンで税リージョンを登録

**画面遷移**：
- 遷移元：税リージョン一覧画面
- 遷移先：作成成功時は作成した税リージョンの詳細画面へ遷移

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 56 | 税地域管理 | 主機能 | 新規税リージョンの作成 |
| 55 | 税率管理 | 補助機能 | デフォルト税率の設定 |

## 画面種別

登録（モーダルフォーム）

## URL/ルーティング

`/settings/tax-regions/create`

## 入出力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| country_code | string | 必須 | 対象国のISO 2コード |
| provider_id | string | 必須 | 税プロバイダーID |
| name | string | 任意 | デフォルト税率の名前 |
| rate | number | 任意 | デフォルト税率（%） |
| code | string | 任意 | 税コード |

## 表示項目

| セクション | 項目 | 説明 |
|-----------|------|------|
| ヘッダー | 画面タイトル | 「税リージョンを作成」 |
| 基本情報 | 国選択 | ドロップダウンで国を選択 |
| 基本情報 | 税プロバイダー | コンボボックスで税プロバイダーを選択 |
| デフォルト税率 | 名前 | テキスト入力 |
| デフォルト税率 | 税率 | パーセンテージ入力（小数点以下4桁まで） |
| デフォルト税率 | 税コード | テキスト入力 |
| フッター | キャンセルボタン | モーダルを閉じる |
| フッター | 保存ボタン | 税リージョンを作成 |

## イベント仕様

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

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

1. フォームのバリデーションを実行
2. バリデーション成功時、`useCreateTaxRegion` フックを使用してAPI呼び出し
3. リクエストペイロードに国コード、税プロバイダーID、デフォルト税率情報を含める
4. 成功時：成功トーストを表示し、作成された税リージョンの詳細画面へ遷移
5. 失敗時：エラートーストを表示

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

モーダルを閉じて税リージョン一覧画面に戻る。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | tax_region | INSERT | 新規税リージョンの作成 |
| 保存ボタン押下 | tax_rate | INSERT | デフォルト税率の作成（名前が指定された場合のみ） |

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

#### tax_region

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成UUID | |
| INSERT | country_code | フォーム入力値 | ISO 2コード |
| INSERT | provider_id | フォーム入力値 | 税プロバイダーID |
| INSERT | parent_id | null | トップレベルの場合 |
| INSERT | created_at | 現在日時 | |
| INSERT | updated_at | 現在日時 | |

#### tax_rate

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成UUID | |
| INSERT | tax_region_id | 作成した税リージョンのID | |
| INSERT | name | フォーム入力値 | |
| INSERT | rate | フォーム入力値（パーセント値） | |
| INSERT | code | フォーム入力値 | |
| INSERT | is_default | true | デフォルト税率として作成 |

## メッセージ仕様

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

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| 必須項目未入力 | バリデーションエラーを表示し、該当フィールドをハイライト |
| 重複する国コード | APIからエラーレスポンスを受け取り、エラートーストを表示 |
| ネットワークエラー | エラートーストを表示、フォーム入力状態は保持 |
| セッション切れ | ログイン画面へリダイレクト |

## 備考

- デフォルト税率セクションは任意入力項目であり、名前を入力した場合のみ税率が作成される
- 税率は小数点以下4桁まで指定可能
- 税プロバイダーはシステムに登録されているプロバイダーから選択

---

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

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

### 推奨読解順序

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

まず、税リージョン作成に関わるデータ構造を理解することが重要である。

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

**読解のコツ**: Zodスキーマで定義されたバリデーションルールを確認し、各フィールドの必須・任意の区別を理解する。

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

処理の起点となるファイルを特定する。

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

**主要処理フロー**:
1. **4-9行目**: TaxRegionCreateコンポーネントがRouteFocusModal内にTaxRegionCreateFormをレンダリング

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

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

**主要処理フロー**:
- **60-68行目**: useComboboxDataで税プロバイダー一覧を取得
- **70-81行目**: useFormでフォーム状態を初期化
- **83行目**: useCreateTaxRegionフックでAPIミューテーション取得
- **85-114行目**: handleSubmitでフォーム送信処理

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

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

**主要処理フロー**:
- **60-75行目**: useCreateTaxRegionの実装、sdk.admin.taxRegion.createを呼び出し

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

```
TaxRegionCreate (tax-region-create.tsx)
    │
    └─ TaxRegionCreateForm (tax-region-create-form.tsx)
           │
           ├─ useComboboxData (税プロバイダー一覧取得)
           │      └─ sdk.admin.taxProvider.list
           │
           ├─ useForm (react-hook-form)
           │      └─ zodResolver (バリデーション)
           │
           └─ useCreateTaxRegion (tax-regions.tsx)
                  └─ sdk.admin.taxRegion.create (API呼び出し)
```

### データフロー図

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

国コード選択 ────────────┐
                        │
税プロバイダー選択 ─────┤
                        ├─▶ TaxRegionCreateForm ───▶ 税リージョン詳細画面
税率名（任意）─────────┤       │
                        │       ├─▶ useCreateTaxRegion
税率（任意）───────────┤       │       │
                        │       │       └─▶ POST /admin/tax-regions
税コード（任意）────────┘       │
                                └─▶ queryClient.invalidateQueries
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| tax-region-create.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-create/tax-region-create.tsx` | ソース | エントリーポイント |
| tax-region-create-form.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-create/components/tax-region-create-form/tax-region-create-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-create/index.ts` | ソース | エクスポート定義 |
| RouteFocusModal | `packages/admin/dashboard/src/components/modals` | ソース | モーダルコンポーネント |
| CountrySelect | `packages/admin/dashboard/src/components/inputs/country-select` | ソース | 国選択コンポーネント |
| PercentageInput | `packages/admin/dashboard/src/components/inputs/percentage-input` | ソース | パーセント入力コンポーネント |
| Combobox | `packages/admin/dashboard/src/components/inputs/combobox` | ソース | コンボボックスコンポーネント |
