# 画面設計書 126-販売チャネル詳細画面

## 概要

本ドキュメントは、Medusa Admin Dashboardにおける販売チャネル詳細画面の設計を記述したものです。個別の販売チャネルの詳細情報と、紐付けられた商品一覧を表示する画面です。

### 本画面の処理概要

この画面では、個別の販売チャネルの詳細情報を閲覧し、チャネル情報の編集・削除、および紐付けられた商品の管理を行います。

**業務上の目的・背景**：ECサイト運営において、各販売チャネルの状態を確認し、商品の公開範囲を管理することは重要な業務です。この画面は、販売チャネルの基本情報（名前、説明、有効/無効状態）の確認と、チャネルに紐付けられた商品の一覧表示・追加・削除を行うための中心的なインターフェースを提供します。

**画面へのアクセス方法**：販売チャネル一覧画面（No.124）から特定のチャネルをクリック、または販売チャネル作成完了後に自動遷移してアクセスします。URLパスは `/settings/sales-channels/:id` です。

**主要な操作・処理内容**：
1. 販売チャネルの基本情報表示（名前、説明、有効/無効状態）
2. 販売チャネル情報の編集画面への遷移
3. 販売チャネルの削除
4. 紐付けられた商品一覧の表示（ページネーション、検索、フィルタ対応）
5. 商品追加画面への遷移
6. 商品のチャネルからの削除（個別・一括）
7. メタデータ・JSONデータの表示

**画面遷移**：
- 遷移元：販売チャネル一覧画面（No.124）、販売チャネル作成画面（No.125）
- 遷移先：販売チャネル編集画面（No.127）、商品追加画面（No.128）、チャネルメタデータ編集画面（No.129）、商品詳細画面

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 70 | 販売チャネルCRUD | 主機能 | 販売チャネル詳細の表示 |
| 71 | 販売チャネル商品紐付け | 補助機能 | チャネル内商品の表示 |

## 画面種別

詳細

## URL/ルーティング

`/settings/sales-channels/:id`

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| id | 入力（URLパラメータ） | string | Yes | 販売チャネルID |
| sales_channel | 出力 | AdminSalesChannel | - | 販売チャネル情報 |
| products | 出力 | AdminProduct[] | - | 紐付けられた商品一覧 |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| name | string | 販売チャネル名（見出し） |
| is_disabled | boolean | 有効/無効状態（StatusBadgeで表示） |
| description | string | 説明（未設定の場合は「-」） |
| 商品一覧 | DataTable | 紐付けられた商品のテーブル |
| metadata | object | メタデータ |

## イベント仕様

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

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

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

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

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

- 確認ダイアログ表示内容:
  - タイトル: 「本当によろしいですか？」
  - 説明: 販売チャネル削除に関する警告メッセージ
  - 確認テキスト入力: 販売チャネル名の入力が必要
- 処理内容:
  - `DELETE /admin/sales-channels/:id` APIを呼び出し
  - 成功時: トースト通知を表示し、一覧画面へ遷移
  - 失敗時: エラーメッセージをトースト通知で表示

### 3-商品追加ボタンクリック

商品セクションの「追加」ボタンをクリックすると、商品追加画面へ遷移します。

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

### 4-商品削除（個別）

商品行のアクションメニューから「削除」を選択すると、商品をチャネルから削除します。

- 処理内容:
  - `POST /admin/sales-channels/:id/products/batch` APIを呼び出し（remove）
  - 成功時: トースト通知を表示し、商品一覧を更新

### 5-商品削除（一括）

チェックボックスで複数商品を選択し、コマンドメニューから「削除」を選択すると一括削除を実行します。

- 確認ダイアログ表示後、選択された全商品をチャネルから削除

### 6-商品行クリック

商品行をクリックすると、商品詳細画面へ遷移します。

- 遷移先URL: `/products/:product_id`

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | sales_channel | SELECT | 販売チャネル情報の取得 |
| 画面表示 | product | SELECT | 紐付き商品一覧の取得 |
| 削除ボタン押下 | sales_channel | DELETE | 販売チャネルの削除 |
| 商品削除 | sales_channel_product | DELETE | 商品紐付けの解除 |

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

#### sales_channel

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, name, description, is_disabled, metadata | id = URLパラメータのid | - |
| DELETE | - | id = URLパラメータのid | 販売チャネルの削除 |

