# 画面設計書 64-キャンペーン一覧画面

## 概要

本ドキュメントは、Medusa Admin Dashboard のキャンペーン一覧画面について、画面仕様・機能・データ処理を定義した画面設計書です。

### 本画面の処理概要

この画面では、登録されているキャンペーンの一覧を表示し、検索・ソート・ページネーションを行えます。また、キャンペーンの新規作成、編集、削除のアクションを実行できます。

**業務上の目的・背景**：キャンペーンは複数のプロモーションをグループ化し、予算や期間を一元管理するための機能です。マーケティング担当者がキャンペーンの全体像を把握し、効率的に管理するために、一覧画面での検索・ソート・フィルタ機能が必要です。また、キャンペーンの迅速な作成・編集・削除を可能にすることで、マーケティング施策の機動的な運用を支援します。

**画面へのアクセス方法**：サイドメニューの「キャンペーン」をクリックすることでアクセスできます。URL: `/campaigns`

**主要な操作・処理内容**：
1. キャンペーン一覧の表示（ページネーション付き）
2. キャンペーンの検索
3. ソート順の変更（名前、作成日、更新日）
4. キャンペーン詳細画面への遷移
5. 新規キャンペーン作成画面への遷移
6. キャンペーンの編集画面への遷移
7. キャンペーンの削除

**画面遷移**：
- 遷移元：サイドメニュー、ホーム画面
- 遷移先：キャンペーン詳細画面、キャンペーン作成画面、キャンペーン編集画面

**権限による表示制御**：認証済みの管理者ユーザーのみがアクセス可能です。キャンペーン管理権限を持つユーザーが操作できます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 38 | キャンペーン管理 | 主機能 | キャンペーン一覧の取得・表示 |

## 画面種別

一覧

## URL/ルーティング

`/campaigns`

## 入出力項目

| 項目名 | 項目ID | 型 | 必須 | 入力/出力 | 説明 |
|--------|--------|-----|------|-----------|------|
| 検索キーワード | q | string | - | 入力 | キャンペーン名での検索 |
| ソート項目 | order | string | - | 入力 | name/created_at/updated_at |
| ページ番号 | offset | number | - | 入力 | ページネーション用 |
| 表示件数 | limit | number | - | 入力 | デフォルト20件 |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| 画面タイトル | 「キャンペーン」 |
| 作成ボタン | 新規キャンペーン作成画面へ遷移 |
| 検索ボックス | キーワード検索 |
| ソートセレクタ | ソート順の変更 |
| キャンペーンテーブル | キャンペーン一覧のデータテーブル |
| ページネーション | ページ切り替え |
| アクションメニュー | 各行の編集・削除アクション |

## テーブル列定義

| 列名 | フィールド | 説明 |
|------|-----------|------|
| 名前 | name | キャンペーン名（リンク） |
| 識別子 | campaign_identifier | キャンペーン識別子 |
| 説明 | description | キャンペーンの説明 |
| ステータス | status | 計算値（scheduled/active/expired） |
| 開始日 | starts_at | キャンペーン開始日時 |
| 終了日 | ends_at | キャンペーン終了日時 |
| アクション | - | 編集・削除アクション |

## イベント仕様

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

**処理フロー**：
1. `/campaigns/create` へ遷移
2. キャンペーン作成画面を表示

### 2-キャンペーン行クリック

**処理フロー**：
1. クリックしたキャンペーンのIDを取得
2. `/campaigns/:id` へ遷移
3. キャンペーン詳細画面を表示

### 3-編集アクション選択

**処理フロー**：
1. 選択したキャンペーンのIDを取得
2. `/campaigns/:id/edit` へ遷移
3. キャンペーン編集画面を表示

### 4-削除アクション選択

**処理フロー**：
1. 確認ダイアログを表示（キャンペーン名の入力確認）
2. ユーザーがキャンセルした場合は処理終了
3. `useDeleteCampaign` フックを使用してAPIを呼び出し
4. 成功時：トースト通知を表示し、一覧を更新
5. 失敗時：エラーメッセージをトーストで表示

**API呼び出し**：
- エンドポイント: `DELETE /admin/campaigns/:id`

### 5-検索実行

**処理フロー**：
1. 検索キーワードをクエリパラメータに設定
2. キャンペーン一覧を再取得
3. 結果を表示

### 6-ソート変更

**処理フロー**：
1. ソート項目をクエリパラメータに設定
2. キャンペーン一覧を再取得
3. 結果を表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 削除アクション選択 | campaign | DELETE | キャンペーンの削除 |

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

#### campaign

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | キャンペーンID | 関連プロモーションとの紐付けも解除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| MSG-001 | 確認 | 本当に削除しますか？ | 削除アクション選択時 |
| MSG-002 | 警告 | このキャンペーンを削除すると、関連するプロモーションとの紐付けが解除されます。 | 削除確認ダイアログ |
| MSG-003 | 成功 | キャンペーン「{name}」を削除しました | 削除成功時 |
| MSG-004 | エラー | {エラーメッセージ} | API通信エラー時 |

