## Requirements

# 4. Requirements

## 4.1 Functional Requirements

### 4.1.1 Order Creation and Management

- The system shall allow creation of a single order per API request. Bulk or batch order creation is not supported in the current implementation. Each order must specify customer information (name, email), order items (product name, quantity, unit price), and currency. The total 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-86e313b9-691a-4830-b560-a2097e138f34]

- The system shall support paginated retrieval of order lists with 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 by order ID, including itemized information. [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [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, transitioning the status to CANCELLED. [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f]

### 4.1.2 Payment Processing

- 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 validation: minimum 100 JPY, maximum 1,000,000 JPY per single transaction. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]

- Each order can only have one payment (1:1 relationship). Duplicate payment requests for the same order are rejected. [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]

- Payment Service notifies Order Service of payment status via webhook callback for each order. 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

- The system shall send email and SMS notifications for individual orders using templates. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-582e7673-bd66-493e-b511-017708ae9326], [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, supporting Japanese language content. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-3133bf0e-2d7-9e36-c8548c037b2c], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e]

- Notification delivery status is tracked (PENDING, SENT, FAILED). [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e]

- Notification history can be retrieved by notification ID or for a specific order. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-4d364408-238b-4248-925a-97d5a3446d3c]

- Notification Service API rate limit: 10 requests per second. [KB-582e7673-bd66-493e-b511-017708ae9326]

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

- [GAP: Missing data for Requirements]

### 4.1.5 Order Cancellation Side Effects

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

## 4.2 Constraints

- Each payment transaction is limited to a maximum of 1,000,000 JPY per order. There is no batch payment endpoint; processing multiple orders requires individual payment API calls. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-8072a75f-d61d-49b1-a859-1be86806c449]

- No batch or bulk API endpoints exist for order creation, payment, or notification. All operations are per single order. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]

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

## 4.3 Interface Requirements

### 4.3.1 Order Service API

| Endpoint                                | Description                                 | Notes                   |
|------------------------------------------|---------------------------------------------|-------------------------|
| POST /api/v1/orders/                     | Create single order                         | No batch creation       |
| GET /api/v1/orders/                      | List orders (pagination: skip, limit)       | Default limit: 20       |
| GET /api/v1/orders/{order_id}            | Retrieve order details                      | Includes item details   |
| PUT /api/v1/orders/{order_id}/status     | Update order status                         | Triggers notifications  |
| DELETE /api/v1/orders/{order_id}         | Cancel order                                | Refund + notification   |
| POST /api/v1/orders/{order_id}/webhook   | Payment status update (single order)         | No batch webhook        |

[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                                 | Notes                   |
|------------------------------------------|---------------------------------------------|-------------------------|
| POST /api/v1/payments/                   | Process payment for single order            | Min 100 JPY, max 1M JPY|
| GET /api/v1/payments/{payment_id}        | Retrieve payment by payment ID              |                         |
| 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        |                         |

[KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a]

### 4.3.3 Notification Service API

| Endpoint                                    | Description                                 | Notes                   |
|----------------------------------------------|---------------------------------------------|-------------------------|
| POST /api/v1/notifications/email             | Send single email notification               | Rate limit: 10/sec      |
| POST /api/v1/notifications/sms               | Send single SMS notification                 | Rate limit: 10/sec      |
| GET /api/v1/notifications/{notification_id}  | Retrieve notification by ID                  |                         |
| GET /api/v1/notifications/order/{order_id}   | Retrieve all notifications for an order      | Multiple notifications  |

[KB-582e7673-bd66-493e-b511-017708ae9326], [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-4d364408-238b-4248-925a-97d5a3446d3c]

## 4.4 Data Requirements

- Order data must include customer name, customer email, itemized products (name, quantity, unit price), total amount, currency, and timestamps for creation and update. [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4]

- 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, and timestamps. [KB-258b5996-5aad-4f5f-acd2-8e458c49f884]

## 4.5 Quality Requirements

- Payment processing must enforce amount validation and reject duplicate payments. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]

- Notification delivery status must be tracked and retrievable. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e]

## 4.6 Business Requirements

- The system is designed to support operational efficiency for corporate clients, but currently only supports single order creation per API request. Bulk CSV import for orders is a requested feature but is not implemented. [KB-94407aa3-d1ac-4455-a68c-265236fefec4], [KB-2b07b017-3e2f-47a4-9b03-d2be4a0e5644], [KB-5bd83fdc-f7d5-4953-bd1e-e9b287f0bf96]

---

**Note:** All requirements are based strictly on the provided context. Where bulk order creation or CSV import is referenced as a business need, it is not currently supported in the implemented APIs. [GAP: Missing data for Requirements] applies to CSV import and bulk operations.