# 機能設計書 28-顧客グループメンバー管理

## 概要

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

### 本機能の処理概要

本機能は、顧客グループに対して顧客を追加または削除する機能である。顧客と顧客グループの多対多関係を管理し、1人の顧客が複数のグループに所属したり、1つのグループに複数の顧客が所属することを可能にする。中間テーブル（CustomerGroupCustomer）を通じて関連を管理する。

**業務上の目的・背景**：顧客セグメンテーションを効果的に行うためには、顧客を適切なグループに分類する必要がある。マーケティングキャンペーンの対象者選定、グループ限定価格の適用、特定グループへのプロモーション配信などに活用される。顧客のステータス変化（VIP昇格、法人契約等）に応じて、柔軟にグループメンバーシップを変更できることが重要。

**機能の利用シーン**：
- 管理者が顧客を特定のグループに追加する時
- 管理者が顧客をグループから削除する時
- 顧客の詳細画面から所属グループを変更する時
- バルク操作で複数の顧客を一括でグループに追加/削除する時

**主要な処理内容**：
1. 顧客をグループに追加
2. 顧客をグループから削除
3. グループ内の顧客一覧取得
4. 顧客の所属グループ一覧取得

**関連システム・外部連携**：
- 顧客モジュール: 顧客データとの関連
- 顧客グループモジュール: グループデータとの関連

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 管理画面（顧客グループ詳細） | 主画面 | グループメンバー追加・削除 |
| - | 管理画面（顧客詳細） | 主画面 | 所属グループ変更 |

## 機能種別

CRUD操作

## 入力仕様

### 入力パラメータ

#### グループへの顧客追加

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| customer_group_id | string | Yes | グループID | グループが存在すること |
| customer_id | string | Yes | 顧客ID | 顧客が存在すること |

#### グループからの顧客削除

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| customer_group_id | string | Yes | グループID | グループが存在すること |
| customer_id | string | Yes | 顧客ID | 顧客が存在すること |

### 入力データソース

- Admin API: POST /admin/customer-groups/{id}/customers（顧客追加）
- Admin API: DELETE /admin/customer-groups/{id}/customers（顧客削除）
- Admin API: POST /admin/customers/{id}/customer-groups（グループ追加）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | 中間テーブルレコードID（cusgcプレフィックス） |
| customer_group_id | string | グループID |
| customer_id | string | 顧客ID |
| created_by | string | 作成者ID |
| metadata | object | メタデータ |

### 出力先

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

## 処理フロー

### 処理シーケンス（追加）

```
1. リクエスト受信
   └─ customer_group_idとcustomer_idを取得

2. 存在確認
   ├─ グループの存在確認
   └─ 顧客の存在確認

3. 重複チェック
   └─ 既に関連が存在するか確認

4. 関連作成
   └─ addCustomerToGroup実行

5. イベント発行
   └─ customer_group_customer.attachedイベント

6. レスポンス返却
   └─ 作成された関連情報を返却
```

### フローチャート