## 例外処理

| 例外 | 処理内容 |
|------|---------|
| API通信エラー | エラーをスローしてエラー画面を表示 |
| 削除失敗 | エラーメッセージをtoastで表示 |

## 備考

- ページサイズは20件固定
- ステータスはキャンペーンの開始日・終了日から動的に計算される（scheduled/active/expired）
- 削除確認ダイアログではキャンペーン名の入力確認が必要

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | campaigns.tsx | `packages/admin/dashboard/src/hooks/api/campaigns.tsx` | AdminCampaign型とAPIレスポンスの構造を確認 |
| 1-2 | campaign-status.ts | `packages/admin/dashboard/src/routes/campaigns/common/utils/campaign-status.ts` | ステータス計算ロジック |

**読解のコツ**: キャンペーンのステータスはstarts_atとends_atから動的に計算されます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | campaign-list.tsx | `packages/admin/dashboard/src/routes/campaigns/campaign-list/campaign-list.tsx` | SingleColumnPageレイアウトとウィジェット設定 |

**主要処理フロー**:
1. **6行目**: useExtensionでウィジェットを取得
2. **8-17行目**: SingleColumnPageレイアウトでCampaignListTableをレンダリング

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | campaign-list-table.tsx | `packages/admin/dashboard/src/routes/campaigns/campaign-list/components/campaign-list-table.tsx` | データテーブルの実装 |

**主要処理フロー**:
- **23行目**: useCampaignTableQueryでクエリパラメータ管理
- **25-33行目**: useCampaignsでキャンペーン一覧を取得
- **35行目**: useColumns()でテーブル列を定義
- **37-44行目**: useDataTableでテーブル状態管理
- **50-77行目**: _DataTableコンポーネントでテーブルをレンダリング

#### Step 4: アクションメニューを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | campaign-list-table.tsx | `packages/admin/dashboard/src/routes/campaigns/campaign-list/components/campaign-list-table.tsx` | CampaignActionsコンポーネント（81-138行目） |

**主要処理フロー**:
- **84行目**: useDeleteCampaignで削除ミューテーション準備
- **86-112行目**: handleDeleteで削除処理（確認ダイアログ含む）

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

```
CampaignList (campaign-list.tsx)
    │
    └─ CampaignListTable (campaign-list-table.tsx)
           │
           ├─ useCampaignTableQuery() - クエリパラメータ管理
           │
           ├─ useCampaigns() - キャンペーン一覧取得
           │      └─ sdk.admin.campaign.list()
           │             └─ GET /admin/campaigns
           │
           ├─ useColumns() - テーブル列定義
           │      └─ useCampaignTableColumns()
           │
           ├─ useDataTable() - テーブル状態管理
           │
           ├─ _DataTable - データテーブルUI
           │
           └─ CampaignActions - アクションメニュー
                  │
                  ├─ useDeleteCampaign() - 削除処理
                  │      └─ sdk.admin.campaign.delete()
                  │             └─ DELETE /admin/campaigns/:id
                  │
                  └─ usePrompt() - 確認ダイアログ
```

### データフロー図

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

クエリパラメータ ──▶ useCampaignTableQuery ──▶ searchParams
      ↓
                    useCampaigns() ────▶ キャンペーン一覧
                                              ↓
                                        useDataTable()
                                              ↓
                                        _DataTable表示
                                              ↓
行クリック ───────▶ navigateTo ────▶ 詳細画面遷移

削除アクション ───▶ usePrompt() ────▶ 確認ダイアログ
                          ↓
                  useDeleteCampaign() ▶ API削除
                          ↓
                  invalidateQueries() ▶ 一覧更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| campaign-list.tsx | `packages/admin/dashboard/src/routes/campaigns/campaign-list/campaign-list.tsx` | ソース | エントリーポイント |
| campaign-list-table.tsx | `packages/admin/dashboard/src/routes/campaigns/campaign-list/components/campaign-list-table.tsx` | ソース | テーブルコンポーネント |
| campaigns.tsx | `packages/admin/dashboard/src/hooks/api/campaigns.tsx` | ソース | APIフック |
| use-campaign-table-columns.tsx | `packages/admin/dashboard/src/hooks/table/columns/use-campaign-table-columns.tsx` | ソース | テーブル列定義 |
| use-campaign-table-query.tsx | `packages/admin/dashboard/src/hooks/table/query/use-campaign-table-query.tsx` | ソース | クエリパラメータ管理 |
| campaign-status.ts | `packages/admin/dashboard/src/routes/campaigns/common/utils/campaign-status.ts` | ソース | ステータス計算 |
| route.ts | `packages/medusa/src/api/admin/campaigns/route.ts` | ソース | APIエンドポイント |
