# 機能設計書 10-注文明細管理

## 概要

本ドキュメントは、Medusaコマースプラットフォームにおける注文明細（Order Line Item / Order Item）管理機能の設計を記述する。

### 本機能の処理概要

**業務上の目的・背景**：
注文明細は、注文に含まれる個々の商品・数量・価格情報を管理する。Medusaでは注文明細は2つのモデルで構成される：OrderItem（注文と明細の関連、数量状態管理）とOrderLineItem（商品情報のスナップショット）。バージョン管理により、注文変更時の履歴追跡が可能。

**機能の利用シーン**：
- 注文作成時の明細自動生成
- 注文詳細画面での明細表示
- フルフィルメント処理（出荷数量の更新）
- 返品処理（返品数量の更新）
- 注文編集での明細変更

**主要な処理内容**：
1. 注文作成時の明細自動生成
2. 注文明細の一覧取得（バージョン履歴付き）
3. フルフィルメント時の数量更新
4. 返品時の数量更新
5. 注文削除時の明細カスケード削除

**関連システム・外部連携**：
- 注文モジュール：親となる注文エンティティ
- 商品モジュール：商品・バリアント情報のスナップショット
- フルフィルメントモジュール：出荷処理との連携
- 返品モジュール：返品処理との連携

**権限による制御**：
- Admin API経由のアクセスには認証が必要（AuthenticatedMedusaRequest）
- 明細の閲覧・更新は管理者権限を持つユーザーのみ

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | 注文詳細画面 | 主画面 | 注文明細の表示 |

## 機能種別

CRUD操作（注文の子リソースとしてのCRUD）

## 入力仕様

### 入力パラメータ

#### 明細一覧取得（GET /admin/orders/:id/line-items）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| id | string | Yes | 注文ID | 存在確認 |

#### 注文作成時の明細（POST /admin/orders items配列）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| variant_id | string | No | バリアントID | 存在確認 |
| quantity | number | Yes | 数量 | 正の整数 |
| unit_price | number | No | 単価 | - |
| title | string | No | 商品名 | - |
| subtitle | string | No | サブタイトル | - |
| thumbnail | string | No | サムネイルURL | - |
| is_tax_inclusive | boolean | No | 税込み価格か | - |
| tax_lines | array | No | 税金明細 | - |
| adjustments | array | No | 調整明細 | - |

### 入力データソース

- 注文作成ワークフロー経由
- REST API経由のJSON/リクエストボディ

## 出力仕様

### 出力データ

#### OrderItem（注文-明細関連）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | 注文明細関連ID（orditem_xxx形式） |
| order_id | string | 注文ID |
| item_id | string | 明細ID |
| version | number | バージョン番号 |
| unit_price | bigNumber | 単価 |
| compare_at_unit_price | bigNumber | 比較価格 |
| quantity | bigNumber | 注文数量 |
| fulfilled_quantity | bigNumber | 出荷済み数量 |
| delivered_quantity | bigNumber | 配達済み数量 |
| shipped_quantity | bigNumber | 発送済み数量 |
| return_requested_quantity | bigNumber | 返品リクエスト数量 |
| return_received_quantity | bigNumber | 返品受領数量 |
| return_dismissed_quantity | bigNumber | 返品却下数量 |
| written_off_quantity | bigNumber | 損金処理数量 |
| metadata | object | メタデータ |

#### OrderLineItem（明細詳細）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | 明細ID（ordli_xxx形式） |
| title | string | 商品名 |
| subtitle | string | サブタイトル |
| thumbnail | string | サムネイルURL |
| variant_id | string | バリアントID |
| product_id | string | 商品ID |
| product_title | string | 商品タイトル |
| product_description | string | 商品説明 |
| variant_sku | string | バリアントSKU |
| variant_barcode | string | バリアントバーコード |
| variant_title | string | バリアントタイトル |
| variant_option_values | object | オプション値 |
| requires_shipping | boolean | 配送要否 |
| is_giftcard | boolean | ギフトカードか |
| is_discountable | boolean | 割引適用可能か |
| is_tax_inclusive | boolean | 税込みか |
| unit_price | bigNumber | 単価 |
| is_custom_price | boolean | カスタム価格か |
| tax_lines | array | 税金明細 |
| adjustments | array | 調整明細 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 注文作成時の明細生成フロー
   ├─ バリアント情報の取得
   ├─ 価格計算（calculated_price取得）
   ├─ 明細データの準備（prepareLineItemData）
   ├─ 価格バリデーション
   └─ 注文と一緒に明細を作成

