# 画面設計書 124-販売チャネル一覧画面

## 概要

本ドキュメントは、Medusa Admin Dashboardにおける販売チャネル一覧画面の設計を記述したものです。登録されている全ての販売チャネルをテーブル形式で表示し、検索・フィルタ・作成・編集・削除などの操作を提供します。

### 本画面の処理概要

この画面では、ストアに登録されている販売チャネルの一覧を確認し、新規作成や既存チャネルの管理を行います。DataTableコンポーネントを使用した高機能なテーブル表示を提供します。

**業務上の目的・背景**：ECサイト運営において、複数の販売チャネル（Webサイト、モバイルアプリ、POSシステムなど）を管理する必要があります。販売チャネルは商品の公開範囲やAPIアクセスを制御するための重要な概念です。この画面は、これらの販売チャネルを一元的に管理し、各チャネルへの商品割り当てや設定変更を効率的に行うための中心的なインターフェースを提供します。

**画面へのアクセス方法**：設定メニューから「販売チャネル」を選択してアクセスします。URLパスは `/settings/sales-channels` です。サイドナビゲーションの設定エリアからもアクセス可能です。

**主要な操作・処理内容**：
1. 販売チャネル一覧の表示（ページネーション対応）
2. 販売チャネルの検索・フィルタリング
3. 新規販売チャネル作成画面への遷移
4. 販売チャネル詳細画面への遷移（行クリック）
5. 販売チャネルの編集（アクションメニュー）
6. 販売チャネルの削除（アクションメニュー、デフォルトチャネルは削除不可）

**画面遷移**：
- 遷移元：設定トップ画面（No.105）、サイドナビゲーション
- 遷移先：販売チャネル作成画面（No.125）、販売チャネル詳細画面（No.126）、販売チャネル編集画面（No.127）

**権限による表示制御**：認証済みの管理者ユーザーのみアクセス可能です。デフォルトの販売チャネルは削除できません（削除ボタンが無効化されます）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 70 | 販売チャネルCRUD | 主機能 | 販売チャネル一覧の取得・表示 |

## 画面種別

一覧

## URL/ルーティング

`/settings/sales-channels`

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| searchParams | 入力（クエリパラメータ） | object | No | 検索・フィルタ・ページネーションパラメータ |
| sales_channels | 出力 | AdminSalesChannel[] | - | 販売チャネル一覧 |
| count | 出力 | number | - | 総件数 |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| name | string | 販売チャネル名 |
| is_default | boolean | デフォルトチャネルかどうか |
| アクションメニュー | ActionMenu | 編集・削除アクション |

## イベント仕様

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

ヘッダーの「作成」ボタンをクリックすると、販売チャネル作成画面へ遷移します。

- 遷移先URL: `/settings/sales-channels/create`

### 2-行クリック

テーブル行をクリックすると、該当する販売チャネルの詳細画面へ遷移します。

- 遷移先URL: `/settings/sales-channels/:id`

### 3-編集アクションクリック

アクションメニューの「編集」をクリックすると、編集画面へ遷移します。

- 遷移先URL: `/settings/sales-channels/:id/edit`

### 4-削除アクションクリック

アクションメニューの「削除」をクリックすると、確認ダイアログが表示されます。

- 確認ダイアログ表示内容:
  - タイトル: 「本当によろしいですか？」（i18n: general.areYouSure）
  - 説明: 販売チャネル削除に関する警告メッセージ（i18n: salesChannels.deleteSalesChannelWarning）
  - 確認テキスト入力: 販売チャネル名の入力が必要
- 処理内容:
  - `DELETE /admin/sales-channels/:id` APIを呼び出し
  - 成功時: トースト通知を表示し、一覧を再取得
  - 失敗時: エラーメッセージをトースト通知で表示
- 制限: デフォルトチャネルの場合は削除ボタンが無効化される

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | sales_channel | SELECT | 販売チャネル一覧の取得 |
| 画面表示 | store | SELECT | デフォルトチャネルIDの取得 |
| 削除アクション | sales_channel | DELETE | 販売チャネルの削除 |

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

