# 機能設計書 15-返品管理

## 概要

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

### 本機能の処理概要

返品管理機能は、ECサイトにおける返品処理を一元管理するための機能である。

**業務上の目的・背景**：ECサイトにおいて、顧客からの返品依頼に対応することは顧客満足度維持のために重要である。本機能は、返品依頼の受付から返金までの一連のプロセスを管理し、返品アイテム・返品理由・返金金額等を追跡可能にする。

**機能の利用シーン**：
- 顧客が返品を申請する場面
- 管理者が返品依頼を確認・承認する場面
- 倉庫で返品商品を受領する場面
- 返金処理を実行する場面
- 返品をキャンセルする場面

**主要な処理内容**：
1. 返品（Return）の作成・取得・更新・削除
2. 返品アイテム（ReturnItem）の管理
3. 返品の受領処理（receiveReturn）
4. 返品のキャンセル処理（cancelReturn）
5. 返品ステータスの管理
6. 返金金額の管理

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| order_id | string | Yes | 注文ID | 有効な注文IDであること |
| items | ReturnItemInput[] | Yes | 返品アイテム情報 | 1件以上必須 |
| location_id | string | No | 返品先ロケーションID | - |
| refund_amount | BigNumber | No | 返金金額 | 0以上 |
| no_notification | boolean | No | 通知抑制フラグ | - |
| created_by | string | No | 作成者ID | - |
| metadata | object | No | メタデータ | JSON形式 |

### ReturnItemInput

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| item_id | string | Yes | 注文明細ID | 有効なOrderLineItemIDであること |
| quantity | number | Yes | 返品数量 | 1以上、注文数量以下 |
| reason_id | string | No | 返品理由ID | 有効なReturnReasonIDであること |
| note | string | No | メモ | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | 返品ID（prefix: return） |
| order_id | string | 注文ID |
| order_version | number | 注文バージョン |
| display_id | number | 表示用ID（自動採番） |
| status | ReturnStatus | ステータス（open, requested, received等） |
| location_id | string | 返品先ロケーションID |
| refund_amount | BigNumber | 返金金額 |
| created_by | string | 作成者ID |
| requested_at | Date | リクエスト日時 |
| received_at | Date | 受領日時 |
| canceled_at | Date | キャンセル日時 |
| items | ReturnItem[] | 返品アイテム一覧 |
| shipping_methods | OrderShipping[] | 返品配送方法 |
| transactions | OrderTransaction[] | 返金トランザクション |

### 出力先

- データベース：return、return_itemテーブル
- API応答：ReturnDTO形式

## 処理フロー

### 処理シーケンス

```
1. 返品作成リクエスト受信
   └─ order_id、items等を含むリクエストを受信

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

3. 返品の作成
   └─ Returnレコードを作成（status: OPEN）
   └─ OrderChangeを作成

4. 返品アイテムの作成
   └─ ReturnItemレコードを作成
   └─ OrderChangeActionを追加

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

6. 受領処理（後続）
   └─ receiveReturnで返品商品を受領
   └─ received_quantityを更新
   └─ status: RECEIVEDに更新

7. 返金処理（後続）
   └─ 返金トランザクションを作成
```

### フローチャート

