# 画面設計書 165-都道府県詳細画面

## 概要

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

### 本画面の処理概要

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

**業務上の目的・背景**：都道府県レベルでの税設定状況を確認し、デフォルト税率の編集や、特定の商品・配送オプションに対する税オーバーライドを設定することで、州・都道府県固有の税金計算に対応する。

**画面へのアクセス方法**：税リージョン詳細画面の都道府県セクションから特定の都道府県を選択することでアクセスする。

**主要な操作・処理内容**：
1. 都道府県の基本情報（名前、税率）の確認
2. デフォルト税率の確認・編集
3. 税オーバーライドの確認・追加・編集

**画面遷移**：
- 遷移元：税リージョン詳細画面
- 遷移先：
  - 税率作成画面（税率追加ボタン）
  - 税率編集画面（税率編集ボタン）
  - 税オーバーライド作成画面（オーバーライド追加ボタン）
  - 税オーバーライド編集画面（オーバーライド編集ボタン）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 56 | 税地域管理 | 主機能 | 都道府県詳細の表示 |
| 55 | 税率管理 | 補助機能 | 税率の管理 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | 親税リージョンID |
| province_id | string | 都道府県税リージョンID |

## 表示項目

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

## イベント仕様

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

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

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

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

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

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

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

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

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

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

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

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

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

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|--------------|--------------|---------|
| 警告バッジ | デフォルト税率なし | デフォルト税率が設定されていない場合 |

## 例外処理

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

## 備考

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

---

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

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

### 推奨読解順序

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

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

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

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

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

**主要処理フロー**:
1. **13行目**: useParamsでURLからprovince_idを取得
2. **19-24行目**: useTaxRegionで都道府県税リージョンデータを取得
3. **36-48行目**: SingleColumnPage内に各セクションをレンダリング

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

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

**主要処理フロー（tax-region-detail-section.tsx）**:
- **17行目**: デフォルト税率のフィルタリング（is_default === true）
- **37-38行目**: TaxRateLine に isSublevelTaxRate=true を渡す

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

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

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

```
TaxRegionDetail (tax-region-detail.tsx - province版)
    │
    ├─ useParams (React Router)
    │      └─ province_id取得
    │
    ├─ useTaxRegion (tax-regions.tsx)
    │      └─ sdk.admin.taxRegion.retrieve
    │
    ├─ TaxRegionProvinceDetailSection
    │      ├─ TaxRegionCard (ヘッダー表示)
    │      └─ TaxRateLine (デフォルト税率表示, isSublevelTaxRate=true)
    │
    └─ TaxRegionProvinceOverrideSection
           └─ TaxOverrideTable (オーバーライド一覧)
```

### データフロー図

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

URL パラメータ
  (id, province_id) ───▶ TaxRegionDetail ────────────────▶ 画面表示
                              │
                              ├─▶ useTaxRegion ──────────▶ 都道府県税リージョンデータ
                              │       │
                              │       └─▶ GET /admin/tax-regions/:province_id
                              │
                              └─▶ SingleColumnPage
                                      │
                                      ├─▶ TaxRegionProvinceDetailSection
                                      └─▶ TaxRegionProvinceOverrideSection
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| tax-region-detail.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-province-detail/tax-region-detail.tsx` | ソース | メインコンポーネント |
| loader.ts | `packages/admin/dashboard/src/routes/tax-regions/tax-region-province-detail/loader.ts` | ソース | データローダー |
| tax-region-detail-section.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-province-detail/components/tax-region-province-detail-section/tax-region-detail-section.tsx` | ソース | 詳細セクション |
| tax-region-province-override-section.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-province-detail/components/tax-region-province-override-section/tax-region-province-override-section.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` | ソース | 税率表示行 |
