# 画面設計書 53-注文移管リクエスト画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における「注文移管リクエスト画面」の設計仕様を定義するものである。

### 本画面の処理概要

**業務上の目的・背景**：EC運営において、注文の所有権を別の顧客に移管する必要が生じる場合がある（例：法人アカウントへの移管、代理購入からの移管、アカウント統合等）。本画面は、管理者が注文を現在の顧客から別の登録済み顧客アカウントに移管するリクエストを作成するためのインターフェースを提供する。移管は顧客の承認を経て完了するワークフローとなっている。

**画面へのアクセス方法**：注文詳細画面または顧客詳細画面から「注文移管」アクションを選択することでアクセスする。

**主要な操作・処理内容**：
1. 現在の注文所有者（顧客）情報を確認する
2. 移管先の顧客をコンボボックスから検索・選択する
3. 保存ボタンを押下して移管リクエストを作成する

**画面遷移**：
- 遷移元：注文詳細画面（`/orders/:id`）または顧客詳細画面（`/customers/:id/orders/:order_id`）
- 遷移先：移管リクエスト作成後、元の画面に戻る

**権限による表示制御**：認証済みの管理者ユーザーのみアクセス可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 27 | 注文移管 | 主機能 | 移管リクエストの作成 |
| 4 | 顧客検索 | API連携 | 移管先顧客の検索・選択 |

## 画面種別

編集（ドロワー形式）

## URL/ルーティング

```
/orders/:id/transfer
/customers/:id/orders/:order_id/transfer
```

## 入出力項目

| 項目名 | 項目ID | データ型 | 必須 | 入力形式 | バリデーション | 説明 |
|--------|--------|----------|------|----------|----------------|------|
| 移管先顧客 | customer_id | string | ○ | コンボボックス | 有効な顧客ID、最小1文字 | 移管先の顧客を選択 |
| 現在の所有者 | current_customer_details | string | - | テキスト（無効） | 最小1文字 | 現在の所有者情報（読み取り専用） |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| 移管ヘッダー | カスタムコンポーネント | 移管の視覚的説明 |
| 現在の所有者 | テキスト | 「{姓} {名} ({メール})」または「{メール}」形式 |
| 移管先顧客候補 | リスト | 「{姓} {名} ({メール})」形式、アカウント保有者のみ |

## イベント仕様

### 1-顧客検索

コンボボックスに検索文字列が入力された場合：
- useComboboxDataフックで顧客APIを呼び出し
- `has_account: true`フィルターで登録済みアカウント保有者のみ取得
- 検索結果を選択肢として表示
- 無限スクロールによるページング対応

### 2-顧客選択

コンボボックスから顧客が選択された場合：
- 選択された顧客IDをフォーム状態に保存
- バリデーションエラーをクリア

### 3-保存ボタン押下

保存ボタンが押下された場合：
1. フォームバリデーションを実行
2. `useRequestTransferOrder`フックを使用してAPI呼び出し
3. APIエンドポイント：`POST /admin/orders/:id/transfer`
4. リクエストボディ：`{ customer_id }`
5. 成功時：トースト通知を表示し、ドロワーを閉じる
6. 失敗時：エラーメッセージをトーストで表示

### 4-キャンセルボタン押下

キャンセルボタンが押下された場合：
- フォームの変更を破棄
- ドロワーを閉じて元の画面に戻る

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | order_transfer | INSERT | 移管リクエストレコードの作成 |

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

#### order_transfer

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | UUID自動生成 | - |
| INSERT | order_id | 対象注文ID | - |
| INSERT | from_customer_id | 現在の顧客ID | 注文から取得 |
| INSERT | to_customer_id | 選択された移管先顧客ID | - |
| INSERT | status | "pending" | 承認待ち状態 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| requestSuccess | 成功 | 「移管リクエストを送信しました（{メール}宛）」 | 移管リクエスト作成成功時 |
| error | エラー | APIから返されたエラーメッセージ | 移管リクエスト作成失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 注文が見つからない | エラーをスローし、エラーページを表示 |
| 移管先顧客が選択されていない | 保存ボタンが無効化される |
| 同じ顧客への移管 | APIエラーとして処理（想定） |
| ネットワークエラー | エラートーストを表示 |

