## 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 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], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]

- The system shall automatically calculate the total order amount as the sum of (quantity × unit price) for all items.  
  [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-86e313b9-691a-4830-b560-a2097e138f34]

- The system shall support paginated retrieval of order lists via skip and limit parameters (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 item breakdown.  
  [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]

- 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 and triggering refund and notification workflows.  
  [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f], [KB-4651de1d-570d-4c49-8a65-ec5b22855797], [KB-981308db-2c30-4894-ba6b-491bf40b1d24]

### 4.1.2 Payment Service

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

- Each order can only be paid once; 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, triggered by order cancellation.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-4651de1d-570d-4c49-8a65-ec5b22855797], [KB-981308db-2c30-4894-ba6b-491bf40b1d24]

- Payment Service notifies Order Service of payment status via webhook callback (single-order only).  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397]

### 4.1.3 Notification Service

- The Notification Service shall send email and SMS notifications for individual orders, using templates.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-582e7673-bd66-493e-b511-017708ae9326]

- Supported notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]

- Templates use Jinja2 variable substitution and support Japanese content.  
  [KB-3133bf0e-2d7b-9e36-c8548c037b2c], [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [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 by order ID.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e], [KB-4d364408-238b-4248-925a-97d5a3446d3c]

### 4.1.4 Bulk Operations (Planned/Future)

- There is significant business demand for CSV bulk import of orders (100–10,000 orders per file) to improve operational efficiency for corporate customers.  
  [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08], [KB-94407aa3-d1ac-4455-a68c-265236fefec4], [KB-6ef0a78b-63b6-493a-a7b0-76398d5a2889]

- Current system does NOT support bulk order creation, bulk payment, or batch notification. Each operation is strictly single-order per API call.  
  [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397]

- If bulk import is implemented, each order must be processed individually for payment and notification due to per-transaction limits and API design.  
  [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]

## 4.2 Constraints

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

- Payment and order relationship is strictly 1:1; batch or aggregated payments are not permitted.  
  [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [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]

- Refunds are only allowed for completed payments and are triggered by order cancellation.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-4651de1d-570d-4c49-8a65-ec5b22855797]

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

## 4.3 Interface Requirements

### 4.3.1 Order Service API

| Endpoint                          | Description                                  |
|------------------------------------|----------------------------------------------|
| POST /api/v1/orders/               | Create single order                          |
| GET /api/v1/orders/                | List orders (paginated)                      |
| 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 | Payment status update callback             |

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

### 4.3.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         |

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

### 4.3.3 Notification Service API

| Endpoint                                   | Description                                  |
|---------------------------------------------|----------------------------------------------|
| POST /api/v1/notifications/email            | Send single email notification               |
| 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-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-4d364408-238b-4248-925a-97d5a3446d3c]

## 4.4 Data Requirements

- Order data must include customer name, email, item details, total amount, currency, timestamps, and status.  
  [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4]

- Payment data must include order ID, amount, currency, status, payment method, transaction ID, timestamps.  
  [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a]

- Notification data must include order ID, channel (email/SMS), template name, recipient, subject, body, status, timestamps.  
  [KB-258b5996-5aad-4f5f-acd2-8e458c49f884]

## 4.5 Error Handling Requirements

- All API error responses must follow RFC 7807 Problem Details for HTTP APIs.  
  [KB-6353c73b-fdb1-409c-9679-739f0ab68585]

- Common error codes:  
  - 400: Bad Request / Validation Error  
  - 404: Resource Not Found  
  - 422: Schema Validation Error  
  - 500: Internal Server Error  
  [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22]

## 4.6 Security Requirements

- Authentication: OAuth 2.0 Bearer tokens (JWT).  
  [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b], [KB-7efc7991-042f-4250-a023-be3696c0d900]

- Authorization: @PreAuthorize with role and attribute checks.  
  [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b], [KB-7efc7991-042f-4250-a023-be3696c0d900]

- Input validation: Bean Validation (JSR 380) on all DTOs.  
  [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b], [KB-7efc7991-042f-4250-a023-be3696c0d900]

- Rate limiting: 100 requests/minute per user, 1000 requests/minute per service.  
  [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b], [KB-7efc7991-042f-4250-a023-be3696c0d900]

- TLS 1.3 minimum required.  
  [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b], [KB-7efc7991-042f-4250-a023-be3696c0d900]

- CORS: Whitelist-based, per environment.  
  [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b], [KB-7efc7991-042f-4250-a023-be3696c0d900]

- Audit logging: Every API call logged with correlation ID.  
  [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b], [KB-7efc7991-042f-4250-a023-be3696c0d900]

- PHI must never be included in URLs or logs; only resource IDs are permitted.  
  [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b], [KB-7efc7991-042f-4250-a023-be3696c0d900]

---

[GAP: Missing data for Requirements]  
If additional requirements (e.g., CSV import, bulk order processing, advanced notification workflows) are needed, refer to future planned features or business requests, as the current implementation does not support these functionalities.