# 機能設計書 35-返金理由管理

## 概要

本ドキュメントは、Medusaの支払いモジュールにおける返金理由管理機能の設計を記載する。

### 本機能の処理概要

返金理由管理機能は、返金処理時に選択できる返金理由のマスタデータを管理する機能である。返金理由のラベル、コード、説明を登録・更新・削除し、返金処理の際に適切な理由を選択できるようにする。

**業務上の目的・背景**：返金処理の理由を標準化・分類することで、返金傾向の分析や監査対応が容易になる。また、顧客対応時に一貫した理由説明が可能になり、運用品質が向上する。

**機能の利用シーン**：
1. 管理者が新しい返金理由を登録する場面
2. 返金理由のラベルや説明を更新する場面
3. 使用しなくなった返金理由を削除する場面
4. 返金処理時に返金理由を選択する場面

**主要な処理内容**：
1. 返金理由の一覧取得・検索
2. 返金理由の新規作成
3. 返金理由の更新
4. 返金理由の削除

**関連システム・外部連携**：特になし（内部マスタ管理）

**権限による制御**：管理者（Admin）権限を持つユーザーのみが返金理由の作成・更新・削除が可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 182 | 返金理由一覧画面 | 主機能 | 返金理由一覧の取得・表示 |
| 183 | 返金理由作成画面 | 主機能 | 新規返金理由の作成 |
| 184 | 返金理由編集画面 | 主機能 | 返金理由の編集 |
| 51 | 返金作成画面 | 参照画面 | 返金理由の選択 |

## 機能種別

CRUD操作 / マスタ管理

## 入力仕様

### 入力パラメータ

#### 返金理由作成

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | string | Yes | 返金理由のラベル（表示名） | 空文字不可 |
| code | string | Yes | 返金理由のコード（識別子） | 空文字不可、一意 |
| description | string | No | 返金理由の説明 | - |
| metadata | object | No | メタデータ | - |

#### 返金理由更新

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| id | string | Yes | 返金理由ID | 存在するIDであること |
| label | string | No | 更新後のラベル | - |
| description | string | No | 更新後の説明 | - |
| metadata | object | No | 更新後のメタデータ | - |

### 入力データソース

- 画面入力：管理画面からの入力
- DBテーブル：refund_reason

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| refund_reason | RefundReasonDTO | 返金理由情報 |
| refund_reason.id | string | 返金理由ID |
| refund_reason.label | string | ラベル（表示名） |
| refund_reason.code | string | コード（識別子） |
| refund_reason.description | string | 説明 |
| refund_reason.metadata | object | メタデータ |

### 出力先

- 画面表示：管理画面の返金理由一覧・詳細
- DBテーブル：refund_reason

## 処理フロー

### 処理シーケンス

```
1. 返金理由一覧取得
   └─ refetchEntitiesでフィルタ条件に基づき取得

2. 返金理由作成
   ├─ createRefundReasonsWorkflowの実行
   ├─ RefundReasonレコードの作成
   └─ 作成した返金理由を返却

3. 返金理由更新
   ├─ updateRefundReasonsWorkflowの実行
   ├─ RefundReasonレコードの更新
   └─ 更新した返金理由を返却

4. 返金理由削除
   ├─ deleteRefundReasonsWorkflowの実行
   └─ RefundReasonレコードの削除
```

### フローチャート

