# 機能設計書 70-販売チャネルCRUD

## 概要

本ドキュメントは、Medusaコマースプラットフォームにおける販売チャネルのCRUD機能の設計を記述する。販売チャネルの作成、取得、更新、削除を提供する。

### 本機能の処理概要

**業務上の目的・背景**：ECビジネスでは、ウェブサイト、モバイルアプリ、マーケットプレイス、店舗POS等、複数の販売チャネルで商品を販売することが一般的である。販売チャネルCRUD機能は、各チャネルを定義・管理し、商品をチャネルごとに紐付けることで、チャネル別の在庫管理や販売戦略を実現する。APIキーと連携することで、チャネルごとのアクセス制御も可能となる。

**機能の利用シーン**：
- 新規販売チャネルの作成（例：「Webshop」「Mobile App」）
- 販売チャネル一覧画面での確認
- 販売チャネル名・説明の更新
- 販売チャネルの有効化・無効化
- 不要になった販売チャネルの削除

**主要な処理内容**：
1. 販売チャネル一覧取得（フィルタ・ページネーション対応）
2. 販売チャネル詳細取得
3. 販売チャネル作成
4. 販売チャネル更新（名前、説明、is_disabled）
5. 販売チャネル削除（デフォルトチャネルは削除不可）

**関連システム・外部連携**：
- 商品モジュールとの連携（チャネルと商品の紐付け）
- APIキーモジュールとの連携（チャネルごとのアクセス制御）
- ストアモジュールとの連携（デフォルト販売チャネル設定）
- 在庫ロケーションモジュールとの連携（チャネルとロケーションの紐付け）

**権限による制御**：販売チャネルの作成・更新・削除は認証済み管理者のみ可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | 商品作成画面 | API連携 | 販売チャネル情報の取得 |
| 124 | 販売チャネル一覧画面 | 主画面 | 販売チャネル一覧の取得・表示 |
| 125 | 販売チャネル作成画面 | 主画面 | 新規販売チャネルの作成 |
| 126 | 販売チャネル詳細画面 | 主画面 | 販売チャネル詳細の表示 |
| 127 | 販売チャネル編集画面 | 主画面 | 販売チャネル情報の編集 |
| 129 | チャネルメタデータ編集画面 | 主画面 | チャネルメタデータの編集 |
| 134 | 販売チャネル設定画面 | 主画面 | ロケーションの販売チャネル設定 |
| 174 | 販売チャネル設定画面 | API連携 | APIキーの販売チャネル設定 |

## 機能種別

CRUD操作

## 入力仕様

### 入力パラメータ

#### 販売チャネル作成

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | 販売チャネル名 | - |
| description | string | No | 説明 | - |
| is_disabled | boolean | No | 無効化フラグ | デフォルトfalse |
| metadata | object | No | メタデータ | - |

#### 販売チャネル更新

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| id | string | Yes | 販売チャネルID | 存在するチャネル |
| name | string | No | 販売チャネル名 | - |
| description | string | No | 説明 | - |
| is_disabled | boolean | No | 無効化フラグ | - |
| metadata | object | No | メタデータ | - |

#### 一覧取得

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| q | string | No | 検索クエリ | - |
| id | string[] | No | IDフィルタ | - |
| name | string[] | No | 名前フィルタ | - |
| is_disabled | boolean | No | 無効フラグフィルタ | - |
| limit | number | No | 取得件数 | 1以上 |
| offset | number | No | オフセット | 0以上 |

### 入力データソース

- Admin API HTTPリクエスト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | 販売チャネルID（sc_プレフィックス） |
| name | string | 販売チャネル名 |
| description | string | null | 説明 |
| is_disabled | boolean | 無効化フラグ |
| metadata | object | null | メタデータ |
| created_at | Date | 作成日時 |
| updated_at | Date | 更新日時 |
| deleted_at | Date | null | 削除日時 |

### 出力先

- Admin API HTTPレスポンス
- イベント発行（sales_channel.created, sales_channel.updated, sales_channel.deleted）

## 処理フロー

### 処理シーケンス

