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

## 概要

本ドキュメントは、Medusa Admin Dashboardにおけるリージョン詳細画面に関する設計書です。この画面により、特定のリージョンの詳細情報を確認し、各種編集操作への導線を提供します。

### 本画面の処理概要

**業務上の目的・背景**：リージョン設定の確認・管理を行う中心的な画面です。リージョンの基本情報（名前、通貨、税金設定、決済プロバイダー）と、そのリージョンに含まれる国の一覧を確認できます。また、各情報の編集・削除操作への導線を提供します。

**画面へのアクセス方法**：リージョン一覧画面（/settings/regions）でリージョン行をクリック、またはURL直接アクセス（/settings/regions/:id）。

**主要な操作・処理内容**：
1. リージョン基本情報の表示（名前、通貨、税金設定、決済プロバイダー）
2. リージョンに含まれる国の一覧表示
3. リージョン編集画面への遷移
4. リージョンの削除
5. 国の追加・削除
6. メタデータ・JSON表示

**画面遷移**：
- 遷移元：リージョン一覧画面（/settings/regions）、リージョン作成画面（/settings/regions/create）
- 遷移先：リージョン編集画面（/settings/regions/:id/edit）、国追加画面（/settings/regions/:id/countries/add）、メタデータ編集画面（/settings/regions/:id/metadata）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 65 | 地域CRUD | 主機能 | リージョン詳細の表示 |
| 66 | 地域国設定 | 補助機能 | 含まれる国の表示 |

## 画面種別

詳細画面（SingleColumnPage）

## URL/ルーティング

`/settings/regions/:id`

## 入出力項目

該当なし（詳細表示のみ）

## 表示項目

### 一般情報セクション（RegionGeneralSection）

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|------|------|
| リージョン名 | name | string | 見出しとして表示 |
| 通貨 | currency_code | string | バッジと通貨名を表示 |
| 自動税金計算 | automatic_taxes | boolean | 有効/無効を表示 |
| 税込価格 | is_tax_inclusive | boolean | price_preferencesから取得、有効/無効を表示 |
| 決済プロバイダー | payment_providers | string[] | ListSummaryコンポーネントで一覧表示 |

### 国一覧セクション（RegionCountrySection）

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|------|------|
| 選択チェックボックス | select | boolean | 複数選択用 |
| 国名 | display_name | string | 国の表示名 |
| 国コード | iso_2 | string | ISO 3166-1 alpha-2コード |
| アクション | actions | - | 削除メニュー |

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

| 項目名 | 説明 |
|--------|------|
| 編集ボタン | リージョン編集画面への遷移 |
| 削除ボタン | リージョンの削除（確認ダイアログ付き） |

## イベント仕様

### 1-リージョン詳細取得

**トリガー**：画面読み込み時

**処理内容**：
1. URLパラメータからリージョンIDを取得
2. useRegionフックでリージョン詳細を取得（loaderでプリフェッチ）
3. usePricePreferencesで税込価格設定を取得
4. データを各セクションに表示

### 2-編集ボタンクリック

**トリガー**：一般情報セクションの編集アイコンをクリック

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

### 3-削除ボタンクリック

**トリガー**：一般情報セクションの削除アイコンをクリック

**処理内容**：
1. 確認ダイアログを表示（リージョン名の入力確認）
2. useDeleteRegionで削除APIを呼び出し
3. 成功時：トースト通知を表示、リージョン一覧画面へ遷移
4. 失敗時：エラートースト通知を表示

### 4-国追加ボタンクリック

**トリガー**：国一覧セクションのアクションメニューから「国を追加」を選択

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

### 5-国の削除（単体）

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

**処理内容**：
1. 確認ダイアログを表示（国名の入力確認）
2. useUpdateRegionで既存の国から該当国を除外して更新
3. 成功時：トースト通知を表示
4. 失敗時：エラートースト通知を表示

### 6-国の削除（複数）

**トリガー**：国を複数選択後、キーボードショートカット「r」を押下

**処理内容**：
1. 確認ダイアログを表示
2. useUpdateRegionで選択された国を除外して更新
3. 成功時：トースト通知を表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 詳細表示 | region | SELECT | リージョン情報の取得 |
| 詳細表示 | price_preference | SELECT | 税込設定の取得 |
| リージョン削除 | region | DELETE | リージョンの削除 |
| 国削除 | region | UPDATE | countriesフィールドの更新 |

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

