## Requirements

# 4. Requirements

## 4.1 Functional Requirements

### 4.1.1 Order Service

- The system must support creation of a single order per API request. Bulk or batch order creation is not supported in the current implementation. Each order must include customer information (name, email), order details (product name, quantity, unit price), and currency. The total order amount is automatically calculated as the sum of (quantity × unit price) for all items. [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]
- The order status transitions are supported as follows: PENDING → PROCESSING_PAYMENT → PAID → SHIPPED → DELIVERED. Cancellation is supported, and the status transitions to CANCELLED. [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f]
- Order listing supports pagination (parameters: skip, limit; default limit = 20), filtering, and sorting. [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-1c1c2fd0-b5e6-4649-ae18-9d6a2b7602a4], [KB-6353c73b-fdb1-409c-9679-739f0ab68585]
- Order detail retrieval is supported by order ID and includes all order items. [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f]
- Order cancellation triggers refund processing via Payment Service and sends cancellation notification via Notification Service. [KB-4651de1d-570d-4c49-8a65-ec5b22855797], [KB-981308db-2c30-4a19-ac30-457c4c49753b], [KB-1a8a8c49-5d2d-4747-b2de-4e95950cdf44]

### 4.1.2 Payment Service

- Payment processing is supported 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]
- 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], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]
- Duplicate payment requests for the same order ID are rejected. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]
- Payment and order maintain a 1:1 relationship (one payment per order). [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]
- Refund processing is supported for completed payments. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]
- Payment Service notifies Order Service of payment status via webhook callback (single order per callback). No batch webhook or batch status update exists. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397]

### 4.1.3 Notification Service

- Email and SMS notifications are sent for individual orders using templates. Batch notification is not supported; each notification is processed per order. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-3133bf0e-2d7b-4477-9e36-c8548c037b2c]
- Supported notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]
- Templates use Jinja2 syntax for variable substitution and support Japanese content. [KB-3133bf0e-2d7b-4477-9e36-c8548c037b2c], [KB-79cd66a7-f8fb-49eb-8181-2e231c58f49d]
- Notification delivery status is tracked (PENDING, SENT, FAILED). [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-f8fb-49eb-8181-2e231c58f49d]
- Notification history can be retrieved by notification ID or by order ID (all notifications for a specific order). [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-4d364408-238b-4248-925a-97d5a3446d3c]

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

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

## 4.2 Interface Requirements

### 4.2.1 API Endpoints

#### Order Service

| Endpoint                              | Functionality                                               |
|----------------------------------------|------------------------------------------------------------|
| 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; triggers shipping notification         |
| DELETE /api/v1/orders/{order_id}       | Cancel order; triggers refund and cancellation notification |
| POST /api/v1/orders/{order_id}/webhook | Receive payment status update (single order only)          |

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

#### Payment Service

| Endpoint                              | Functionality                                               |
|----------------------------------------|------------------------------------------------------------|
| 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 (1:1 relationship)     |
| POST /api/v1/payments/refund           | Process refund for completed payment                       |
| POST /api/v1/payments/webhook          | Receive external payment gateway callbacks                 |

[KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-8e5c6600-75fa-4e87-a6f5-0d06b21d8625]

#### Notification Service

| Endpoint                                  | Functionality                                    |
|--------------------------------------------|--------------------------------------------------|
| POST /api/v1/notifications/email           | Send single email notification (rate limit: 10/s)|
| 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-4d364408-238b-4248-925a-97d5a3446d3c]

### 4.2.2 Cross-Service API Contracts

| Source Service | Target Service   | Endpoint                                      | Trigger                  | Payload                                      | Expected Response | Timeout |
|----------------|------------------|-----------------------------------------------|--------------------------|----------------------------------------------|-------------------|---------|
| Order Service  | Payment Service  | POST /api/v1/payments                         | Order creation           | {"order_id": N, "amount": N.N, "currency": "JPY"} | 201 Created        | 30s     |
| Payment Service| Order Service    | POST /api/v1/orders/{order_id}/webhook        | Payment status change    | {"payment_status": "completed", "transaction_id": "uuid"} | 200 OK             | 10s     |
| Order Service  | Notification Service | POST /api/v1/notifications/email            | Order creation/status/cancellation | {"order_id": N, "to_email": "...", "template_name": "...", "template_data": {...}} | 201 Created        | 10s     |

[KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22]

## 4.3 Constraint Requirements

- Maximum payment amount per transaction is 1,000,000 JPY. No batch payment endpoint exists; bulk operations would require individual API calls for each order. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-8072a75f-d61d-49b1-a859-1be86806c449]
- Duplicate payment requests for the same order are rejected. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]
- Payment and order must maintain a 1:1 relationship. [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]
- Refund processing is only supported for completed payments. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]
- Notification Service rate limit: 10 email notifications per second. [KB-582e7673-bd66-493e-b511-017708ae9326]

## 4.4 Data Requirements

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

## 4.5 Business Requirements

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

---

**Note:** All requirements are derived strictly from the provided context and are compliant with ISO-29148 structure and terminology. Any missing information is explicitly noted as a gap.