```
1. 販売チャネル一覧取得
   └─ remoteQueryでsales_channelsテーブル検索

2. 販売チャネル詳細取得
   └─ remoteQueryでID指定検索

3. 販売チャネル作成
   ├─ createSalesChannelsWorkflow実行
   ├─ createSalesChannelsStep実行
   └─ イベント発行（CREATED）

4. 販売チャネル更新
   ├─ 存在確認
   ├─ updateSalesChannelsWorkflow実行
   └─ 更新結果返却

5. 販売チャネル削除
   ├─ デフォルトチャネルチェック
   ├─ deleteSalesChannelsWorkflow実行
   └─ 削除結果返却
```

### フローチャート

```mermaid
flowchart TD
    A[API リクエスト] --> B{操作種別}
    B -->|GET /sales-channels| C[チャネル一覧取得]
    B -->|GET /sales-channels/:id| D[チャネル詳細取得]
    B -->|POST /sales-channels| E[チャネル作成]
    B -->|POST /sales-channels/:id| F[チャネル更新]
    B -->|DELETE /sales-channels/:id| G[チャネル削除]

    C --> H[remoteQuery実行]
    D --> H
    H --> I[結果返却]

    E --> J[createSalesChannelsWorkflow]
    J --> K[createSalesChannelsStep]
    K --> L[イベント発行]
    L --> I

    F --> M[存在確認]
    M --> N{存在する?}
    N -->|No| O[NOT_FOUNDエラー]
    N -->|Yes| P[updateSalesChannelsWorkflow]
    P --> Q[refetchSalesChannel]
    Q --> I

    G --> R[canDeleteSalesChannelsStep]
    R --> S{削除可能?}
    S -->|No| T[NOT_ALLOWEDエラー]
    S -->|Yes| U[deleteSalesChannelsStep]
    U --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-70-01 | 名前必須 | 販売チャネル作成時、nameは必須 | 作成時 |
| BR-70-02 | 無効化デフォルト | is_disabledはデフォルトfalse（有効状態） | 作成時 |
| BR-70-03 | デフォルト削除禁止 | ストアのデフォルト販売チャネルは削除不可 | 削除時 |
| BR-70-04 | ソフトデリート | 販売チャネル削除はdeleted_at設定による論理削除 | 削除時 |

### 計算ロジック

特になし

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 一覧取得 | sales_channel | SELECT | フィルタ・ページネーション付き |
| 詳細取得 | sales_channel | SELECT | ID指定 |
| 作成 | sales_channel | INSERT | 新規チャネルレコード |
| 更新 | sales_channel | UPDATE | チャネル情報更新 |
| 削除 | sales_channel | UPDATE | deleted_at設定 |

### テーブル別操作詳細

#### sales_channel

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（sc_プレフィックス） | - |
| INSERT | name | 入力値 | searchable |
| INSERT | description | 入力値 | nullable, searchable |
| INSERT | is_disabled | 入力値またはfalse | デフォルトfalse |
| INSERT | metadata | 入力値 | nullable |
| UPDATE | name, description, is_disabled, metadata | 入力値 | 指定されたフィールドのみ更新 |
| UPDATE | deleted_at | 現在日時 | ソフトデリート時 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NOT_FOUND | MedusaError | 指定IDのチャネルが存在しない | 404レスポンス |
| NOT_ALLOWED | MedusaError | デフォルトチャネルを削除しようとした | 400レスポンス |

### リトライ仕様

データベース操作失敗時のリトライはワークフローエンジンで管理。

## トランザクション仕様

- チャネル作成・更新・削除はワークフロー内でトランザクション管理
- @InjectTransactionManagerデコレータで内部トランザクションを制御

## パフォーマンス要件

- name, descriptionカラムはsearchableで全文検索対応
- IDに主キーインデックス

## セキュリティ考慮事項

- 認証必須エンドポイント
- RBACによる権限制御可能
- is_disabledによるチャネル無効化が可能

## 備考

- 販売チャネルIDはsc_プレフィックス付きで自動生成
- 商品との紐付けは別途「販売チャネル商品紐付け」機能で管理

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sales-channel.ts | `packages/modules/sales-channel/src/models/sales-channel.ts` | SalesChannelモデルの構造（id, name, description, is_disabled, metadata） |

**読解のコツ**: シンプルなモデル構造。name, descriptionはsearchable。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | route.ts | `packages/medusa/src/api/admin/sales-channels/route.ts` | GET - 一覧取得、POST - 作成 |
| 2-2 | [id]/route.ts | `packages/medusa/src/api/admin/sales-channels/[id]/route.ts` | GET, POST, DELETE - 個別操作 |

**主要処理フロー**:
1. **route.ts 13-36行目**: 一覧取得、remoteQuery使用
2. **route.ts 38-58行目**: 作成処理、createSalesChannelsWorkflow使用
3. **[id]/route.ts 13-31行目**: 詳細取得
4. **[id]/route.ts 33-66行目**: 更新処理、updateSalesChannelsWorkflow使用
5. **[id]/route.ts 68-83行目**: 削除処理、deleteSalesChannelsWorkflow使用

#### Step 3: サービス層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sales-channel-module.ts | `packages/modules/sales-channel/src/services/sales-channel-module.ts` | SalesChannelModuleServiceの実装 |

**主要処理フロー**:
- **70-84行目**: createSalesChannels - 作成処理
- **86-92行目**: createSalesChannels_ - 内部作成処理
- **107-139行目**: updateSalesChannels - 更新処理

#### Step 4: ワークフローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | create-sales-channels.ts | `packages/core/core-flows/src/sales-channel/workflows/create-sales-channels.ts` | 作成ワークフロー |
| 4-2 | delete-sales-channels.ts | `packages/core/core-flows/src/sales-channel/workflows/delete-sales-channels.ts` | 削除ワークフロー |

**主要処理フロー**:
- **create-sales-channels.ts 54-79行目**: チャネル作成、イベント発行

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

```
Admin API Route
    │
    ├─ GET /sales-channels
    │      └─ remoteQuery (sales_channels エントリーポイント)
    │
    ├─ POST /sales-channels
    │      └─ createSalesChannelsWorkflow
    │             ├─ createSalesChannelsStep
    │             │      └─ salesChannelService.createSalesChannels
    │             └─ emitEventStep (CREATED)
    │
    ├─ POST /sales-channels/:id
    │      └─ updateSalesChannelsWorkflow
    │             └─ updateSalesChannelsStep
    │                    └─ salesChannelService.updateSalesChannels
    │
    └─ DELETE /sales-channels/:id
           └─ deleteSalesChannelsWorkflow
                  ├─ canDeleteSalesChannelsStep
                  │      └─ ストアのデフォルトチャネルチェック
                  └─ deleteSalesChannelsStep
                         └─ salesChannelService.softDeleteSalesChannels