## 備考

- 移管先顧客はアカウント（has_account: true）を持つ顧客のみ選択可能
- 移管はリクエストベースで、顧客側の承認が必要（本画面では承認処理は行わない）
- 注文詳細画面と顧客詳細画面の両方からアクセス可能なため、URLパラメータの取得方法が異なる

---

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

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

### 推奨読解順序

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

まず、移管リクエストで使用されるデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CreateOrderTransferSchema | `packages/admin/dashboard/src/routes/orders/order-request-transfer/components/create-order-transfer-form/create-order-transfer-form.tsx` | Zodスキーマによる入力データの型定義（20-24行目） |

**読解のコツ**: customer_idとcurrent_customer_detailsの2フィールドを持つシンプルな構造。

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

処理の起点となるファイル・関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | OrderRequestTransfer | `packages/admin/dashboard/src/routes/orders/order-request-transfer/order-request-transfer.tsx` | 画面コンポーネントのエントリーポイント |

**主要処理フロー**:
1. **15行目**: order_idまたはidパラメータを取得（2つのルートに対応）
2. **17-19行目**: useOrderフックで注文データを取得
3. **31行目**: CreateOrderTransferFormコンポーネントをレンダリング

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

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

**主要処理フロー**:
- **32-40行目**: useFormによるフォーム初期化、デフォルト値設定
- **42-51行目**: useComboboxDataで顧客検索機能を構築
- **53行目**: useRequestTransferOrderフックの取得
- **55-65行目**: フォーム送信ハンドラ

#### Step 4: ヘッダーコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TransferHeader | `packages/admin/dashboard/src/routes/orders/order-request-transfer/components/create-order-transfer-form/transfer-header.tsx` | 移管の視覚的説明 |

#### Step 5: APIフックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | useRequestTransferOrder | `packages/admin/dashboard/src/hooks/api/orders.tsx` | 移管リクエストAPIミューテーションフック（338-355行目） |

**主要処理フロー**:
- **347行目**: sdk.admin.order.requestTransfer呼び出し

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

```
OrderRequestTransfer (order-request-transfer.tsx)
    │
    ├─ useParams (order_idまたはidを取得)
    │
    ├─ useOrder (注文データ取得)
    │
    └─ CreateOrderTransferForm (create-order-transfer-form.tsx)
           │
           ├─ useComboboxData
           │      └─ sdk.admin.customer.list (has_account: true)
           │
           └─ useRequestTransferOrder (orders.tsx)
                  └─ sdk.admin.order.requestTransfer
                         └─ POST /admin/orders/:id/transfer
```

### データフロー図

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

顧客検索入力 ─────────┐
                      │
                      ├───▶ useComboboxData ───▶ 顧客API ───▶ 選択肢リスト
                      │
顧客選択 ────────────┼───▶ CreateOrderTransferForm ───▶ useRequestTransferOrder
                      │         │                              │
                      │         │                              └─▶ order_transfer (DB)
                      │         ▼
                      │    フォームバリデーション
                      │         │
                      │         ▼
                      │   トースト通知 ───▶ 元の画面
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order-request-transfer.tsx | `packages/admin/dashboard/src/routes/orders/order-request-transfer/order-request-transfer.tsx` | ソース | 画面コンポーネント |
| create-order-transfer-form.tsx | `packages/admin/dashboard/src/routes/orders/order-request-transfer/components/create-order-transfer-form/create-order-transfer-form.tsx` | ソース | 移管フォーム |
| transfer-header.tsx | `packages/admin/dashboard/src/routes/orders/order-request-transfer/components/create-order-transfer-form/transfer-header.tsx` | ソース | ヘッダーコンポーネント |
| orders.tsx | `packages/admin/dashboard/src/hooks/api/orders.tsx` | ソース | 注文APIフック |
| use-combobox-data.tsx | `packages/admin/dashboard/src/hooks/use-combobox-data.tsx` | ソース | コンボボックスデータフック |