#### sales_channel

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, name, description, is_disabled | ページネーション・フィルタ条件に基づく | - |
| DELETE | - | id = 選択された販売チャネルID | デフォルトチャネルは削除不可 |

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容（i18nキー） |
|--------------|----------|------------------------|
| 成功 | 削除成功時 | salesChannels.toast.delete |
| エラー | API呼び出し失敗時 | error.message |
| 確認 | 削除確認ダイアログ | general.areYouSure, salesChannels.deleteSalesChannelWarning |
| ツールチップ | デフォルトチャネル削除不可 | salesChannels.tooltip.cannotDeleteDefault |
| 空状態 | データなし時 | 空状態メッセージ（emptyState） |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| API呼び出しエラー | エラーをスロー（isError状態）してエラーバウンダリでハンドリング |
| ローディング中 | DataTableコンポーネントのisLoadingプロパティでローディング表示 |

## 備考

- ページサイズは20件固定
- DataTableコンポーネントを使用した高機能テーブル（ソート、フィルタ、ページネーション）
- 拡張ポイント: `sales_channel.list.before`、`sales_channel.list.after` のウィジェットスロット
- useStoreフックでストア情報を取得し、デフォルトチャネルを判定

---

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

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

### 推奨読解順序

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

まず、販売チャネルデータの型定義を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | HttpTypes | `packages/types/src/http/sales-channel/admin/index.ts` | AdminSalesChannel型の構造 |

**読解のコツ**: is_disabledフィールドで有効/無効状態を管理し、is_defaultはストア情報から判定します。

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

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

**主要処理フロー**:
1. **7行目**: useExtensionでウィジェット取得関数を取得
2. **9-18行目**: SingleColumnPageでレイアウト構成、SalesChannelListTableを配置

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sales-channel-list-table.tsx | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-list/components/sales-channel-list-table.tsx` | DataTableコンポーネント、カラム定義、アクション |

**主要処理フロー**:
- **30-31行目**: useStoreでストア情報を取得（デフォルトチャネル判定用）
- **32-34行目**: useSalesChannelTableQueryで検索パラメータを生成
- **36-41行目**: useSalesChannelsでデータ取得
- **47-53行目**: デフォルトチャネルフラグを付与
- **59-78行目**: DataTableコンポーネントでテーブル表示
- **86-158行目**: useColumnsでカラム定義と削除アクション

#### Step 4: API呼び出しフックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | sales-channels.tsx | `packages/admin/dashboard/src/hooks/api/sales-channels.tsx` | useSalesChannels、useDeleteSalesChannelLazyフックの実装 |

**主要処理フロー**:
- **43-62行目**: useSalesChannelsでリスト取得
- **136-162行目**: useDeleteSalesChannelLazyで遅延削除（IDを引数に受け取る）

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

```
SalesChannelList (sales-channel-list.tsx)
    │
    ├─ useExtension() → getWidgets()
    │
    └─ SingleColumnPage
           └─ SalesChannelListTable (sales-channel-list-table.tsx)
                  │
                  ├─ useStore() → store.default_sales_channel_id
                  │
                  ├─ useSalesChannelTableQuery() → searchParams
                  │
                  ├─ useSalesChannels(searchParams)
                  │      └─ sdk.admin.salesChannel.list()
                  │
                  ├─ useColumns()
                  │      └─ useDeleteSalesChannelLazy()
                  │
                  └─ DataTable
                         ├─ rowHref → /settings/sales-channels/:id
                         └─ action → /settings/sales-channels/create
```

### データフロー図

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

クエリパラメータ ─────▶ useSalesChannelTableQuery()
                              │
                              ▼
                        useSalesChannels(params)
                              │
                              ▼
                        sdk.admin.salesChannel.list() ───▶ sales_channels[]
                              │
                              ▼
                        useStore()                   ───▶ default_sales_channel_id
                              │
                              ▼
                        is_default フラグ付与        ───▶ SalesChannelWithIsDefault[]
                              │
                              ▼
                        DataTable表示
                              │
                    ┌─────────┼─────────┐
                    ▼         ▼         ▼
              行クリック   作成ボタン  アクションメニュー
                 │           │              │
                 ▼           ▼         ┌────┴────┐
              詳細画面    作成画面    編集   削除
                                              │
                                              ▼
                                       確認ダイアログ
                                              │
                                              ▼
                                       DELETE API
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sales-channel-list.tsx | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-list/sales-channel-list.tsx` | ソース | エントリーポイント |
| sales-channel-list-table.tsx | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-list/components/sales-channel-list-table.tsx` | ソース | テーブルコンポーネント |
| sales-channels.tsx | `packages/admin/dashboard/src/hooks/api/sales-channels.tsx` | ソース | APIフック |
| index.ts | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-list/index.ts` | ソース | バレルエクスポート |
| index.ts | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-list/components/index.ts` | ソース | コンポーネントエクスポート |