#### product

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, title, status, thumbnail, variants | sales_channel_id = 販売チャネルID | - |

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容（i18nキー） |
|--------------|----------|------------------------|
| 成功 | 削除成功時 | salesChannels.toast.delete |
| 成功 | 商品削除成功時 | salesChannels.toast.update |
| エラー | API呼び出し失敗時 | error.message |
| 確認 | 削除確認ダイアログ | general.areYouSure, salesChannels.deleteSalesChannelWarning |
| 確認 | 商品削除確認ダイアログ | salesChannels.removeProductsWarning |
| 空状態 | 商品なし時 | salesChannels.products.list.noRecordsMessage |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 販売チャネルが見つからない | エラーをスロー（isError状態）してエラーバウンダリでハンドリング |
| ローディング中 | SingleColumnPageSkeletonでスケルトン表示 |

## 備考

- SingleColumnPageレイアウトで表示
- 拡張ポイント: `sales_channel.details.before`、`sales_channel.details.after` のウィジェットスロット
- showJSONとshowMetadataが有効

---

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

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

### 推奨読解順序

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sales-channel-detail.tsx | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-detail/sales-channel-detail.tsx` | データ取得、レイアウト構成 |
| 2-2 | loader.ts | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-detail/loader.ts` | ローダー関数 |

**主要処理フロー**:
1. **12-14行目**: useLoaderDataで事前取得データを受け取る
2. **16-19行目**: useSalesChannelでデータ取得
3. **27-40行目**: SingleColumnPageでレイアウト構成、2つのセクションを配置

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sales-channel-general-section.tsx | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-detail/components/sales-channel-general-section/sales-channel-general-section.tsx` | 基本情報表示、削除処理 |

**主要処理フロー**:
- **28行目**: useDeleteSalesChannelで削除フック取得
- **30-55行目**: handleDelete関数で削除確認と処理
- **57-99行目**: 基本情報の表示（名前、ステータスバッジ、説明）

#### Step 4: 商品セクションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | sales-channel-product-section.tsx | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-detail/components/sales-channel-product-section/sales-channel-product-section.tsx` | 商品一覧、削除処理 |

**主要処理フロー**:
- **37-52行目**: useProductsでチャネル紐付き商品を取得
- **74行目**: useSalesChannelRemoveProductsで商品削除フック取得
- **79-105行目**: handleRemove関数で一括削除処理
- **111-149行目**: DataTableで商品一覧表示

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

```
SalesChannelDetail (sales-channel-detail.tsx)
    │
    ├─ useLoaderData() → loader.ts
    │      └─ sdk.admin.salesChannel.retrieve()
    │
    ├─ useSalesChannel(id)
    │      └─ sdk.admin.salesChannel.retrieve()
    │
    └─ SingleColumnPage
           │
           ├─ SalesChannelGeneralSection
           │      │
           │      ├─ useDeleteSalesChannel()
           │      │      └─ sdk.admin.salesChannel.delete()
           │      │
           │      └─ ActionMenu
           │             ├─ Edit → /edit
           │             └─ Delete → handleDelete()
           │
           └─ SalesChannelProductSection
                  │
                  ├─ useProducts({ sales_channel_id })
                  │      └─ sdk.admin.product.list()
                  │
                  ├─ useSalesChannelRemoveProducts()
                  │      └─ sdk.admin.salesChannel.batchProducts()
                  │
                  └─ DataTable
                         ├─ Add → /add-products
                         ├─ Row click → /products/:id
                         └─ Remove → handleRemove()
```

### データフロー図

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

URLパラメータ(:id) ───▶ loader.ts
                              │
                              ▼
                        useSalesChannel(id)        ───▶ sales_channel
                              │
                              ▼
                        useProducts({
                          sales_channel_id: id
                        })                          ───▶ products[]
                              │
                              ▼
                        SingleColumnPage
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
          GeneralSection         ProductSection
                 │                      │
          ┌──────┴──────┐        ┌──────┴──────┐
          ▼             ▼        ▼             ▼
        表示         ActionMenu  DataTable   Add Button
                         │           │           │
                    ┌────┴────┐      │           ▼
                    ▼         ▼      │     /add-products
                  編集       削除    │
                              │      │
                              ▼      ▼
                           DELETE  Remove Products
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sales-channel-detail.tsx | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-detail/sales-channel-detail.tsx` | ソース | エントリーポイント |
| loader.ts | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-detail/loader.ts` | ソース | データ事前取得ローダー |
| sales-channel-general-section.tsx | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-detail/components/sales-channel-general-section/sales-channel-general-section.tsx` | ソース | 基本情報セクション |
| sales-channel-product-section.tsx | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-detail/components/sales-channel-product-section/sales-channel-product-section.tsx` | ソース | 商品セクション |
| sales-channels.tsx | `packages/admin/dashboard/src/hooks/api/sales-channels.tsx` | ソース | APIフック |
| breadcrumb.tsx | `packages/admin/dashboard/src/routes/sales-channels/sales-channel-detail/breadcrumb.tsx` | ソース | パンくずリスト |
