# 機能設計書 9-注文CRUD

## 概要

本ドキュメントは、Medusaコマースプラットフォームにおける注文（Order）のCRUD操作機能の設計を記述する。

### 本機能の処理概要

**業務上の目的・背景**：
注文は、ECサイトにおける購買取引の中核となるエンティティである。顧客が商品を購入した際の全情報（明細、配送先、支払い、フルフィルメント状態など）を管理する。注文はバージョン管理されており、変更履歴を追跡できる。

**機能の利用シーン**：
- ストアフロントでのチェックアウト後の注文作成
- 管理画面での注文一覧表示・検索
- 注文詳細の確認
- 注文情報の更新（住所変更、メール変更など）
- 注文のキャンセル
- 注文の完了・アーカイブ

**主要な処理内容**：
1. 注文の作成（ドラフト注文含む）
2. 注文一覧の取得（フィルタ・ページネーション対応）
3. 注文詳細の取得（バージョン指定可能）
4. 注文の更新（住所、メール、ロケールなど）
5. 注文のキャンセル
6. 注文の完了・アーカイブ

**関連システム・外部連携**：
- 顧客モジュール（Customer Module）：顧客情報との関連
- 決済モジュール（Payment Module）：決済処理
- フルフィルメントモジュール：出荷処理
- 在庫モジュール（Inventory Module）：在庫引当
- リージョンモジュール：地域・通貨設定

**権限による制御**：
- Admin API経由のアクセスには認証が必要（AuthenticatedMedusaRequest）
- 注文の作成・更新・キャンセルは管理者権限を持つユーザーのみ実行可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | 注文一覧画面 | 主画面 | 注文の一覧表示・検索 |
| 22 | 注文詳細画面 | 主画面 | 注文詳細の確認・更新 |

## 機能種別

CRUD操作（Create / Read / Update / Delete（キャンセル））

## 入力仕様

### 入力パラメータ

#### 注文作成（POST /admin/orders）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| region_id | string | No | リージョンID | 存在確認 |
| items | array | No | 注文明細 | - |
| items[].variant_id | string | No | バリアントID | 存在確認 |
| items[].quantity | number | Yes | 数量 | 正の整数 |
| items[].unit_price | number | No | 単価 | - |
| shipping_address | object | No | 配送先住所 | - |
| billing_address | object | No | 請求先住所 | - |
| email | string | No | メールアドレス | email形式 |
| customer_id | string | No | 顧客ID | - |
| sales_channel_id | string | No | 販売チャネルID | - |
| status | string | No | 注文ステータス | OrderStatus enum |
| promo_codes | array | No | プロモーションコード | - |

#### 注文更新（POST /admin/orders/:id）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| shipping_address | object | No | 配送先住所 | 国コード変更不可 |
| billing_address | object | No | 請求先住所 | 国コード変更不可 |
| email | string | No | メールアドレス | email形式 |
| locale | string | No | ロケール | - |
| metadata | object | No | メタデータ | - |

### 入力データソース

- 管理画面（Admin Dashboard）からの操作
- ストアフロントからのチェックアウト処理
- REST API経由のJSON/リクエストボディ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | 注文ID（order_xxx形式） |
| display_id | number | 表示用連番ID |
| status | string | 注文ステータス |
| version | number | バージョン番号 |
| email | string | 顧客メールアドレス |
| currency_code | string | 通貨コード |
| region_id | string | リージョンID |
| customer_id | string | 顧客ID |
| sales_channel_id | string | 販売チャネルID |
| shipping_address | object | 配送先住所 |
| billing_address | object | 請求先住所 |
| items | array | 注文明細 |
| shipping_methods | array | 配送方法 |
| transactions | array | 取引履歴 |
| summary | object | 合計金額サマリー |
| created_at | datetime | 作成日時 |
| updated_at | datetime | 更新日時 |
| canceled_at | datetime | キャンセル日時 |

### 出力先

- REST APIレスポンス（JSON形式）
- 管理画面への表示

## 処理フロー

### 処理シーケンス

