## Requirements

# 4. Requirements

## 4.1 Functional Requirements

### 4.1.1 Order Service

- The system shall allow creation of a single order per API request. Batch or bulk 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 system shall validate order data, calculate total amount (sum of quantity × unit price for all items), and store the order in the database with status "pending."  
  [KB-86e313b9-691a-4830-b560-a2097e138f34]

- The system shall support pagination for order listing (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 itemized details.  
  [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]

- 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 the status to "cancelled."  
  [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f], [KB-981308db-2c30-4894-ba6b-491bf40b1d24]

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

- Payment amount 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-564ae239-84b1-4ef2-bb04-b7e829eb53b6]

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

- Each order has a 1:1 relationship with payment.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [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], [KB-981308db-2c30-4894-ba6b-491bf40b1d24]

- Payment status updates are communicated to Order Service via webhook (single order callback, no batch webhook).  
  [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397]

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

- Supported notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-1c5832cc-4e41-483e-9898-60c735170444]

- Templates use Jinja2-style variable substitution and support Japanese language content.  
  [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c], [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-f8fb-49eb-8181-2e231c58f49d]

- Notification delivery status shall be tracked (PENDING, SENT, FAILED).  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-f8fb-49eb-8181-2e231c58f49d]

- Notification history can be retrieved by notification ID and for a specific order.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-f8fb-49eb-8181-2e231c58f49d], [KB-4d364408-238b-4248-925a-97d5a3446d3c]

- Rate limit: 10 notifications per second per channel.  
  [KB-582e7673-bd66-493e-b511-017708ae9326]

### 4.1.4 Bulk Operations (CSV Import)

- [GAP: Missing data for Requirements]  
  *Bulk/batch CSV import for orders is not supported in the current system. Multiple context blocks indicate business demand for bulk import (100–10,000 orders via CSV), but no functional implementation is present.*  
  [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08], [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-2183809f-cfa9-4b0b-a30d-320f78a4f161], [KB-5bd83fdc-f7d5-4953-bd1e-e9b287f0bf96], [KB-2cb01db2-27b0-46bc-ae60-dac1a20281ed], [KB-5a963d29-d4ed-4859-ba71-d355620aa5bc], [KB-2708f598-e5da-4cca-91f0-fd3d267de542], [KB-25b436c5-c5b0-48c1-97de-61d50bd37e57], [KB-1ac0c309-d977-46d8-9523-c7d212164f65], [KB-6aa21c29-11f1-4b6b-b8e8-2c9990900522], [KB-89dddd9a-2e13-46e7-99a4-34c3fff47435]

## 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; triggers shipping notification if status is SHIPPED |
| DELETE /api/v1/orders/{order_id}            | Cancel order; triggers refund and cancellation notification |
| POST /api/v1/orders/{order_id}/webhook      | Receive payment status update from Payment Service |

[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.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 callbacks       |

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

### 4.2.3 Notification Service API

| Endpoint                                   | Description                                      |
|---------------------------------------------|--------------------------------------------------|
| POST /api/v1/notifications/email            | Send email notification for single order         |
| POST /api/v1/notifications/sms              | Send SMS notification for single order           |
| 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.3 Constraint Requirements

- Maximum payment amount per transaction: 1,000,000 JPY.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]

- Minimum payment amount per transaction: 100 JPY.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]

- One payment per order (1:1 relationship).  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]

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

- No batch payment or batch notification endpoints; all operations are single order per request.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-582e7673-bd66-493e-b511-017708ae9326]

## 4.4 Data Requirements

- Order data includes: customer name, customer email, itemized products (name, quantity, unit price), total amount, currency, timestamps, and status.  
  [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]

- Payment data includes: payment ID, order ID, amount, currency, status, payment method, transaction ID, timestamps.  
  [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3]

- Notification data includes: notification ID, order ID, channel (email/SMS), template name, recipient, subject, body, status, timestamps.  
  [KB-258b5996-5aad-4f5f-acd2-8e458c49f884], [KB-582e7673-bd66-493e-b511-017708ae9326]

## 4.5 Business Requirements

- The system is designed to improve operational efficiency for corporate customers and support business processes.  
  [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08], [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-2183809f-cfa9-4b0b-a30d-320f78a4f161], [KB-5bd83fdc-f7d5-4953-bd1e-e9b287f0bf96], [KB-2cb01db2-27b0-46bc-ae60-dac1a20281ed], [KB-5a963d29-d4ed-4859-ba71-d355620aa5bc], [KB-2708f598-e5da-4cca-91f0-fd3d267de542], [KB-25b436c5-c5b0-48c1-97de-61d50bd37e57], [KB-1ac0c309-d977-46d8-9523-c7d212164f65], [KB-6aa21c29-11f1-4b6b-b8e8-2c9990900522], [KB-89dddd9a-2e13-46e7-99a4-34c3fff47435]

## 4.6 Non-Functional Requirements

- [GAP: Missing data for Requirements]  
  *Non-functional requirements (performance, reliability, security, usability, etc.) are not specified in the provided context for the order/payment/notification services.*

---

**Note:**  
- All requirements are based strictly on the provided context.  
- Where business demand for bulk operations is documented, implementation is not present and is noted as a gap.  
- All API endpoints and data models are documented as per the context.  
- No assumptions or external knowledge have been applied.