# 機能設計書 16-注文クレーム管理

## 概要

本ドキュメントは、Medusaコマースプラットフォームにおける注文クレーム管理機能の設計を記載したものである。注文に対するクレーム（苦情・不良品対応）処理の管理機能について、処理フロー、データ構造、ビジネスルールを定義する。

### 本機能の処理概要

注文クレーム管理機能は、ECサイトにおけるクレーム処理を一元管理するための機能である。

**業務上の目的・背景**：ECサイトにおいて、商品の不良・破損・誤配送等に対するクレーム対応は顧客満足度と信頼性維持のために重要である。本機能は、クレームの受付から解決（返金または代替品送付）までの一連のプロセスを管理し、クレーム理由・証拠画像・対応内容等を追跡可能にする。

**機能の利用シーン**：
- 顧客がクレームを申請する場面
- 管理者がクレーム内容を確認・承認する場面
- 返金または代替品送付を決定する場面
- クレームをキャンセルする場面

**主要な処理内容**：
1. クレーム（OrderClaim）の作成・取得・更新・削除
2. クレームアイテム（OrderClaimItem）の管理
3. クレーム画像（OrderClaimItemImage）の管理
4. クレームに紐づく返品の管理
5. クレームステータスの管理
6. 返金金額の管理

**関連システム・外部連携**：
- 注文モジュール：注文との紐付け
- 返品モジュール：クレームに伴う返品
- フルフィルメントモジュール：代替品配送
- 支払いモジュール：返金処理

**権限による制御**：
- クレームの作成・承認・キャンセルは管理者権限を持つユーザーのみ実行可能
- 顧客は自身の注文に対するクレーム申請のみ可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 53 | クレーム作成画面 | 主画面 | クレームリクエストの作成 |
| 43 | 注文詳細画面 | 参照画面 | クレーム履歴の表示 |

## 機能種別

CRUD操作 / 状態管理 / ワークフロー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| order_id | string | Yes | 注文ID | 有効な注文IDであること |
| type | ClaimType | Yes | クレーム種別（refund, replace） | 有効な種別であること |
| claim_items | ClaimItemInput[] | Yes | クレーム対象アイテム | 1件以上必須 |
| additional_items | ClaimItemInput[] | No | 追加アイテム（代替品） | replace時に使用 |
| refund_amount | BigNumber | No | 返金金額 | 0以上 |
| no_notification | boolean | No | 通知抑制フラグ | - |
| created_by | string | No | 作成者ID | - |
| metadata | object | No | メタデータ | JSON形式 |

### ClaimItemInput

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| item_id | string | Yes | 注文明細ID | 有効なOrderLineItemIDであること |
| quantity | number | Yes | クレーム数量 | 1以上 |
| reason | ClaimReason | No | クレーム理由 | 有効な理由であること |
| note | string | No | メモ | - |
| images | ImageInput[] | No | 証拠画像 | - |

### 入力データソース

- 管理画面：クレーム申請の作成
- 顧客画面：クレームリクエストの送信

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | クレームID（prefix: claim） |
| order_id | string | 注文ID |
| order_version | number | 注文バージョン |
| display_id | number | 表示用ID（自動採番） |
| type | ClaimType | クレーム種別 |
| refund_amount | BigNumber | 返金金額 |
| created_by | string | 作成者ID |
| canceled_at | Date | キャンセル日時 |
| claim_items | OrderClaimItem[] | クレーム対象アイテム |
| additional_items | OrderClaimItem[] | 追加アイテム |
| return | Return | 紐づく返品 |
| shipping_methods | OrderShipping[] | 配送方法 |
| transactions | OrderTransaction[] | トランザクション |

### 出力先

- データベース：order_claim、order_claim_item、claim_item_imageテーブル
- API応答：OrderClaimDTO形式

## 処理フロー

### 処理シーケンス

