# 機能設計書 14-返品理由管理

## 概要

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

### 本機能の処理概要

返品理由管理機能は、ECサイトにおける返品理由のマスタデータを管理するための機能である。

**業務上の目的・背景**：ECサイトにおいて、顧客からの返品依頼時に返品理由を記録することは、品質改善やサービス向上のために重要である。本機能は、返品理由のマスタデータを管理し、返品処理時に理由を紐付けることで、返品傾向の分析を可能にする。

**機能の利用シーン**：
- 管理者が返品理由マスタを設定する場面
- 顧客が返品申請時に理由を選択する場面
- 返品データ分析で理由別の集計を行う場面
- 階層構造を持つ返品理由の管理

**主要な処理内容**：
1. 返品理由（ReturnReason）の作成・取得・更新・削除
2. 親子関係による階層構造の管理
3. 返品アイテムとの紐付け

**関連システム・外部連携**：
- 返品モジュール：返品アイテムに理由を紐付け
- レポーティングシステム：理由別分析

**権限による制御**：
- 返品理由マスタの作成・更新・削除は管理者権限を持つユーザーのみ実行可能
- 理由の一覧取得は認証済みユーザーが実行可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 59 | 返品理由一覧画面 | 主画面 | 返品理由の一覧表示・管理 |
| 60 | 返品理由詳細画面 | 主画面 | 返品理由の詳細表示・編集 |

## 機能種別

マスタ管理 / CRUD操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| value | string | Yes | 返品理由の値（識別子） | 空文字不可、検索可能 |
| label | string | Yes | 返品理由のラベル（表示名） | 空文字不可、検索可能 |
| description | string | No | 返品理由の説明 | - |
| parent_return_reason_id | string | No | 親の返品理由ID | 有効な返品理由IDであること |
| metadata | object | No | メタデータ | JSON形式 |

### 入力データソース

- 管理画面：返品理由マスタの設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | 返品理由ID（prefix: rr） |
| value | string | 返品理由の値 |
| label | string | 返品理由のラベル |
| description | string | 説明 |
| parent_return_reason_id | string | 親の返品理由ID |
| parent_return_reason | ReturnReason | 親の返品理由オブジェクト |
| return_reason_children | ReturnReason[] | 子の返品理由オブジェクト配列 |
| metadata | object | メタデータ |

### 出力先

- データベース：return_reasonテーブル
- API応答：OrderReturnReasonDTO形式

## 処理フロー

### 処理シーケンス

```
1. 返品理由作成リクエスト受信
   └─ value、label、parent_return_reason_id等を受信

2. バリデーション
   └─ 必須項目の確認
   └─ 親IDが指定されている場合は存在確認

3. 返品理由の作成
   └─ ReturnReasonレコードを作成

4. 結果返却
   └─ 作成された返品理由をシリアライズして返却
```

### フローチャート

```mermaid
flowchart TD
    A[返品理由作成リクエスト] --> B[バリデーション]
    B --> C{parent_id指定?}
    C -->|Yes| D{親が存在?}
    C -->|No| E[ReturnReason作成]
    D -->|Yes| E
    D -->|No| F[エラー返却]
    E --> G[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-14-01 | 階層構造 | 返品理由は親子関係を持つことができる | 親ID指定時 |
| BR-14-02 | 検索可能フィールド | value、labelフィールドは検索対象となる | 検索時 |
| BR-14-03 | 論理削除 | 削除時は論理削除（deleted_at設定）される | 削除時 |

### 計算ロジック

特になし（マスタデータの管理のみ）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 返品理由作成 | return_reason | INSERT | 返品理由の作成 |
| 返品理由更新 | return_reason | UPDATE | 返品理由の更新 |
| 返品理由削除 | return_reason | UPDATE (soft delete) | 論理削除 |

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

#### return_reason

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（prefix: rr） | 主キー |
| INSERT | value | リクエストのvalue | 検索可能 |
| INSERT | label | リクエストのlabel | 検索可能 |
| INSERT | description | リクエストのdescription | nullable |
| INSERT | parent_return_reason_id | リクエストの親ID | nullable、外部キー（自己参照） |
| INSERT | metadata | リクエストのmetadata | JSON形式 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NOT_FOUND | MedusaError | 指定されたIDの返品理由が存在しない | 有効なIDを指定 |
| INVALID_DATA | MedusaError | 必須パラメータ（value, label）が未指定 | 必須項目を入力 |
| INVALID_DATA | MedusaError | 親IDが存在しない | 有効な親IDを指定 |

### リトライ仕様

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

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

- 標準のMedusaService CRUD操作を使用
- 単一レコードの操作のためトランザクション管理は自動

## パフォーマンス要件

- 返品理由一覧取得：100件以下で200ms以内
- インデックス：value、parent_return_reason_idにインデックス設定

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

- 返品理由マスタの変更は認証済み管理者のみ実行可能
- 一覧取得は認証済みユーザーが実行可能

## 備考

- 階層構造により、大分類・小分類のような返品理由の整理が可能
- return_reason_childrenリレーションで子要素を取得可能
- ReturnItemのreason_idとして使用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | return-reason.ts | `packages/modules/order/src/models/return-reason.ts` | ReturnReasonエンティティ、value/label/descriptionプロパティ、自己参照リレーション |

**読解のコツ**:
- **5行目**: IDプレフィックスは"rr"
- **6-7行目**: value、labelは.searchable()で検索可能に設定
- **10-20行目**: parent_return_reason（親）とreturn_reason_children（子）の自己参照リレーション

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | order-module-service.ts | `packages/modules/order/src/services/order-module-service.ts` | returnReasonService_の使用箇所（110行目付近、269-271行目） |

**読解のコツ**:
- ReturnReasonはMedusaServiceの標準CRUD操作（create, update, delete, list, retrieve等）を継承
- 専用のカスタムメソッドは少なく、基本的なマスタ管理操作のみ

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

```
OrderModuleService (MedusaService継承)
    ├─ createReturnReasons (標準CRUD)
    ├─ updateReturnReasons (標準CRUD)
    ├─ deleteReturnReasons (標準CRUD)
    ├─ listReturnReasons (標準CRUD)
    └─ retrieveReturnReason (標準CRUD)

※ 全てMedusaServiceの標準メソッドとして自動生成
```

### データフロー図

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

CreateReturnReasonDTO ──▶ returnReasonService_.create ──▶ return_reason テーブル
       │
       v
 value, label,
 parent_return_reason_id                            OrderReturnReasonDTO
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| return-reason.ts | `packages/modules/order/src/models/return-reason.ts` | ソース | ReturnReasonエンティティ定義 |
| order-module-service.ts | `packages/modules/order/src/services/order-module-service.ts` | ソース | サービス（標準CRUD使用） |
| return-item.ts | `packages/modules/order/src/models/return-item.ts` | ソース | ReturnItemエンティティ（理由を参照） |
| return-reason.ts | `packages/modules/order/src/types/return-reason.ts` | ソース | DTO型定義 |
