# 画面設計書 43-注文詳細画面

## 概要

本ドキュメントは、Medusa管理画面における注文詳細画面の設計を記載する。本画面は、個別の注文に関する包括的な情報を表示し、フルフィルメント、支払い、返品、クレーム、交換、注文編集などの各種操作の起点となる重要な管理画面である。

### 本画面の処理概要

**業務上の目的・背景**：ECサイト運営において、注文の詳細情報を確認し、適切な処理（発送、返品対応、問い合わせ対応等）を行うことは日常的な業務である。本画面は、注文に関するすべての情報を一元的に表示し、各種操作へのナビゲーションを提供することで、オペレーターが効率的に注文処理を行えるようにする。また、注文の履歴（タイムライン）を表示することで、注文の状態変化を追跡できる。

**画面へのアクセス方法**：注文一覧画面（/orders）から特定の注文行をクリックすることでアクセス。または直接URLを指定してアクセス可能。

**主要な操作・処理内容**：
1. 注文基本情報の確認：注文ID、日時、ステータス（支払・フルフィルメント）
2. 注文サマリーの確認：注文商品、数量、金額、割引、送料、税金
3. 支払情報の確認：支払状況、支払コレクション、返金履歴
4. フルフィルメント情報の確認：発送状況、追跡情報
5. 顧客情報の確認：顧客名、連絡先、配送先住所、請求先住所
6. アクティビティ（タイムライン）の確認：注文に関する操作履歴
7. 注文キャンセル：注文のキャンセル処理
8. フルフィルメント作成：発送処理の開始
9. 返品/クレーム/交換の作成：各種RMA処理の開始
10. 注文編集：注文内容の変更
11. メタデータ/JSON表示：詳細データの確認

**画面遷移**：
- 遷移元：注文一覧画面（/orders）
- 遷移先：
  - フルフィルメント作成画面（/orders/{id}/fulfillment）
  - 出荷作成画面（/orders/{id}/fulfillments/{f_id}/create-shipment）
  - 返品作成画面（/orders/{id}/returns）
  - 返品受領画面（/orders/{id}/returns/{return_id}/receive）
  - クレーム作成画面（/orders/{id}/claims）
  - 交換作成画面（/orders/{id}/exchanges）
  - 注文編集画面（/orders/{id}/edit）

**権限による表示制御**：管理者権限を持つユーザーのみがアクセス可能。注文キャンセルなどの破壊的操作は確認ダイアログを表示。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| F-001 | 注文詳細取得 | 主機能 | 注文データの取得・表示 |
| F-002 | 注文キャンセル | 主機能 | 注文のキャンセル処理 |
| F-003 | フルフィルメント作成 | 遷移先機能 | 発送処理画面への遷移 |
| F-004 | 出荷作成 | 遷移先機能 | 出荷情報登録画面への遷移 |
| F-005 | 返品作成 | 遷移先機能 | 返品処理画面への遷移 |
| F-006 | 返品受領 | 遷移先機能 | 返品受領処理画面への遷移 |
| F-007 | クレーム作成 | 遷移先機能 | クレーム処理画面への遷移 |
| F-008 | 交換作成 | 遷移先機能 | 交換処理画面への遷移 |
| F-009 | 注文編集 | 遷移先機能 | 注文編集画面への遷移 |
| F-010 | ノート追加 | 補助機能 | 注文にノートを追加 |

## 画面種別

詳細（Two-Column Layout）

## URL/ルーティング

```
/orders/:id
```

## 入出力項目

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| id | 入力 | string | ○ | 注文ID（URLパラメータ） |

## 表示項目

### GeneralSection（ヘッダー）
| 項目名 | 表示名 | 型 | 説明 |
|--------|--------|-----|------|
| display_id | # | number | 注文表示ID |
| created_at | Date | datetime | 作成日時 |
| sales_channel.name | Sales Channel | string | 販売チャネル名 |
| status | Status | badge | 注文ステータス（canceled時のみ表示） |
| payment_status | Payment | badge | 支払状況 |
| fulfillment_status | Fulfillment | badge | フルフィルメント状況 |

### SummarySection（注文サマリー）
| 項目名 | 表示名 | 型 | 説明 |
|--------|--------|-----|------|
| items | Items | array | 注文商品一覧 |
| items[].thumbnail | - | image | 商品サムネイル |
| items[].product_title | Product | string | 商品名 |
| items[].variant_title | Variant | string | バリアント名 |
| items[].quantity | Qty | number | 数量 |
| items[].unit_price | Price | number | 単価 |
| items[].total | Total | number | 小計 |
| subtotal | Subtotal | number | 小計 |
| discount_total | Discount | number | 割引合計 |
| shipping_total | Shipping | number | 送料 |
| tax_total | Tax | number | 税金 |
| total | Total | number | 合計 |

