# 画面設計書 164-都道府県作成画面

## 概要

本ドキュメントは、Medusa Admin Dashboardの都道府県作成画面の設計仕様を定義したものである。

### 本画面の処理概要

都道府県作成画面は、既存の税リージョン（国レベル）に対して、都道府県・州レベルのサブリージョン（サブレベル税リージョン）を作成するためのモーダル形式の画面である。

**業務上の目的・背景**：米国やカナダのように、国だけでなく州・都道府県ごとに異なる税率が適用される国では、サブレベルの税リージョンを作成して個別の税設定を行う必要がある。この画面では、親となる国の税リージョンに対して、子となる都道府県レベルの税リージョンを追加する。

**画面へのアクセス方法**：税リージョン詳細画面の都道府県セクションから「都道府県を追加」ボタンをクリックすることでモーダルが表示される。

**主要な操作・処理内容**：
1. 都道府県・州の選択（必須）
2. デフォルト税率名の入力（任意）
3. デフォルト税率の設定（任意）
4. 税コードの入力（必須 - 税率名を入力した場合）
5. 税率の結合可能フラグ設定（任意）
6. 保存ボタンで都道府県税リージョンを登録

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 56 | 税地域管理 | 主機能 | 都道府県の税設定作成 |

## 画面種別

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

## URL/ルーティング

`/settings/tax-regions/:id/provinces/create`

## 入出力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| province_code | string | 必須 | 都道府県コード |
| name | string | 任意 | デフォルト税率の名前 |
| rate | number | 任意 | デフォルト税率（%） |
| code | string | 条件付き必須 | 税コード（税率名を入力した場合は必須） |
| is_combinable | boolean | 任意 | 税率の結合可能フラグ |

## 表示項目

| セクション | 項目 | 説明 |
|-----------|------|------|
| ヘッダー | 画面タイトル | 「{type}を作成」（type: 州/都道府県/サブレベル） |
| 基本情報 | 都道府県選択 | 国に応じたドロップダウンまたはテキスト入力 |
| デフォルト税率 | 名前 | テキスト入力 |
| デフォルト税率 | 税率 | パーセンテージ入力（小数点以下4桁まで） |
| デフォルト税率 | 税コード | テキスト入力 |
| オプション | 結合可能 | スイッチ（is_combinable） |
| フッター | キャンセルボタン | モーダルを閉じる |
| フッター | 保存ボタン | 都道府県を作成 |

## イベント仕様

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

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

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

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

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

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

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

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

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

#### tax_region

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成UUID | |
| INSERT | country_code | 親の国コード | 親税リージョンから取得 |
| INSERT | province_code | フォーム入力値 | 都道府県コード |
| INSERT | parent_id | 親税リージョンのID | URLパラメータから取得 |
| 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 | デフォルト税率として作成 |
| INSERT | is_combinable | フォーム入力値 | 結合可能フラグ |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|--------------|--------------|---------|
| 成功 | 税リージョンが作成されました | 作成成功時 |
| エラー | 都道府県を選択/入力してください | 都道府県未入力時 |
| エラー | 税コードを入力してください | 税率名入力時に税コード未入力 |
| エラー | {エラーメッセージ} | API呼び出し失敗時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| 必須項目未入力 | バリデーションエラーを表示 |
| 重複する都道府県コード | APIからエラーレスポンスを受け取り、エラートーストを表示 |
| 親税リージョンが存在しない | エラーをスロー、エラー画面へ |
| ネットワークエラー | エラートーストを表示、フォーム入力状態は保持 |

## 備考

- 国によって都道府県の呼び方が異なる（州、都道府県、サブレベルなど）
- 米国・カナダなど、都道府県リストが定義されている国ではドロップダウン選択
- 定義されていない国では手入力（例：KR-26 形式）
- is_combinable は、サブレベル税率と親レベル税率を合算して適用するかどうかを制御

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: province_codeが必須、その他のデフォルト税率関連はオプションであることを確認。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tax-region-province-create.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-province-create/tax-region-province-create.tsx` | 親税リージョンの取得とモーダル表示 |

**主要処理フロー**:
1. **7行目**: useParamsでURLからidを取得
2. **9行目**: useTaxRegionで親の税リージョンデータを取得
3. **17-21行目**: RouteFocusModal内にフォームをレンダリング

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

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

**主要処理フロー**:
- **44-55行目**: useFormでフォーム状態を初期化
- **57行目**: useCreateTaxRegionフックでAPIミューテーション取得
- **59-89行目**: handleSubmitでフォーム送信処理
- **91-96行目**: 国に応じた都道府県タイプ（州/都道府県/サブレベル）を取得
- **130-143行目**: ProvinceSelect または Input で都道府県を入力

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

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

**主要処理フロー**:
- **60-75行目**: useCreateTaxRegionの実装
- parent_id を含めることでサブレベル税リージョンとして作成される

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

```
TaxProvinceCreate (tax-region-province-create.tsx)
    │
    ├─ useParams (React Router)
    │      └─ id取得
    │
    ├─ useTaxRegion (tax-regions.tsx)
    │      └─ sdk.admin.taxRegion.retrieve (親税リージョン取得)
    │
    └─ TaxRegionProvinceCreateForm (tax-region-province-create-form.tsx)
           │
           ├─ getCountryProvinceObjectByIso2
           │      └─ 国に応じた都道府県情報取得
           │
           ├─ useForm (react-hook-form)
           │      └─ zodResolver (バリデーション)
           │
           └─ useCreateTaxRegion (tax-regions.tsx)
                  └─ sdk.admin.taxRegion.create (API呼び出し)
```

### データフロー図

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

URLパラメータ (id) ───────▶ TaxProvinceCreate
                                │
親税リージョン ◀───────────── useTaxRegion
                                │
都道府県コード ──────────┐    │
                        │    ▼
税率名（任意）─────────┤  TaxRegionProvinceCreateForm ───▶ 都道府県詳細画面
                        │       │
税率（任意）───────────┤       └─▶ useCreateTaxRegion
                        │               │
税コード ──────────────┤               └─▶ POST /admin/tax-regions
                        │                       (parent_id指定)
結合可能フラグ ─────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| tax-region-province-create.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-province-create/tax-region-province-create.tsx` | ソース | エントリーポイント |
| tax-region-province-create-form.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-province-create/components/tax-region-province-create-form/tax-region-province-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-province-create/index.ts` | ソース | エクスポート定義 |
| ProvinceSelect | `packages/admin/dashboard/src/components/inputs/province-select` | ソース | 都道府県選択コンポーネント |
| PercentageInput | `packages/admin/dashboard/src/components/inputs/percentage-input` | ソース | パーセント入力コンポーネント |
| SwitchBox | `packages/admin/dashboard/src/components/common/switch-box` | ソース | スイッチボックスコンポーネント |
| country-states.ts | `packages/admin/dashboard/src/lib/data/country-states` | ソース | 国別都道府県データ |
