# 画面設計書 162-税リージョン詳細画面

## 概要

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

### 本画面の処理概要

税リージョン詳細画面は、特定の税リージョン（課税対象地域）の詳細情報を表示し、関連する都道府県、税率、税オーバーライドの管理を行うための画面である。

**業務上の目的・背景**：税リージョンの設定状況を確認し、必要に応じて都道府県レベルの税設定を追加したり、特定の商品や配送オプションに対する税オーバーライドを設定することで、複雑な税制度に対応した税金計算を実現する。

**画面へのアクセス方法**：設定 > 税リージョン一覧画面から特定の税リージョンを選択することでアクセスする。

**主要な操作・処理内容**：
1. 税リージョンの基本情報（国、税プロバイダー）の確認
2. デフォルト税率の確認・編集
3. 都道府県レベルの税設定の確認・追加
4. 税オーバーライドの確認・追加・編集
5. 税プロバイダーの確認・変更

**画面遷移**：
- 遷移元：税リージョン一覧画面
- 遷移先：
  - 税リージョン編集画面（編集ボタン）
  - 都道府県作成画面（都道府県追加ボタン）
  - 都道府県詳細画面（都道府県リスト選択）
  - 税率作成画面（税率追加ボタン）
  - 税率編集画面（税率編集ボタン）
  - 税オーバーライド作成画面（オーバーライド追加ボタン）
  - 税オーバーライド編集画面（オーバーライド編集ボタン）

**権限による表示制御**：管理者権限を持つユーザーのみがアクセス可能。編集・削除アクションは権限に応じて表示/非表示を制御。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 56 | 税地域管理 | 主機能 | 税リージョン詳細の表示 |
| 55 | 税率管理 | 補助機能 | 税率一覧の表示 |

## 画面種別

詳細（シングルカラムページ）

## URL/ルーティング

`/settings/tax-regions/:id`

## 入出力項目

本画面は主に表示画面であり、入力項目は各編集モーダルで処理される。

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | URLパラメータから取得する税リージョンID |

## 表示項目

| セクション | 項目 | 説明 |
|-----------|------|------|
| 詳細セクション | 国名/国旗 | 税リージョンの対象国 |
| 詳細セクション | デフォルト税率名 | デフォルト税率の名前 |
| 詳細セクション | デフォルト税率 | 税率（%） |
| 詳細セクション | デフォルト税率なしバッジ | デフォルト税率が未設定の場合にオレンジバッジを表示 |
| 都道府県セクション | 都道府県一覧 | サブレベルの税リージョン一覧 |
| オーバーライドセクション | 税オーバーライド一覧 | 商品/配送オプションごとの税オーバーライド一覧 |
| プロバイダーセクション | 税プロバイダー | 使用している税プロバイダー名 |
| JSON表示 | RAWデータ | 税リージョンのJSONデータ |

## イベント仕様

### 1-編集ボタン押下（ヘッダー）

税リージョン編集画面（ドロワー形式）を開く。税プロバイダーの変更が可能。

### 2-都道府県追加ボタン押下

都道府県作成画面（モーダル形式）を開く。

### 3-都道府県行クリック

選択した都道府県の詳細画面へ遷移する。

### 4-税率追加ボタン押下

税率作成画面（モーダル形式）を開く。

### 5-税率編集ボタン押下

税率編集画面（ドロワー形式）を開く。

### 6-税オーバーライド追加ボタン押下

税オーバーライド作成画面（モーダル形式）を開く。

### 7-税オーバーライド編集ボタン押下

税オーバーライド編集画面（ドロワー形式）を開く。

### 8-サブレベル表示トグル

都道府県セクションで「サブレベルリージョンを表示」をトグルすると、非表示のサブレベル税リージョンが表示される。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | tax_region | SELECT | 税リージョン情報の取得 |
| 画面表示 | tax_rate | SELECT | 関連する税率の取得 |

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

本画面は参照のみであり、データベースの更新は行わない（各編集画面で実施）。

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|--------------|--------------|---------|
| 警告バッジ | デフォルト税率なし | デフォルト税率が設定されていない場合 |
| アラート | サブレベルリージョンがあります | 都道府県レベルの税リージョンが存在する場合 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| 税リージョンが存在しない | エラーをスロー、エラーバウンダリーで処理 |
| データ読み込み中 | SingleColumnPageSkeletonを表示 |
| APIエラー | エラーをスロー、エラーバウンダリーで処理 |

## 備考

- 画面にはJSON表示機能があり、税リージョンの生データを確認可能
- ウィジェット拡張ポイント（tax.details.before, tax.details.after）が用意されている
- デフォルト税率が設定されていない場合、オレンジ色のバッジで警告を表示

---

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

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

