# 画面設計書 46-返品作成画面

## 概要

本ドキュメントは、Medusa管理画面における返品作成画面の設計を記載する。本画面は、注文に対する返品リクエストを作成するためのモーダル形式の画面であり、返品対象商品の選択、返品理由の設定、返品先ロケーション、返品送料の設定を行う。

### 本画面の処理概要

**業務上の目的・背景**：ECサイト運営において、顧客からの返品リクエストに対応することは重要な業務である。本画面は、返品対象商品の選択、返品理由の記録、返品送料の設定を行い、返品リクエストを作成する機能を提供する。返品リクエスト作成後は、商品の受領処理を経て返金等の処理が行われる。

**画面へのアクセス方法**：注文詳細画面（/orders/{id}）のサマリーセクションから「Create Return」アクションを選択することでアクセス。画面表示時に自動的に返品リクエストが初期化される。

**主要な操作・処理内容**：
1. 返品対象商品の追加：返品する商品を選択
2. 返品数量の調整：各商品の返品数量を指定
3. 返品理由の設定：返品理由とメモを記録
4. 返品先ロケーションの選択：商品を受け取る倉庫・店舗を選択
5. 返品送料の設定：返品用の配送オプションと送料を設定
6. 返品リクエストの確定：設定内容で返品リクエストを確定

**画面遷移**：
- 遷移元：注文詳細画面（/orders/{id}）
- 遷移先：注文詳細画面（返品作成完了またはキャンセル後）

**権限による表示制御**：管理者権限を持つユーザーのみがアクセス可能。他のアクティブな変更がある場合はエラー表示されリダイレクト。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| F-001 | 返品リクエスト作成 | 主機能 | 返品リクエストの初期化と確定 |
| F-002 | 返品商品追加 | 補助機能 | 返品対象商品の追加 |
| F-003 | 返品商品更新 | 補助機能 | 返品数量・理由の更新 |
| F-004 | 返品商品削除 | 補助機能 | 返品対象商品の削除 |
| F-005 | 返品送料設定 | 補助機能 | 返品用配送オプションの設定 |

## 画面種別

モーダル（RouteFocusModal）

## URL/ルーティング

```
/orders/:id/returns
```

## 入出力項目

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| id | 入力 | string | ○ | 注文ID（URLパラメータ） |
| items | 入力 | array | ○ | 返品対象商品配列 |
| items[].item_id | 入力 | string | ○ | 商品ID |
| items[].quantity | 入力 | number | ○ | 返品数量 |
| items[].reason_id | 入力 | string | × | 返品理由ID |
| items[].note | 入力 | string | × | 内部メモ |
| location_id | 入力 | string | × | 返品先ロケーションID |
| option_id | 入力 | string | × | 返品配送オプションID |
| send_notification | 入力 | boolean | × | 顧客への通知送信フラグ |

## 表示項目

| 項目名 | 表示名 | 型 | 説明 |
|--------|--------|-----|------|
| items | Inbound Items | list | 返品対象商品一覧 |
| items[].thumbnail | - | image | 商品サムネイル |
| items[].title | Title | string | 商品名 |
| items[].quantity | Quantity | number | 返品数量（入力） |
| items[].unit_price | Unit Price | number | 単価 |
| items[].total | Total | number | 小計 |
| location_id | Location | select | 返品先ロケーション選択 |
| option_id | Inbound Shipping | select | 返品配送オプション選択 |
| return_total | Return Total | number | 返品合計金額 |
| shipping_total | Inbound Shipping | number | 返品送料 |
| estimated_difference | Est. Difference | number | 推定差額 |
| send_notification | Send Notification | switch | 通知送信スイッチ |

## イベント仕様

### 1-返品商品追加

「Add Items」リンクをクリックすると、商品選択モーダルが表示される。商品を選択して「Save」をクリックすると、返品対象商品が追加される。

- API呼び出し: `POST /admin/returns/{return_id}/request-items`
- リクエストボディ:
  ```json
  {
    "items": [{ "id": "item_xxx", "quantity": 1 }]
  }
  ```

### 2-返品商品更新

返品商品の数量や理由を変更すると、返品リクエストが更新される。

- API呼び出し: `POST /admin/returns/{return_id}/request-items/{action_id}`
- リクエストボディ:
  ```json
  {
    "quantity": 2,
    "reason_id": "reason_xxx",
    "internal_note": "note"
  }
  ```

### 3-返品商品削除

返品商品の削除ボタンをクリックすると、返品対象から除外される。

- API呼び出し: `DELETE /admin/returns/{return_id}/request-items/{action_id}`

### 4-ロケーション変更

ロケーションを変更すると、返品リクエストのlocation_idが更新される。

- API呼び出し: `POST /admin/returns/{return_id}`
- 連動: 配送オプションがロケーションでフィルタリングされる

### 5-配送オプション変更

配送オプションを変更すると、既存の返品送料が削除され、新しい配送オプションが設定される。

- API呼び出し（削除）: `DELETE /admin/returns/{return_id}/shipping-method/{action_id}`
- API呼び出し（追加）: `POST /admin/returns/{return_id}/shipping-method`

### 6-送料カスタマイズ

送料の編集アイコンをクリックすると、カスタム送料を入力できる。

- API呼び出し: `POST /admin/returns/{return_id}/shipping-method/{action_id}`
- リクエストボディ:
  ```json
  {
    "custom_amount": 500
  }
  ```

### 7-返品リクエスト確定

「Confirm」ボタンをクリックすると、確認ダイアログ表示後、返品リクエストが確定される。

- 確認ダイアログ: 「Are you sure?」メッセージを表示
- API呼び出し: `POST /admin/returns/{return_id}/confirm`
- 成功時: モーダルを閉じて注文詳細画面へ遷移
- エラー時: トースト通知でエラーメッセージを表示

