# 注文サービス 詳細設計書

| 項目 | 内容 |
|------|------|
| 文書番号 | DD-ORDER-001 |
| バージョン | 1.0 |
| 作成日 | 2025年12月1日 |
| ステータス | 承認済み |

---

## 1. サービス概要

注文サービスはECサイトプラットフォームの中核オーケストレーターである。注文ライフサイクル管理を担い、決済サービス・通知サービスとの連携を調整する。

---

## 2. APIエンドポイント

### 2.1 POST /api/v1/orders/ — 注文作成

**1件の注文**を作成する。一括・バッチ作成はサポートしていない。

**リクエスト例:**
```json
{
    "customer_email": "tanaka@example.co.jp",
    "customer_name": "田中太郎",
    "items": [
        {"product_name": "ノートPC", "quantity": 2, "unit_price": 89800.0}
    ],
    "currency": "JPY"
}
```

### 2.2 GET /api/v1/orders/ — 注文一覧

ページネーション対応（skip, limit）。デフォルト: limit=20。

### 2.3 GET /api/v1/orders/{order_id} — 注文取得

### 2.4 PUT /api/v1/orders/{order_id}/status — ステータス更新

発送済みステータスに変更時、発送通知を送信。

### 2.5 DELETE /api/v1/orders/{order_id} — 注文キャンセル

決済サービスに返金リクエスト + 通知サービスにキャンセル通知を送信。

### 2.6 POST /api/v1/orders/{order_id}/webhook — 決済Webhook

決済サービスからのステータス更新コールバックを受信。

---

## 3. データモデル

```mermaid
erDiagram
    orders {
        int id PK
        string customer_email
        string customer_name
        enum status "保留中|決済処理中|決済済み|発送済み|配達完了|キャンセル済み"
        float total_amount
        string currency "JPY"
        datetime created_at
        datetime updated_at
    }
    order_items {
        int id PK
        int order_id FK
        string product_name
        int quantity
        float unit_price
    }
    orders ||--o{ order_items : "明細"
```

> **スキーマ制限:** ordersテーブルには **batch_idカラムなし**、**csv_sourceフィールドなし**、**bulk_import_groupカラムなし**。どの注文がバッチインポートに属するかを追跡する仕組みがない。

---

## 4. 注文ステータス状態遷移

```mermaid
stateDiagram-v2
    [*] --> 保留中 : 注文作成
    保留中 --> 決済処理中 : 決済開始
    決済処理中 --> 決済済み : 決済成功
    決済処理中 --> 保留中 : 決済失敗
    決済済み --> 発送済み : 発送
    発送済み --> 配達完了 : 配達
    保留中 --> キャンセル済み : キャンセル
    決済済み --> キャンセル済み : キャンセル（返金）
    配達完了 --> [*]
    キャンセル済み --> [*]
```

---

## 5. ビジネスロジック — 注文作成オーケストレーション

注文作成フローは**厳密にシーケンシャル**：

1. 注文データ**検証**（1件のペイロードのみ）
2. 合計金額**計算**（数量×単価の合計）
3. 注文をDB**保存**（ステータス: 保留中）
4. ステータスを決済処理中に**更新**
5. **決済サービス呼出** — `POST /api/v1/payments`
6. 決済成功 → ステータスを決済済みに**更新**
7. **通知サービス呼出** — `POST /api/v1/notifications/email`
8. 作成済み注文を**返却**

> **重要:** ステップ5-7は**シーケンシャル実行であり、並列処理ではない**。決済サービスの呼出しに10秒かかれば、注文作成全体が10秒以上かかる。

---

## 6. サービス間連携

### 6.1 決済クライアント

| メソッド | エンドポイント | 目的 |
|---------|--------------|------|
| create_payment | POST /api/v1/payments | 1件の注文の決済処理 |
| get_payment_by_order | GET /api/v1/payments/order/{oid} | 返金用の決済情報取得 |
| process_refund | POST /api/v1/payments/refund | キャンセル時の返金 |

タイムアウト: 30秒。リトライ: なし。

### 6.2 通知クライアント

| メソッド | エンドポイント | 目的 |
|---------|--------------|------|
| send_order_confirmation | POST /api/v1/notifications/email | 注文確認メール |
| send_order_shipped | POST /api/v1/notifications/email | 発送通知 |
| send_order_cancelled | POST /api/v1/notifications/email | キャンセル通知 |

タイムアウト: 10秒。リトライ: なし。通知失敗は注文処理をブロックしない。

---

## 7. 現在の制限事項

| ID | 制限事項 | 影響 |
|----|---------|------|
| DD-LIM-001 | **CSVインポート機能なし。** REST APIのみ。ファイルベースの注文取込み機能は存在しない。 | 法人顧客のCSV一括注文を処理できない。 |
| DD-LIM-002 | **バッチ注文作成エンドポイントなし。** 10,000件の注文処理には10,000回のAPIコールが必要。 | 大量注文処理が極めて低速。 |
| DD-LIM-003 | **サービス間呼出しはシーケンシャル。** 決済と通知は逐次実行。 | 注文作成レイテンシ = 保存 + 決済 + 通知の合計時間。 |
| DD-LIM-004 | **リトライ機構・サーキットブレーカーなし。** 決済サービスダウン時、即座に失敗。 | 一時的障害への耐性なし。 |
| DD-LIM-005 | **サービス間トランザクションロールバックなし。** 決済成功後に通知失敗しても補償トランザクションなし。 | 結果整合性のみ。 |
| DD-LIM-006 | **DBスキーマにバッチ追跡カラムなし。** batch_id, csv_source, import_groupフィールドが存在しない。 | 同一バッチの注文を関連付けできない。 |