### PaymentSection（支払情報）
| 項目名 | 表示名 | 型 | 説明 |
|--------|--------|-----|------|
| payment_collections | Payment Collections | array | 支払コレクション一覧 |
| payment_collections[].payments | Payments | array | 支払一覧 |
| payment_collections[].payments[].refunds | Refunds | array | 返金一覧 |

### FulfillmentSection（フルフィルメント情報）
| 項目名 | 表示名 | 型 | 説明 |
|--------|--------|-----|------|
| fulfillments | Fulfillments | array | フルフィルメント一覧 |
| fulfillments[].items | Items | array | フルフィルメント対象商品 |
| fulfillments[].labels | Labels | array | 配送ラベル/追跡情報 |

### CustomerSection（顧客情報）
| 項目名 | 表示名 | 型 | 説明 |
|--------|--------|-----|------|
| customer | Customer | object | 顧客情報 |
| email | Email | string | メールアドレス |
| shipping_address | Shipping Address | object | 配送先住所 |
| billing_address | Billing Address | object | 請求先住所 |

### ActivitySection（アクティビティ）
| 項目名 | 表示名 | 型 | 説明 |
|--------|--------|-----|------|
| timeline | Timeline | array | 注文履歴タイムライン |

## イベント仕様

### 1-注文キャンセル

ActionMenuから「Cancel」を選択すると、確認ダイアログを表示後、注文をキャンセルする。

- 確認ダイアログ: 「Are you sure?」メッセージと注文IDを表示
- API呼び出し: `POST /admin/orders/{id}/cancel`
- 成功時: トースト通知で成功メッセージを表示
- エラー時: トースト通知でエラーメッセージを表示
- 既にキャンセル済みの場合: ボタンが無効化される

### 2-フルフィルメント作成画面遷移

SummarySectionまたはFulfillmentSectionから「Create Fulfillment」を選択。

- 遷移先: `/orders/{id}/fulfillment`

### 3-出荷作成画面遷移

FulfillmentSectionの個別フルフィルメントから「Create Shipment」を選択。

- 遷移先: `/orders/{id}/fulfillments/{fulfillment_id}/create-shipment`

### 4-返品作成画面遷移

SummarySectionから「Create Return」を選択。

- 遷移先: `/orders/{id}/returns`

### 5-クレーム作成画面遷移

SummarySectionから「Create Claim」を選択。

- 遷移先: `/orders/{id}/claims`

### 6-交換作成画面遷移

SummarySectionから「Create Exchange」を選択。

- 遷移先: `/orders/{id}/exchanges`

### 7-注文編集画面遷移

SummarySectionから「Edit Order」を選択。

- 遷移先: `/orders/{id}/edit`

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 注文詳細表示 | order | SELECT | 注文データの取得 |
| 注文詳細表示 | order_item | SELECT | 注文商品データの取得 |
| 注文詳細表示 | customer | SELECT | 顧客データの取得 |
| 注文詳細表示 | fulfillment | SELECT | フルフィルメントデータの取得 |
| 注文詳細表示 | payment_collection | SELECT | 支払データの取得 |
| 注文キャンセル | order | UPDATE | status, canceled_atの更新 |

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

#### order（キャンセル時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | status | "canceled" | 注文ステータス |
| UPDATE | canceled_at | 現在日時 | キャンセル日時 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| orders.orderCanceled | 成功 | Order canceled | 注文キャンセル成功時 |
| orders.cancelWarning | 警告 | Are you sure you want to cancel order #{id}? | キャンセル確認ダイアログ |
| エラーメッセージ | エラー | API返却のエラーメッセージ | API呼び出しエラー時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 注文が見つからない | エラーをthrowしてエラーバウンダリで処理 |
| API呼び出しエラー | トースト通知でエラーメッセージを表示 |
| 認証エラー | ログイン画面へリダイレクト |
| データ取得中 | TwoColumnPageSkeletonを表示 |

## 備考

- ウィジェット拡張ポイントが複数用意されている
  - `order.details.before` / `order.details.after`（メインコンテンツ）
  - `order.details.side.before` / `order.details.side.after`（サイドバー）
- JSON表示とメタデータ表示機能が有効
- 注文にアクティブな変更（Return/Claim/Exchange/Edit）がある場合、専用セクションが表示される
- プラグイン情報を取得し、支払セクションで利用される

---

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

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

### 推奨読解順序

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

まず、注文詳細で取得するフィールドとリレーションを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | constants.ts | `packages/admin/dashboard/src/routes/orders/order-detail/constants.ts` | DEFAULT_FIELDSで取得するプロパティとリレーションを確認 |

**読解のコツ**:
- `DEFAULT_PROPERTIES`には金額関連の詳細フィールドが多数含まれる
- `DEFAULT_RELATIONS`では`*`プレフィックスで関連エンティティを、`+`プレフィックスで追加フィールドを指定

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

処理の起点となるコンポーネントを特定する。

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

