# 画面設計書 160-税リージョン一覧画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における税リージョン一覧画面の設計仕様を定義するものである。

### 本画面の処理概要

税リージョン一覧画面は、システムに登録されている税リージョン（国・地域ごとの税設定）の一覧を表示する画面である。各税リージョンはカード形式で表示され、国旗アイコンとともに国名が表示される。

**業務上の目的・背景**：ECサイトでは国・地域ごとに異なる税率が適用される。税リージョン機能により、各地域に適切な税率を設定し、正確な税額計算を実現する。管理者はこの画面から税リージョンの作成、編集、削除、および詳細確認が可能。

**画面へのアクセス方法**：
1. 設定メニュー > 税金をクリック
2. 直接URL `/settings/tax-regions` にアクセス

**主要な操作・処理内容**：
1. 登録済み税リージョンの一覧を表示
2. ソート順の変更（作成日、更新日）
3. ページネーションによるページ切り替え
4. 「作成」ボタンから新規税リージョン作成画面に遷移
5. 税リージョンカードクリックで詳細画面に遷移
6. アクションメニューから編集・削除

**画面遷移**：
- 遷移元：設定画面、サイドナビゲーション
- 遷移先：税リージョン作成画面、税リージョン詳細画面、税リージョン編集画面

**権限による表示制御**：認証済みの管理ユーザーのみがアクセス可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 30 | 税設定管理 | 主機能 | 税リージョン一覧の表示 |

## 画面種別

一覧

## URL/ルーティング

- パス: `/settings/tax-regions`
- コンポーネント: `TaxRegionsList`
- レイアウト: `SingleColumnPage`

## 入出力項目

本画面は一覧表示画面のため、入力項目はなし。クエリパラメータとして以下を受け取る。

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| offset | number | No | ページネーションのオフセット |
| order | string | No | ソート順（updated_at, created_at） |

## 表示項目

### ヘッダーセクション

| 項目名 | 説明 | 備考 |
|--------|------|------|
| タイトル | 「税金」 | Heading コンポーネント |
| ヒントテキスト | 税リージョンに関する説明 | Text コンポーネント |
| 作成ボタン | 新規税リージョン作成 | `/settings/tax-regions/create` に遷移 |
| ソート | 作成日、更新日でソート | DataTableOrderBy コンポーネント |

### 税リージョンカード

| 項目名 | 説明 | 備考 |
|--------|------|------|
| 国旗アイコン | 国のフラグ画像 | ReactCountryFlag コンポーネント |
| 国名/地域名 | 税リージョンの名前 | 国コードから変換 |
| アクションメニュー | 編集・削除メニュー | ActionMenu コンポーネント |

### ページネーション

| 項目名 | 説明 | 備考 |
|--------|------|------|
| ページ情報 | 現在のページ/総ページ数 | - |
| 前へ/次へボタン | ページ移動ボタン | - |

## イベント仕様

### 1-作成ボタン押下

1. 「作成」ボタンをクリック
2. 税リージョン作成画面（`/settings/tax-regions/create`）に遷移

### 2-税リージョンカードクリック

1. 税リージョンのカードをクリック
2. 税リージョン詳細画面（`/settings/tax-regions/{id}`）に遷移

### 3-編集ボタン押下（アクションメニュー）

1. アクションメニューから「編集」を選択
2. 税リージョン編集画面（`/settings/tax-regions/{id}/edit`）に遷移
3. 注：編集は親税リージョン（国レベル）のみ可能

### 4-削除ボタン押下（アクションメニュー）

1. アクションメニューから「削除」を選択
2. 確認ダイアログを表示
   - タイトル: 「本当に削除しますか?」
   - 説明: 削除確認メッセージ
3. 「削除」確認時:
   - `useDeleteTaxRegion` フックで API 呼び出し
   - 成功時: トースト通知「税リージョンが削除されました」を表示
   - 一覧画面を更新
4. 「キャンセル」時: ダイアログを閉じる

### 5-ソート変更