### 8-キャンセル

「Cancel」ボタンをクリックまたはモーダルを閉じると、返品リクエストがキャンセルされる。

- API呼び出し: `POST /admin/returns/{return_id}/cancel`

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | order | SELECT | 注文データの取得 |
| 返品初期化 | return | INSERT | 返品リクエストの作成 |
| 返品初期化 | order_change | INSERT | 注文変更の作成 |
| 商品追加 | order_change_action | INSERT | 返品アクションの追加 |
| 商品更新 | order_change_action | UPDATE | 返品アクションの更新 |
| 商品削除 | order_change_action | DELETE | 返品アクションの削除 |
| 返品確定 | return | UPDATE | ステータス更新 |
| 返品確定 | order_change | UPDATE | 変更の確定 |
| キャンセル | return | UPDATE | ステータス更新 |
| キャンセル | order_change | DELETE | 変更の削除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| orders.returns.confirmText | 確認 | Are you sure you want to confirm this return? | 返品確定前 |
| orders.returns.activeChangeError | エラー | There is an active change on this order | 他の変更がアクティブな場合 |
| orders.returns.noInventoryLevel | 警告 | No inventory level | 在庫レベルが設定されていない場合 |
| エラーメッセージ | エラー | API返却のエラーメッセージ | API呼び出しエラー時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 他のアクティブな変更がある | エラートースト表示し、注文詳細画面へリダイレクト |
| 返品初期化失敗 | エラートースト表示し、注文詳細画面へリダイレクト |
| API呼び出しエラー | トースト通知でエラーメッセージを表示 |
| モーダルクローズ | 未確定の場合、返品リクエストをキャンセル |

## 備考

- 画面表示時に自動的に返品リクエストが初期化される（initiateReturn API呼び出し）
- 既存のアクティブな返品変更がある場合は、その変更を継続して編集できる
- 在庫レベルが設定されていない商品には警告が表示される
- カスタム送料は通貨に応じた小数点桁数で設定される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | schema.ts | `packages/admin/dashboard/src/routes/orders/order-create-return/components/return-create-form/schema.ts` | ReturnCreateSchemaでバリデーションスキーマを確認 |

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | return-create.tsx | `packages/admin/dashboard/src/routes/orders/order-create-return/return-create.tsx` | ページコンポーネントの構成を確認 |

**主要処理フロー**:
1. **行17**: `useParams`で注文ID取得
2. **行22-24**: `useOrder`で注文データ取得
3. **行26**: `useOrderPreview`で注文プレビュー取得
4. **行30**: `useInitiateReturn`で返品初期化フック取得
5. **行36-67**: `useEffect`で返品リクエストの初期化処理

#### Step 3: フォームコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | return-create-form.tsx | `packages/admin/dashboard/src/routes/orders/order-create-return/components/return-create-form/return-create-form.tsx` | フォームの実装詳細 |

**主要処理フロー**:
- **行123-127**: `useConfirmReturnRequest`で返品確定フック取得
- **行126-127**: `useCancelReturnRequest`でキャンセルフック取得
- **行131-142**: 各種配送・商品操作フック取得
- **行261-284**: `handleSubmit`で確認ダイアログと確定処理
- **行286-295**: `onItemsSelected`で商品追加処理
- **行301-314**: `onShippingOptionChange`で配送オプション変更処理

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

```
ReturnCreate (return-create.tsx)
    │
    ├─ useParams (注文ID)
    ├─ useOrder (注文データ)
    ├─ useOrderPreview (プレビュー)
    ├─ useInitiateReturn (返品初期化)
    ├─ useReturn (返品データ)
    │
    └─ ReturnCreateForm
           │
           ├─ useConfirmReturnRequest
           ├─ useCancelReturnRequest
           ├─ useAddReturnItem
           ├─ useRemoveReturnItem
           ├─ useUpdateReturnItem
           ├─ useAddReturnShipping
           ├─ useUpdateReturnShipping
           ├─ useDeleteReturnShipping
           ├─ useUpdateReturn
           │
           └─ handleSubmit → confirmReturnRequest
```

### データフロー図

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

URLパラメータ ───▶ useParams ──────────────▶ orderId
                          │
                          ▼
画面表示 ────────▶ initiateReturn ─────────▶ 返品リクエスト作成
                          │
                          ▼
操作（追加/更新/削除）▶ 各種API ────────────▶ 返品リクエスト更新
                          │
                          ▼
確定ボタン ──────▶ confirmReturnRequest ──▶ 返品確定
                          │
                          ▼
キャンセル ──────▶ cancelReturnRequest ───▶ 返品取消
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| return-create.tsx | `packages/admin/dashboard/src/routes/orders/order-create-return/return-create.tsx` | ソース | ページコンポーネント |
| return-create-form.tsx | `packages/admin/dashboard/src/routes/orders/order-create-return/components/return-create-form/return-create-form.tsx` | ソース | フォームコンポーネント |
| return-item.tsx | `packages/admin/dashboard/src/routes/orders/order-create-return/components/return-create-form/return-item.tsx` | ソース | 返品商品コンポーネント |
| add-return-items-table.tsx | `packages/admin/dashboard/src/routes/orders/order-create-return/components/add-return-items-table/add-return-items-table.tsx` | ソース | 商品選択テーブル |
| schema.ts | `packages/admin/dashboard/src/routes/orders/order-create-return/components/return-create-form/schema.ts` | ソース | バリデーションスキーマ |
| returns.tsx | `packages/admin/dashboard/src/hooks/api/returns.tsx` | ソース | API呼び出しフック |