```
1. 注文作成フロー
   ├─ 販売チャネル・リージョン・顧客の取得/作成
   ├─ 価格コンテキストの設定（setPricingContextフック）
   ├─ バリアント在庫の確認
   ├─ 明細データの準備
   ├─ 注文作成（createOrdersStep）
   ├─ 税金計算（updateOrderTaxLinesWorkflow）
   ├─ プロモーション適用
   └─ orderCreatedフック実行

2. 注文一覧取得フロー
   ├─ getOrdersListWorkflow実行
   ├─ フィルタ条件の適用（is_draft_order: false）
   └─ ページネーション処理

3. 注文詳細取得フロー
   ├─ getOrderDetailWorkflow実行
   └─ バージョン指定による履歴取得

4. 注文更新フロー
   ├─ 注文の取得・バリデーション
   ├─ キャンセル済みチェック
   ├─ 国コード変更チェック
   ├─ メール形式バリデーション
   ├─ 更新実行（updateOrdersStep）
   ├─ 変更履歴登録（registerOrderChangesStep）
   ├─ ロケール変更時の翻訳更新
   └─ イベント発行（OrderWorkflowEvents.UPDATED）

5. 注文キャンセルフロー
   ├─ キャンセル可否バリデーション
   ├─ 未キャプチャ決済のキャンセル
   ├─ 予約の削除
   ├─ キャプチャ済み決済の返金
   ├─ クレジットライン作成
   ├─ 支払いコレクションのステータス更新
   ├─ 注文キャンセル実行（cancelOrdersStep）
   └─ イベント発行（OrderWorkflowEvents.CANCELED）
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-O01 | キャンセル済み不可更新 | キャンセルされた注文は更新不可 | 注文更新時 |
| BR-O02 | 国コード不変 | 住所の国コードは変更不可 | 注文更新時 |
| BR-O03 | フルフィルメント確認 | キャンセル時は全フルフィルメントがキャンセル済みであること | 注文キャンセル時 |
| BR-O04 | 決済処理 | キャンセル時は未キャプチャ決済をキャンセル、キャプチャ済みは返金 | 注文キャンセル時 |
| BR-O05 | バージョン管理 | 注文変更はバージョンとして記録 | 注文更新時 |
| BR-O06 | ドラフト注文除外 | 一覧取得時はドラフト注文を除外 | 注文一覧取得時 |

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 作成 | order | INSERT | 注文レコードの挿入 |
| 取得 | order | SELECT | 注文の取得 |
| 更新 | order | UPDATE | 注文の更新 |
| 更新 | order_address | INSERT | 住所変更時に新規作成 |
| キャンセル | order | UPDATE | status/canceled_atの更新 |

### テーブル別操作詳細

#### order

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（order_xxx形式） | generateEntityId使用 |
| INSERT | display_id | 自動インクリメント | searchable |
| INSERT | status | pending | デフォルト |
| INSERT | version | 1 | デフォルト |
| UPDATE | version | インクリメント | 変更時 |
| CANCEL | canceled_at | 現在日時 | キャンセル時 |

### インデックス情報

| インデックス名 | カラム | 用途 |
|--------------|--------|------|
| IDX_order_display_id | display_id | 表示ID検索 |
| IDX_order_custom_display_id | custom_display_id | カスタムID検索（ユニーク） |
| IDX_order_region_id | region_id | リージョン絞り込み |
| IDX_order_customer_id | customer_id | 顧客絞り込み |
| IDX_order_sales_channel_id | sales_channel_id | 販売チャネル絞り込み |
| IDX_order_currency_code | currency_code | 通貨絞り込み |
| IDX_order_is_draft_order | is_draft_order | ドラフト除外 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NOT_FOUND | 404 | 指定IDの注文が存在しない | 正しいIDを指定 |
| INVALID_DATA | 400 | 国コード変更を試みた | 国コードは変更不可 |
| INVALID_DATA | 400 | メールアドレスが不正 | 正しいemail形式を指定 |
| NOT_ALLOWED | 403 | キャンセル済み注文の更新 | キャンセル済み注文は更新不可 |
| NOT_ALLOWED | 403 | 未キャンセルのフルフィルメントがある | 全フルフィルメントをキャンセル後に実行 |

## 備考

- 注文のIDプレフィックスは「order」
- display_idは自動インクリメントで顧客表示用
- 注文削除時はcascadesでsummary, items, shipping_methods, transactions, credit_linesも削除
- ステータスはOrderStatus enum（pending, completed, canceled等）

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | order.ts | `packages/modules/order/src/models/order.ts` | 注文モデル定義 |

**主要処理フロー（order.ts）**:
- **10-59行目**: Orderモデル定義
- **12行目**: IDプレフィックス「order」
- **13行目**: display_id（autoincrement, searchable）
- **17行目**: version（default(1)）
- **19行目**: status（OrderStatus enum）
- **27-40行目**: 住所リレーション（shipping_address, billing_address）
- **44-58行目**: 関連エンティティ（items, shipping_methods, transactions等）
- **60-68行目**: cascades設定

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | route.ts | `packages/medusa/src/api/admin/orders/route.ts` | 一覧取得エンドポイント |
| 2-2 | [id]/route.ts | `packages/medusa/src/api/admin/orders/[id]/route.ts` | 詳細・更新エンドポイント |
| 2-3 | cancel/route.ts | `packages/medusa/src/api/admin/orders/[id]/cancel/route.ts` | キャンセルエンドポイント |

**主要処理フロー（route.ts）**:
- **8-38行目**: GET - getOrdersListWorkflowで一覧取得
- **15-16行目**: is_draft_order: falseでドラフト除外

**主要処理フロー（[id]/route.ts）**:
- **12-28行目**: GET - getOrderDetailWorkflowで詳細取得
- **30-54行目**: POST - updateOrderWorkflowで更新

#### Step 3: ワークフローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | create-order.ts | `packages/core/core-flows/src/order/workflows/create-order.ts` | 注文作成ワークフロー |
| 3-2 | update-order.ts | `packages/core/core-flows/src/order/workflows/update-order.ts` | 注文更新ワークフロー |
| 3-3 | cancel-order.ts | `packages/core/core-flows/src/order/workflows/cancel-order.ts` | 注文キャンセルワークフロー |

**主要処理フロー（create-order.ts）**:
- **173-437行目**: createOrderWorkflow定義
- **182-193行目**: 販売チャネル・リージョン・顧客の並列取得
- **195-206行目**: setPricingContextフック
- **304-310行目**: 在庫確認ワークフロー実行
- **370行目**: createOrdersStep実行
- **413-426行目**: 税金計算・プロモーション適用

**主要処理フロー（update-order.ts）**:
- **71-102行目**: updateOrderValidationStep（バリデーション）
- **126-307行目**: updateOrderWorkflow定義
- **154行目**: updateOrderValidationStep実行
- **194-197行目**: updateOrdersStep実行
- **300-303行目**: OrderWorkflowEvents.UPDATEDイベント発行

**主要処理フロー（cancel-order.ts）**:
- **69-96行目**: cancelValidateOrderステップ
- **125-238行目**: cancelOrderWorkflow定義
- **152行目**: cancelValidateOrder実行
- **172-182行目**: 返金・予約削除・決済キャンセル・イベント発行の並列実行
- **228行目**: cancelOrdersStep実行

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

```
[Admin Dashboard / REST Client]
    │
    ▼
