## 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), order items (product name, quantity, unit price), and currency. Bulk or batch order creation is not supported in the current API ([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 all items ([KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205]).
- 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 allow retrieval of order details by order ID, including itemized order information ([KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]).
- 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]).
- 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-4a19-ac30-457c4c49753b]).
- The system shall expose a webhook endpoint to receive payment status updates from the Payment Service ([KB-981308db-2c30-4a19-ac30-457c4c49753b], [KB-69d55b34-e506-4b4e-a043-ef842030f397]).

### 4.1.2 Payment Service

- The Payment Service shall process payments for a single order per request. Batch payment processing is not supported ([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-8ca26148-03e1-4184-a736-624e14448df9]).
- Payment amount must be between 100 JPY and 1,000,000 JPY per transaction ([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]).
- The Payment Service shall enforce a 1:1 relationship between order and payment (one payment per order) ([KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]).
- Duplicate payment requests for the same order 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]).
- After payment processing, the Payment Service shall notify the Order Service of payment status via webhook ([KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-981308db-2c30-4a19-ac30-457c4c49753b]).

### 4.1.3 Notification Service

- The Notification Service shall send email notifications for individual orders using templates ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]).
- The Notification Service shall send SMS notifications for individual orders using templates ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]).
- 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 allow retrieval of notification history by notification ID ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]).
- The Notification Service shall allow retrieval of all notifications for a specific order ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]).

### 4.1.4 CSV Import (Bulk Order)

- [GAP: Missing data for Requirements] — Bulk CSV import is requested by business stakeholders for operational efficiency (100–10,000 orders per batch), but is not currently implemented in the Order Service API ([KB-16181d30-2dd3-421e-bab0-939cd85255d2], [KB-564ae239-84b1-4b64-bbb0-73de35f73a08]).
- [GAP: Missing data for Requirements] — CSV upload, validation, batch order creation, and batch payment processing requirements are documented but not available in the current API ([KB-16181d30-2dd3-421e-bab0-939cd85255d2], [KB-564ae239-84b1-4b64-bbb0-73de35f73a08]).

## 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               |

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

### 4.2.2 Payment Service API

| Endpoint                              | Description                                 |
|----------------------------------------|---------------------------------------------|
| POST /api/v1/payments/                 | Create payment for single order             |
| GET /api/v1/payments/{payment_id}      | Retrieve payment by ID                      |
| 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-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a])

### 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 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.3 Constraint Requirements

- Maximum payment amount per transaction is 1,000,000 JPY ([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]).
- Minimum payment amount per transaction is 100 JPY ([KB-8072a75f-d61d-49b1-a859-1be86806c449]).
- Only one payment per order is allowed; duplicate payments are rejected ([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]).
- Refunds are only processed for completed payments ([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]).
- Notification Service rate limit: 10 emails per second ([KB-582e7673-bd66-493e-b511-017708ae9326]).

## 4.4 Data Requirements

- Order data must include customer name, customer email, itemized product list (product name, quantity, unit price), total amount, currency, status, timestamps ([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 Business Requirements

- The system must support operational efficiency for corporate customers by enabling bulk order import via CSV (100–10,000 orders per batch). This feature is requested but not currently implemented ([KB-16181d30-2dd3-421e-bab0-939cd85255d2], [KB-564ae239-84b1-4b64-bbb0-73de35f73a08]).
- Upon order creation, payment processing, and status changes, appropriate notifications must be sent to customers ([KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c], [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]).

## 4.6 [GAP] Requirements

- Bulk CSV import, validation, batch order creation, and batch payment processing are requested but not available in the current implementation ([KB-16181d30-2dd3-421e-bab0-939cd85255d2], [KB-564ae239-84b1-4b64-bbb0-73de35f73a08]).
- [GAP: Missing data for Requirements] — No API endpoints or detailed requirements for CSV import and batch operations are present in the current system documentation.

---

**References:**  
- [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]  
- [KB-8072a75f-d61d-49b1-a859-1be86806c449]  
- [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]  
- [KB-16181d30-2dd3-421e-bab0-939cd85255d2]  
- [KB-564ae239-84b1-4b64-bbb0-73de35f73a08]  
- [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4]  
- [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a]  
- [KB-258b5996-5aad-4f5f-acd2-8e458c49f884]  
- [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c]  
- [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add]  
- [KB-69d55b34-e506-4b4e-a043-ef842030f397]  
- [KB-981308db-2c30-4a19-ac30-457c4c49753b]  
- [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c]