# 画面設計書 60-プロモーション詳細画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における「プロモーション詳細画面」の設計仕様を定義するものである。

### 本画面の処理概要

**業務上の目的・背景**：EC運営において、作成したプロモーションの詳細情報を確認し、必要に応じて編集・削除を行う必要がある。本画面は、プロモーションの設定内容、適用ルール、紐づくキャンペーン情報を一覧表示し、各種操作を行うためのインターフェースを提供する。

**画面へのアクセス方法**：プロモーション一覧画面から特定のプロモーションを選択することでアクセスする。

**主要な操作・処理内容**：
1. プロモーションの基本情報を確認する
2. 適用ルール・対象ルール・購入ルールを確認する
3. 紐づくキャンペーン情報を確認する
4. 編集・削除アクションを実行する
5. JSON形式でデータを確認する

**画面遷移**：
- 遷移元：プロモーション一覧画面（`/promotions`）
- 遷移先：プロモーション編集画面（`/promotions/:id/edit`）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 36 | プロモーション管理 | 主機能 | プロモーションの詳細表示・削除 |
| 37 | キャンペーン管理 | 関連表示 | 紐づくキャンペーンの表示 |

## 画面種別

詳細（2カラムレイアウト）

## URL/ルーティング

```
/promotions/:id
```

## 入出力項目

なし（詳細表示画面のため入力項目なし）

## 表示項目

### メインカラム - 基本情報セクション

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| プロモーションコード | Heading + Badge | プロモーションのコード（コピー可能） |
| ステータス | StatusBadge | active / expired / scheduled / draft |
| 適用方法 | テキスト | コード入力 / 自動適用 |
| タイプ | テキスト | standard / buyget |
| 値 | テキスト | 割引金額（通貨バッジ付き）または割引率 |
| 配分方法 | テキスト | each / across / once |
| 税込設定 | テキスト | true / false（fixedタイプのみ） |
| 使用状況 | テキスト | 使用回数 / 制限数（limitがある場合） |

### メインカラム - ルールセクション

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| 適用ルール | PromotionConditionsSection | 一般的な適用条件ルール |
| 対象ルール | PromotionConditionsSection | 対象商品の条件ルール |
| 購入ルール | PromotionConditionsSection | 購入条件ルール（buygetのみ） |

### サイドバー - キャンペーンセクション

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| キャンペーン名 | テキスト | 紐づくキャンペーンの名称 |
| キャンペーン詳細 | リンク | キャンペーン詳細画面へのリンク |

### アクションメニュー

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| 編集 | メニュー項目 | 編集画面に遷移 |
| 削除 | メニュー項目 | 削除確認後に実行 |

## イベント仕様

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

アクションメニューから「編集」を選択した場合：
- プロモーション編集画面（`/promotions/:id/edit`）に遷移

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

アクションメニューから「削除」を選択した場合：
1. 確認ダイアログを表示（プロモーションコードの入力確認）
2. 確認後、`useDeletePromotion`フックを使用してAPI呼び出し
3. APIエンドポイント：`DELETE /admin/promotions/:id`
4. 成功時：プロモーション一覧画面に遷移
5. 失敗時：エラー処理

### 3-コードコピー

コードバッジをクリックした場合：
- クリップボードにプロモーションコードをコピー

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 削除アクション | promotion | DELETE | プロモーションの削除 |
| 削除アクション | promotion_rule | DELETE | 関連ルールの削除 |

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

#### promotion

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | id = 指定されたプロモーションID | - |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| areYouSure | 確認 | 「本当に削除しますか？」 | 削除確認時 |
| deleteWarning | 確認 | 「プロモーション{code}を削除します」 | 削除確認時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| プロモーションが見つからない | スケルトンを表示（ローディング中と同様の表示） |
| 削除失敗 | エラー処理 |
| ネットワークエラー | エラー処理 |

## 備考

- TwoColumnPageコンポーネントによる2カラムレイアウト
- loaderでサーバーサイドの初期データをプリフェッチ
- buygetタイプの場合のみ購入ルールセクションを表示
- JSON形式でのデータ表示機能あり（showJSON）
- 拡張機能（widgets）によるカスタマイズポイントあり

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | PromotionDetail | `packages/admin/dashboard/src/routes/promotions/promotion-detail/promotion-detail.tsx` | 画面コンポーネント |

**主要処理フロー**:
1. **12-15行目**: useLoaderDataで初期データ取得
2. **17行目**: useParamsでIDを取得
3. **18行目**: usePromotionフックでプロモーションデータ取得
4. **25-27行目**: usePromotionRulesで各種ルール取得
5. **29行目**: useExtensionでウィジェット取得
6. **37-70行目**: TwoColumnPageコンポーネントでレイアウト構築

