## 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 support paginated listing of orders, with parameters `skip` (default 0) and `limit` (default 20). [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] - The system shall allow retrieval of order details by order ID, including itemized order 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 the status to CANCELLED. [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] ### 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] - Payment amount validation: minimum 100 JPY, maximum 1,000,000 JPY per transaction. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] - Duplicate payment requests for the same order ID shall be rejected. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - Payment and order must maintain a 1:1 relationship (one payment per order). [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - Refund processing is supported 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-2d7b-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. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e] - The system shall retrieve all notifications for a specific order. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e] ### 4.1.4 API Integration and Side Effects - Order cancellation triggers a refund request to Payment Service and a cancellation notification to Notification Service. [KB-186b33d7-f985-455b-8117-0cd019912510], [KB-981308db-2c30-4894-ba6b-491bf40b1d24], [KB-1a8a8c49-5d2d-4747-b2de-4e95950cdf44] - Payment completion triggers a webhook callback to Order Service to update order status. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22] - Order creation triggers a confirmation notification to the customer. [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c] ### 4.1.5 CSV Import (Bulk Order Creation) — [GAP: Missing data for Requirements] > Although there is significant demand for CSV bulk import of orders (100–10,000 orders at once), the current system does **not** support this feature. All order creation, payment, and notification processing are strictly single-order per API call. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-16181d30-2dd3-421e-bab0-939cd85255d2] ## 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] - Payment Service only processes individual orders; batch payment is not permitted. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] - Notification Service sends one notification per API request; batch notification is not permitted. [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-3133bf0e-2d7b-4477-9e36-c8548c037b2c] ## 4.3 Interface Requirements ### 4.3.1 Order Service API | Endpoint | Description | Notes | |-------------------------------------|---------------------------------------------|----------------------------| | POST /api/v1/orders/ | Create single order | No batch endpoint | | GET /api/v1/orders/ | List orders (paginated: skip, limit) | Default limit: 20 | | GET /api/v1/orders/{order_id} | Retrieve order details | | | PUT /api/v1/orders/{order_id}/status| Update order status | Triggers shipped notification| | DELETE /api/v1/orders/{order_id} | Cancel order | Triggers refund & notification| | POST /api/v1/orders/{order_id}/webhook | Payment status update (single order) | No batch webhook | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-69d55b34-e506-4b4e-a043-ef842030f397] ### 4.3.2 Payment Service API | Endpoint | Description | Notes | |---------------------------------------|---------------------------------------------|----------------------------| | POST /api/v1/payments/ | Create payment for single order | Amount validation enforced | | GET /api/v1/payments/{payment_id} | Retrieve payment details | | | GET /api/v1/payments/order/{order_id} | Retrieve payment for order (1:1 relationship)| | | POST /api/v1/payments/refund | Process refund for completed payment | | [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] ### 4.3.3 Notification Service API | Endpoint | Description | Notes | |--------------------------------------------|----------------------------------------------|----------------------------| | POST /api/v1/notifications/email | Send single email notification | Rate limit: 10/sec | | POST /api/v1/notifications/sms | Send single SMS notification | Same structure as email | | 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] ## 4.4 Data Requirements - Order data must include customer name, email, itemized product list (product name, quantity, unit price), and currency. [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4] - Payment data must include order ID, amount, currency, payment method, transaction ID, status, 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] ## 4.5 Business Requirements - The system is designed to improve operational efficiency for corporate customers, but currently only supports single order processing per API call. Bulk CSV import for orders is a requested feature but not implemented. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-16181d30-2dd3-421e-bab0-939cd85255d2] --- **Note:** For CSV bulk import and batch processing requirements, see [GAP: Missing data for Requirements]. All requirements are based strictly on the provided context and reflect the current system limitations and functional scope.