# 画面設計書 47-返品受領画面

## 概要

本ドキュメントは、Medusa管理画面における返品受領画面の設計を記載する。本画面は、確定された返品リクエストに対して商品の受領処理を行うためのドロワー形式の画面であり、受領数量の確認・調整と破損商品の処理を行う。

### 本画面の処理概要

**業務上の目的・背景**：返品リクエストが確定された後、実際に商品が返送されてきた際には受領処理が必要である。本画面は、返品された商品の受領数量を確認し、破損商品がある場合はその数量を記録する機能を提供する。受領処理が完了すると、在庫の復元と返金処理が可能となる。

**画面へのアクセス方法**：注文詳細画面（/orders/{id}）のアクティブな返品セクションから「Receive Return」アクションを選択することでアクセス。画面表示時に自動的に受領処理が初期化される。

**主要な操作・処理内容**：
1. 受領数量の確認・調整：各商品の実際に受け取った数量を入力
2. 破損数量の記録：破損していた商品の数量を記録
3. 受領確定：設定内容で受領処理を確定

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| F-001 | 返品受領初期化 | 主機能 | 受領処理の初期化 |
| F-002 | 受領数量更新 | 主機能 | 受領数量の調整 |
| F-003 | 破損数量記録 | 補助機能 | 破損商品数量の記録 |
| F-004 | 受領確定 | 主機能 | 受領処理の確定 |

## 画面種別

ドロワー（RouteDrawer）

## URL/ルーティング

```
/orders/:id/returns/:return_id/receive
```

## 入出力項目

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| id | 入力 | string | ○ | 注文ID（URLパラメータ） |
| return_id | 入力 | string | ○ | 返品ID（URLパラメータ） |
| items | 入力 | array | ○ | 受領商品配列 |
| items[].item_id | 入力 | string | ○ | 商品ID |
| items[].quantity | 入力 | number | × | 受領数量 |
| items[].dismissed_quantity | 入力 | number | × | 破損数量 |
| send_notification | 入力 | boolean | × | 顧客への通知送信フラグ |

## 表示項目

| 項目名 | 表示名 | 型 | 説明 |
|--------|--------|-----|------|
| stock_location.name | Location | string | 返品先ロケーション名 |
| items | Items | list | 受領対象商品一覧 |
| items[].thumbnail | - | image | 商品サムネイル |
| items[].title | Title | string | 商品名 |
| items[].variant_sku | SKU | string | バリアントSKU |
| items[].quantity | Expected | number | 期待数量 |
| items[].received_quantity | Received | input | 受領数量入力 |
| items[].dismissed_quantity | Dismissed | input | 破損数量入力 |
| total | Total | number | 注文合計 |
| pending_difference | Outstanding Amount | number | 未決済金額 |
| send_notification | Send Notification | switch | 通知送信スイッチ |

## イベント仕様

### 1-受領数量変更

受領数量を変更すると、APIが呼び出されて更新される。

- バリデーション:
  - 0以上であること
  - 期待数量以下であること
- API呼び出し（追加/更新）: `POST /admin/returns/{return_id}/receive-items/{action_id}`
- API呼び出し（数量0または削除）: `DELETE /admin/returns/{return_id}/receive-items/{action_id}`
- エラー時: 元の値に戻してエラートースト表示

### 2-破損数量変更

破損数量（Dismissed Quantity）を変更すると、別のアクションとして記録される。

- API呼び出し: `POST /admin/returns/{return_id}/dismiss-items/{action_id}`
- DismissedQuantityコンポーネントで処理

### 3-受領確定

「Save」ボタンをクリックすると、受領処理が確定される。

- API呼び出し: `POST /admin/returns/{return_id}/receive/confirm`
- リクエストボディ:
  ```json
  {
    "no_notification": false
  }
  ```
- 成功時: トースト通知で成功メッセージを表示し、注文詳細画面へ遷移
- エラー時: トースト通知でエラーメッセージを表示

### 4-キャンセル