1. ソートドロップダウンから順序を選択（created_at または updated_at）
2. 選択に応じて一覧を再取得・表示

### 6-ページネーション

1. 一覧は20件/ページで表示
2. 前へ/次へボタンでページを切り替え
3. URLパラメータ（offset）を更新

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | tax_region | SELECT | 税リージョン一覧の取得 |
| 削除ボタン押下 | tax_region | DELETE | 税リージョンの削除 |

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

#### tax_region（参照）

| 操作 | 項目（カラム名） | 取得条件 | 備考 |
|-----|-----------------|---------|------|
| SELECT | id, country_code, province_code, tax_rates, parent_id, created_at, updated_at | WHERE parent_id IS NULL | ルートレベルの税リージョンのみ |

## メッセージ仕様

| 種別 | メッセージキー | メッセージ内容 | 表示条件 |
|------|---------------|---------------|----------|
| 成功 | taxRegions.delete.successToast | 税リージョンが削除されました | 削除成功時 |
| 確認 | general.areYouSure | 本当に削除しますか? | 削除確認ダイアログ |
| 確認 | taxRegions.delete.confirmation | 削除確認メッセージ | 削除確認ダイアログ |
| エラー | （APIエラー） | APIからのエラーメッセージ | 削除失敗時 |
| 空状態 | noRecords | レコードがありません | データがない場合 |
| 空状態 | noResults | 結果がありません | 検索結果がない場合 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| ネットワークエラー | エラーをスロー（エラー境界でキャッチ） |
| データ読み込み中 | スケルトンローダーを表示（3行分） |
| データなし | NoRecords コンポーネントを表示 |
| 検索結果なし | NoResults コンポーネントを表示 |

## 備考

- `SingleColumnPage` レイアウトを使用
- 拡張ウィジェット対応: `tax.list.before`, `tax.list.after`
- 一覧は `parent_id: "null"` でフィルタし、ルートレベル（国）の税リージョンのみ表示
- デフォルトソートは `country_code` 順
- `keepPreviousData` オプションでページ切り替え時のちらつきを防止
- 税リージョンカードはカード形式で表示（テーブル形式ではない）
- 地域税リージョン（子リージョン）は詳細画面で確認

---

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

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

### 推奨読解順序

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

まず、税リージョンのデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | HttpTypes | `@medusajs/types` | `AdminTaxRegion`, `AdminTaxRegionListParams` の型定義 |
| 1-2 | tax-regions.tsx | `packages/admin/dashboard/src/hooks/api/tax-regions.tsx` | API フックの型定義と実装 |

**読解のコツ**: 税リージョンには `parent_id` があり、階層構造を持つ。ルートレベルは国、子レベルは州/県を表す。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TaxRegionsList | `packages/admin/dashboard/src/routes/tax-regions/tax-region-list/tax-region-list.tsx` | SingleColumnPage でラップされたエントリーポイント |

**主要処理フロー**:
1. **行6**: getWidgets で拡張ウィジェットを取得
2. **行8-17**: SingleColumnPage 内に TaxRegionListView をレンダリング

#### Step 3: リストビューコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TaxRegionListView | `packages/admin/dashboard/src/routes/tax-regions/tax-region-list/components/tax-region-list-view/tax-region-list-view.tsx` | 実際のデータ取得とテーブル表示 |

**主要処理フロー**:
- **行10**: PAGE_SIZE = 20 を定義
- **行15-17**: useTaxRegionTableQuery でクエリパラメータを管理
- **行18-27**: useTaxRegions でデータ取得、`parent_id: "null"` でルートレベルのみフィルタ
- **行29-33**: useTaxRegionTable でテーブル状態を管理
- **行41-56**: TaxRegionTable コンポーネントでカード一覧をレンダリング

#### Step 4: テーブル/カードコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TaxRegionTable | `packages/admin/dashboard/src/routes/tax-regions/common/components/tax-region-table/tax-region-table.tsx` | カード一覧のコンテナ |
| 4-2 | TaxRegionCard | `packages/admin/dashboard/src/routes/tax-regions/common/components/tax-region-card/tax-region-card.tsx` | 個別の税リージョンカード |