GET /admin/orders
    │
    ├──▶ getOrdersListWorkflow
    │       └── Query Graph (order entity)
    │
GET /admin/orders/:id
    │
    ├──▶ getOrderDetailWorkflow
    │       └── Query Graph with version
    │
POST /admin/orders/:id
    │
    ├──▶ updateOrderWorkflow
    │       ├── useQueryGraphStep (order取得)
    │       ├── updateOrderValidationStep
    │       ├── findOrCreateCustomerStep (email変更時)
    │       ├── updateOrdersStep
    │       ├── registerOrderChangesStep
    │       ├── updateOrderItemsTranslationsStep (locale変更時)
    │       └── emitEventStep(OrderWorkflowEvents.UPDATED)
    │
POST /admin/orders/:id/cancel
    │
    └──▶ cancelOrderWorkflow
            ├── useQueryGraphStep (order取得)
            ├── cancelValidateOrder
            ├── parallelize:
            │   ├── refundCapturedPaymentsWorkflow
            │   ├── deleteReservationsByLineItemsStep
            │   ├── cancelPaymentStep
            │   └── emitEventStep(OrderWorkflowEvents.CANCELED)
            ├── createOrderRefundCreditLinesWorkflow
            ├── updatePaymentCollectionStep
            └── cancelOrdersStep
