## Requirements # 4. Requirements ## 4.1 Functional Requirements ### 4.1.1 Order Creation and Management - The system shall support creation of a single order per API request. Bulk or batch creation endpoints are not supported. [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-86e313b9-691a-4830-b560-a2097e138f34] - The order creation process shall include: 1. Validation of order data (single payload only) 2. Automatic calculation of total amount (sum of quantity × unit price for each item) 3. Saving order to database with status: PENDING 4. Status update to PROCESSING_PAYMENT 5. Payment Service invocation (POST /api/v1/payments/) 6. On successful payment, status update to PAID 7. Notification Service invocation (POST /api/v1/notifications/email) 8. Return of created order [KB-86e313b9-691a-4830-b560-a2097e138f34], [KB-77ed901f-0149-4b9e-838d-6f8fda48ab51], [KB-71ff9c60-13e4-4194-88e5-a67607551893] - The system shall support paginated listing of orders with parameters: skip (default 0), limit (default 20). [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] - The system shall support retrieval of order details by order ID, including item details. [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] - The system shall support order status transitions: PENDING → PROCESSING_PAYMENT → 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] ### 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 validation rules: - Minimum amount: 100 JPY - Maximum amount: 1,000,000 JPY per transaction - order_id must be unique (no duplicate payments for the same order) [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] - Payment Service notifies Order Service of payment status via webhook callback (POST /api/v1/orders/{order_id}/webhook). [KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22] - Refund processing is supported for completed payments via POST /api/v1/payments/refund. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3] ### 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-1c5832cc-4e41-483e-9898-60c735170444] - Supported notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e] - Templates use Jinja2-style variable substitution with Japanese language content. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-3133bf0e-2d7b-9e36-c8548c037b2c] - Notification delivery status shall be 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] - Notification Service API rate limit: 10 requests/second for email. [KB-582e7673-bd66-493e-b511-017708ae9326] ### 4.1.4 System Integration - Payment Service and Notification Service are invoked by Order Service as follows: - Payment Service: POST /api/v1/payments/ for payment processing; POST /api/v1/payments/refund for refunds. - Notification Service: POST /api/v1/notifications/email and POST /api/v1/notifications/sms for notifications. [KB-1a8a8c49-5d2d-4747-b2de-4e95950cdf44], [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] - Payment Service notifies Order Service of payment status via webhook (single order callback only). [KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] ## 4.2 Constraint Requirements - Maximum payment amount per transaction is 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 is 100 JPY. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - Each order can be paid only once; duplicate payment requests for the same order are rejected. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - Refunds are only supported for completed payments. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - No batch payment or batch webhook processing is supported; all operations are per single order. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397] ## 4.3 Interface Requirements | Endpoint | Description | Reference | |------------------------------------------------|-------------------------------------------------|---------------------------------------------| | POST /api/v1/orders/ | Create single order | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] | | GET /api/v1/orders/ | List orders (pagination: skip, limit) | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] | | GET /api/v1/orders/{order_id} | Retrieve order details | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] | | PUT /api/v1/orders/{order_id}/status | Update order status | [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] | | DELETE /api/v1/orders/{order_id} | Cancel order, triggers refund & notification | [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] | | POST /api/v1/orders/{order_id}/webhook | Payment status update (single order only) | [KB-69d55b34-e506-4b4e-a043-ef842030f397] | | POST /api/v1/payments/ | Process payment for single order | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | GET /api/v1/payments/{payment_id} | Retrieve payment by payment ID | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | GET /api/v1/payments/order/{order_id} | Retrieve payment for specific order | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | POST /api/v1/payments/refund | Process refund for completed payment | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | POST /api/v1/notifications/email | Send email notification for single order | [KB-582e7673-bd66-493e-b511-017708ae9326] | | POST /api/v1/notifications/sms | Send SMS notification for single order | [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] | | GET /api/v1/notifications/{notification_id} | Retrieve notification by ID | [KB-4d364408-238b-4248-925a-97d5a3446d3c] | | GET /api/v1/notifications/order/{order_id} | Retrieve all notifications for an order | [KB-4d364408-238b-4248-925a-97d5a3446d3c] | ## 4.4 Data Requirements - Order data must include: customer name, customer email, item details (product name, quantity, unit price), currency. - Payment data must include: order_id, amount, currency. - Notification data must include: order_id, recipient (email or phone), template_name, template_data (variables for Jinja2 rendering). [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-582e7673-bd66-493e-b511-017708ae9326] ## 4.5 Quality Requirements ### 4.5.1 Security - Authentication via OAuth 2.0 Bearer tokens (JWT) - Authorization via @PreAuthorize with role and attribute checks - Input validation using Bean Validation (JSR 380) - Output filtering: PHI field filtering based on caller role - Rate limiting: 100 requests/minute (user), 1000 requests/minute (service) - TLS 1.3 minimum - CORS: whitelist-based, per environment - Audit logging: every API call logged with correlation ID - 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] ### 4.5.2 Performance - Order creation and payment processing must complete within the expected business SLA (not specified in the provided context). [GAP: Missing data for Requirements] ### 4.5.3 Usability - Notification templates support Japanese content and variable substitution. - Notification delivery status is visible and retrievable. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e] ## 4.6 Business Requirements - The system is designed to improve operational efficiency for corporate customers by automating order creation, payment processing, and notification workflows. - Bulk order import, batch payment, and batch notification are not supported in the current system. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] --- **Note:** All requirements are strictly based on the provided context. Any missing requirement details are indicated as [GAP: Missing data for Requirements].