## Requirements # 4. Requirements ## 4.1 Functional Requirements ### 4.1.1 Order Creation and Management - The system must support 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], [KB-77ed901f-0149-4b9e-838d-6f8fda48ab51] - Orders must include customer information (name, email), item details (product name, quantity, unit price), and currency. [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] - The total order amount is automatically calculated as the sum of (quantity × unit price) for all items. [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-86e313b9-691a-4830-b560-a2097e138f34] - Orders can be retrieved via their order ID, including item details. [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] - Order status transitions are supported: Pending → Payment Processing → Paid → Shipped → Delivered. [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] - Order cancellation is supported, with status updated to "Cancelled." [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] - Pagination (skip, limit) is available for order listing, with a default limit of 20. [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] ### 4.1.2 Payment Processing - Payment processing is performed 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-564ae239-84b1-4ef2-bb04-b7e829eb53b6] - 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], [KB-186b33d7-f985-455b-8117-0cd019912510] - Each order can have only one payment (1:1 relationship). Duplicate payment requests for the same order are rejected. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - Refund processing is supported for completed payments, triggered by order cancellation. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-981308db-2c30-4894-ba6b-491bf40b1d24] ### 4.1.3 Notification Service - Email and SMS notifications are sent for individual orders using templates. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-1c5832cc-4e41-483e-9898-60c735170444], [KB-582e7673-bd66-493e-b511-017708ae9326] - Supported notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-1c5832cc-4e41-483e-9898-60c735170444] - Templates use Jinja2-style variable substitution with Japanese language content. [KB-3133bf0e-2d7b-4477-9e36-c8548c037b2c], [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e] - Notification delivery status is tracked (PENDING, SENT, FAILED). [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e] - Notification history can be retrieved by notification ID and all notifications for a specific order can be listed. [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-1c5832cc-4e41-483e-9898-60c735170444], [KB-4d364408-238b-4248-925a-97d5a3446d3c] ### 4.1.4 API Integration and Webhook Mechanism - Payment Service notifies Order Service of payment status via webhook callback for each order: - POST /api/v1/orders/{order_id}/webhook Payload: {"payment_status": "completed", "transaction_id": "uuid"} [KB-69d55b34-e506-4b4e-a043-ef842030f397], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-981308db-2c30-4894-ba6b-491bf40b1d24] - No batch webhook or batch status update exists; all integrations are single-order per call. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397] - Notification Service API endpoints support sending one email or SMS per request. Rate limit: 10 requests/second. [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-08459d3c-cf60-4021-9822-34a48d940c94] ### 4.1.5 Error Handling - All error responses follow the Problem Details for HTTP APIs standard (RFC 7807). [KB-6353c73b-fdb1-409c-9679-739f0ab68585], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] - Common error codes: - 400: Bad Request / Validation Error (e.g., amount out of range, duplicate order_id) - 404: Resource Not Found - 422: Schema Validation Error - 500: Internal Server Error [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22], [KB-8072a75f-d61d-49b1-a859-1be86806c449] ## 4.2 Constraints - Maximum payment amount per transaction: 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: 100 JPY. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - Only one payment per order is allowed; duplicate payment requests 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-36050440-5a8a-4389-8690-8fd0a46f5cd3] - Notification Service rate limit: 10 requests per second. [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-08459d3c-cf60-4021-9822-34a48d940c94] ## 4.3 Interface Requirements - Order Service API endpoints: - 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 - PUT /api/v1/orders/{order_id}/status — Update Status - DELETE /api/v1/orders/{order_id} — Cancel Order - POST /api/v1/orders/{order_id}/webhook — Payment Status Update [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-981308db-2c30-4894-ba6b-491bf40b1d24] - Payment Service API endpoints: - POST /api/v1/payments/ — Create Payment - GET /api/v1/payments/{payment_id} - GET /api/v1/payments/order/{order_id} - POST /api/v1/payments/refund [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] - Notification Service API endpoints: - POST /api/v1/notifications/email — Send Single Email - POST /api/v1/notifications/sms — Send Single SMS - GET /api/v1/notifications/{notification_id} - GET /api/v1/notifications/order/{order_id} [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-1c5832cc-4e41-483e-9898-60c735170444], [KB-4d364408-238b-4248-925a-97d5a3446d3c] ## 4.4 Data Requirements - Order data must include: - Customer name - Customer email - Item list (product name, quantity, unit price) - Currency - Total amount (auto-calculated) - Status - Timestamps (created_at, updated_at) [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4] - Payment data must include: - Order ID - Amount - Currency - Status - Payment method - Transaction ID - Timestamps [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3] - Notification data must include: - Order ID - Channel (email or SMS) - Template name - Recipient - Subject - Body - Status - Timestamps [KB-258b5996-5aad-4f5f-acd2-8e458c49f884], [KB-582e7673-bd66-493e-b511-017708ae9326] ## 4.5 [GAP: Missing data for Requirements] - Bulk order creation and CSV import are frequently requested by business users, but are not implemented in the current system. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-16181d30-2dd3-421e-bab0-939cd85255d2], [KB-2b07b017-3e2f-47a4-9b03-d2be4a0e5644] - Requirements for CSV import, validation, and bulk processing are referenced in business requests, but technical implementation details are absent. [KB-2b07b017-3e2f-47a4-9b03-d2be4a0e5644], [KB-5bd83fdc-f7d5-4953-bd1e-e9b287f0bf96], [KB-94407aa3-d1ac-4455-a68c-265236fefec4] --- **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-564ae239-84b1-4ef2-bb04-b7e829eb53b6] - [KB-3133bf0e-2d7b-4477-9e36-c8548c037b2c] - [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] - [KB-1c5832cc-4e41-483e-9898-60c735170444] - [KB-4d364408-238b-4248-925a-97d5a3446d3c] - [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3] - [KB-258b5996-5aad-4f5f-acd2-8e458c49f884] - [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4] - [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205] - [KB-981308db-2c30-4894-ba6b-491bf40b1d24] - [KB-69d55b34-e506-4b4e-a043-ef842030f397] - [KB-77ed901f-0149-4b9e-838d-6f8fda48ab51] - [KB-86e313b9-691a-4830-b560-a2097e138f34] - [KB-6353c73b-fdb1-409c-9679-739f0ab68585] - [KB-16181d30-2dd3-421e-bab0-939cd85255d2] - [KB-2b07b017-3e2f-47a4-9b03-d2be4a0e5644] - [KB-5bd83fdc-f7d5-4953-bd1e-e9b287f0bf96] - [KB-94407aa3-d1ac-4455-a68c-265236fefec4]