## 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], [KB-86e313b9-691a-4830-b560-a2097e138f34] - The order creation process must include validation of order data, automatic calculation of total amount (sum of quantity × unit price for each item), and storage of the order in the database with an initial status of "pending." [KB-86e313b9-691a-4830-b560-a2097e138f34] - The system shall support paginated listing of orders using skip and limit parameters (default limit: 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 information. [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] - The system shall support order status transitions: pending → payment 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] ### 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] - The payment amount must be validated: minimum 100 JPY, maximum 1,000,000 JPY per transaction. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - Each order can have only one payment (1:1 relationship). Duplicate payment requests for the same order ID are rejected. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [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] - After payment completion, Payment Service shall notify Order Service of payment status via webhook (single-order callback). [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397] ### 4.1.3 Notification Service - The Notification Service shall send email and SMS notifications for individual orders using templates. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-582e7673-bd66-493e-b511-017708ae9326] - Three notification templates must be supported: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] - Templates must support Jinja2-style variable substitution with Japanese language content. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c] - The system shall track notification delivery status (PENDING, SENT, FAILED). [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] - The system shall allow retrieval of notification history by notification ID and retrieval of all notifications for a specific order. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-4d364408-238b-4248-925a-97d5a3446d3c] ### 4.1.4 Bulk Operations (CSV Import) - [GAP: Missing data for Requirements] *Note: Bulk CSV import is frequently requested by business stakeholders for operational efficiency (100–10,000 orders per import), but is not implemented in the current system. All bulk-related requirements are pending implementation and not supported in the current API or workflow.* [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-2183809f-cfa9-4b0b-a30d-320f78a4f161], [KB-2b0238e6-fb8b-4b64-bbb0-73de35f73a08], [KB-94407aa3-d1ac-4455-a68c-265236fefec4], [KB-9722c127-de97-4494-bb8d-1d840efa8899], [KB-5a963d29-d4ed-4859-ba71-d355620aa5bc], [KB-6ef0a78b-63b6-493a-a7b0-76398d5a2889] ## 4.2 Interface Requirements ### 4.2.1 Order Service API | Endpoint | Description | Notes | |------------------------------------------|------------------------------------------------|--------------------------------------| | POST /api/v1/orders/ | Create single order | No bulk creation | | 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 | "Shipped" triggers notification | | DELETE /api/v1/orders/{order_id} | Cancel order | Triggers refund + cancellation email | | 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], [KB-981308db-2c30-4894-ba6b-491bf40b1d24] ### 4.2.2 Payment Service API | Endpoint | Description | Notes | |------------------------------------------|------------------------------------------------|--------------------------------------| | POST /api/v1/payments/ | Create payment for single order | Amount: 100–1,000,000 JPY | | GET /api/v1/payments/{payment_id} | Retrieve payment by payment ID | | | GET /api/v1/payments/order/{order_id} | Retrieve payment for specific 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.2.3 Notification Service API | Endpoint | Description | Notes | |------------------------------------------|------------------------------------------------|--------------------------------------| | POST /api/v1/notifications/email | Send single email notification | One email per request, rate limit: 10/sec | | POST /api/v1/notifications/sms | Send single SMS notification | One SMS per request | | GET /api/v1/notifications/{notification_id} | Retrieve notification by ID | | | GET /api/v1/notifications/order/{order_id} | Retrieve all notifications for an order | Multiple notifications per order | [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4], [KB-4d364408-238b-4248-925a-97d5a3446d3c] ## 4.3 Constraint Requirements - Maximum payment amount per transaction is 1,000,000 JPY. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - Minimum payment amount per transaction is 100 JPY. [KB-8072a75f-d61d-49b1-a859-1be86806c449] - Only one payment per order is allowed; duplicate payments 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-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - Notification Service rate limit: 10 emails per second. [KB-582e7673-bd66-493e-b511-017708ae9326] ## 4.4 Business Requirements - The current order management system is designed for individual order processing. Bulk CSV import for large corporate customers (100–10,000 orders per import) is a requested but unimplemented feature. [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-2183809f-cfa9-4b0b-a30d-320f78a4f161], [KB-2b0238e6-fb8b-4b64-bbb0-73de35f73a08], [KB-94407aa3-d1ac-4455-a68c-265236fefec4], [KB-9722c127-de97-4494-bb8d-1d840efa8899], [KB-5a963d29-d4ed-4859-ba71-d355620aa5bc], [KB-6ef0a78b-63b6-493a-a7b0-76398d5a2889] ## 4.5 [GAP] Bulk CSV Import Requirements - [GAP: Missing data for Requirements] *Bulk CSV import requirements are referenced in business context but not implemented or specified in the current system. Functional, interface, and constraint requirements for bulk import are pending and must be defined prior to implementation.* --- **References:** - [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] - [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] - [KB-86e313b9-691a-4830-b560-a2097e138f34] - [KB-8072a75f-d61d-49b1-a859-1be86806c449] - [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - [KB-582e7673-bd66-493e-b511-017708ae9326] - [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1] - [KB-1603dccf-0e13-426d-a4c3-527af9e69c16] - [KB-2183809f-cfa9-4b0b-a30d-320f78a4f161] - [KB-2b0238e6-fb8b-4b64-bbb0-73de35f73a08] - [KB-94407aa3-d1ac-4455-a68c-265236fefec4] - [KB-9722c127-de97-4494-bb8d-1d840efa8899] - [KB-5a963d29-d4ed-4859-ba71-d355620aa5bc] - [KB-6ef0a78b-63b6-493a-a7b0-76398d5a2889] - [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] - [KB-69d55b34-e506-4b4e-a043-ef842030f397] - [KB-981308db-2c30-4894-ba6b-491f-40a2-b97e5-69862203abce] - [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] - [KB-4d364408-238b-4248-925a-97d5a3446d3c] - [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3] - [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a]