「Cancel」ボタンをクリックまたはドロワーを閉じると、受領処理がキャンセルされる。

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

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | order | SELECT | 注文データの取得 |
| 画面表示 | return | SELECT | 返品データの取得 |
| 受領初期化 | order_change | INSERT | 受領変更の作成 |
| 数量更新 | order_change_action | INSERT/UPDATE/DELETE | 受領アクションの操作 |
| 受領確定 | return | UPDATE | 受領日時の更新 |
| 受領確定 | order_change | UPDATE | 変更の確定 |
| 受領確定 | inventory_item | UPDATE | 在庫の復元 |

### テーブル別更新項目詳細

#### return

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | received_at | 現在日時 | 受領日時 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| orders.returns.receive.toast.success | 成功 | Return received | 受領確定成功時 |
| orders.returns.receive.toast.errorNegativeValue | エラー | Cannot set negative value | 負の数値入力時 |
| orders.returns.receive.toast.errorLargeValue | エラー | Cannot exceed expected quantity | 期待数量超過時 |
| orders.returns.receive.inventoryWarning | 警告 | Inventory will be updated | 在庫更新の警告 |
| orders.returns.activeChangeError | エラー | There is an active change on this order | 他の変更がアクティブな場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 他のアクティブな変更がある | エラートースト表示し、注文詳細画面へリダイレクト |
| 受領初期化失敗 | エラートースト表示 |
| 数量バリデーションエラー | 元の値に戻してエラートースト表示 |
| API呼び出しエラー | トースト通知でエラーメッセージを表示 |
| ドロワークローズ | 未確定の場合、受領処理をキャンセル |

## 備考

- 画面表示時に自動的に受領処理が初期化される（initiateReceiveReturn + addReceiveItems）
- 在庫更新の警告メッセージが表示される
- 受領数量と破損数量は別々のアクションとして管理される
- 受領完了後、返金処理が可能となる

---

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

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

### 推奨読解順序

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

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

**主要処理フロー**:
1. **行18**: `useParams`で注文IDと返品ID取得
2. **行26-28**: `useOrder`, `useOrderPreview`, `useReturn`でデータ取得
3. **行36-37**: `useInitiateReceiveReturn`, `useAddReceiveItems`で初期化フック取得
4. **行43-73**: `useEffect`で受領処理の初期化

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

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

**主要処理フロー**:
- **行51-54**: `useConfirmReturnReceive`で確定フック取得
- **行56-59**: `useCancelReceiveReturn`でキャンセルフック取得
- **行128-144**: `handleSubmit`で確定処理
- **行146-199**: `handleQuantityChange`で数量変更処理

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

```
OrderReceiveReturn (order-receive-return.tsx)
    │
    ├─ useParams (id, return_id)
    ├─ useOrder (注文データ)
    ├─ useOrderPreview (プレビュー)
    ├─ useReturn (返品データ)
    ├─ useInitiateReceiveReturn
    ├─ useAddReceiveItems
    │
    └─ OrderReceiveReturnForm
           │
           ├─ useConfirmReturnReceive
           ├─ useCancelReceiveReturn
           ├─ useAddReceiveItems
           ├─ useUpdateReceiveItem
           ├─ useRemoveReceiveItems
           ├─ useStockLocation
           │
           └─ DismissedQuantity (破損数量)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order-receive-return.tsx | `packages/admin/dashboard/src/routes/orders/order-receive-return/order-receive-return.tsx` | ソース | ページコンポーネント |
| order-receive-return-form.tsx | `packages/admin/dashboard/src/routes/orders/order-receive-return/components/order-receive-return-form/order-receive-return-form.tsx` | ソース | フォームコンポーネント |
| dismissed-quantity.tsx | `packages/admin/dashboard/src/routes/orders/order-receive-return/components/order-receive-return-form/dismissed-quantity.tsx` | ソース | 破損数量コンポーネント |
| constants.ts | `packages/admin/dashboard/src/routes/orders/order-receive-return/components/order-receive-return-form/constants.ts` | ソース | 定数・スキーマ定義 |
| returns.tsx | `packages/admin/dashboard/src/hooks/api/returns.tsx` | ソース | API呼び出しフック |
