# 機能設計書 27-顧客グループ管理

## 概要

本ドキュメントは、Medusaコマースプラットフォームにおける顧客グループ（Customer Group）の管理機能について記載する。

### 本機能の処理概要

本機能は、顧客をグループ化して管理するための機能である。顧客グループを作成し、複数の顧客を1つのグループにまとめることで、グループ単位でのプロモーション適用、価格設定、マーケティング施策などが可能となる。

**業務上の目的・背景**：ECサイトにおいて、顧客をセグメント化して管理することは効果的なマーケティングの基盤となる。VIP顧客、法人顧客、会員ランクなど、属性や購買行動に基づいたグループ分けを行うことで、ターゲットを絞ったプロモーションやパーソナライズされた価格設定が可能となる。

**機能の利用シーン**：
- 管理者が新しい顧客グループを作成する時（例：「VIP会員」「法人顧客」）
- 既存の顧客グループ名を変更する時
- 顧客グループを削除する時
- 特定のグループに対してプロモーションを設定する時

**主要な処理内容**：
1. 顧客グループの新規作成
2. 顧客グループの取得（単一/一覧）
3. 顧客グループの更新
4. 顧客グループの削除

**関連システム・外部連携**：
- プロモーションモジュール: グループ限定プロモーションの適用
- 価格モジュール: グループ別価格設定
- 顧客モジュール: 顧客との多対多関連

**権限による制御**：Admin APIのみで操作可能。認証された管理者のみアクセス可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 管理画面（顧客グループ一覧） | 主画面 | グループ一覧表示、作成、削除 |
| - | 管理画面（顧客グループ詳細） | 主画面 | グループ情報編集、メンバー管理 |

## 機能種別

CRUD操作

## 入力仕様

### 入力パラメータ

#### グループ作成

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | グループ名 | 一意であること |
| metadata | object | No | メタデータ | JSON形式 |

#### グループ更新

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| id | string | Yes | グループID | グループが存在すること |
| name | string | No | グループ名 | 一意であること |
| metadata | object | No | メタデータ | JSON形式 |

### 入力データソース

- Admin API: GET /admin/customer-groups（一覧取得）
- Admin API: GET /admin/customer-groups/{id}（単一取得）
- Admin API: POST /admin/customer-groups（作成）
- Admin API: POST /admin/customer-groups/{id}（更新）
- Admin API: DELETE /admin/customer-groups/{id}（削除）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| customer_group | CustomerGroupDTO | グループ情報 |
| customer_group.id | string | グループID（cusgroupプレフィックス） |
| customer_group.name | string | グループ名 |
| customer_group.customers | CustomerDTO[] | 所属顧客一覧 |
| customer_group.metadata | object | メタデータ |
| customer_group.created_by | string | 作成者ID |
| customer_group.created_at | DateTime | 作成日時 |
| customer_group.updated_at | DateTime | 更新日時 |

### 出力先

- APIレスポンス（JSON形式）
- データベース（customer_groupテーブル）

## 処理フロー

### 処理シーケンス（作成）

```
1. リクエスト受信
   └─ グループ名とメタデータを取得

2. バリデーション
   └─ グループ名の一意性検証

3. グループ作成ワークフロー実行
   └─ createCustomerGroupsWorkflow

4. イベント発行
   └─ customer_group.createdイベント

5. レスポンス返却
   └─ 作成されたグループ情報を返却
```

### フローチャート

