# 画面設計書 168-税オーバーライド作成画面

## 概要

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

### 本画面の処理概要

税オーバーライド作成画面は、特定の商品、商品タイプ、または配送オプションに対して、通常のデフォルト税率とは異なる税率を適用するためのオーバーライド設定を作成するモーダル形式の画面である。

**業務上の目的・背景**：一部の商品（食料品や医薬品など）や特定の配送オプションには、標準税率とは異なる軽減税率や非課税扱いが適用される場合がある。この画面では、そのような例外的な税設定（税オーバーライド）を作成し、対象となる商品や配送オプションを指定できる。

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

**主要な操作・処理内容**：
1. オーバーライド名の入力（必須）
2. 税率の設定（任意）
3. 税コードの入力（必須）
4. 結合可能フラグの設定
5. 適用対象（商品/商品タイプ/配送オプション）の選択
6. 保存ボタンで税オーバーライドを登録

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 55 | 税率管理 | 主機能 | 税オーバーライドの作成 |

## 画面種別

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

## URL/ルーティング

- 税リージョンレベル: `/settings/tax-regions/:id/overrides/create`
- 都道府県レベル: `/settings/tax-regions/:id/provinces/:province_id/overrides/create`

## 入出力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| name | string | 必須 | オーバーライド名 |
| rate | number | 任意 | 税率（%） |
| code | string | 必須 | 税コード |
| is_combinable | boolean | 任意 | 税率の結合可能フラグ |
| enabled_rules.product | boolean | - | 商品ルールの有効/無効 |
| enabled_rules.product_type | boolean | - | 商品タイプルールの有効/無効 |
| enabled_rules.shipping_option | boolean | - | 配送オプションルールの有効/無効 |
| product | array | 任意 | 対象商品一覧 |
| product_type | array | 任意 | 対象商品タイプ一覧 |
| shipping_option | array | 任意 | 対象配送オプション一覧 |

## 表示項目

| セクション | 項目 | 説明 |
|-----------|------|------|
| ヘッダー | 画面タイトル | 「税オーバーライドを作成」 |
| 基本情報 | 名前 | テキスト入力 |
| 基本情報 | 税率 | パーセンテージ入力（小数点以下4桁まで） |
| 基本情報 | 税コード | テキスト入力 |
| オプション | 結合可能 | スイッチ |
| 適用対象 | ターゲットルール | 商品/商品タイプ/配送オプションの選択カード |
| フッター | キャンセルボタン | モーダルを閉じる |
| フッター | 保存ボタン | 税オーバーライドを作成 |

## イベント仕様

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

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

1. フォームのバリデーションを実行
2. バリデーション成功時、`useCreateTaxRate` フックを使用してAPI呼び出し
3. リクエストペイロードに税リージョンID、税率情報、ルール情報、is_default=false を含める
4. 成功時：モーダルを閉じる
5. 失敗時：エラートーストを表示

### 2-ターゲット追加ボタン押下

新しいルールタイプを追加する。利用可能なルールタイプ（商品/商品タイプ/配送オプション）から選択。

### 3-ブラウズボタン押下

StackedFocusModalを開き、対象（商品/商品タイプ/配送オプション）を検索・選択する。

### 4-ターゲット削除ボタン押下

選択したルールタイプとその対象を削除する。

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

モーダルを閉じて元の画面に戻る。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | tax_rate | INSERT | 税オーバーライド（税率）の作成 |
| 保存ボタン押下 | tax_rate_rule | INSERT | 税率ルールの作成（複数） |

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

#### tax_rate

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成UUID | |
| INSERT | tax_region_id | URLパラメータから取得 | |
| INSERT | name | フォーム入力値 | |
| INSERT | rate | フォーム入力値（パーセント値） | |
| INSERT | code | フォーム入力値 | |
| INSERT | is_default | false | オーバーライドとして作成 |
| INSERT | is_combinable | フォーム入力値 | |
| INSERT | created_at | 現在日時 | |
| INSERT | updated_at | 現在日時 | |

#### tax_rate_rule

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成UUID | |
| INSERT | tax_rate_id | 作成した税率のID | |
| INSERT | reference | ルールタイプ（product/product_type/shipping_option） | |
| INSERT | reference_id | 対象エンティティのID | |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|--------------|--------------|---------|
| エラー | 名前を入力してください | 名前未入力時 |
| エラー | 税コードを入力してください | 税コード未入力時 |
| エラー | {エラーメッセージ} | API呼び出し失敗時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| 必須項目未入力 | バリデーションエラーを表示し、該当フィールドをハイライト |
| 税リージョンが存在しない | エラーをスロー |
| ネットワークエラー | エラートーストを表示、フォーム入力状態は保持 |

## 備考

