# 画面設計書 174-販売チャネル設定画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における販売チャネル設定画面（APIキー用）の設計を記述したものです。

### 本画面の処理概要

販売チャネル設定画面は、公開APIキーに紐付ける販売チャネルを選択・追加するためのモーダル画面です。公開APIキーは特定の販売チャネルに限定することで、アクセス可能な範囲を制御できます。

**業務上の目的・背景**：公開APIキーは外部クライアント（ストアフロント等）からのアクセスに使用されます。各クライアントがアクセスできる販売チャネルを制限することで、マルチテナント環境やマルチブランド運営において、適切なアクセス制御を実現します。例えば、特定のストアフロントが特定のブランドの商品のみを表示できるように制御できます。

**画面へのアクセス方法**：公開APIキー詳細画面の販売チャネルセクション > 「追加」ボタンをクリックしてアクセスします。URLは `/settings/publishable-api-keys/{id}/sales-channels` です。

**主要な操作・処理内容**：
1. 販売チャネルの一覧が表示される（既に紐付け済みのものは選択不可）
2. 追加したい販売チャネルをチェックボックスで選択
3. 「保存」ボタンをクリックして紐付けを保存

**画面遷移**：
- 遷移元：公開APIキー詳細画面（販売チャネルセクションの「追加」ボタン押下）
- 遷移先：公開APIキー詳細画面（保存成功時/キャンセル時）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 72 | APIキーCRUD | 主機能 | APIキーの販売チャネル設定 |
| 70 | 販売チャネルCRUD | API連携 | 販売チャネル一覧の取得 |

## 画面種別

設定（モーダル形式）

## URL/ルーティング

`/settings/publishable-api-keys/{id}/sales-channels`

## 入出力項目

| 項目名 | 項目ID | 種別 | 必須 | 最大長 | 説明 |
|--------|--------|------|------|--------|------|
| 販売チャネル選択 | sales_channel_ids | 入力（チェックボックス） | ○ | - | 追加する販売チャネルの選択 |

## 表示項目

### 販売チャネル一覧テーブル

| 項目名 | 説明 |
|--------|------|
| チェックボックス | 選択状態（既に紐付け済みの場合は選択不可） |
| 名前 | 販売チャネルの名前 |
| 説明 | 販売チャネルの説明 |
| ステータス | 販売チャネルの有効/無効状態 |

## イベント仕様

### 1-フォーム送信（保存ボタン押下）

1. フォームバリデーションを実行
   - 最低1つ以上の販売チャネルが選択されていることを確認
2. `useBatchAddSalesChannelsToApiKey` フックを使用してAPIを呼び出し
3. 成功時：
   - トースト通知で成功メッセージを表示
   - モーダルを閉じて詳細画面に戻る
4. エラー時：
   - トースト通知でエラーメッセージを表示

### 2-キャンセルボタン押下

モーダルを閉じ、APIキー詳細画面に戻る。

### 3-販売チャネル行クリック

チェックボックスの選択状態をトグルする（既に紐付け済みの場合は無効）。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | api_key_sales_channel | INSERT | APIキーと販売チャネルの紐付け作成 |

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

#### api_key_sales_channel

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | api_key_id | URLパラメータのID | APIキーID |
| INSERT | sales_channel_id | 選択された販売チャネルID | 販売チャネルID |

## メッセージ仕様

| 種別 | メッセージキー | 表示条件 |
|------|--------------|----------|
| 成功 | apiKeyManagement.salesChannels.successToast | 販売チャネル追加成功時 |
| エラー | (APIエラーメッセージ) | API呼び出し失敗時 |
| エラー | (フォームバリデーション) | 販売チャネル未選択時 |
| ツールチップ | apiKeyManagement.salesChannels.alreadyAddedTooltip | 既に紐付け済みの項目にホバー時 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| 販売チャネル未選択 | フォームバリデーションエラー表示 |
| APIキーが見つからない | エラーをスロー |
| API呼び出しエラー | トースト通知でエラーメッセージ表示 |

## 備考

