## Requirements # 4. Requirements ## 4.1 Functional Requirements ### 4.1.1 Order Service - The system shall allow 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] - The system shall calculate the total order amount automatically based on the sum of (quantity × unit price) for each item. [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-86e313b9-691a-4830-b560-a2097e138f34] - The system shall support paginated retrieval of order lists using parameters `skip` (default 0) and `limit` (default 20). [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] - The system shall allow retrieval of order details, including item breakdown, by order ID. [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] - 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-b64d2918c588] ### 4.1.2 Payment Service - The system shall process payment 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], [KB-9b61fb5a-8a89-4024-a535-ca56b147a8c8] - The system shall enforce a minimum payment amount of 100 JPY and a maximum of 1,000,000 JPY per transaction. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - The system shall maintain a one-to-one relationship between orders and payments (1 order = 1 payment). [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - The system shall reject duplicate payment requests for the same order ID. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - The system shall support refund processing for completed payments. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] ### 4.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] - The system shall support three notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] - Templates shall support Jinja2-style variable substitution with Japanese language content. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e] - The system shall track notification delivery status (PENDING, SENT, FAILED). [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e] - The system shall retrieve notification history by notification ID and retrieve all notifications for a specific order. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e], [KB-4d364408-238b-4248-925a-97d5a3446d3c] ### 4.1.4 API and Integration - The Order Service shall call Payment Service to process payment upon order creation. [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22] - The Payment Service shall notify Order Service of payment status via webhook callback after payment processing. [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22], [KB-69d55b34-e506-4b4e-a043-ef842030f397] - The Order Service shall call Notification Service to send confirmation, shipping, and cancellation notifications. [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c], [KB-582e7673-bd66-493e-b511-017708ae9326] - All API endpoints shall return error responses in RFC 7807 Problem Details format. [KB-6353c73b-fdb1-409c-9679-739f0ab68585], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] ### 4.1.5 Constraints - Only single order creation, payment, and notification per API request are supported; batch operations are not available. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397] - Payment amount must be between 100 JPY and 1,000,000 JPY per transaction. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - Duplicate payments for the same order ID are rejected. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] ## 4.2 Data Requirements - Order data shall include customer name, customer email, item details (product name, quantity, unit price), total amount, currency, status, and timestamps. [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] - Payment data shall include order ID, amount, currency, payment method, transaction ID, status, and timestamps. [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a], [KB-8072a75f-d61d-49b1-a859-1be86806c449] - Notification data shall include order ID, channel (email/SMS), template name, recipient, subject, body, status, sent timestamp, and creation timestamp. [KB-258b5996-5aad-4f5f-acd2-8e458c49f884], [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 (pagination: skip, limit) | | 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, trigger refund & 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-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-981308db-2c30-4894-ba6b-b64d2918c588] ### 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-258b5996-5aad-4f5f-acd2-8e458c49f884], [KB-4d364408-238b-4248-925a-97d5a3446d3c] ## 4.4 Business Requirements - The system is designed to improve operational efficiency for corporate customers by supporting streamlined order, payment, and notification workflows. [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08] - Bulk order import via CSV is a requested feature for future enhancement, but is not currently implemented. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-16181d30-2dd3-421e-bab0-939cd85255d2] ## 4.5 Quality Requirements - All API endpoints must validate input data and return structured error responses. [KB-6353c73b-fdb1-409c-9679-739f0ab68585], [KB-86f3136c-8b45-4757-b02f-35ea0bb67b98] - Notification templates must render correctly with variable substitution and support Japanese content. [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e] ## 4.6 [GAP: Missing data for Requirements] - Bulk CSV import and batch processing requirements are referenced as business needs but are not currently supported. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-16181d30-2dd3-421e-bab0-939cd85255d2] --- **References:** [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a], [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-258b5996-5aad-4f5f-acd2-8e458c49f884], [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c], [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-16181d30-2dd3-421e-bab0-939cd85255d2], [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08], [KB-86f3136c-8b45-4757-b02f-35ea0bb67b98], [KB-69d55b34-e506-4b4e-a043-ef842030f397]