- is_default は常にfalseが設定される（オーバーライドとして作成）
- 適用対象（ターゲット）は任意だが、指定しないとオーバーライドとしての意味がない
- 商品、商品タイプ、配送オプションの3種類のルールタイプがサポートされている
- 各ルールタイプは複数の対象を指定可能
- StackedFocusModalで対象の検索・選択UIを提供

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | tax-region-tax-override-create.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-tax-override-create/components/tax-region-override-create-form/tax-region-tax-override-create.tsx` | TaxRegionCreateTaxOverrideSchema（41-65行目）でフォームのデータ構造を確認 |
| 1-2 | constants.ts | `packages/admin/dashboard/src/routes/tax-regions/common/constants.ts` | TaxRateRuleReferenceType列挙型を確認 |

**読解のコツ**: enabled_rulesでルールの有効/無効を管理し、各ルールタイプに対応する配列で対象を保持する構造を理解する。

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

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

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

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

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

**主要処理フロー**:
- **82-106行目**: useFormでフォーム状態を初期化
- **108行目**: useCreateTaxRateフックでAPIミューテーション取得
- **110-175行目**: handleSubmitでフォーム送信処理
  - createTaxRulePayloadでルール情報を整形
  - is_default: false でオーバーライドとして作成
- **177-206行目**: useFieldArrayで各ルールタイプの対象配列を管理
- **273-301行目**: getFieldHandlerでルール対象の追加/削除ロジック

#### Step 4: ターゲット選択UIを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | target-form.tsx | `packages/admin/dashboard/src/routes/tax-regions/common/components/target-form/target-form.tsx` | ターゲット選択モーダルの実装 |
| 4-2 | target-item.tsx | `packages/admin/dashboard/src/routes/tax-regions/common/components/target-item/target-item.tsx` | 選択されたターゲットの表示 |

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

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

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

```
TaxRegionCreateTaxOverride (tax-region-tax-override-create.tsx)
    │
    ├─ useParams (React Router)
    │      └─ id, province_id取得
    │
    ├─ useTaxRegion (tax-regions.tsx)
    │      └─ sdk.admin.taxRegion.retrieve
    │
    └─ TaxRegionCreateTaxOverrideForm (tax-region-tax-override-create.tsx)
           │
           ├─ useForm (react-hook-form)
           │      └─ zodResolver (バリデーション)
           │
           ├─ useFieldArray (複数)
           │      ├─ products
           │      ├─ productTypes
           │      └─ shippingOptions
           │
           ├─ StackedFocusModal
           │      └─ TargetForm (商品/商品タイプ/配送オプション選択)
           │
           └─ useCreateTaxRate (tax-rates.tsx)
                  └─ sdk.admin.taxRate.create (API呼び出し)
                         └─ rules配列を含む
```

### データフロー図

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

URLパラメータ
  (id, province_id) ───▶ TaxRegionCreateTaxOverride
                                │
税リージョン ◀───────────── useTaxRegion
                                │
名前（必須）─────────────┐    │
                        │    ▼
税率（任意）───────────┤  TaxRegionCreateTaxOverrideForm
                        │       │
税コード（必須）────────┤       ├─▶ createTaxRulePayload
                        │       │       └─▶ ルール配列を生成
結合可能フラグ ─────────┤       │
                        │       └─▶ useCreateTaxRate
ターゲットルール ───────┤               │
  - 商品               │               └─▶ POST /admin/tax-rates
  - 商品タイプ         │                       (is_default: false)
  - 配送オプション ────┘                       (rules: [...])
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| tax-region-tax-override-create.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-tax-override-create/tax-region-tax-override-create.tsx` | ソース | エントリーポイント |
| tax-region-tax-override-create.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-tax-override-create/components/tax-region-override-create-form/tax-region-tax-override-create.tsx` | ソース | フォームコンポーネント |
| constants.ts | `packages/admin/dashboard/src/routes/tax-regions/common/constants.ts` | ソース | ルールタイプ定義 |
| schemas.ts | `packages/admin/dashboard/src/routes/tax-regions/common/schemas.ts` | ソース | スキーマ定義 |
| utils.ts | `packages/admin/dashboard/src/routes/tax-regions/common/utils.ts` | ソース | ユーティリティ関数 |
| target-form.tsx | `packages/admin/dashboard/src/routes/tax-regions/common/components/target-form/target-form.tsx` | ソース | ターゲット選択フォーム |
| target-item.tsx | `packages/admin/dashboard/src/routes/tax-regions/common/components/target-item/target-item.tsx` | ソース | ターゲットアイテム表示 |
| tax-rates.tsx | `packages/admin/dashboard/src/hooks/api/tax-rates.tsx` | ソース | API連携フック |
