## Requirements

# 4. Requirements

## 4.1 Functional Requirements

### 4.1.1 Order Service

- The system shall allow creation of a single order per API request. Bulk or batch order creation is not supported.  
  [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]
- The system shall require customer information (name, email) and order details (product name, quantity, unit price) for order creation.  
  [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205]
- The system shall automatically calculate the total order amount as the sum of (quantity × unit price) for all items.  
  [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205]
- The system shall support paginated retrieval of order lists (parameters: skip, limit; default limit: 20).  
  [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add]
- The system shall allow retrieval of order details by order ID, including item details.  
  [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f]
- The system shall support order status transitions: PENDING → PROCESSING → PAID → SHIPPED → DELIVERED.  
  [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f]
- The system shall support order cancellation, updating status to CANCELLED.  
  [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f]

### 4.1.2 Payment Service

- The system shall process payment for a single order per request. Batch payment processing is not supported.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-8ca26148-03e1-4184-a736-624e14448df9]
- The system shall enforce a minimum payment amount of 100 JPY and a maximum of 1,000,000 JPY per transaction.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]
- The system shall maintain a 1:1 relationship between order and payment (one payment per order).  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]
- The system shall reject duplicate payment requests for the same order ID.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]
- The system shall support refund processing for completed payments.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]
- The system shall notify Order Service of payment status via webhook callback after payment processing.  
  [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397]

### 4.1.3 Notification Service

- The system shall send email notifications for individual orders using templates.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]
- The system shall send SMS notifications for individual orders using templates.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]
- The system shall support three notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]
- Templates shall support Jinja2-style variable substitution with Japanese language content.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c]
- The system shall track notification delivery status (PENDING, SENT, FAILED).  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]
- The system shall retrieve notification history by notification ID.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]
- The system shall retrieve all notifications for a specific order.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]

### 4.1.4 Cross-Service Integration

- Order Service shall call Payment Service to process payment upon order creation.  
  [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c]
- Payment Service shall call Order Service via webhook to update order status after payment completion.  
  [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397]
- Order Service shall call Notification Service to send confirmation, shipment, and cancellation notifications.  
  [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c]

## 4.2 Constraint Requirements

- Only single order creation, payment, and notification per API request are permitted. No batch or bulk endpoints exist.  
  [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-582e7673-bd66-493e-b511-017708ae9326]
- Maximum payment amount per transaction is strictly 1,000,000 JPY.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]
- Duplicate payment requests for the same order ID are rejected.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]
- Notification Service enforces a rate limit of 10 requests per second for email notifications.  
  [KB-582e7673-bd66-493e-b511-017708ae9326]

## 4.3 Interface Requirements

### 4.3.1 Order Service API

| Endpoint                              | Description                                 |
|----------------------------------------|---------------------------------------------|
| POST /api/v1/orders/                   | Create single order                         |
| GET /api/v1/orders/                    | List orders (paginated: skip, limit)        |
| GET /api/v1/orders/{order_id}          | Retrieve order details                      |
| PUT /api/v1/orders/{order_id}/status   | Update order status                         |
| DELETE /api/v1/orders/{order_id}       | Cancel order (triggers refund, notification)|
| POST /api/v1/orders/{order_id}/webhook | Payment status update (single order only)   |

[KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-69d55b34-e506-4b4e-a043-ef842030f397]

### 4.3.2 Payment Service API

| Endpoint                              | Description                                 |
|----------------------------------------|---------------------------------------------|
| POST /api/v1/payments/                 | Create payment for single order             |
| GET /api/v1/payments/{payment_id}      | Retrieve payment by payment ID              |
| GET /api/v1/payments/order/{order_id}  | Retrieve payment for specific order         |
| POST /api/v1/payments/refund           | Process refund for completed payment        |

[KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a]

### 4.3.3 Notification Service API

| Endpoint                                    | Description                                 |
|----------------------------------------------|---------------------------------------------|
| POST /api/v1/notifications/email             | Send single email notification (rate limit) |
| POST /api/v1/notifications/sms               | Send single SMS notification                |
| GET /api/v1/notifications/{notification_id}  | Retrieve notification by ID                 |
| GET /api/v1/notifications/order/{order_id}   | Retrieve all notifications for an order     |

[KB-582e7673-bd66-493e-b511-017708ae9326], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4]

## 4.4 Data Requirements

- Order data must include customer name, email, item list (product name, quantity, unit price), total amount, currency, status, timestamps, and item details.  
  [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4]
- Payment data must include order ID, amount, currency, status, payment method, transaction ID, timestamps.  
  [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a]
- Notification data must include order ID, channel (email/SMS), template name, recipient, subject, body, status, timestamps.  
  [KB-258b5996-5aad-4f5f-acd2-8e458c49f884]

## 4.5 Error Handling Requirements

- All API errors must return a structured error response with a descriptive message.  
  [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]
- Payment Service must return 400 error for amounts below 100 JPY, above 1,000,000 JPY, or duplicate order ID.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a]

## 4.6 [GAP: Missing data for Requirements]

If requirements for bulk order import, batch payment, or CSV upload are needed, refer to business requests for CSV import and bulk processing, but note that the current system does not support these features.  
[KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397]

---

*All requirements strictly reflect the provided context and do not include external or inferred information.*