## Requirements # 4. Requirements ## 4.1 Functional Requirements ### 4.1.1 Order Service - The system shall allow creation of a single order per request, specifying customer information (name, email) and order details (product name, quantity, unit price). Bulk or batch order creation is not supported. [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] - The system shall automatically calculate the total order amount as the sum of (quantity × unit price) for each item. [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205] - The system shall support paginated retrieval of orders (parameters: skip, limit; default limit = 20). [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] - The system shall allow retrieval of order details by order ID, including line items. [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] - 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 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] ### 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] - Payment amount must be validated: minimum 100 JPY, maximum 1,000,000 JPY per transaction. [KB-8072a75f-d61d-49b1-a859-1be86806c449] - Each payment must be uniquely associated with an order (1:1 relationship). Duplicate payment requests for the same order_id shall be rejected. [KB-8072a75f-d61d-49b1-a859-1be86806c449] - The Payment Service shall support refund processing for completed payments. [KB-8072a75f-d61d-49b1-a859-1be86806c449] - After payment processing, the Payment Service shall notify the Order Service of payment status via a webhook callback (single order per call). [KB-69d55b34-e506-4b4e-a043-ef842030f397] ### 4.1.3 Notification Service - The Notification Service shall send email notifications for individual orders using templates. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] - The Notification Service 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] - The system shall track notification delivery status (PENDING, SENT, FAILED). [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] - The system shall retrieve notification history by notification ID and retrieve all notifications for a specific order. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] ### 4.1.4 CSV Import (Bulk Order — Business Requirement) - There is a documented business requirement to support bulk order import via CSV file (100–10,000 orders per batch) to improve operational efficiency for corporate clients. [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1] - Current system only supports single order creation; bulk CSV import is not implemented. [KB-16181d30-2dd3-421e-bab0-939cd85255d2] - If implemented, each order in the CSV would be processed individually, with payment and notification handled per order (no batch payment or batch notification endpoints exist). [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] ## 4.2 Interface Requirements ### 4.2.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} | Get order details by ID | | PUT /api/v1/orders/{order_id}/status | Update order status | | DELETE /api/v1/orders/{order_id} | Cancel order (triggers refund, notification)| | POST /api/v1/orders/{order_id}/webhook | Receive payment status update (single order)| [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-69d55b34-e506-4b4e-a043-ef842030f397] ### 4.2.2 Payment Service API | Endpoint | Description | |-------------------------------------------|----------------------------------------------| | POST /api/v1/payments/ | Process payment for single order | | GET /api/v1/payments/{payment_id} | Retrieve payment by payment ID | | GET /api/v1/payments/order/{order_id} | Retrieve payment for specific order | | POST /api/v1/payments/refund | Process refund for completed payment | | POST /api/v1/payments/webhook | Receive external payment gateway callbacks | [KB-8072a75f-d61d-49b1-a859-1be86806c449] ### 4.2.3 Notification Service API | Endpoint | Description | |--------------------------------------------------|--------------------------------------------------| | POST /api/v1/notifications/email | Send single email notification (rate limit: 10/sec)| | 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 specific order | [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] ## 4.3 Constraint Requirements - Maximum payment amount per transaction is 1,000,000 JPY; minimum is 100 JPY. [KB-8072a75f-d61d-49b1-a859-1be86806c449] - Payment and order relationship is strictly 1:1; batch payment processing is not supported. [KB-8072a75f-d61d-49b1-a859-1be86806c449] - Duplicate payment requests for the same order are rejected. [KB-8072a75f-d61d-49b1-a859-1be86806c449] - Webhook notifications for payment status are sent per order; batch webhook or batch status update is not supported. [KB-69d55b34-e506-4b4e-a043-ef842030f397] - Notification Service processes one notification per request; batch notification sending is not supported. [KB-582e7673-bd66-493e-b511-017708ae9326] ## 4.4 Data Requirements - Order data includes: customer name, customer email, items (product name, quantity, unit price), total amount, currency, timestamps, and status. [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4] - Payment data includes: order_id, amount, currency, status, payment method, transaction_id, timestamps. [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] - Notification data includes: order_id, channel (email/SMS), template_name, recipient, subject, body, status, sent_at, created_at. [KB-258b5996-5aad-4f5f-acd2-8e458c49f884] ## 4.5 Business Requirements - Bulk order import via CSV (100–10,000 orders) is a high-priority business requirement for corporate clients, but is not currently implemented. [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-16181d30-2dd3-421e-bab0-939cd85255d2] ## 4.6 [GAP: Missing data for Requirements] - No requirements for CSV import validation, error handling, progress tracking, or partial failure management are currently implemented in the system. [KB-16181d30-2dd3-421e-bab0-939cd85255d2] - No requirements for bulk notification or bulk payment processing are currently implemented. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] --- **References:** [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] [KB-8072a75f-d61d-49b1-a859-1be86806c449] [KB-582e7673-bd66-493e-b511-017708ae9326] [KB-69d55b34-e506-4b4e-a043-ef842030f397] [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1] [KB-16181d30-2dd3-421e-bab0-939cd85255d2] [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4] [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] [KB-258b5996-5aad-4f5f-acd2-8e458c49f884] [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]