**TaxRegionTable の主要処理**:
- **行36-50**: ローディング中はスケルトン表示
- **行52-55**: 空状態の判定（noQuery, noResults, noRecords）
- **行70-80**: ソートボタンと作成ボタンの配置
- **行85-106**: 各税リージョンをカード形式で表示
- **行107-119**: ページネーション

**TaxRegionCard の主要処理**:
- **行45-46**: 国コードから国名を取得
- **行88-112**: 国旗アイコンの表示（country_code のみの場合）
- **行154-163**: リンクとしてラップ（詳細画面への遷移）
- **行169-217**: アクションメニュー（編集・削除）

#### Step 5: 削除処理フックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | useDeleteTaxRegionAction | `packages/admin/dashboard/src/routes/tax-regions/common/hooks.ts:8-46` | 削除処理のカスタムフック |

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

```
TaxRegionsList（エントリーポイント）
    │
    ├─ useExtension()
    │      └─ getWidgets("tax.list.before", "tax.list.after")
    │
    └─ SingleColumnPage
           │
           └─ TaxRegionListView
                  │
                  ├─ useTaxRegionTableQuery({ pageSize: 20 })
                  │
                  ├─ useTaxRegions({ parent_id: "null", order: "country_code" })
                  │      └─ sdk.admin.taxRegion.list()
                  │
                  ├─ useTaxRegionTable({ data, count, pageSize })
                  │      └─ useReactTable()
                  │
                  └─ TaxRegionTable
                         │
                         ├─ DataTableOrderBy（ソート）
                         │
                         ├─ TaxRegionCard[]
                         │      ├─ ReactCountryFlag
                         │      └─ TaxRegionCardActions
                         │             └─ useDeleteTaxRegionAction
                         │                    └─ useDeleteTaxRegion
                         │
                         └─ LocalizedTablePagination
```

### データフロー図

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

クエリパラメータ ───▶ TaxRegionListView ───▶ 税リージョンカード一覧
(offset, order)           │
                          ├─ useTaxRegionTableQuery
                          │      │
                          │      └─ クエリパラメータ解析
                          │
                          ├─ useTaxRegions
                          │      │
                          │      └─ GET /admin/tax-regions
                          │              │
                          │              └─ tax_regions[], count
                          │
                          └─ TaxRegionTable
                                 │
                                 ├─ TaxRegionCard（各リージョン）
                                 │      │
                                 │      ├─ 国旗表示
                                 │      ├─ 国名表示
                                 │      └─ アクションメニュー
                                 │
                                 └─ ページネーション
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| tax-region-list.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-list/tax-region-list.tsx` | ソース | エントリーポイント |
| tax-region-list-view.tsx | `packages/admin/dashboard/src/routes/tax-regions/tax-region-list/components/tax-region-list-view/tax-region-list-view.tsx` | ソース | データ取得とリスト表示 |
| tax-region-table.tsx | `packages/admin/dashboard/src/routes/tax-regions/common/components/tax-region-table/tax-region-table.tsx` | ソース | テーブル/カードコンテナ |
| tax-region-card.tsx | `packages/admin/dashboard/src/routes/tax-regions/common/components/tax-region-card/tax-region-card.tsx` | ソース | 個別カードコンポーネント |
| use-tax-region-table.tsx | `packages/admin/dashboard/src/routes/tax-regions/common/hooks/use-tax-region-table.tsx` | ソース | テーブル状態管理フック |
| hooks.ts | `packages/admin/dashboard/src/routes/tax-regions/common/hooks.ts` | ソース | 削除アクションフック |
| tax-regions.tsx | `packages/admin/dashboard/src/hooks/api/tax-regions.tsx` | ソース | 税リージョンAPIフック |
| use-tax-region-table-query.ts | `packages/admin/dashboard/src/hooks/table/query/use-tax-region-table-query.ts` | ソース | テーブルクエリフック |
