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

## 概要

本ドキュメントは、Medusa Admin Dashboardにおけるリージョン一覧画面に関する設計書です。この画面により、ストアで利用可能なリージョン（地域設定）の一覧を表示・管理することができます。

### 本画面の処理概要

**業務上の目的・背景**：グローバルEコマースでは、販売対象地域ごとに異なる通貨、税率、決済プロバイダーを設定する必要があります。リージョンは、これらの地域固有の設定をまとめて管理するための概念です。本画面では、設定済みのリージョンを一覧表示し、新規作成・編集・削除などの操作への導線を提供します。

**画面へのアクセス方法**：設定トップ画面（/settings）から「リージョン」をクリック、またはサイドナビゲーションから直接アクセスできます。URL直接アクセスも可能（/settings/regions）。

**主要な操作・処理内容**：
1. リージョン一覧をテーブル形式で表示
2. 名前や作成日時でのソート機能
3. フィルタ機能による絞り込み
4. 検索機能による名前検索
5. 新規リージョン作成画面への遷移
6. リージョン詳細画面への遷移
7. リージョンの編集・削除アクション

**画面遷移**：
- 遷移元：設定トップ画面（/settings）
- 遷移先：リージョン作成画面（/settings/regions/create）、リージョン詳細画面（/settings/regions/:id）、リージョン編集画面（/settings/regions/:id/edit）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 65 | 地域CRUD | 主機能 | リージョン一覧の取得・表示 |

## 画面種別

一覧画面（SingleColumnPage + DataTable）

## URL/ルーティング

`/settings/regions`

## 入出力項目

該当なし（一覧表示のみ）

## 表示項目

### リージョン一覧テーブル

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|------|------|
| リージョン名 | name | string | リージョンの名称 |
| 通貨 | currency_code | string | リージョンの通貨コード |
| 国数 | countries | number | リージョンに含まれる国の数 |
| 決済プロバイダー | payment_providers | string[] | 利用可能な決済プロバイダー |
| 作成日時 | created_at | datetime | リージョン作成日時 |
| 更新日時 | updated_at | datetime | リージョン最終更新日時 |
| アクション | actions | - | 編集・削除メニュー |

### ヘッダー部

| 項目名 | 説明 |
|--------|------|
| タイトル | 「リージョン」 |
| サブタイトル | リージョン管理の説明文 |
| 作成ボタン | 新規リージョン作成画面への遷移 |

## イベント仕様

### 1-リージョン一覧取得

**トリガー**：画面読み込み時、検索・フィルタ・ソート・ページネーション操作時

**処理内容**：
1. useRegionTableQueryで検索パラメータを取得
2. useRegionsフックでリージョン一覧APIを呼び出し
3. 取得したデータをテーブルに表示
4. ページサイズは20件固定

### 2-検索

**トリガー**：検索フィールドへの入力

**処理内容**：
1. 入力値をクエリパラメータに反映
2. リージョン一覧を再取得

### 3-ソート

**トリガー**：テーブルヘッダーのソートボタンをクリック

**処理内容**：
1. ソート対象：name、created_at、updated_at
2. ソート順をクエリパラメータに反映
3. リージョン一覧を再取得

### 4-行クリック（詳細画面遷移）

**トリガー**：テーブル行をクリック

**処理内容**：
1. クリックされたリージョンのIDを取得
2. `/settings/regions/{id}`に遷移

### 5-作成ボタンクリック

**トリガー**：「作成」ボタンをクリック

**処理内容**：
1. `/settings/regions/create`に遷移

### 6-編集アクション

**トリガー**：行のアクションメニューから「編集」を選択

**処理内容**：
1. `/settings/regions/{id}/edit`に遷移

### 7-削除アクション

**トリガー**：行のアクションメニューから「削除」を選択

**処理内容**：
1. 確認ダイアログを表示（リージョン名の入力確認）
2. ユーザーが確認した場合、useDeleteRegionフックで削除APIを呼び出し
3. 成功時：トースト通知を表示、一覧を再取得
4. 失敗時：エラートースト通知を表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 一覧表示 | region | SELECT | リージョン一覧の取得 |
| 削除アクション | region | DELETE | リージョンの削除 |

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

