## Requirements # 4. Requirements ## 4.1 Functional Requirements ### 4.1.1 Order Service - The system shall allow creation of a single order per request, specifying customer information (name, email), order items (product name, quantity, unit price), and currency. Bulk or batch order creation is not supported. [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] - The system shall support paginated order listing with parameters skip (default 0) and limit (default 20). [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] - The system shall retrieve order details, including line items, by order ID. [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 status to CANCELLED. [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] - Upon order cancellation, the system shall trigger refund processing via Payment Service and send a cancellation notification via Notification Service. [KB-4651de1d-570d-4c49-8a65-ec5b22855797] - The system shall support webhook integration for payment status updates: POST /api/v1/orders/{order_id}/webhook with payment_status and transaction_id. [KB-69d55b34-e506-4b4e-a043-ef842030f397] ### 4.1.2 Payment Service - The system shall process payments for a single order per request. Batch payment processing is not supported. [KB-8072a75f-d61d-49b1-a859-1be86806c449] - Payment amount must be between 100 JPY and 1,000,000 JPY per transaction. [KB-8072a75f-d61d-49b1-a859-1be86806c449] - Each order can have only one payment (1:1 relationship). Duplicate payment requests for the same order_id are rejected. [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - The system shall support refund processing for completed payments via POST /api/v1/payments/refund. [KB-8072a75f-d61d-49b1-a859-1be86806c449] - Payment status updates are communicated to Order Service via webhook callback. [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] - The system shall support three notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] - Templates shall use Jinja2-style variable substitution and support Japanese language content. [KB-79cd66a7-f8fb-49eb-8181-2e231c58f49d] - 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 and all notifications for a specific order. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] - Notification Service API endpoints process one notification per request; batch notification sending is not supported. [KB-582e7673-bd66-493e-b511-017708ae9326] ### 4.1.4 CSV Import (Bulk Order Creation) - [GAP: Missing data for Requirements] ### 4.1.5 Security and Access Control - The system shall implement authentication using OAuth 2.0 Bearer tokens (JWT). [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b] - Authorization is enforced via @PreAuthorize with role and attribute checks. [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b] - Input validation is performed using Bean Validation (JSR 380) on all DTOs. [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b] - Output filtering ensures PHI fields are only accessible to authorized roles. [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b] - Rate limiting: 100 requests/minute per user, 1000 requests/minute per service. [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b] - TLS 1.3 is required for all communications. [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b] - CORS is enforced with whitelist-based origin validation. [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b] - Audit logging is required for every API call with correlation ID. [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b] - PHI must never be included in URLs or query parameters, and must not be logged (use resource IDs only). [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b] ## 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} | Get order details | | PUT /api/v1/orders/{order_id}/status | Update order status | | DELETE /api/v1/orders/{order_id} | Cancel order, triggers refund and notification | | POST /api/v1/orders/{order_id}/webhook | Receive payment status update | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [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] ### 4.2.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 history by ID | | GET /api/v1/notifications/order/{order_id} | Retrieve all notifications for an order | [KB-582e7673-bd66-493e-b511-017708ae9326] ## 4.3 Constraint Requirements - Payment amount per transaction must not exceed 1,000,000 JPY and must not be less than 100 JPY. [KB-8072a75f-d61d-49b1-a859-1be86806c449] - Each order can only be associated with one payment; duplicate payment requests for the same order are rejected. [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - Batch processing (order creation, payment, notification) is not supported; all operations are per single order/notification. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-582e7673-bd66-493e-b511-017708ae9326] ## 4.4 Data Requirements - Order data must include customer name, customer email, items (product name, quantity, unit price), total amount, currency, status, timestamps, and item details. [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, sent_at, created_at. [KB-258b5996-5aad-4f5f-acd2-8e458c49f884] ## 4.5 Quality Requirements ### 4.5.1 Security - Authentication and authorization must comply with OAuth 2.0, JWT, and role-based access controls. [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b] - TLS 1.3 is required for all communications. [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b] - Audit logging and PHI handling requirements must be enforced. [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b] ### 4.5.2 Performance - [GAP: Missing data for Requirements] ### 4.5.3 Usability - [GAP: Missing data for Requirements] --- **Note:** All requirements are strictly based on the provided context. Where requirements or details are missing, explicit gaps are indicated.