#### region（国削除時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | countries | 削除対象を除いた国コード配列 | iso_2コードの配列 |
| UPDATE | updated_at | 現在日時 | 自動更新 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|---------|
| regions.toast.delete | 成功 | リージョンが削除されました | リージョン削除成功時 |
| regions.toast.countries | 成功 | 国設定が更新されました | 国削除成功時 |
| - | エラー | {エラーメッセージ} | API呼び出し失敗時 |
| general.areYouSure | 確認 | 本当によろしいですか？ | 削除確認ダイアログ |
| regions.deleteRegionWarning | 確認 | {name}を削除しますか？ | リージョン削除確認 |
| regions.removeCountryWarning | 確認 | {name}を削除しますか？ | 国削除確認 |
| regions.removeCountriesWarning | 確認 | {count}件の国を削除しますか？ | 複数国削除確認 |

## 例外処理

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

## 備考

- 画面読み込み時にloaderでリージョン情報をプリフェッチ
- メタデータ表示・JSON表示機能あり（showMetadata, showJSON）
- 拡張ウィジェット対応（before/after）
- 国一覧のページサイズは10件
- 国一覧はテーブル内検索・ソート機能あり

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | constants.ts | `packages/admin/dashboard/src/routes/regions/region-detail/constants.ts` | REGION_DETAIL_FIELDSの定義 |

**読解のコツ**: APIリクエストで取得するフィールドが定義されています。

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

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

**主要処理フロー**:
1. **14-17行目**: useLoaderDataでプリフェッチデータを取得
2. **19-31行目**: useRegionでリージョン詳細を取得
3. **33-44行目**: usePricePreferencesで税込設定を取得
4. **60-76行目**: SingleColumnPageで各セクションをレンダリング

#### Step 3: 一般情報セクションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | region-general-section.tsx | `packages/admin/dashboard/src/routes/regions/region-detail/components/region-general-section/region-general-section.tsx` | 一般情報セクション |

**主要処理フロー**:
- **22-28行目**: pricePreferencesから税込設定を取得
- **30-78行目**: Container内でSectionRowコンポーネントで各項目を表示
- **81-138行目**: RegionActions - 編集・削除アクションメニュー

#### Step 4: 国一覧セクションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | region-country-section.tsx | `packages/admin/dashboard/src/routes/regions/region-detail/components/region-country-section/region-country-section.tsx` | 国一覧セクション |

**主要処理フロー**:
- **26-39行目**: useCountriesで国一覧をフィルタ・ソート
- **61-98行目**: handleRemoveCountries - 複数国削除処理
- **100-117行目**: _DataTableでテーブル表示
- **143-187行目**: CountryActions - 個別国削除

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

```
RegionDetail (region-detail.tsx)
    │
    ├─ useLoaderData()
    │      └─ regionLoader (プリフェッチ)
    │
    ├─ useRegion()
    │      └─ sdk.admin.region.retrieve()
    │
    ├─ usePricePreferences()
    │      └─ price_preferences API
    │
    ├─ RegionGeneralSection
    │      │
    │      └─ RegionActions
    │             └─ useDeleteRegion()
    │
    └─ RegionCountrySection
           │
           ├─ useCountries()
           │      └─ ローカルフィルタ・ソート
           │
           └─ useUpdateRegion()
                  └─ sdk.admin.region.update()
```

### データフロー図

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

URL :id ───────────▶ useRegion() ─────────────────▶ region詳細
                           │
                           ├─ usePricePreferences()
                           │
                           ▼
                  RegionGeneralSection ────────────▶ 基本情報表示
                           │
                           ├─ 編集アクション ─────────▶ 編集画面遷移
                           │
                           └─ 削除アクション ─────────▶ 一覧画面遷移

region.countries ──▶ RegionCountrySection ─────────▶ 国一覧表示
                           │
                           └─ 国削除 ─────────────────▶ useUpdateRegion()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| region-detail.tsx | `packages/admin/dashboard/src/routes/regions/region-detail/region-detail.tsx` | ソース | エントリーポイント |
| region-general-section.tsx | `packages/admin/dashboard/src/routes/regions/region-detail/components/region-general-section/region-general-section.tsx` | ソース | 一般情報セクション |
| region-country-section.tsx | `packages/admin/dashboard/src/routes/regions/region-detail/components/region-country-section/region-country-section.tsx` | ソース | 国一覧セクション |
| loader.ts | `packages/admin/dashboard/src/routes/regions/region-detail/loader.ts` | ソース | データプリフェッチ |
| constants.ts | `packages/admin/dashboard/src/routes/regions/region-detail/constants.ts` | ソース | 定数定義 |
| regions.tsx | `packages/admin/dashboard/src/hooks/api/regions.tsx` | ソース | リージョンAPIフック |
| price-preferences.tsx | `packages/admin/dashboard/src/hooks/api/price-preferences.tsx` | ソース | 価格設定APIフック |
| currencies.ts | `packages/admin/dashboard/src/lib/data/currencies.ts` | データ | 通貨データ |