#### region（削除時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | id = 指定ID | リージョン全体を削除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|---------|
| regions.toast.delete | 成功 | リージョンが削除されました | 削除成功時 |
| - | エラー | {エラーメッセージ} | 削除API失敗時 |
| regions.list.noRecordsMessage | 情報 | リージョンがありません | 一覧が空の場合 |
| general.areYouSure | 確認 | 本当によろしいですか？ | 削除確認ダイアログ |
| regions.deleteRegionWarning | 確認 | {name}を削除しますか？ | 削除確認ダイアログ |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| リージョン一覧取得エラー | エラーをスローしてエラーバウンダリで処理 |
| 削除API失敗 | エラートーストを表示 |

## 備考

- ページサイズは20件固定
- keepPreviousDataオプションでページ切り替え時のちらつきを防止
- payment_providersは`*payment_providers`フィールドで展開取得
- 拡張ウィジェット対応（before/after）

---

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

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

### 推奨読解順序

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

リージョンのデータ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types | `@medusajs/types` | HttpTypes.AdminRegionの型定義 |

**読解のコツ**: AdminRegionはname、currency_code、countries、payment_providers等のフィールドを持ちます。

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

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

**主要処理フロー**:
1. **6行目**: useExtensionでウィジェット取得関数を取得
2. **8-17行目**: SingleColumnPageでRegionListTableをラップ

#### Step 3: テーブルコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | region-list-table.tsx | `packages/admin/dashboard/src/routes/regions/region-list/components/region-list-table/region-list-table.tsx` | メインテーブルロジック |

**主要処理フロー**:
- **25行目**: PAGE_SIZE = 20
- **30行目**: useRegionTableQueryで検索パラメータ取得
- **31-45行目**: useRegionsでリージョン一覧取得（payment_providers展開含む）
- **47行目**: useRegionTableFiltersでフィルタ定義取得
- **48行目**: useColumnsでカラム定義取得
- **50-57行目**: useDataTableでテーブル状態管理
- **63-99行目**: JSXレンダリング（Container、_DataTable）
- **103-159行目**: RegionActions - 編集・削除アクションメニュー

#### Step 4: APIフックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | regions.tsx | `packages/admin/dashboard/src/hooks/api/regions.tsx` | リージョンAPIフック |

**主要処理フロー**:
- **40-59行目**: useRegions - リージョン一覧取得
- **113-131行目**: useDeleteRegion - リージョン削除、成功時にキャッシュ無効化

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

```
RegionList (region-list.tsx)
    │
    ├─ useExtension()
    │      └─ 拡張ウィジェット取得
    │
    └─ RegionListTable
           │
           ├─ useRegionTableQuery()
           │      └─ URL検索パラメータ取得
           │
           ├─ useRegions()
           │      └─ sdk.admin.region.list()
           │
           ├─ useDataTable()
           │      └─ テーブル状態管理
           │
           └─ RegionActions
                  └─ useDeleteRegion()
                         └─ sdk.admin.region.delete()
```

### データフロー図

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

URL検索パラメータ ──▶ useRegionTableQuery ────▶ searchParams
                           │
                           ▼
                     useRegions API呼び出し
                           │
                           ▼
                  [Region APIサーバー]
                           │
                           ▼
regions一覧データ ──▶ useDataTable ────────────▶ テーブル表示
                           │
                           ▼
行クリック ────────▶ navigateTo ───────────────▶ 詳細画面遷移

削除アクション ───▶ useDeleteRegion ───────────▶ 一覧再取得
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| region-list.tsx | `packages/admin/dashboard/src/routes/regions/region-list/region-list.tsx` | ソース | エントリーポイント |
| region-list-table.tsx | `packages/admin/dashboard/src/routes/regions/region-list/components/region-list-table/region-list-table.tsx` | ソース | テーブルコンポーネント |
| regions.tsx | `packages/admin/dashboard/src/hooks/api/regions.tsx` | ソース | リージョンAPIフック |
| use-region-table-columns.ts | `packages/admin/dashboard/src/hooks/table/columns/use-region-table-columns.ts` | ソース | カラム定義 |
| use-region-table-filters.ts | `packages/admin/dashboard/src/hooks/table/filters/use-region-table-filters.ts` | ソース | フィルタ定義 |
| use-region-table-query.ts | `packages/admin/dashboard/src/hooks/table/query/use-region-table-query.ts` | ソース | クエリパラメータ処理 |
| data-table.tsx | `packages/admin/dashboard/src/components/table/data-table/` | ソース | データテーブルコンポーネント |
| action-menu.tsx | `packages/admin/dashboard/src/components/common/action-menu/` | ソース | アクションメニューコンポーネント |
