## 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. [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-86e313b9-691a-4830-b560-a2097e138f34] - The system shall calculate the total order amount automatically as 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 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, including item information, 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. [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] - Upon order cancellation, the system shall trigger a refund request to the Payment Service and send a cancellation notification via the Notification Service. [KB-4651de1d-570d-4c49-8a65-ec5b22855797], [KB-981308db-2c30-4894-ba6b-491bf40b1d24], [KB-186b33d7-f985-455b-8117-0cd019912510], [KB-1a8a8c49-5d2d-4747-b2de-4e95950cdf44], [KB-531d0e2e-8232-44c5-bd97-31abf9e53c85] - The system shall support webhook callbacks from Payment Service for payment status updates (single order only). [KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22] ### 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], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] - The Payment Service shall validate that payment amounts are between 100 JPY and 1,000,000 JPY per transaction. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-186b33d7-f985-455b-8117-0cd019912510], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] - The Payment Service shall enforce a 1:1 relationship between orders and payments (one payment per order). [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - The Payment Service shall reject duplicate payment requests for the same order ID. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - The Payment Service shall support refund processing for completed payments. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3] ### 4.1.3 Notification Service - The Notification Service shall send email notifications for individual orders using templates. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c] - The Notification Service shall send SMS notifications for individual orders using templates. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-582e7673-bd66-493e-b511-017708ae9326] - The Notification Service shall support three notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-1c5832cc-4e41-483e-9898-60c735170444] - Templates shall support Jinja2-style variable substitution with Japanese language content. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-3133bf0e-2d7b-46bc-ae60-dac1a20281ed], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e] - The Notification Service shall track notification delivery status (PENDING, SENT, FAILED). [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e] - The Notification Service 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 CSV Import (Bulk Order Creation) — [GAP: Missing data for Requirements] - Multiple context blocks indicate business demand for CSV bulk import of orders (100–10,000 orders per file) to improve operational efficiency for corporate customers. [KB-0300f3b7-a279-4396-bf18-c17f413ebe6d], [KB-049c5f42-4f53-4566-bbd6-62b438d57b92], [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-1ac0c309-d977-46d8-9523-c7d212164f65], [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08], [KB-2b07b017-3e2f-47a4-9b03-d2be4a0e5644], [KB-5bd83fdc-f7d5-4953-bd1e-e9b287f0bf96], [KB-94407aa3-d1ac-4455-a68c-265236fefec4], [KB-9722c127-de97-4494-bb8d-1d840efa8899], [KB-2183809f-cfa9-4b0b-a30d-320f78a4f161], [KB-2708f598-e5da-4cca-91f0-fd3d267de542], [KB-2cb01db2-27b0-46bc-ae60-dac1a20281ed], [KB-5a963d29-d4ed-4859-ba71-d355620aa5bc] - [GAP: Missing data for Requirements] — No functional specification for CSV import endpoints, validation, or processing logic is present in the provided context. ## 4.2 Interface Requirements ### 4.2.1 API Endpoints | Endpoint | Description | Reference | |-------------------------------------------|----------------------------------------------------------|------------------------------------------------------------------| | POST /api/v1/orders/ | Create a single order | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] | | GET /api/v1/orders/ | List orders (pagination: skip, limit) | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] | | GET /api/v1/orders/{order_id} | Retrieve order details | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] | | 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 and cancellation email | [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-186b33d7-f985-455b-8117-0cd019912510], [KB-981308db-2c30-4894-ba6b-491bf40b1d24] | | POST /api/v1/orders/{order_id}/webhook | Payment status update (single order only) | [KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] | | POST /api/v1/payments/ | Process payment for a single order | [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-8ca26148-03e1-4184-a736-624e14448df9] | | GET /api/v1/payments/{payment_id} | Retrieve payment details | [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], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3] | | POST /api/v1/notifications/email | Send a single email notification (rate limit: 10/sec) | [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c] | | POST /api/v1/notifications/sms | Send a single SMS notification | [KB-582e7673-bd66-493e-b511-017708ae9326] | | GET /api/v1/notifications/{notification_id}| Retrieve notification history by ID | [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-4d364408-238b-4248-925a-97d5a3446d3c] | | GET /api/v1/notifications/order/{order_id}| Retrieve all notifications for a specific order | [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-4d364408-238b-4248-925a-97d5a3446d3c] | ## 4.3 Constraint Requirements - Payment processing is limited to a maximum of 1,000,000 JPY per single transaction. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] - No batch payment or batch webhook processing is supported; each order and payment must be handled individually. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397] - Duplicate payment requests for the same order ID 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-36050440-5a8a-4389-8690-8fd0a46f5cd3] ## 4.4 Data Requirements - Order data must include customer name, customer email, item details (product name, quantity, unit price), and currency. [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] - Payment data must include order ID, amount, currency, payment method, transaction ID, and timestamps. [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] - Notification data must include order ID, channel (email/SMS), template name, recipient, subject, body, status, and timestamps. [KB-258b5996-5aad-4f5f-acd2-8e458c49f884], [KB-582e7673-bd66-493e-b511-017708ae9326] ## 4.5 Business Requirements - The system must support operational efficiency for corporate customers by enabling bulk order creation via CSV import (100–10,000 orders per file). [KB-0300f3b7-a279-4396-bf18-c17f413ebe6d], [KB-049c5f42-4f53-4566-bbd6-62b438d57b92], [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-1ac0c309-d977-46d8-9523-c7d212164f65], [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08], [KB-2b07b017-3e2f-47a4-9b03