# 画面設計書 50-注文編集作成画面

## 概要

本ドキュメントは、Medusa管理画面における注文編集作成画面の設計を記載する。本画面は、既存の注文内容を編集（商品の追加・削除・数量変更）するためのモーダル形式の画面であり、顧客の要望に応じた注文変更を行う。

### 本画面の処理概要

**業務上の目的・背景**：ECサイト運営において、顧客から注文内容の変更依頼（商品の追加、削除、数量変更等）を受けることがある。本画面は、出荷前の注文に対して商品構成を変更し、顧客に変更内容の承認を依頼する機能を提供する。編集がリクエストされると、顧客が承認または拒否することで最終的な注文内容が確定する。

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

**主要な操作・処理内容**：
1. 商品の追加：新しい商品バリアントを注文に追加
2. 商品数量の変更：既存商品の数量を変更
3. 商品の削除：注文から商品を削除
4. メモの追加：変更理由等のメモを追加
5. 編集リクエストの送信：顧客に変更内容を通知し承認を依頼

**画面遷移**：
- 遷移元：注文詳細画面（/orders/{id}）
- 遷移先：注文詳細画面（編集リクエスト送信完了またはキャンセル後）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| F-001 | 注文編集作成 | 主機能 | 編集リクエストの初期化と送信 |
| F-002 | 商品追加 | 補助機能 | 新規商品の追加 |
| F-003 | 商品数量変更 | 補助機能 | 数量の変更 |
| F-004 | 商品削除 | 補助機能 | 商品の削除 |
| F-005 | 編集キャンセル | 補助機能 | 編集リクエストの取消 |

## 画面種別

モーダル（RouteFocusModal）

## URL/ルーティング

```
/orders/:id/edits
```

## 入出力項目

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| id | 入力 | string | ○ | 注文ID（URLパラメータ） |
| items | 入力 | array | × | 編集対象商品配列 |
| items[].variant_id | 入力 | string | ○ | バリアントID |
| items[].quantity | 入力 | number | ○ | 数量 |
| note | 入力 | string | × | 編集理由メモ |
| send_notification | 入力 | boolean | × | 顧客への通知送信フラグ |

## 表示項目

| 項目名 | 表示名 | 型 | 説明 |
|--------|--------|-----|------|
| items | Items | list | 注文商品一覧 |
| items[].thumbnail | - | image | 商品サムネイル |
| items[].title | Title | string | 商品名 |
| items[].product_title | Product | string | 製品名 |
| items[].quantity | Quantity | number | 数量（入力） |
| items[].unit_price | Unit Price | number | 単価 |
| items[].total | Total | number | 小計 |
| current_total | Current Total | number | 現在の注文合計 |
| new_total | New Total | number | 編集後の注文合計 |
| pending_difference | Refund Amount | number | 返金/追加請求金額 |
| note | Note | input | 編集理由メモ |
| send_notification | Send Notification | switch | 通知送信スイッチ |

## イベント仕様

### 1-商品追加

「Add Items」ボタンをクリックすると、商品選択モーダルが表示される。バリアントを選択して「Save」をクリックすると、注文に商品が追加される。

- API呼び出し: `POST /admin/order-edits/{order_id}/items`
- リクエストボディ:
  ```json
  {
    "items": [{ "variant_id": "variant_xxx", "quantity": 1 }]
  }
  ```

### 2-商品数量変更

商品の数量フィールドを変更すると、数量が更新される。

- 数量増加の場合:
  - 数量差分に応じてITEM_ADDアクションが作成される
- 数量減少の場合:
  - 数量差分に応じてITEM_REMOVEアクションが作成される
- API呼び出し: `POST /admin/order-edits/{order_id}/items/{action_id}`

### 3-商品削除

商品行の削除ボタンをクリックすると、商品の数量が0になり注文から除外される。

- 既存商品の場合: 全数量分のITEM_REMOVEアクションが作成される
- 追加商品の場合: ITEM_ADDアクションが削除される
- API呼び出し: `DELETE /admin/order-edits/{order_id}/items/{action_id}`