```

### データフロー図

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

販売チャネル作成
  name ─────────────────▶ createSalesChannelsStep ───▶ SalesChannel record
  description                    │
  is_disabled                    ▼
  metadata                  emitEventStep
                                 │
                                 ▼
                         sales_channel.created イベント

販売チャネル削除
  id ───────────────────▶ canDeleteSalesChannelsStep
                                 │
                         ┌───────┴───────┐
                         ▼               ▼
                   削除可能         デフォルトチャネル
                         │               │
                         ▼               ▼
              deleteSalesChannelsStep   NOT_ALLOWEDエラー
                         │
                         ▼
                   deleted_at設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sales-channel.ts | `packages/modules/sales-channel/src/models/sales-channel.ts` | ソース | SalesChannelモデル定義 |
| sales-channel-module.ts | `packages/modules/sales-channel/src/services/sales-channel-module.ts` | ソース | SalesChannelModuleService |
| route.ts | `packages/medusa/src/api/admin/sales-channels/route.ts` | ソース | チャネル一覧・作成API |
| [id]/route.ts | `packages/medusa/src/api/admin/sales-channels/[id]/route.ts` | ソース | チャネル詳細・更新・削除API |
| create-sales-channels.ts | `packages/core/core-flows/src/sales-channel/workflows/create-sales-channels.ts` | ソース | 作成ワークフロー |
| update-sales-channels.ts | `packages/core/core-flows/src/sales-channel/workflows/update-sales-channels.ts` | ソース | 更新ワークフロー |
| delete-sales-channels.ts | `packages/core/core-flows/src/sales-channel/workflows/delete-sales-channels.ts` | ソース | 削除ワークフロー |
| can-delete-sales-channels.ts | `packages/core/core-flows/src/sales-channel/steps/can-delete-sales-channels.ts` | ソース | 削除可否チェックステップ |