```
1. クレーム作成リクエスト受信
   └─ order_id、type、claim_items等を含むリクエストを受信

2. 注文存在確認・バージョン取得
   └─ 対象注文の存在確認とバージョン取得

3. クレームの作成
   └─ OrderClaimレコードを作成
   └─ OrderChangeを作成

4. クレームアイテムの作成
   └─ OrderClaimItemレコードを作成
   └─ 画像がある場合はOrderClaimItemImageを作成
   └─ OrderChangeActionを追加

5. 返品の作成（必要に応じて）
   └─ クレーム対象商品の返品Returnを作成

6. 変更の確認
   └─ confirmOrderChangeで変更を確定

7. 後続処理
   └─ type=refund: 返金処理
   └─ type=replace: 代替品発送
```

### フローチャート

```mermaid
flowchart TD
    A[クレーム作成リクエスト] --> B[注文存在確認]
    B --> C{注文が存在?}
    C -->|No| D[エラー返却]
    C -->|Yes| E[OrderClaim作成]
    E --> F[OrderClaimItem作成]
    F --> G{画像あり?}
    G -->|Yes| H[ClaimItemImage作成]
    G -->|No| I[Return作成]
    H --> I
    I --> J[OrderChange作成]
    J --> K[confirmOrderChange]
    K --> L{type?}
    L -->|refund| M[返金処理]
    L -->|replace| N[代替品発送]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-16-01 | クレーム種別 | type=refundは返金、type=replaceは代替品送付 | クレーム作成時 |
| BR-16-02 | 追加アイテム | type=replaceの場合のみadditional_itemsを設定可能 | クレーム作成時 |
| BR-16-03 | 返品連携 | クレーム対象商品は自動的に返品（Return）と紐付けられる | クレーム作成時 |
| BR-16-04 | 画像管理 | クレームアイテムには証拠画像を添付可能 | クレーム作成時 |
| BR-16-05 | カスケード削除 | OrderClaim削除時はadditional_items、claim_items、transactionsも削除 | 削除時 |

### 計算ロジック

- 返金金額は手動設定または自動計算（クレームアイテムの合計金額）
- 差額計算：追加アイテム金額 - クレームアイテム金額

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| クレーム作成 | order_claim | INSERT | クレームレコードの作成 |
| クレーム作成 | order_claim_item | INSERT | クレームアイテムの作成 |
| クレーム作成 | claim_item_image | INSERT | 画像の作成 |
| クレーム作成 | return | INSERT | 紐づく返品の作成 |
| クレーム作成 | order_change | INSERT | 注文変更の作成 |
| クレームキャンセル | order_claim | UPDATE | canceled_at更新 |

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

#### order_claim

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（prefix: claim） | 主キー |
| INSERT | order_id | 対象注文ID | 外部キー |
| INSERT | order_version | 注文の現在バージョン | 整数 |
| INSERT | display_id | 自動採番 | 表示用 |
| INSERT | type | リクエストのtype | ClaimType |
| INSERT | refund_amount | リクエストのrefund_amount | BigNumber |
| INSERT | created_by | リクエストのcreated_by | nullable |
| INSERT | return_id | 作成された返品ID | nullable |
| UPDATE (cancel) | canceled_at | 現在日時 | - |

#### order_claim_item

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（prefix: claitem） | 主キー |
| INSERT | claim_id | 親のクレームID | 外部キー |
| INSERT | item_id | 注文明細ID | 外部キー |
| INSERT | quantity | リクエストのquantity | BigNumber |
| INSERT | reason | リクエストのreason | ClaimReason |
| INSERT | is_additional_item | false（通常）/ true（追加） | ブール値 |
| INSERT | note | リクエストのnote | nullable |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NOT_FOUND | MedusaError | 指定されたorder_idの注文が存在しない | 有効な注文IDを指定 |
| INVALID_DATA | MedusaError | クレームアイテムが空 | 1件以上のアイテムを指定 |
| INVALID_DATA | MedusaError | type=refundでadditional_itemsを指定 | additional_itemsを削除 |
| NOT_ALLOWED | MedusaError | 既にキャンセルされたクレームを操作 | キャンセル済みクレームは操作不可 |

### リトライ仕様

データベース操作はトランザクション内で実行されるため、失敗時は自動ロールバックされる。

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

- `@InjectTransactionManager`デコレータにより、クレーム作成・キャンセル処理はトランザクション内で実行
- クレーム作成時はOrderClaim、OrderClaimItem、Return、OrderChange等が同一トランザクション内で作成
- 処理失敗時は全ての変更がロールバックされる

## パフォーマンス要件

- クレーム作成：500ms以内
- クレーム一覧取得：100件以下で500ms以内
- インデックス：order_id、return_idにインデックス設定

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

- クレームの作成・承認・キャンセルは認証済み管理者のみ実行可能
- 証拠画像は適切に保護・管理
- クレーム情報は監査ログに記録

## 備考

- ClaimTypeの値：refund, replace
- ClaimReasonの値：missing_item, wrong_item, production_failure, other等
- クレームは必ず返品（Return）と紐付けられる設計

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | claim.ts | `packages/modules/order/src/models/claim.ts` | OrderClaimエンティティ、type/refund_amount/order_versionプロパティ、return/claim_items/additional_itemsリレーション |
| 1-2 | claim-item.ts | `packages/modules/order/src/models/claim-item.ts` | OrderClaimItemエンティティ、reason/is_additional_item/imagesプロパティ |

**読解のコツ**:
- **9-18行目 (claim.ts)**: type、refund_amount等の主要プロパティ
- **23-52行目 (claim.ts)**: return、additional_items、claim_items、shipping_methods、transactionsリレーション
- **9-11行目 (claim-item.ts)**: reason（ClaimReason enum）、is_additional_itemフラグ

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | order-module-service.ts | `packages/modules/order/src/services/order-module-service.ts` | 566-630行：retrieveOrderClaim、listOrderClaims、listAndCountOrderClaimsメソッド |
| 2-2 | create-claim.ts | `packages/modules/order/src/services/actions/create-claim.ts` | クレーム作成の詳細ロジック |
| 2-3 | cancel-claim.ts | `packages/modules/order/src/services/actions/cancel-claim.ts` | クレームキャンセルの詳細ロジック |

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

```
createClaim (actions/create-claim.ts)
    ├─ orderClaimService_.create
    ├─ orderClaimItemService_.create
    ├─ claimItemImageService_.create
    ├─ Return作成（返品連携）
    ├─ createOrderChange_
    └─ confirmOrderChange