```mermaid
flowchart TD
    A[リクエスト受信] --> B{操作種別}
    B -->|追加| C[グループ・顧客存在確認]
    B -->|削除| D[関連存在確認]

    C --> E{存在する?}
    E -->|No| F[エラー返却]
    E -->|Yes| G{既に関連あり?}
    G -->|Yes| H[既存関連を返却]
    G -->|No| I[関連作成]
    I --> J[イベント発行]
    J --> K[レスポンス返却]

    D --> L{関連存在?}
    L -->|No| F
    L -->|Yes| M[関連削除]
    M --> N[イベント発行]
    N --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-28-01 | 重複追加防止 | 同一顧客を同一グループに重複追加できない | 追加時 |
| BR-28-02 | 複数グループ所属 | 1人の顧客は複数のグループに所属可能 | 常時 |
| BR-28-03 | 複数顧客所属 | 1つのグループには複数の顧客が所属可能 | 常時 |
| BR-28-04 | 作成者記録 | 関連作成時にcreated_byに管理者IDを記録 | 追加時 |
| BR-28-05 | グループ削除時解除 | グループ削除時は関連がdetach（顧客は削除されない） | グループ削除時 |
| BR-28-06 | 顧客削除時解除 | 顧客削除時は関連がdetach（グループは削除されない） | 顧客削除時 |

### 計算ロジック

特になし（関連管理機能のため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 追加 | customer_group_customer | INSERT | 関連レコード作成 |
| 削除 | customer_group_customer | DELETE | 関連レコード削除 |

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

#### customer_group_customer

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（cusgcプレフィックス） | 主キー |
| INSERT | customer_id | 顧客ID | 外部キー |
| INSERT | customer_group_id | グループID | 外部キー |
| INSERT | created_by | 作成者ID | NULL許可 |
| INSERT | metadata | メタデータ | JSON形式 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NOT_FOUND | MedusaError | グループが存在しない | 有効なグループIDを指定 |
| NOT_FOUND | MedusaError | 顧客が存在しない | 有効な顧客IDを指定 |
| NOT_FOUND | MedusaError | 関連が存在しない（削除時） | 正しい組み合わせを指定 |

### リトライ仕様

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

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

- 関連の追加・削除は単一トランザクション内で実行
- エラー発生時はロールバック

## パフォーマンス要件

- 単一操作（追加/削除）: 300ms以内
- バルク操作: 顧客数 x 50ms程度

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

- Admin APIのみで操作可能（認証必須）
- グループメンバーシップ情報は業務上重要な情報として管理

## 備考

- 中間テーブルのIDプレフィックスはcusgc
- CustomerGroupCustomerモデルはpivotEntity（中間テーブル）として定義されている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | customer-group-customer.ts | `packages/modules/customer/src/models/customer-group-customer.ts` | 中間テーブルモデル定義 |

**主要処理フロー（customer-group-customer.ts）**:
- **5-17行目**: CustomerGroupCustomerモデル定義
- **6行目**: IDプレフィックスはcusgc
- **7行目**: created_byフィールド
- **8行目**: metadataフィールド
- **9-11行目**: 顧客とのbelongsTo関連
- **12-14行目**: グループとのbelongsTo関連

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

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

**主要処理フロー**:
- **380-420行目**: addCustomerToGroup - 顧客をグループに追加
- **401-419行目**: addCustomerToGroup_ - 内部実装、customerGroupCustomerService_.createを呼び出し
- **562-593行目**: removeCustomerFromGroup - 顧客をグループから削除
- **580-592行目**: removeCustomerFromGroup_ - 内部実装

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

```
Admin API /admin/customer-groups/{id}/customers
    │
    ├─ POST (追加)
    │      └─ linkCustomersToGroupWorkflow
    │             └─ CustomerModuleService.addCustomerToGroup
    │                    └─ customerGroupCustomerService_.create
    │
    └─ DELETE (削除)
           └─ unlinkCustomersFromGroupWorkflow
                  └─ CustomerModuleService.removeCustomerFromGroup
                         ├─ customerGroupCustomerService_.list
                         └─ customerGroupCustomerService_.delete
```

### データフロー図

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

customer_group_id ───┐
                    ├──▶ addCustomerToGroup ───▶ 関連レコード
customer_id      ───┘         │
                              └─▶ 中間テーブル作成 ───▶ customer_group_customer
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| customer-group-customer.ts | `packages/modules/customer/src/models/customer-group-customer.ts` | ソース | 中間テーブルモデル定義 |
| customer-module.ts | `packages/modules/customer/src/services/customer-module.ts` | ソース | 顧客モジュールサービス |
| customer.ts | `packages/modules/customer/src/models/customer.ts` | ソース | 顧客モデル（グループ関連） |
| customer-group.ts | `packages/modules/customer/src/models/customer-group.ts` | ソース | グループモデル（顧客関連） |
