# Order Service — Detailed Design

| Field | Value |
|-------|-------|
| Document ID | DD-ORDER-001 |
| Version | 1.0 |
| Date | 2025-12-01 |
| Status | Approved |

---

## 1. Service Overview

The Order Service is the primary orchestrator of the E-Commerce platform. It manages order lifecycle and coordinates with Payment Service and Notification Service for payment processing and customer communications.

**Responsibilities:**
- Order CRUD operations (create, read, update status, cancel)
- Order total calculation from line items
- Cross-service orchestration (Payment + Notification)
- Payment webhook handling

---

## 2. API Endpoints

### 2.1 POST /api/v1/orders/ — Create Order

Creates a **single** order. No bulk/batch creation supported.

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

**Response (201):**
```json
{
    "id": 1,
    "customer_email": "tanaka@example.co.jp",
    "customer_name": "田中太郎",
    "status": "paid",
    "total_amount": 179600.0,
    "currency": "JPY",
    "items": [{"id": 1, "product_name": "ノートPC", "quantity": 2, "unit_price": 89800.0}],
    "created_at": "2025-12-01T10:00:00Z",
    "updated_at": "2025-12-01T10:00:01Z"
}
```

### 2.2 GET /api/v1/orders/ — List Orders

Paginated listing. Parameters: `skip` (default 0), `limit` (default 20).

### 2.3 GET /api/v1/orders/{order_id} — Get Order

Returns single order with items. 404 if not found.

### 2.4 PUT /api/v1/orders/{order_id}/status — Update Status

Updates order status. SHIPPED status triggers shipping notification.

### 2.5 DELETE /api/v1/orders/{order_id} — Cancel Order

Cancels order. Triggers: refund via Payment Service, cancellation email via Notification Service.

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

Receives payment status updates from Payment Service. Updates order status accordingly.

---

## 3. Data Model

```mermaid
erDiagram
    orders {
        int id PK
        string customer_email
        string customer_name
        enum status "PENDING|PAYMENT_PROCESSING|PAID|SHIPPED|DELIVERED|CANCELLED"
        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 : "has"
```

> **Schema Limitation:** The orders table has **no batch_id column**, **no csv_source field**, and **no bulk_import_group column**. There is no mechanism to track which orders belong to a batch import operation. Each order is an independent entity.

---

## 4. Order Status State Machine

```mermaid
stateDiagram-v2
    [*] --> PENDING : Order created
    PENDING --> PAYMENT_PROCESSING : Payment initiated
    PAYMENT_PROCESSING --> PAID : Payment successful
    PAYMENT_PROCESSING --> PENDING : Payment failed
    PAID --> SHIPPED : Order shipped
    SHIPPED --> DELIVERED : Order delivered
    PENDING --> CANCELLED : Customer cancels
    PAID --> CANCELLED : Customer cancels (triggers refund)
    DELIVERED --> [*]
    CANCELLED --> [*]
```

---

## 5. Business Logic — Order Creation Orchestration

The order creation flow is **strictly sequential**:

1. **Validate** order data (single order payload only)
2. **Calculate** total amount from line items: `sum(quantity × unit_price)`
3. **Save** order to database with status PENDING
4. **Update** status to PAYMENT_PROCESSING
5. **Call Payment Service** — `POST /api/v1/payments` with order_id, amount, currency
6. On payment success → **Update** status to PAID
7. **Call Notification Service** — `POST /api/v1/notifications/email` with ORDER_CONFIRMATION template
8. **Return** created order

> **IMPORTANT:** Steps 5-7 execute **sequentially, not in parallel**. If Payment Service call takes 10 seconds, the entire order creation takes 10+ seconds. There is no parallel processing capability.

---

## 6. Cross-Service Integration

### 6.1 PaymentClient

| Method | Endpoint | Purpose |
|--------|----------|---------|
| create_payment | POST /api/v1/payments | Process payment for single order |
| get_payment_by_order | GET /api/v1/payments/order/{oid} | Lookup payment for refund |
| process_refund | POST /api/v1/payments/refund | Refund on cancellation |

**Timeout:** 30 seconds. **Retry:** None. **Error handling:** Log error, revert status to PENDING.

### 6.2 NotificationClient

| Method | Endpoint | Purpose |
|--------|----------|---------|
| send_order_confirmation | POST /api/v1/notifications/email | Confirmation email |
| send_order_shipped | POST /api/v1/notifications/email | Shipping notification |
| send_order_cancelled | POST /api/v1/notifications/email | Cancellation notification |

**Timeout:** 10 seconds. **Retry:** None. **Error handling:** Log error, continue (notification failure does not block order).

---

## 7. Current Limitations

| ID | Limitation | Impact |
|----|-----------|--------|
| DD-LIM-001 | **No CSV import capability.** Orders are created via REST API only. No endpoint exists for file-based order import. | Cannot process bulk orders from enterprise customers who submit CSV files. |
| DD-LIM-002 | **No batch order creation endpoint.** The POST /api/v1/orders/ endpoint accepts a single order. Processing 10,000 orders requires 10,000 API calls. | Extremely slow for large-volume order processing. |
| DD-LIM-003 | **Cross-service calls are sequential, not parallel.** Payment and notification calls execute one after another. | Order creation latency = save + payment + notification time. |
| DD-LIM-004 | **No retry mechanism or circuit breaker.** If Payment Service is down, order creation fails immediately. | No resilience against transient failures. |
| DD-LIM-005 | **No cross-service transaction rollback.** If payment succeeds but notification fails, there is no compensating transaction. | Eventual consistency only — no guaranteed atomicity. |
| DD-LIM-006 | **Database schema has no batch tracking columns.** No batch_id, csv_source, or import_group fields exist in the orders table. | Cannot correlate orders belonging to the same import batch. |