### 4-編集確定（リクエスト送信）

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

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

### 5-キャンセル

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

- API呼び出し: `POST /admin/order-edits/{order_id}/cancel`
- 成功時: 成功トーストを表示

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

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

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

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

#### order_change

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | change_type | "edit" | 編集変更タイプ |
| UPDATE | status | "requested" | リクエスト送信時 |
| UPDATE | requested_at | 現在日時 | リクエスト日時 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| orders.edits.confirmText | 確認 | Are you sure you want to confirm this edit? | 編集確定前 |
| orders.edits.createSuccessToast | 成功 | Order edit requested | 編集リクエスト成功時 |
| orders.edits.cancelSuccessToast | 成功 | Order edit cancelled | キャンセル成功時 |
| orders.edits.activeChangeError | エラー | There is an active change on this order | 他の変更がアクティブな場合 |
| orders.edits.noteHint | ヒント | Add a note for this edit | メモフィールドのヒント |

## 例外処理

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

## 備考

- 画面表示時に自動的に編集リクエストが初期化される（createOrderEdit API呼び出し）
- 既存のアクティブな編集変更がある場合は、その変更を継続して編集できる
- 編集リクエストは「リクエスト」状態で顧客に送信され、顧客の承認待ちとなる
- 顧客が承認すると実際の注文変更が適用される
- 顧客が拒否すると編集は取り消される
- メモはTODO: API対応待ちのため現在は保存されない
- send_notificationはTODO: API対応待ちのため現在は機能しない
- フィルタ機能で商品名での検索が可能

---

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

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

### 推奨読解順序

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

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

**主要処理フロー**:
1. **行15**: `useParams`で注文ID取得
2. **行19-21**: `useOrder`で注文データ取得
3. **行23**: `useOrderPreview`で注文プレビュー取得
4. **行24**: `useCreateOrderEdit`で編集作成フック取得
5. **行26-56**: `useEffect`で編集リクエストの初期化処理

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

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

**主要処理フロー**:
- **行38-39**: `useCancelOrderEdit`でキャンセルフック取得
- **行41-42**: `useRequestOrderEdit`でリクエスト送信フック取得
- **行61-84**: `handleSubmit`で確認ダイアログと確定処理
- **行87-100**: `onClose`でキャンセル処理

#### Step 3: 商品セクションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | order-edit-items-section.tsx | `packages/admin/dashboard/src/routes/orders/order-create-edit/components/order-edit-create-form/order-edit-items-section.tsx` | 商品一覧セクションの実装 |

**主要処理フロー**:
- **行36**: `useAddOrderEditItems`で商品追加フック取得
- **行41-57**: `onItemsSelected`で商品追加処理
- **行59-65**: `filteredItems`でフィルタリング

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

```
OrderEditCreate (order-edit-create.tsx)
    │
    ├─ useParams (id)
    ├─ useOrder (注文データ)
    ├─ useOrderPreview (プレビュー)
    ├─ useCreateOrderEdit (編集作成)
    │
    └─ OrderEditCreateForm
           │
           ├─ useCancelOrderEdit
           ├─ useRequestOrderEdit
           │
           ├─ OrderEditItemsSection
           │      │
           │      ├─ useAddOrderEditItems
           │      │
           │      ├─ AddOrderEditItemsTable (商品選択)
           │      │
           │      └─ OrderEditItem (各商品)
           │             │
           │             ├─ useUpdateOrderEditItem
           │             └─ useRemoveOrderEditItem
           │
           └─ handleSubmit → requestOrderEdit
```

### データフロー図

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

URLパラメータ ───▶ useParams ──────────────▶ orderId
                          │
                          ▼
画面表示 ────────▶ createOrderEdit ─────────▶ 編集作成
                          │
                          ▼
操作（追加/更新/削除）▶ 商品操作API ──────────▶ 編集更新
                          │
                          ▼
確定ボタン ──────▶ requestOrderEdit ────────▶ リクエスト送信
                          │
                          ▼
キャンセル ──────▶ cancelOrderEdit ─────────▶ 編集取消
```

### 関連ファイル一覧

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