**主要処理フロー**:
1. **行22-23**: `useLoaderData`でSSR/プリフェッチデータを取得
2. **行25**: `useParams`で注文IDを取得
3. **行26**: `useExtension`でウィジェット取得関数を取得
4. **行27**: `usePlugins`でプラグイン情報を取得
5. **行29-36**: `useOrder`で注文データを取得
6. **行53-56**: `useOrderPreview`で注文プレビューデータを取得
7. **行67-94**: TwoColumnPageレイアウトで各セクションをレンダリング

#### Step 3: メインセクションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | order-general-section.tsx | `packages/admin/dashboard/src/routes/orders/order-detail/components/order-general-section/order-general-section.tsx` | ヘッダー部分の実装 |
| 3-2 | order-summary-section.tsx | `packages/admin/dashboard/src/routes/orders/order-detail/components/order-summary-section/order-summary-section.tsx` | 注文サマリーの実装 |
| 3-3 | order-payment-section.tsx | `packages/admin/dashboard/src/routes/orders/order-detail/components/order-payment-section/order-payment-section.tsx` | 支払情報の実装 |
| 3-4 | order-fulfillment-section.tsx | `packages/admin/dashboard/src/routes/orders/order-detail/components/order-fulfillment-section/order-fulfillment-section.tsx` | フルフィルメント情報の実装 |

**主要処理フロー（order-general-section.tsx）**:
- **行31**: `useCancelOrder`で注文キャンセルフックを取得
- **行33-55**: `handleCancel`関数で確認ダイアログとキャンセル処理
- **行73-76**: ステータスバッジ（Order/Payment/Fulfillment）の表示
- **行77-90**: ActionMenuでキャンセルアクションを提供

#### Step 4: サイドバーセクションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | order-customer-section.tsx | `packages/admin/dashboard/src/routes/orders/order-detail/components/order-customer-section/order-customer-section.tsx` | 顧客情報の実装 |
| 4-2 | order-activity-section.tsx | `packages/admin/dashboard/src/routes/orders/order-detail/components/order-activity-section/order-activity-section.tsx` | アクティビティ/タイムラインの実装 |

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

```
OrderDetail (order-detail.tsx)
    │
    ├─ useLoaderData (プリフェッチデータ)
    ├─ useParams (注文ID)
    ├─ useExtension (ウィジェット)
    ├─ usePlugins (プラグイン)
    ├─ useOrder (注文データ)
    └─ useOrderPreview (注文プレビュー)
           │
           └─ TwoColumnPage
                  │
                  ├─ Main
                  │      ├─ OrderActiveEditSection
                  │      ├─ ActiveOrderClaimSection
                  │      ├─ ActiveOrderExchangeSection
                  │      ├─ ActiveOrderReturnSection
                  │      ├─ OrderGeneralSection
                  │      │      └─ useCancelOrder
                  │      ├─ OrderSummarySection
                  │      ├─ OrderPaymentSection
                  │      └─ OrderFulfillmentSection
                  │
                  └─ Sidebar
                         ├─ OrderCustomerSection
                         └─ OrderActivitySection
```

### データフロー図

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

URLパラメータ(id) ▶ useParams ──────────────▶ orderId
                          │
                          ▼
orderId ────────▶ useOrder ────────────────▶ order
                          │
                          ▼
order ──────────▶ 各セクション ─────────────▶ 画面表示
                          │
                          ▼
ユーザー操作 ───▶ ActionMenu/Button ────────▶ API呼び出し
                          │
                          ▼
API結果 ────────▶ toast通知 ────────────────▶ フィードバック
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order-detail.tsx | `packages/admin/dashboard/src/routes/orders/order-detail/order-detail.tsx` | ソース | ページコンポーネント |
| constants.ts | `packages/admin/dashboard/src/routes/orders/order-detail/constants.ts` | ソース | 定数定義 |
| loader.ts | `packages/admin/dashboard/src/routes/orders/order-detail/loader.ts` | ソース | データローダー |
| order-general-section.tsx | `packages/admin/dashboard/src/routes/orders/order-detail/components/order-general-section/order-general-section.tsx` | ソース | ヘッダーセクション |
| order-summary-section.tsx | `packages/admin/dashboard/src/routes/orders/order-detail/components/order-summary-section/order-summary-section.tsx` | ソース | サマリーセクション |
| order-payment-section.tsx | `packages/admin/dashboard/src/routes/orders/order-detail/components/order-payment-section/order-payment-section.tsx` | ソース | 支払セクション |
| order-fulfillment-section.tsx | `packages/admin/dashboard/src/routes/orders/order-detail/components/order-fulfillment-section/order-fulfillment-section.tsx` | ソース | フルフィルメントセクション |
| order-customer-section.tsx | `packages/admin/dashboard/src/routes/orders/order-detail/components/order-customer-section/order-customer-section.tsx` | ソース | 顧客セクション |
| order-activity-section.tsx | `packages/admin/dashboard/src/routes/orders/order-detail/components/order-activity-section/order-activity-section.tsx` | ソース | アクティビティセクション |
| orders.tsx | `packages/admin/dashboard/src/hooks/api/orders.tsx` | ソース | API呼び出しフック |