#### Step 2: 基本情報セクションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | PromotionGeneralSection | `packages/admin/dashboard/src/routes/promotions/promotion-detail/components/promotion-general-section/promotion-general-section.tsx` | 基本情報の表示 |

**主要処理フロー**:
- **25-45行目**: getDisplayValue関数（値の表示形式変換）
- **47-76行目**: 削除ハンドラ
- **78行目**: getPromotionStatusでステータス取得
- **81-213行目**: JSXレンダリング

#### Step 3: ルールセクションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | PromotionConditionsSection | `packages/admin/dashboard/src/routes/promotions/promotion-detail/components/promotion-conditions-section/promotion-conditions-section.tsx` | ルールの表示 |

#### Step 4: キャンペーンセクションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | CampaignSection | `packages/admin/dashboard/src/routes/promotions/promotion-detail/components/campaign-section/campaign-section.tsx` | キャンペーン情報の表示 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | usePromotion | `packages/admin/dashboard/src/hooks/api/promotions.tsx` | プロモーション詳細取得フック（41-60行目） |
| 5-2 | usePromotionRules | `packages/admin/dashboard/src/hooks/api/promotions.tsx` | ルール取得フック（62-83行目） |
| 5-3 | useDeletePromotion | `packages/admin/dashboard/src/hooks/api/promotions.tsx` | プロモーション削除フック（166-186行目） |

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

```
PromotionDetail (promotion-detail.tsx)
    │
    ├─ useLoaderData (初期データ)
    │
    ├─ usePromotion (promotions.tsx)
    │      └─ sdk.admin.promotion.retrieve
    │             └─ GET /admin/promotions/:id
    │
    ├─ usePromotionRules (各種ルール取得)
    │      └─ sdk.admin.promotion.listRules
    │             └─ GET /admin/promotions/:id/:ruleType/rules
    │
    ├─ useExtension (ウィジェット取得)
    │
    ├─ TwoColumnPage
    │      ├─ TwoColumnPage.Main
    │      │      ├─ PromotionGeneralSection
    │      │      │      └─ useDeletePromotion
    │      │      │             └─ DELETE /admin/promotions/:id
    │      │      │
    │      │      ├─ PromotionConditionsSection (rules)
    │      │      ├─ PromotionConditionsSection (target-rules)
    │      │      └─ PromotionConditionsSection (buy-rules) ※buygetのみ
    │      │
    │      └─ TwoColumnPage.Sidebar
    │             └─ CampaignSection
```

### データフロー図

```
[データ取得]                  [処理]                         [表示]

loader ──────────────▶ useLoaderData ───┐
                                        │
                                        ▼
usePromotion ──────────────────────▶ プロモーションデータ ───▶ PromotionGeneralSection
                                        │                         │
                                        │                         ├─▶ ステータス表示
                                        │                         ├─▶ 値表示
                                        │                         └─▶ アクションメニュー
                                        │
usePromotionRules("rules") ────────▶ 適用ルール ───────────▶ PromotionConditionsSection
                                        │
usePromotionRules("target-rules") ─▶ 対象ルール ───────────▶ PromotionConditionsSection
                                        │
usePromotionRules("buy-rules") ────▶ 購入ルール ───────────▶ PromotionConditionsSection
                                        │                    (buygetのみ)
                                        │
promotion.campaign ────────────────────────────────────────▶ CampaignSection
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| promotion-detail.tsx | `packages/admin/dashboard/src/routes/promotions/promotion-detail/promotion-detail.tsx` | ソース | 画面コンポーネント |
| promotion-general-section.tsx | `packages/admin/dashboard/src/routes/promotions/promotion-detail/components/promotion-general-section/promotion-general-section.tsx` | ソース | 基本情報セクション |
| promotion-conditions-section.tsx | `packages/admin/dashboard/src/routes/promotions/promotion-detail/components/promotion-conditions-section/promotion-conditions-section.tsx` | ソース | ルールセクション |
| campaign-section.tsx | `packages/admin/dashboard/src/routes/promotions/promotion-detail/components/campaign-section/campaign-section.tsx` | ソース | キャンペーンセクション |
| loader.ts | `packages/admin/dashboard/src/routes/promotions/promotion-detail/loader.ts` | ソース | データローダー |
| breadcrumb.tsx | `packages/admin/dashboard/src/routes/promotions/promotion-detail/breadcrumb.tsx` | ソース | パンくずリスト |
| promotions.tsx | `packages/admin/dashboard/src/hooks/api/promotions.tsx` | ソース | プロモーションAPIフック |