2. 明細一覧取得フロー
   ├─ Query Graphでorder_items取得
   ├─ バージョン別重複排除
   ├─ 履歴情報の付与
   └─ 最新バージョンの明細を返却

3. フルフィルメント時の数量更新
   ├─ fulfilled_quantity更新
   ├─ shipped_quantity更新
   ├─ delivered_quantity更新
   └─ バージョンインクリメント

4. 返品時の数量更新
   ├─ return_requested_quantity更新
   ├─ return_received_quantity更新
   └─ バージョンインクリメント

5. 注文削除時のカスケード削除
   └─ cascades.deleteでitems自動削除
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-LI01 | バージョン管理 | 明細変更はバージョンとして記録 | 明細更新時 |
| BR-LI02 | 数量追跡 | フルフィルメント・返品の各段階で数量を追跡 | 処理進行時 |
| BR-LI03 | 商品スナップショット | 注文時点の商品情報を保持 | 注文作成時 |
| BR-LI04 | カスケード削除 | 注文削除時に関連明細も削除 | 注文削除時 |
| BR-LI05 | 税金・調整 | 明細ごとに税金明細と調整明細を持つ | 明細作成時 |

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 作成 | order_item | INSERT | 注文-明細関連の挿入 |
| 作成 | order_line_item | INSERT | 明細詳細の挿入 |
| 取得 | order_item | SELECT | 明細関連の取得 |
| 更新 | order_item | UPDATE | 数量の更新 |
| 削除 | order_item | UPDATE | deleted_atの設定 |

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

#### order_item

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（orditem_xxx形式） | generateEntityId使用 |
| INSERT | version | 1 | デフォルト |
| UPDATE | fulfilled_quantity | フルフィルメント数 | 出荷時 |
| UPDATE | version | インクリメント | 変更時 |

#### order_line_item

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（ordli_xxx形式） | generateEntityId使用 |
| INSERT | title | 商品名 | 必須 |
| INSERT | variant_id | バリアントID | スナップショット参照 |

### インデックス情報

| インデックス名 | カラム | 用途 |
|--------------|--------|------|
| IDX_order_item_order_id | order_id | 注文による絞り込み |
| IDX_order_item_order_id_version | order_id, version | バージョン履歴取得 |
| IDX_order_item_item_id | item_id | 明細参照 |
| IDX_order_line_item_product_id | product_id | 商品検索 |
| IDX_order_line_item_variant_id | variant_id | バリアント検索 |
| IDX_line_item_product_type_id | product_type_id | タイプ検索 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NOT_FOUND | 404 | 指定IDの注文が存在しない | 正しいIDを指定 |
| INVALID_DATA | 400 | 数量が不正 | 正の数値を指定 |
| INVALID_DATA | 400 | 単価が未設定かつ計算不可 | 単価を明示的に指定 |

## 備考

- OrderItemのIDプレフィックスは「orditem」
- OrderLineItemのIDプレフィックスは「ordli」
- 注文削除時にcascadesでitemsも自動削除
- bigNumber型で高精度な金額計算に対応
- tax_linesとadjustmentsもカスケード削除対象

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | order-item.ts | `packages/modules/order/src/models/order-item.ts` | 注文-明細関連モデル |
| 1-2 | line-item.ts | `packages/modules/order/src/models/line-item.ts` | 明細詳細モデル |

**主要処理フロー（order-item.ts）**:
- **6-28行目**: OrderItemモデル定義
- **8行目**: IDプレフィックス「orditem」
- **9行目**: version（default(1)）
- **12-19行目**: 数量管理フィールド群
- **21-23行目**: 注文とのbelongsToリレーション
- **24-27行目**: 明細とのhasOneリレーション
- **29-54行目**: インデックス定義

**主要処理フロー（line-item.ts）**:
- **5-44行目**: OrderLineItemモデル定義
- **7行目**: IDプレフィックス「ordli」
- **8-30行目**: 商品情報スナップショットフィールド
- **32-43行目**: tax_lines, adjustmentsリレーション
- **45-47行目**: cascades設定

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | line-items/route.ts | `packages/medusa/src/api/admin/orders/[id]/line-items/route.ts` | 明細一覧取得エンドポイント |