### 推奨読解順序

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

税リージョンのデータ構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | loader.ts | `packages/admin/dashboard/src/routes/tax-regions/tax-region-detail/loader.ts` | 初期データ取得のクエリパラメータを確認 |

**読解のコツ**: loaderでどのようなデータを事前取得しているかを確認し、画面表示に必要なデータ構造を把握する。

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

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

**主要処理フロー**:
1. **17行目**: useParamsでURLからidを取得
2. **18行目**: showSublevelRegionsのstate管理
3. **24-29行目**: useTaxRegionで税リージョンデータを取得
4. **41-64行目**: SingleColumnPage内に各セクションをレンダリング

#### Step 3: 各セクションコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | tax-region-detail-section.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-detail/components/tax-region-detail-section/tax-region-detail-section.tsx` | ヘッダー部分とデフォルト税率表示 |
| 3-2 | tax-region-province-section.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-detail/components/tax-region-province-section/tax-region-province-section.tsx` | 都道府県セクション |
| 3-3 | tax-region-override-section.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-detail/components/tax-region-override-section/tax-region-override-section.tsx` | 税オーバーライドセクション |
| 3-4 | tax-region-provider-section.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-detail/tax-region-provider-section/tax-region-provider-section.tsx` | 税プロバイダーセクション |

**主要処理フロー（tax-region-detail-section.tsx）**:
- **17行目**: デフォルト税率のフィルタリング（is_default === true）
- **18行目**: デフォルト税率がない場合のバッジ表示判定
- **28-33行目**: デフォルト税率なしバッジの表示

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

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

**主要処理フロー**:
- **17-37行目**: useTaxRegionの実装、sdk.admin.taxRegion.retrieveを呼び出し

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

```
TaxRegionDetail (tax-region-detail.tsx)
    │
    ├─ useParams (React Router)
    │      └─ id取得
    │
    ├─ useTaxRegion (tax-regions.tsx)
    │      └─ sdk.admin.taxRegion.retrieve
    │
    ├─ TaxRegionSublevelAlert
    │      └─ サブレベル存在時のアラート表示
    │
    ├─ TaxRegionDetailSection
    │      ├─ TaxRegionCard (ヘッダー表示)
    │      └─ TaxRateLine (デフォルト税率表示)
    │
    ├─ TaxRegionProvinceSection
    │      └─ TaxRegionTable (都道府県一覧)
    │
    ├─ TaxRegionOverrideSection
    │      └─ TaxOverrideTable (オーバーライド一覧)
    │
    └─ TaxRegionProviderSection
           └─ 税プロバイダー表示
```

### データフロー図

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

URL パラメータ (id) ───▶ TaxRegionDetail ────────────────▶ 画面表示
                              │
                              ├─▶ useTaxRegion ──────────▶ 税リージョンデータ
                              │       │
                              │       └─▶ GET /admin/tax-regions/:id
                              │
                              └─▶ SingleColumnPage
                                      │
                                      ├─▶ TaxRegionDetailSection
                                      ├─▶ TaxRegionProvinceSection
                                      ├─▶ TaxRegionOverrideSection
                                      └─▶ TaxRegionProviderSection
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| tax-region-detail.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-detail/tax-region-detail.tsx` | ソース | メインコンポーネント |
| loader.ts | `packages/admin/dashboard/src/routes/tax-regions/tax-region-detail/loader.ts` | ソース | データローダー |
| breadcrumb.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-detail/breadcrumb.tsx` | ソース | パンくずリスト |
| tax-region-detail-section.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-detail/components/tax-region-detail-section/tax-region-detail-section.tsx` | ソース | 詳細セクション |
| tax-region-province-section.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-detail/components/tax-region-province-section/tax-region-province-section.tsx` | ソース | 都道府県セクション |
| tax-region-override-section.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-detail/components/tax-region-override-section/tax-region-override-section.tsx` | ソース | オーバーライドセクション |
| tax-region-provider-section.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-detail/tax-region-provider-section/tax-region-provider-section.tsx` | ソース | プロバイダーセクション |
| tax-region-sublevel-alert.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-detail/components/tax-region-sublevel-alert/tax-region-sublevel-alert.tsx` | ソース | サブレベルアラート |
| tax-regions.tsx | `packages/admin/dashboard/src/hooks/api/tax-regions.tsx` | ソース | API連携フック |
| tax-region-card.tsx | `packages/admin/dashboard/src/routes/tax-regions/common/components/tax-region-card/tax-region-card.tsx` | ソース | 税リージョンカード |
| tax-rate-line.tsx | `packages/admin/dashboard/src/routes/tax-regions/common/components/tax-rate-line/tax-rate-line.tsx` | ソース | 税率表示行 |
