## 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. Batch or bulk order creation is not supported in the current implementation. [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-86e313b9-691a-4830-b560-a2097e138f34], [KB-77ed901f-0149-4b9e-838d-6f8fda48ab51] - The order creation process includes validation of order data, automatic calculation of total amount (sum of quantity × unit price for each item), saving to the database with status "pending," updating status to "processing payment," and invoking the Payment Service for payment processing. [KB-86e313b9-691a-4830-b560-a2097e138f34], [KB-77ed901f-0149-4b9e-838d-6f8fda48ab51] - The system shall support paginated retrieval of order lists with parameters `skip` (default 0) and `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 itemized information. [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," and triggering refund and notification processes. [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f], [KB-4651de1d-570d-4c49-8a65-ec5b22855797], [KB-531d0e2e-8232-44c5-bb97-31abf9e53c85], [KB-981308db-2c30-4894-ba6b-491bf40b1d24] ### 4.1.2 Payment Processing - The Payment Service processes payment for a single order per request. 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 validation enforces a minimum amount of 100 JPY and a maximum amount of 1,000,000 JPY per transaction. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] - Each order can have only one payment transaction (1:1 relationship). 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-531d0e2e-8232-44c5-bb97-31abf9e53c85], [KB-981308db-2c30-4894-ba6b-491bf40b1d24] - Payment status updates are communicated to the Order Service via webhook callbacks (single order per callback). [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 sends email and SMS notifications for individual orders using templates. Batch notification is not supported; each notification is processed per request. [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c] - Supported notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] - Templates use Jinja2 syntax for variable substitution and support Japanese language content. [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c], [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-f8fb-49eb-8181-2e231c58f49d] - Notification delivery status is tracked (PENDING, SENT, FAILED). [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-f8fb-49eb-8181-2e231c58f49d] - Notification history can be retrieved by notification ID or for a specific order. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-4d364408-238b-4248-925a-97d5a3446d3c] - Rate limit for email notifications: 10 requests per second. [KB-582e7673-bd66-493e-b511-017708ae9326] ### 4.1.4 API Endpoints and Integration - Order Service API endpoints: - POST /api/v1/orders/: Create single order - GET /api/v1/orders/: List orders (pagination) - GET /api/v1/orders/{order_id}: Retrieve order details - PUT /api/v1/orders/{order_id}/status: Update order status - DELETE /api/v1/orders/{order_id}: Cancel order (triggers refund and cancellation 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-981308db-2c30-4894-ba6b-491bf40b1d24], [KB-69d55b34-e506-4b4e-a043-ef842030f397] - Payment Service API endpoints: - POST /api/v1/payments/: Process payment for single order - GET /api/v1/payments/{payment_id}: Retrieve payment by ID - 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] - Notification Service API endpoints: - 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-2414677b-6e22-47f5-917c-2ed718d86fd4], [KB-4d364408-238b-4248-925a-97d5a3446d3c] - Cross-service integration: - Order creation triggers payment processing via Payment Service. - Payment completion triggers status update in Order Service via webhook. - Order creation, status change, and cancellation trigger notifications via Notification Service. [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22], [KB-69d55b34-e506-4b4e-a043-ef842030f397] ## 4.2 Constraint Requirements - Maximum payment amount per transaction is 1,000,000 JPY. No batch payment endpoint exists; bulk operations require individual API calls for each order. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - 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-4651de1d-570d-4c49-8a65-ec5b22855797] - Notification templates are rendered per notification; batch template rendering optimization is not supported. [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c] ## 4.3 Business Requirements - The system is designed to improve operational efficiency for corporate customers by automating order, payment, and notification workflows. [KB-9b61fb5a-8a89-4024-a535-ca56b147a8c8] - Order cancellation triggers both refund processing and cancellation notification to the customer. [KB-4651de1d-570d-4c49-8a65-ec5b22855797], [KB-531d0e2e-8232-44c5-bb97-31abf9e53c85] ## 4.4 Interface Requirements - All API endpoints accept and return JSON payloads. - Error responses follow the Problem Details for HTTP APIs standard (RFC 7807). [KB-6353c73b-fdb1-409c-9679-739f0ab68585], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] ## 4.5 [GAP: Missing data for Requirements] - Bulk order import via CSV is referenced in business requirements, but not supported in the current system. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] --- **References:** [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-86e313b9-691a-4830-b560-a2097e138f34], [KB-77ed901f-0149-4b9e-838d-6f8fda48ab51], [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-8ca26148-03e1-4184-a736-624e14448df9], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a], [KB-4651de1d-570d-4c49-8a65-ec5b22855797], [KB-531d0e2e-8232-44c5-bb97-31abf9e53c85], [KB-981308db-2c30-4894-ba6b-491bf40b1d24], [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-4d364408-238b-4248-925a-97d5a3446d3c], [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22], [KB-6353c73b-fdb1-409c-9679-739f0ab68585]