## Requirements

# 4. Requirements

## 4.1 Functional Requirements

### 4.1.1 Order Service

- 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 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 system shall support paginated retrieval of order lists via skip and limit parameters (default limit: 20). [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f]
- The system shall allow retrieval of order details, including line items, by order ID. [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, updating the status to CANCELLED. [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f]

### 4.1.2 Payment Service

- The Payment Service processes payments for individual orders only. Batch payment processing is not supported. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-8ca26148-03e1-4184-a736-624e14448df9], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]
- 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]
- Duplicate payment requests for the same order ID 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 status updates are communicated to the Order Service via webhook callbacks (single order per callback). [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397]

### 4.1.3 Notification Service

- The system shall send email notifications for individual orders using templates. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-582e7673-bd66-493e-b511-017708ae9326]
- The system shall send SMS notifications for individual orders using templates. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]
- The system 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-2d7-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. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]
- The system shall retrieve all notifications for a specific order. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]

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

- Multiple context blocks indicate business requirements and demand for bulk CSV import (100–10,000 orders), but the current implementation does not support bulk order creation or bulk payment processing. [KB-94407aa3-d1ac-4455-a68c-265236fefec4], [KB-2b07b017-3e2f-47a4-9b03-d2be4a0e5644], [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-5bd83fdc-f7d5-4953-bd1e-e9b287f0bf96], [KB-6ef0a78b-63b6-493a-a7b0-76398d5a2889], [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08], [KB-2708f598-e5da-4cca-91f0-fd3d267de542], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-2183809f-cfa9-4b0b-a30d-320f78a4f161], [KB-5a963d29-d4ed-4859-ba71-d355620aa5bc], [KB-25b436c5-c5b0-48c1-97de-61d50bd37e57], [KB-1ac0c309-d977-46d8-9523-c7d212164f65], [KB-6ef0a78b-63b6-493a-a7b0-76398d5a2889]
- [GAP: Missing data for Requirements] — No functional specification for CSV upload, validation, or bulk processing endpoints.

## 4.2 Interface Requirements

### 4.2.1 Order Service API

| Endpoint                                   | Description                                      | Supported |
|---------------------------------------------|--------------------------------------------------|-----------|
| POST /api/v1/orders/                        | Create single order                              | Yes       |
| GET /api/v1/orders/                         | List orders (pagination: skip, limit)            | Yes       |
| GET /api/v1/orders/{order_id}               | Retrieve order details                           | Yes       |
| PUT /api/v1/orders/{order_id}/status        | Update order status                              | Yes       |
| DELETE /api/v1/orders/{order_id}            | Cancel order (triggers refund, notification)      | Yes       |
| POST /api/v1/orders/{order_id}/webhook      | Payment status update (single order)              | Yes       |

[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                                      | Supported |
|---------------------------------------------|--------------------------------------------------|-----------|
| POST /api/v1/payments/                      | Create payment (single order only)               | Yes       |
| GET /api/v1/payments/{payment_id}           | Retrieve payment by payment ID                   | Yes       |
| GET /api/v1/payments/order/{order_id}       | Retrieve payment by order ID                     | Yes       |
| POST /api/v1/payments/refund                | Process refund for completed payment             | Yes       |
| POST /api/v1/payments/webhook               | Receive external payment gateway callbacks       | Yes       |

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

### 4.2.3 Notification Service API

| Endpoint                                   | Description                                      | Supported |
|---------------------------------------------|--------------------------------------------------|-----------|
| POST /api/v1/notifications/email            | Send single email (rate limit: 10/sec)           | Yes       |
| POST /api/v1/notifications/sms              | Send single SMS                                  | Yes       |
| GET /api/v1/notifications/{notification_id} | Retrieve notification history by ID               | Yes       |
| GET /api/v1/notifications/order/{order_id}  | Retrieve all notifications for an order           | Yes       |

[KB-582e7673-bd66-493e-b511-017708ae9326], [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4], [KB-4d364408-238b-4248-925a-97d5a3446d3c]

## 4.3 Constraint Requirements

- Payment amount per transaction must be between 100 JPY and 1,000,000 JPY. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]
- Only one payment per order is allowed (1:1 relationship). Duplicate payment requests for the same order 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 templates must use Jinja2 syntax for variable substitution. Batch template rendering optimization is not supported; rendering occurs per notification. [KB-3133bf0e-2d7-9e36-c8548c037b2c]
- Notification Service API is rate-limited to 10 requests per second for email notifications. [KB-582e7673-bd66-493e-b511-017708ae9326]

## 4.4 Data Requirements

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

- There is a strong business demand for bulk order creation via CSV import (100–10,000 orders per batch) to improve operational efficiency for corporate customers. However, this feature is not implemented in the current system. [KB-94407aa3-d1ac-4455-a68c-265236fefec4], [KB-2b07b017-3e2f-47a4-9b03-d2be4a0e5644], [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-5bd83fdc-f7d5-4953-bd1e-e9b287f0bf96], [KB-6ef0a78b-63b6-493a-a7b0-76398d5a2889], [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08], [KB-2708f598-e5da-4cca-91f0-fd3d267de542], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-2183809f-cfa9-4b0b-a30d-320f78a4f161], [KB-5a963d29-d4ed-4859-ba71-d355620aa5bc], [KB-25b436c5-c5b0-48c1-97de-61d50bd37e57], [KB-1ac0c309-d977-46d8-9523-c7d212164f65], [KB-6ef0a78b-63b6-493a-a7b0-76398d5a2889]
- [GAP: Missing data for Requirements] — No business logic or workflow specified for CSV upload, validation, or bulk processing.

## 4.6 Error Handling Requirements

- All error responses must follow the Problem Details for HTTP APIs standard (RFC 7807). [KB-6353c73b-fdb1-409c-9679-739f0ab68585]
- Common error codes include: 400 (Bad Request/Validation Error), 404 (Resource Not Found), 422 (Schema Validation Error), 500 (Internal Server Error). [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22]

---

**Legend:**
- Jinja2: Python-based template syntax used for variable substitution
- ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED: Notification template names

---

**Gaps Identified:**
- Bulk CSV import requirements are referenced but not specified; implementation details, endpoints, and validation rules are missing.

---

**References:**
- [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]
- [KB-8072a75f-d61d-49b1-a859-1be86806c449]
- [KB-582e7673-bd66-493e-b511-017708ae9326]
- [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]
- [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]
- [KB-3133bf0e-2d7-9e36-c8548c037b2c]
- [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]
- [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a]
- [KB-258b5996-5aad-4f5f-acd2-8e458c49f884]
- [KB-6353c73b-fdb1-409c-9679-739f0ab68585]
- [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22]
- [KB-94407aa3-d1ac-4455-a68c-265236fefec4]
- [KB-2b07b017-3e2f-47a4-9b03-d2be4a0e5644]
- [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1]
- [KB-5bd83fdc-f7d5-4953-bd1e-e9b287f0bf96]
- [KB-6ef0a78b-63b6-493a-a7b0-76398d5a2889]
- [KB-2b0238e6-fb8b-4c