```mermaid
flowchart TD
    A[返品作成リクエスト] --> B[注文存在確認]
    B --> C{注文が存在?}
    C -->|No| D[エラー返却]
    C -->|Yes| E[Return作成 status=OPEN]
    E --> F[ReturnItem作成]
    F --> G[OrderChange作成]
    G --> H[confirmOrderChange]
    H --> I[返品作成完了]
    I --> J{受領?}
    J -->|Yes| K[receiveReturn]
    K --> L[status=RECEIVED]
    J -->|No| M{キャンセル?}
    M -->|Yes| N[cancelReturn]
    N --> O[status=CANCELED]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-15-01 | バージョン管理 | 返品作成時に注文のバージョンを記録（order_version） | 返品作成時 |
| BR-15-02 | 表示ID自動採番 | display_idは自動採番される | 返品作成時 |
| BR-15-03 | ステータス遷移 | OPEN → REQUESTED → RECEIVED または OPEN → CANCELED | 状態遷移時 |
| BR-15-04 | 受領数量管理 | received_quantity、damaged_quantityで受領状況を管理 | 受領処理時 |
| BR-15-05 | カスケード削除 | Return削除時はitems、shipping_methods、transactionsも削除 | 削除時 |

### 計算ロジック

- 返金金額は手動設定または自動計算（返品アイテムの合計金額）
- 合計金額計算時はtax_lines、adjustmentsを考慮

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 返品作成 | return | INSERT | 返品レコードの作成 |
| 返品作成 | return_item | INSERT | 返品アイテムの作成 |
| 返品作成 | order_change | INSERT | 注文変更の作成 |
| 返品作成 | order_change_action | INSERT | 変更アクションの作成 |
| 返品受領 | return | UPDATE | status, received_at更新 |
| 返品受領 | return_item | UPDATE | received_quantity更新 |
| 返品キャンセル | return | UPDATE | status, canceled_at更新 |

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

#### return

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

#### return_item

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（prefix: retitem） | 主キー |
| INSERT | return_id | 親の返品ID | 外部キー |
| INSERT | item_id | 注文明細ID | 外部キー |
| INSERT | quantity | リクエストのquantity | BigNumber |
| INSERT | received_quantity | 0 | 初期値 |
| INSERT | damaged_quantity | 0 | 初期値 |
| INSERT | reason_id | リクエストのreason_id | nullable |
| INSERT | note | リクエストのnote | nullable |
| UPDATE (receive) | received_quantity | 受領数量 | - |
| UPDATE (receive) | damaged_quantity | 損傷数量 | - |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NOT_FOUND | MedusaError | 指定されたorder_idの注文が存在しない | 有効な注文IDを指定 |
| INVALID_DATA | MedusaError | 返品アイテムが空 | 1件以上のアイテムを指定 |
| INVALID_DATA | MedusaError | 返品数量が注文数量を超過 | 正しい数量を指定 |
| NOT_ALLOWED | MedusaError | 既にキャンセルされた返品を操作 | キャンセル済み返品は操作不可 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 返品作成：500ms以内
- 返品一覧取得：100件以下で500ms以内
- インデックス：order_id、exchange_id、claim_idにインデックス設定

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

- 返品の作成・承認・キャンセルは認証済み管理者のみ実行可能
- 返金情報は監査ログに記録
- 顧客は自身の注文に関連する返品のみ参照可能

## 備考

- ReturnStatusの値：OPEN, REQUESTED, RECEIVED, PARTIALLY_RECEIVED, CANCELED
- 返品は交換（Exchange）またはクレーム（Claim）と紐付け可能
- 返品配送（shipping_methods）と返金トランザクション（transactions）を保持

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | return.ts | `packages/modules/order/src/models/return.ts` | Returnエンティティ、status/refund_amount/order_versionプロパティ、items/shipping_methods/transactionsリレーション |
| 1-2 | return-item.ts | `packages/modules/order/src/models/return-item.ts` | ReturnItemエンティティ、quantity/received_quantity/damaged_quantityプロパティ |

**読解のコツ**:
- **9-22行目 (return.ts)**: status、location_id、refund_amount等の主要プロパティ
- **38-52行目 (return.ts)**: items、shipping_methods、transactionsリレーション
- **54-56行目 (return.ts)**: カスケード削除の設定

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | order-module-service.ts | `packages/modules/order/src/services/order-module-service.ts` | 509-564行：retrieveReturn、listReturns、listAndCountReturnsメソッド |
| 2-2 | create-return.ts | `packages/modules/order/src/services/actions/create-return.ts` | 返品作成の詳細ロジック |
| 2-3 | receive-return.ts | `packages/modules/order/src/services/actions/receive-return.ts` | 返品受領の詳細ロジック |
| 2-4 | cancel-return.ts | `packages/modules/order/src/services/actions/cancel-return.ts` | 返品キャンセルの詳細ロジック |

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

```
createReturn (actions/create-return.ts)
    ├─ createOrderChange_
    ├─ returnService_.create
    ├─ returnItemService_.create
    └─ confirmOrderChange

receiveReturn (actions/receive-return.ts)
    ├─ createOrderChange_
    ├─ returnItemService_.update (received_quantity)
    └─ confirmOrderChange

cancelReturn (actions/cancel-return.ts)
    ├─ createOrderChange_
    ├─ returnService_.update (status=CANCELED)
    └─ confirmOrderChange
```

### データフロー図

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

CreateReturnDTO ─────────▶ createReturn ──────────────▶ return テーブル
       │                        │
       │                        ├─▶ returnItemService_ ─▶ return_item テーブル
       │                        │
       │                        ├─▶ orderChangeService_ ─▶ order_change テーブル
       │                        │
       v                        v
 order_id, items,         confirmOrderChange           ReturnDTO
 refund_amount
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| return.ts | `packages/modules/order/src/models/return.ts` | ソース | Returnエンティティ定義 |
| return-item.ts | `packages/modules/order/src/models/return-item.ts` | ソース | ReturnItemエンティティ定義 |
| order-module-service.ts | `packages/modules/order/src/services/order-module-service.ts` | ソース | サービス層（retrieve/list） |
| create-return.ts | `packages/modules/order/src/services/actions/create-return.ts` | ソース | 返品作成アクション |
| receive-return.ts | `packages/modules/order/src/services/actions/receive-return.ts` | ソース | 返品受領アクション |
| cancel-return.ts | `packages/modules/order/src/services/actions/cancel-return.ts` | ソース | 返品キャンセルアクション |
| return-reason.ts | `packages/modules/order/src/models/return-reason.ts` | ソース | 返品理由エンティティ |
