## 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 in the current implementation.  
  [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-86e313b9-691a-4830-b560-a2097e138f34]

- The order creation request must include customer information (name, email), order details (product name, quantity, unit price), and currency.  
  [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]

- 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], [KB-86e313b9-691a-4830-b560-a2097e138f34]

- The system shall support paginated retrieval of order lists using parameters skip (default 0) and limit (default 20).  
  [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add]

- The system shall allow retrieval of order details, including order items, by order ID.  
  [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]

- The system shall support order status transitions: PENDING → PROCESSING_PAYMENT → PAID → SHIPPED → DELIVERED.  
  [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f]

- The system shall support order cancellation, updating the status to CANCELLED.  
  [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]

- Upon order cancellation, the system shall initiate a refund request to the Payment Service and send a cancellation notification via the Notification Service.  
  [KB-4651de1d-570d-4c49-8a65-ec5b22855797], [KB-981308db-2c30-4894-ba6b-491bf40b1d24], [KB-1a8a8c49-5d2d-4747-b2de-4e95950cdf44]

- The system shall update order status upon receiving a payment status update from the Payment Service via webhook.  
  [KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22]

### 4.1.2 Payment Service

- The Payment Service 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], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]

- Payment amounts must be validated: minimum 100 JPY, maximum 1,000,000 JPY per transaction.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]

- The Payment Service shall enforce a 1:1 relationship between order and payment (one payment per order).  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]

- Duplicate payment requests for the same order ID shall be rejected.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]

- The Payment Service shall support refund processing for completed payments.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-8e5c6600-75fa-4e87-a6f5-0d06b21d8625]

- After payment processing, the Payment Service shall notify the Order Service of payment status via webhook (single order callback).  
  [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22]

### 4.1.3 Notification Service

- The Notification Service shall send email notifications for individual orders using templates.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-582e7673-bd66-493e-b511-017708ae9326]

- The Notification Service shall send SMS notifications for individual orders using templates.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4]

- The Notification Service 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 Notification Service shall track notification delivery status (PENDING, SENT, FAILED).  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]

- The Notification Service shall retrieve notification history by notification ID and all notifications for a specific order.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-4d364408-238b-4248-925a-97d5a3446d3c]

- Notification API endpoints are rate-limited (e.g., 10 emails per second).  
  [KB-582e7673-bd66-493e-b511-017708ae9326]

### 4.1.4 CSV Import (Business Requirement)

- There is a documented business requirement for bulk order creation via CSV import (100–10,000 orders per file) to improve operational efficiency for corporate customers.  
  [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-6ef0a78b-63b6-493a-a7b0-76398d5a2889], [KB-94407aa3-d1ac-4455-a68c-265236fefec4], [KB-2b07b017-3e2f-47a4-9b03-d2be4a0e5644], [KB-5bd83fdc-f7d5-4953-bd1e-e9b287f0bf96], [KB-9722c127-de97-4494-bb8d-1d840efa8899], [KB-2183809f-cfa9-4b0b-a30d-320f78a4f161], [KB-2cb01db2-27b0-46bc-ae60-dac1a20281ed], [KB-2708f598-e5da-4cca-91f0-fd3d267de542], [KB-5a963d29-d4ed-4859-ba71-d355620aa5bc], [KB-25b436c5-c5b0-48c1-97de-61d50bd37e57], [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08], [KB-1ac0c309-d977-46d8-9523-c7d212164f65]

- As of current system state, CSV bulk import is not implemented; UI elements for CSV import are disabled and display an amber warning.  
  [KB-16181d30-2dd3-421e-bab0-939cd85255d2]

## 4.2 Constraint Requirements

- Payment processing is limited to one order per transaction, with a maximum amount of 1,000,000 JPY per order. There is no batch payment endpoint; bulk operations require individual API calls for each order.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]

- Duplicate payment requests for the same order are rejected.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3]

- Notification Service and Payment Service APIs are rate-limited.  
  [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 (pagination: 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 and notification  |
| POST /api/v1/orders/{order_id}/webhook    | Receive payment status update (single order)    |

[KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-981308db-2c30-4894-ba6b-491bf40b1d24], [KB-69d55b34-e506-4b4e-a043-ef842030f397]

### 4.3.2 Payment Service API

| Endpoint                                 | Description                                    |
|-------------------------------------------|------------------------------------------------|
| POST /api/v1/payments/                    | Process payment for single order               |
| GET /api/v1/payments/{payment_id}         | Retrieve payment details                       |
| 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-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-8e5c6600-75fa-4e87-a6f5-0d06b21d8625]

### 4.3.3 Notification Service API

| Endpoint                                         | Description                                    |
|--------------------------------------------------|------------------------------------------------|
| POST /api/v1/notifications/email                 | Send single email notification                  |
| 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], [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]

## 4.4 Data Requirements

- Order data must include customer name, email, items (product name, quantity, unit price), currency, total amount, status, timestamps, and payment information.  
  [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]

- Notification data must include order ID, channel (email/SMS), template name, recipient, subject, body, status, and timestamps.  
  [KB-258b5996-5aad-4f5f-acd2-8e458c49f884]

## 4.5 [GAP: Missing data for Requirements]

- Bulk CSV import functionality is a documented business requirement but not implemented; requirements for CSV validation, error handling, progress tracking, and partial failure management are referenced but not fully specified in the current system.  
  [KB-16181d30-2dd3-421e-bab0-939cd85255d2], [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1]

---

**End of Requirements Section**