**主要処理フロー（line-items/route.ts）**:
- **11-69行目**: GET - Query Graphで明細取得
- **19-26行目**: order_itemsエンティティからの取得
- **29-64行目**: バージョン別重複排除処理
- **38-45行目**: 履歴情報の付与

#### Step 3: 注文作成フローでの明細生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | create-order.ts | `packages/core/core-flows/src/order/workflows/create-order.ts` | 明細生成部分 |

**主要処理フロー（create-order.ts）**:
- **35-59行目**: prepareLineItems関数（明細データ準備）
- **317-359行目**: lineItems作成ロジック
- **361行目**: validateLineItemPricesStep（価格バリデーション）
- **363-368行目**: orderToCreate（明細を含む注文データ）

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

```
[Admin Dashboard / REST Client]
    │
    ▼
GET /admin/orders/:id/line-items
    │
    ├──▶ Query Graph
    │       ├── order_items取得
    │       ├── バージョン別重複排除
    │       └── 履歴情報付与
    │
POST /admin/orders (注文作成)
    │
    └──▶ createOrderWorkflow
            ├── バリアント情報取得
            ├── getVariantsAndItemsWithPrices
            ├── prepareLineItems（明細準備）
            ├── validateLineItemPricesStep
            └── createOrdersStep（明細含む）
```

### データフロー図

```
┌─────────────────────────────────────────────────────────┐
│                     Admin API Layer                      │
│  ┌─────────────────────────────────────────────────────┐│
│  │         /admin/orders/:id/line-items                ││
│  │  ┌───────────────────────────────────────────────┐  ││
│  │  │                    GET                        │  ││
│  │  │    (明細一覧取得、バージョン履歴付き)           │  ││
│  │  └─────────────────────┬─────────────────────────┘  ││
│  └────────────────────────┼────────────────────────────┘│
└───────────────────────────┼─────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                   Query Layer                            │
│  ┌────────────────────────────────────────────────────┐ │
│  │                 Query Graph                        │ │
│  │  entity: order_items                              │ │
│  │  fields: [item_id, version, ...]                  │ │
│  └───────────────────────┬────────────────────────────┘ │
└──────────────────────────┼──────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   Database Layer                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │                 order_item table                  │  │
│  │  id (orditem_xxx) | order_id | item_id | version │  │
│  │  quantity | fulfilled_qty | shipped_qty | ...    │  │
│  └──────────────────────┬────────────────────────────┘  │
│                         │ hasOne                        │
│                         ▼                               │
│  ┌───────────────────────────────────────────────────┐  │
│  │               order_line_item table               │  │
│  │  id (ordli_xxx) | title | variant_id | unit_price│  │
│  │  product_id | variant_sku | thumbnail | ...      │  │
│  └───────────────────────────────────────────────────┘  │
│                         │                               │
│         ┌───────────────┴───────────────┐               │
│         ▼                               ▼               │
│  ┌──────────────────────┐  ┌───────────────────────┐    │
│  │ order_line_item_     │  │ order_line_item_     │    │
│  │ tax_line (税金)      │  │ adjustment (調整)    │    │
│  └──────────────────────┘  └───────────────────────┘    │
└─────────────────────────────────────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order-item.ts | `packages/modules/order/src/models/order-item.ts` | モデル | 注文-明細関連エンティティ |
| line-item.ts | `packages/modules/order/src/models/line-item.ts` | モデル | 明細詳細エンティティ |
| line-item-tax-line.ts | `packages/modules/order/src/models/line-item-tax-line.ts` | モデル | 明細税金エンティティ |
| line-item-adjustment.ts | `packages/modules/order/src/models/line-item-adjustment.ts` | モデル | 明細調整エンティティ |
| line-items/route.ts | `packages/medusa/src/api/admin/orders/[id]/line-items/route.ts` | API | 明細一覧エンドポイント |
| create-order.ts | `packages/core/core-flows/src/order/workflows/create-order.ts` | ワークフロー | 注文作成（明細含む） |
| prepare-line-item-data.ts | `packages/core/core-flows/src/cart/utils/prepare-line-item-data.ts` | ユーティリティ | 明細データ準備 |