```

### データフロー図

```
┌─────────────────────────────────────────────────────────┐
│                     Admin API Layer                      │
│  ┌─────────────────────────────────────────────────────┐│
│  │                  /admin/orders/                     ││
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  ││
│  │  │   GET    │  │ GET/:id  │  │   POST/:id       │  ││
│  │  │ (一覧)   │  │ (詳細)   │  │  (更新/cancel)   │  ││
│  │  └────┬─────┘  └────┬─────┘  └────┬─────────────┘  ││
│  └───────┼─────────────┼─────────────┼────────────────┘│
└──────────┼─────────────┼─────────────┼─────────────────┘
           │             │             │
           ▼             ▼             ▼
┌─────────────────────────────────────────────────────────┐
│                   Workflow Layer                         │
│  ┌────────────────┬────────────────┬──────────────────┐ │
│  │ getOrdersList  │ getOrderDetail │ updateOrder/     │ │
│  │ Workflow       │ Workflow       │ cancelOrder      │ │
│  └───────┬────────┴───────┬────────┴────────┬─────────┘ │
│          │                │                  │          │
│          ▼                ▼                  ▼          │
│  ┌────────────────────────────────────────────────────┐ │
│  │              Order Module Service                  │ │
│  │  ┌───────────┬───────────┬───────────────────────┐│ │
│  │  │   list    │    get    │   update / cancel     ││ │
│  │  └─────┬─────┴─────┬─────┴───────────┬───────────┘│ │
│  └────────┼───────────┼─────────────────┼────────────┘ │
└───────────┼───────────┼─────────────────┼──────────────┘
            │           │                 │
            ▼           ▼                 ▼
┌─────────────────────────────────────────────────────────┐
│                   Database Layer                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │                   order table                     │  │
│  │  id | display_id | status | version | email ...  │  │
│  └───────────────────────────────────────────────────┘  │
│                         │                               │
│         ┌───────────────┼───────────────┐               │
│         ▼               ▼               ▼               │
│  ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐  │
│  │ order_item   │ │ order_address│ │ order_shipping  │  │
│  │ (明細)       │ │ (住所)       │ │ (配送)          │  │
│  └──────────────┘ └──────────────┘ └─────────────────┘  │
└─────────────────────────────────────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order.ts | `packages/modules/order/src/models/order.ts` | モデル | 注文エンティティ定義 |
| route.ts | `packages/medusa/src/api/admin/orders/route.ts` | API | 一覧エンドポイント |
| [id]/route.ts | `packages/medusa/src/api/admin/orders/[id]/route.ts` | API | 詳細・更新エンドポイント |
| cancel/route.ts | `packages/medusa/src/api/admin/orders/[id]/cancel/route.ts` | API | キャンセルエンドポイント |
| create-order.ts | `packages/core/core-flows/src/order/workflows/create-order.ts` | ワークフロー | 注文作成 |
| update-order.ts | `packages/core/core-flows/src/order/workflows/update-order.ts` | ワークフロー | 注文更新 |
| cancel-order.ts | `packages/core/core-flows/src/order/workflows/cancel-order.ts` | ワークフロー | 注文キャンセル |
| get-orders-list.ts | `packages/core/core-flows/src/order/workflows/get-orders-list.ts` | ワークフロー | 一覧取得 |
| get-order-detail.ts | `packages/core/core-flows/src/order/workflows/get-order-detail.ts` | ワークフロー | 詳細取得 |