- 既に紐付け済みの販売チャネルはチェックボックスが無効化され、ツールチップで説明が表示される
- シークレットAPIキーには販売チャネルを紐付けることはできない（公開キーのみ）
- ページネーションと検索機能が利用可能

---

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

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

### 推奨読解順序

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

フォームのスキーマと型定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | api-key-sales-channels-form.tsx | `packages/admin/dashboard/src/routes/api-key-management/api-key-management-sales-channels/components/api-key-sales-channels-form/api-key-sales-channels-form.tsx` | L35-37: Zodスキーマで最低1つの選択を必須に |

**読解のコツ**: DataTableとReact Hook Formの連携パターンを理解する。

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

モーダルコンポーネントの構成を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | api-key-management-sales-channels.tsx | `packages/admin/dashboard/src/routes/api-key-management/api-key-management-sales-channels/api-key-management-sales-channels.tsx` | L8-32: 既存の紐付け情報を取得しフォームに渡す |

**主要処理フロー**:
1. **L9**: useParamsでURLからAPIキーIDを取得
2. **L11**: useApiKeyでAPIキーデータ取得
3. **L13-17**: preSelectedで既に紐付け済みの販売チャネルIDを抽出
4. **L27-28**: ApiKeySalesChannelsFormにpreSelectedを渡す

#### Step 3: フォームコンポーネントを理解する

データテーブルとフォームの連携を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | api-key-sales-channels-form.tsx | `packages/admin/dashboard/src/routes/api-key-management/api-key-management-sales-channels/components/api-key-sales-channels-form/api-key-sales-channels-form.tsx` | L42-164: フォーム処理全体 |

**主要処理フロー**:
- **L49-54**: useFormでフォーム初期化
- **L60-61**: useBatchAddSalesChannelsToApiKeyでミューテーションフック取得
- **L63-66**: useSalesChannelTableQueryでページネーション制御
- **L79-88**: updater関数で行選択をフォーム値に同期
- **L139-142**: enableRowSelectionで既存紐付けを選択不可に

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

```
ApiKeyManagementAddSalesChannels (画面コンポーネント)
    │
    ├─ useParams() (URLパラメータ取得)
    │
    ├─ useApiKey() (APIキーデータ取得)
    │      └─ GET /admin/api-keys/{id}
    │
    └─ ApiKeySalesChannelsForm (フォームコンポーネント)
           │
           ├─ useSalesChannels() (販売チャネル一覧取得)
           │      └─ GET /admin/sales-channels
           │
           ├─ DataTable (一覧表示)
           │
           ├─ useForm() (フォーム状態管理)
           │
           └─ useBatchAddSalesChannelsToApiKey()
                  └─ POST /admin/api-keys/{id}/sales-channels
                         └─ linkSalesChannelsToApiKeyWorkflow
```

### データフロー図

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

URLパラメータ(id) ───▶ useApiKey ───────▶ 既存紐付け情報
                            │
                            ▼
                    useSalesChannels ───▶ 販売チャネル一覧
                            │
                            ▼
                       DataTable ────────▶ 選択可能な一覧表示
                            │
チェック選択 ──────────────▶│
                            │
                            ▼
              useBatchAddSalesChannelsToApiKey
                            │
                            ▼
           POST /admin/api-keys/{id}/sales-channels
                            │
                            ▼
                   紐付けレコード作成 ───▶ 詳細画面へ戻る
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| api-key-management-sales-channels.tsx | `packages/admin/dashboard/src/routes/api-key-management/api-key-management-sales-channels/api-key-management-sales-channels.tsx` | ソース | 画面エントリーポイント |
| api-key-sales-channels-form.tsx | `packages/admin/dashboard/src/routes/api-key-management/api-key-management-sales-channels/components/api-key-sales-channels-form/api-key-sales-channels-form.tsx` | ソース | フォームコンポーネント |
| api-keys.tsx | `packages/admin/dashboard/src/hooks/api/api-keys.tsx` | ソース | APIフック |
| route.ts | `packages/medusa/src/api/admin/api-keys/[id]/sales-channels/route.ts` | ソース | バックエンドAPIルート |