cancelClaim (actions/cancel-claim.ts)
    ├─ createOrderChange_
    ├─ orderClaimService_.update (canceled_at)
    └─ confirmOrderChange
```

### データフロー図

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

CreateClaimDTO ──────────▶ createClaim ──────────────▶ order_claim テーブル
       │                        │
       │                        ├─▶ claimItemService_ ──▶ order_claim_item テーブル
       │                        │
       │                        ├─▶ imageService_ ──────▶ claim_item_image テーブル
       │                        │
       │                        ├─▶ returnService_ ─────▶ return テーブル
       │                        │
       v                        v
 order_id, type,          confirmOrderChange           OrderClaimDTO
 claim_items
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| claim.ts | `packages/modules/order/src/models/claim.ts` | ソース | OrderClaimエンティティ定義 |
| claim-item.ts | `packages/modules/order/src/models/claim-item.ts` | ソース | OrderClaimItemエンティティ定義 |
| claim-item-image.ts | `packages/modules/order/src/models/claim-item-image.ts` | ソース | OrderClaimItemImageエンティティ定義 |
| order-module-service.ts | `packages/modules/order/src/services/order-module-service.ts` | ソース | サービス層（retrieve/list） |
| create-claim.ts | `packages/modules/order/src/services/actions/create-claim.ts` | ソース | クレーム作成アクション |
| cancel-claim.ts | `packages/modules/order/src/services/actions/cancel-claim.ts` | ソース | クレームキャンセルアクション |
