## Requirements

# Requirements

## 1. Functional Requirements

### 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. ([KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c])
- Each order must include customer information (name, email), item details (product name, quantity, unit price), and currency. ([KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205])
- The total amount for the order shall be automatically calculated as the sum of (quantity × unit price) for all items. ([KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205])
- Order status transitions are supported: PENDING → PROCESSING_PAYMENT → PAID → SHIPPED → DELIVERED. ([KB-55d6e023-2c8e-49db-9409-68b9e9ed721f])
- Order cancellation is supported and transitions the status to CANCELLED. ([KB-55d6e023-2c8e-49db-9409-68b9e9ed721f])

### 1.2 Payment Processing

- Payment processing is performed 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])
- Duplicate payment requests for the same order_id are rejected. ([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6])
- Each order has a 1:1 relationship with a payment. ([KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6])
- Refund processing is supported for completed payments. ([KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-8072a75f-d61d-49b1-a859-1be86806c449])

### 1.3 Notification Service

- The system shall send email notifications for individual orders using templates. ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8])
- The system shall send SMS notifications for individual orders using templates. ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8])
- Three notification templates are supported: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED. ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8])
- Templates use Jinja2-style variable substitution and support Japanese language content. ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c])
- Notification delivery status is tracked (PENDING, SENT, FAILED). ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8])
- Notification history can be retrieved by notification ID or by order ID. ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8])

### 1.4 API Endpoints

#### Order Service

| Endpoint                                | Description                                 |
|------------------------------------------|---------------------------------------------|
| POST /api/v1/orders/                     | Create single order                         |
| GET /api/v1/orders/                      | List orders (pagination: skip, limit)       |
| GET /api/v1/orders/{order_id}            | Get 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 (single order) |

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

#### Payment Service

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

([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3])

#### Notification Service

| Endpoint                                | Description                                 |
|------------------------------------------|---------------------------------------------|
| POST /api/v1/notifications/email         | Send single email notification (rate limit: 10/sec) |
| 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])

### 1.5 Cross-Service Integration

- Payment Service notifies Order Service of payment status via webhook (POST /api/v1/orders/{order_id}/webhook). ([KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22])
- Order Service triggers Notification Service for order creation, status change, and cancellation. ([KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c])

### 1.6 Data Validation and Error Handling

- Input validation is enforced on all DTOs. ([KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b])
- Common error responses follow RFC 7807 Problem Details for HTTP APIs. ([KB-6353c73b-fdb1-409c-9679-739f0ab68585], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c])
- Payment errors: 400 for amount out of range or duplicate order_id. ([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3])

### 1.7 Security and Access Control

- Authentication is implemented using OAuth 2.0 Bearer tokens (JWT). ([KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b])
- Authorization is enforced using @PreAuthorize with role and attribute checks. ([KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b])
- Rate limiting: 100 requests/min per user, 1000 requests/min per service. ([KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b])
- TLS 1.3 minimum is required. ([KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b])
- CORS is whitelist-based, per environment. ([KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b])
- Audit logging: every API call is logged with correlation ID. ([KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b])
- PHI must never be included in URLs or query parameters, nor logged (resource IDs only). ([KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b])

## 2. Constraints

- Only single order creation and payment are supported per API request; bulk/batch operations are not available. ([KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-8072a75f-d61d-49b1-a859-1be86806c449])
- Payment amount per transaction is limited to 1,000,000 JPY. ([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6])
- Duplicate payments for the same order are not allowed. ([KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6])
- Notification Service sends one notification per request; batch notification sending is not supported. ([KB-582e7673-bd66-493e-b511-017708ae9326])
- Notification template rendering is performed per notification; batch rendering optimization is not available. ([KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c])

## 3. Data Requirements

- Orders must include customer name, email, item details, and currency. ([KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205])
- Payment records must include order_id, amount, currency, status, payment method, transaction_id, timestamps. ([KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a])
- Notification records must include order_id, channel, template_name, recipient, subject, body, status, sent_at, created_at. ([KB-258b5996-5aad-4f5f-acd2-8e458c49f884])

## 4. Interface Requirements

- All API endpoints must accept and return JSON payloads. ([KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-582e7673-bd66-493e-b511-017708ae9326])
- Pagination parameters (skip, limit) are supported for order listing. ([KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9])
- Notification retrieval supports both notification ID and order ID. ([KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4])

## 5. Performance Requirements

- [GAP: Missing data for Requirements]

## 6. Usability Requirements

- [GAP: Missing data for Requirements]

## 7. Reliability Requirements

- [GAP: Missing data for Requirements]

## 8. Security Requirements

- Authentication and authorization as described in Section 1.7. ([KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b])
- Rate limiting and audit logging as described in Section 1.7. ([KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b])

---

**References:**  
- [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]  
- [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]  
- [KB-8072a75f-d61d-49b1-a859-1be86806c449]  
- [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]  
- [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]  
- [KB-582e7673-bd66-493e-b511-017708ae9326]  
- [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c]  
- [KB-69d55b34-e506-4b4e-a043-ef842030f397]  
- [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22]  
- [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c]  
- [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b]  
- [KB-6353c73b-fdb1-409c-9679-739f0ab68585]  
- [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3]  
- [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a]  
- [KB-258b5996-5aad-4f5f-acd2-8e458c49f884]  
- [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205]