```mermaid
flowchart TD
    A[リクエスト受信] --> B{操作種別}
    B -->|Create| C[名前一意性チェック]
    B -->|Read| D[グループ取得]
    B -->|Update| E[グループ更新]
    B -->|Delete| F[グループ削除]

    C --> G{名前重複?}
    G -->|Yes| H[エラー返却]
    G -->|No| I[グループ作成]
    I --> J[イベント発行]
    J --> K[レスポンス返却]

    D --> K

    E --> L{グループ存在?}
    L -->|No| H
    L -->|Yes| M[グループ更新実行]
    M --> J

    F --> N{グループ存在?}
    N -->|No| H
    N -->|Yes| O[論理削除]
    O --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-27-01 | グループ名一意 | グループ名は一意でなければならない | 作成・更新時 |
| BR-27-02 | 論理削除 | グループ削除は論理削除（deleted_at設定） | 削除時 |
| BR-27-03 | 顧客関連解除 | グループ削除時に顧客との関連はdetach（顧客は削除されない） | 削除時 |
| BR-27-04 | 作成者記録 | 管理者が作成した場合、created_byに管理者IDを記録 | 作成時 |
| BR-27-05 | 翻訳可能 | グループ名は多言語翻訳対応（translatable） | 表示時 |

### 計算ロジック

特になし（データ管理機能のため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 作成 | customer_group | INSERT | グループレコード作成 |
| 取得 | customer_group | SELECT | グループレコード取得 |
| 更新 | customer_group | UPDATE | グループレコード更新 |
| 削除 | customer_group | UPDATE（論理削除） | deleted_atを設定 |
| 関連解除 | customer_group_customer | DELETE | グループ削除時の中間テーブル削除 |

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

#### customer_group

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | id | 自動生成（cusgroupプレフィックス） | 主キー |
| INSERT/UPDATE | name | グループ名 | 一意制約、検索可能、翻訳可能 |
| INSERT/UPDATE | metadata | メタデータ | JSON形式 |
| INSERT/UPDATE | created_by | 作成者ID | NULL許可 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NOT_FOUND | MedusaError | グループが存在しない | 有効なグループIDを指定 |
| DUPLICATE_ERROR | MedusaError | グループ名が重複 | 別のグループ名を使用 |

### リトライ仕様

データベース接続エラー時は自動リトライが行われる場合がある。

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

- グループ作成・更新・削除は単一トランザクション内で実行
- グループ削除時の関連解除も同一トランザクション内
- エラー発生時はロールバック

## パフォーマンス要件

- 一覧取得: 500ms以内
- 単一操作（作成/更新/削除）: 300ms以内

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

- Admin APIのみで操作可能（認証必須）
- グループ名はセキュリティ上の機密情報を含まないこと

## 備考

- グループ名にはユニークインデックスが設定されている（deleted_at IS NULLの条件付き）
- nameフィールドはtranslatable（多言語対応）として設定されている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | customer-group.ts | `packages/modules/customer/src/models/customer-group.ts` | 顧客グループモデル定義 |

**主要処理フロー（customer-group.ts）**:
- **5-27行目**: CustomerGroupモデル定義
- **7行目**: IDプレフィックスはcusgroup
- **8行目**: nameはsearchable、translatable
- **9行目**: metadataはJSON、NULL許可
- **10行目**: created_byは作成者ID
- **11-14行目**: 顧客とのmanyToMany関連（中間テーブル経由）
- **16-22行目**: ユニークインデックス（nameに対して、deleted_at IS NULL条件）
- **23-25行目**: cascades.detach - 削除時に顧客関連を解除

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | route.ts | `packages/medusa/src/api/admin/customer-groups/route.ts` | Admin API顧客グループ操作 |

**主要処理フロー**:
- **13-36行目**: GET メソッド - グループ一覧取得（remoteQueryでページネーション）
- **38-64行目**: POST メソッド - グループ作成（createCustomerGroupsWorkflow使用）
- **49-50行目**: created_byに認証済み管理者IDを設定

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | customer-module.ts | `packages/modules/customer/src/services/customer-module.ts` | グループ関連メソッド |

**主要処理フロー**:
- **240-270行目**: createCustomerGroups - グループ作成
- **272-288行目**: createCustomerGroups_ - 内部実装
- **290-331行目**: updateCustomerGroups - グループ更新
- **333-378行目**: updateCustomerGroups_ - 内部実装

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

```
Admin API /admin/customer-groups
    │
    ├─ GET (一覧取得)
    │      └─ remoteQuery → customer_group テーブル
    │
    ├─ POST (作成)
    │      └─ createCustomerGroupsWorkflow
    │             └─ CustomerModuleService.createCustomerGroups
    │                    └─ customerGroupService_.create
    │
    ├─ POST /{id} (更新)
    │      └─ updateCustomerGroupsWorkflow
    │             └─ CustomerModuleService.updateCustomerGroups
    │                    └─ customerGroupService_.update
    │
    └─ DELETE /{id} (削除)
           └─ deleteCustomerGroupsWorkflow
                  └─ CustomerModuleService.softDeleteCustomerGroups
```

### データフロー図

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

グループ名       ───────▶ createCustomerGroupsWorkflow ───▶ 作成されたグループ
metadata                        │
                               └─▶ グループレコード作成 ───▶ customer_group
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| customer-group.ts | `packages/modules/customer/src/models/customer-group.ts` | ソース | 顧客グループモデル定義 |
| route.ts | `packages/medusa/src/api/admin/customer-groups/route.ts` | ソース | Admin API（一覧・作成） |
| [id]/route.ts | `packages/medusa/src/api/admin/customer-groups/[id]/route.ts` | ソース | Admin API（詳細・更新・削除） |
| customer-module.ts | `packages/modules/customer/src/services/customer-module.ts` | ソース | 顧客モジュールサービス |
