## Requirements

# 4. Requirements

## 4.1 Functional Requirements

### 4.1.1 Order Service

- The system shall allow creation of a single order per API request, specifying customer information (name, email), item details (product name, quantity, unit price), and currency. Bulk or batch order creation is not supported ([KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]).
- The system shall automatically calculate the total order amount as the sum of (quantity × unit price) for each item ([KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-86e313b9-691a-4830-b560-a2097e138f34]).
- The system shall support paginated order listing with parameters skip (default 0) and limit (default 20) ([KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]).
- The system shall retrieve order details, including item breakdown, by order ID ([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, changing the status to CANCELLED ([KB-55d6e023-2c8e-49db-9409-68b9e9ed721f], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]).
- Upon order cancellation, the system shall trigger 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 via webhook callback from the Payment Service after payment processing ([KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22]).

### 4.1.2 Payment Service

- The system shall process payment for a single order per API request. Batch payment processing is not supported ([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-8ca26148-03e1-4184-a736-624e14448df9]).
- The system shall validate payment amounts: minimum 100 JPY, maximum 1,000,000 JPY per transaction ([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]).
- The system shall enforce a 1:1 relationship between orders and payments (one payment per order) ([KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]).
- The system shall reject duplicate payment requests for the same order ([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]).
- Payment status changes shall trigger webhook callbacks to the Order Service ([KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22]).

### 4.1.3 Notification Service

- The system shall send email and SMS notifications for individual orders using templates ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-1c5832cc-4e41-483e-9898-60c735170444]).
- The system shall support three notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]).
- Templates shall use 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 and for all notifications related to a specific order ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-4d364408-238b-4248-925a-97d5a3446d3c]).
- Notification sending is rate-limited to 10 requests per second ([KB-582e7673-bd66-493e-b511-017708ae9326]).

### 4.1.4 CSV Import (Bulk Order Creation) — [GAP: Missing data for Requirements]

Although there is significant business demand for CSV bulk import (100–10,000 orders) to improve operational efficiency for corporate customers, the current system does not support bulk order creation, bulk payment, or batch notification processing. All operations are strictly single-order per API call ([KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]).

## 4.2 Interface Requirements

### 4.2.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 + notification) |
| POST /api/v1/orders/{order_id}/webhook   | Receive payment status update (single order)|

([KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-981308db-2c30-4894-ba6b-491bf40b1d24])

### 4.2.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       |
| POST /api/v1/payments/webhook            | Receive external payment gateway callback  |

([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3])

### 4.2.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 history             |
| 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-4d364408-238b-4248-925a-97d5a3446d3c])

## 4.3 Constraint Requirements

- All payment transactions must be between 100 JPY and 1,000,000 JPY per order ([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]).
- Each order can have only one payment; duplicate payments are rejected ([KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]).
- Refunds are only processed for completed payments ([KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]).
- All notification operations are single-order per API call; batch notification is not supported ([KB-582e7673-bd66-493e-b511-017708ae9326], [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c]).
- CSV bulk import, batch payment, and batch notification are not implemented in the current system ([KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]).

## 4.4 Data Requirements

- Order data must include customer name, email, item details (product name, quantity, unit price), currency, and calculated total amount ([KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]).
- Payment data must include order ID, amount, currency, payment method, transaction ID, status, 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 Business Requirements

- The system must support operational efficiency for corporate customers, but current limitations prevent bulk order import and batch processing ([KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]).
- All order, payment, and notification operations are strictly single-order per API call ([KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-582e7673-bd66-493e-b511-017708ae9326]).

---

**Note:** All requirements are based strictly on the provided context. No assumptions or external information have been added.  
[GAP: Missing data for Requirements] indicates areas where business demand exists but implementation is not present in the current system.  
Sources: [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a], [KB-258b5996-5aad-4f5f-acd2-8e458c49f884], [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c], [KB-4d364408-238b-4248-925a-97d5a3446d3c], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22], [KB-1a8a8c49-5d2d-4747-b2de-4e95950cdf44], [KB-981308db-2c30-4894-ba6b-491bf40b1d24]