```mermaid
flowchart TD
    A[開始: 返金理由CRUD] --> B{操作種別}
    B -->|一覧取得| C[refetchEntities]
    B -->|作成| D[createRefundReasonsWorkflow]
    B -->|更新| E[updateRefundReasonsWorkflow]
    B -->|削除| F[deleteRefundReasonsWorkflow]
    C --> G[結果返却]
    D --> H[RefundReasonレコード作成]
    H --> I[refetchEntity]
    I --> G
    E --> J[RefundReasonレコード更新]
    J --> K[refetchEntity]
    K --> G
    F --> L[RefundReasonレコード削除]
    L --> M[削除完了返却]
    G --> N[終了]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-35-001 | コード一意性 | codeは返金理由全体で一意である必要がある | 作成・更新時 |
| BR-35-002 | 検索可能フィールド | label、code、descriptionは検索可能 | 一覧取得時 |
| BR-35-003 | 返金との関連 | 削除された返金理由を参照している返金は影響を受けない | 削除時 |

### 計算ロジック

特に複雑な計算ロジックはなし。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 一覧取得 | refund_reason | SELECT | 返金理由の取得 |
| 作成 | refund_reason | INSERT | 返金理由レコード作成 |
| 更新 | refund_reason | UPDATE | 返金理由レコード更新 |
| 削除 | refund_reason | DELETE | 返金理由レコード削除 |

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

#### refund_reason

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（prefix: refr） | - |
| INSERT | label | ラベル文字列 | searchable |
| INSERT | code | コード文字列 | searchable |
| INSERT | description | 説明文字列 | searchable、nullable |
| INSERT | metadata | メタデータJSON | nullable |
| UPDATE | label | 更新後のラベル | - |
| UPDATE | description | 更新後の説明 | - |
| UPDATE | metadata | 更新後のメタデータ | - |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| DUPLICATE_KEY | DBError | codeが重複 | 別のコードを指定 |
| NOT_FOUND | MedusaError | 存在しないIDの更新・削除 | 正しいIDを指定 |

### リトライ仕様

- 通常のCRUD操作のため、特別なリトライ仕様なし

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

- ワークフローによるトランザクション管理
- 作成・更新・削除は単一トランザクションで実行

## パフォーマンス要件

- 一覧取得：100ms以内
- 作成・更新・削除：200ms以内

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

- 管理者認証必須（AuthenticatedMedusaRequest）
- 返金理由はマスタデータのため、変更履歴の記録を推奨

## 備考

- 返金理由は返金処理時のオプションとして使用される
- 返金理由を削除しても、過去の返金レコードとの紐付けは維持される（ソフトデリートではない場合は参照整合性に注意）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | refund-reason.ts | `packages/modules/payment/src/models/refund-reason.ts` | RefundReasonエンティティの構造 |

**読解のコツ**:
- **4行目**: idプレフィックスは`refr`
- **6-8行目**: label、code、descriptionはすべて`.searchable()`が付与されており検索対象
- **10-12行目**: refundsとのhasMany関連（1対多）

#### Step 2: APIルートを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | route.ts | `packages/medusa/src/api/admin/refund-reasons/route.ts` | 一覧取得・作成エンドポイント |

**主要処理フロー**:
- **15-32行目**: GET（一覧取得）
  - **19-25行目**: refetchEntitiesでフィルタ・ページネーション付き取得
- **35-56行目**: POST（作成）
  - **44-46行目**: createRefundReasonsWorkflowの実行
  - **48-53行目**: refetchEntityで作成したレコードを再取得

#### Step 3: モジュールサービスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | payment-module.ts | `packages/modules/payment/src/services/payment-module.ts` | RefundReason関連の基本CRUD |

**読解のコツ**: RefundReasonのCRUDはMedusaServiceの基底クラスから自動生成される。明示的なメソッド定義はなく、generateMethodForModels（81-89行目）に含まれている。

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

```
GET /admin/refund-reasons (route.ts)
    │
    └─ refetchEntities()
           │
           └─ remoteQuery (refund_reasons)

POST /admin/refund-reasons (route.ts)
    │
    └─ createRefundReasonsWorkflow
           │
           └─ PaymentModuleService.createRefundReasons()
                  │
                  └─ refundReasonService_.create()
```

### データフロー図

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

label ─────────────────▶ createRefundReasonsWorkflow
code                            │
description                     │
metadata                        │
                                ▼
                    ┌───────────────────────────┐
                    │ refund_reason             │
                    │ (INSERT)                  │
                    └──────────┬────────────────┘
                               │
                               ▼
                          RefundReasonDTO
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| refund-reason.ts | `packages/modules/payment/src/models/refund-reason.ts` | モデル | RefundReasonエンティティ定義 |
| route.ts | `packages/medusa/src/api/admin/refund-reasons/route.ts` | APIルート | 一覧取得・作成エンドポイント |
| payment-module.ts | `packages/modules/payment/src/services/payment-module.ts` | サービス | 基底CRUD（自動生成） |
| refund.ts | `packages/modules/payment/src/models/refund.ts` | モデル | RefundとRefundReasonの関連 |
