## Requirements # 3. Requirements This section defines the functional and interface requirements for the Order, Payment, and Notification Services, as well as cross-service integration and business constraints. All requirements are derived strictly from the provided context and are structured per ISO-29148. --- ## 3.1 Functional Requirements ### 3.1.1 Order Service | Requirement ID | Requirement | Priority | Source | |----------------|---------------------------------------------------------------------------------------------------------------------|----------|--------| | FR-001 | The system shall allow creation of a single order by specifying customer information (name, email) and order items (product name, quantity, unit price). | P1 | [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205] | | FR-002 | The system shall automatically calculate the order total as the sum of (quantity × unit price) for all items. | P1 | [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205] | | FR-003 | The system shall support paginated retrieval of order lists using skip and limit parameters (default limit: 20). | P1 | [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] | | FR-004 | The system shall retrieve order details, including items, by order ID. | P1 | [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] | | FR-005 | The system shall support order status transitions: PENDING → PROCESSING → PAID → SHIPPED → DELIVERED. | P1 | [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] | | FR-006 | The system shall support order cancellation, updating the status to CANCELLED. | P1 | [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] | ### 3.1.2 Payment Service | Requirement ID | Requirement | Priority | Source | |----------------|---------------------------------------------------------------------------------------------------------------------|----------|--------| | FR-013 | The system shall enforce a maximum payment amount of 1,000,000 JPY per transaction. | P1 | [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | FR-014 | The system shall maintain a 1:1 relationship between orders and payments (one payment per order). | P1 | [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | FR-015 | The system shall reject duplicate payment requests for the same order. | P1 | [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | FR-016 | The system shall support refund processing for completed payments. | P1 | [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-8072a75f-d61d-49b1-a859-1be86806c449] | ### 3.1.3 Notification Service | Requirement ID | Requirement | Priority | Source | |----------------|---------------------------------------------------------------------------------------------------------------------|----------|--------| | FR-019 | The system shall send email notifications for individual orders using templates. | P1 | [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] | | FR-020 | The system shall send SMS notifications for individual orders using templates. | P2 | [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] | | FR-021 | The system shall support three notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED. | P1 | [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] | | FR-022 | Templates shall support Jinja2-style variable substitution with Japanese language content. | P1 | [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-3133bf0e-2d7b-9e36-c8548c037b2c] | | FR-023 | The system shall track notification delivery status (PENDING, SENT, FAILED). | P1 | [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] | | FR-024 | The system shall retrieve notification history by notification ID. | P2 | [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] | | FR-025 | The system shall retrieve all notifications for a specific order. | P2 | [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] | --- ## 3.2 Interface Requirements ### 3.2.1 Order Service API | Endpoint | Method | Description | Source | |-------------------------------------------|--------|-------------------------------------------------------------------------------------------------------------|--------| | /api/v1/orders/ | POST | Create a single order. Bulk/batch creation is not supported. | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] | | /api/v1/orders/ | GET | List orders with pagination (skip, limit). | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] | | /api/v1/orders/{order_id} | GET | Retrieve order details by order ID. | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] | | /api/v1/orders/{order_id}/status | PUT | Update order status. Setting to SHIPPED triggers shipping notification. | [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] | | /api/v1/orders/{order_id} | DELETE | Cancel order. Triggers refund via Payment Service and cancellation email via Notification Service. | [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-981308db-2c30-4894-ba6b-491bf40b1d24] | | /api/v1/orders/{order_id}/webhook | POST | Receives payment status updates from Payment Service. Updates order status accordingly. | [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22] | ### 3.2.2 Payment Service API | Endpoint | Method | Description | Source | |-------------------------------------------|--------|-------------------------------------------------------------------------------------------------------------|--------| | /api/v1/payments/ | POST | Process payment for a single order. Amount must be between 100 and 1,000,000 JPY. No batch payments. | [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] | | /api/v1/payments/{payment_id} | GET | Retrieve payment details by payment ID. | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | /api/v1/payments/order/{order_id} | GET | Retrieve payment details for a specific order (1:1 relationship). | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | /api/v1/payments/refund | POST | Process refund for a completed payment. Requires payment_id and reason. | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | ### 3.2.3 Notification Service API | Endpoint | Method | Description | Source | |-------------------------------------------|--------|-------------------------------------------------------------------------------------------------------------|--------| | /api/v1/notifications/email | POST | Send a single email notification. Rate limit: 10/second. | [KB-582e7673-bd66-493e-b511-017708ae9326] | | /api/v1/notifications/sms | POST | Send a single SMS notification. | [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] | | /api/v1/notifications/{notification_id} | GET | Retrieve notification details by notification ID. | [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] | | /api/v1/notifications/order/{order_id} | GET | Retrieve all notifications for a specific order. | [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] | ### 3.2.4 Cross-Service Integration | From | To | Trigger | Endpoint/Contract | Source | |----------------|-------------------|-------------------------------|-----------------------------------------------------------|--------| | Order Service | Payment Service | Order creation | POST /api/v1/payments/ | [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c] | | Payment Service| Order Service | Payment status change | POST /api/v1/orders/{order_id}/webhook | [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22] | | Order Service | Notification Svc | Order creation, status change | POST /api/v1/notifications/email | [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c] | | Order Service | Notification Svc | Order cancellation | POST /api/v1/notifications/email (ORDER_CANCELLED) | [KB-981308db-2c30-4894-ba6b-491bf40b1d24] | | Payment Service| Order Service | Refund processed | POST /api/v1/orders/{order_id}/webhook | [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22] | --- ## 3.3 Constraints | Constraint ID | Constraint | Source | |---------------|---------------------------------------------------------------------------------------------------------------|--------| | C-001 | Only single order creation and payment per API call are supported. No bulk/batch endpoints exist. | [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] | | C-002 | Payment amount must be between 100 and 1,000,000 JPY per transaction. | [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] | | C-003 | Each order can have only one associated payment (1:1 relationship). | [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] | | C-004 | Duplicate payment requests for the same order are rejected. | [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] | | C-005 | Refunds are only allowed for completed payments. | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | C-006 | Notification templates use Jinja2 syntax and are rendered per notification; no batch rendering optimization. | [KB-3133bf0e-2d7b-9e36-c8548c037b2c] | | C-007 | Notification Service enforces a rate limit of 10 email notifications per second. | [KB-582e7673-bd66-493e-b511-017708ae9326] | --- ## 3.4 Business Requirements | Requirement ID | Requirement | Source | |----------------|---------------------------------------------------------------------------------------------------------------------|--------| | BR-001 | The system must support order and payment flows suitable for B2B clients, but only single order creation is currently implemented. | [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] | | BR-002 | Bulk order import and batch payment features are requested by business users but are not implemented in the current system. | [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] | --- ## 3.5 Error Handling - All error responses follow the Problem Details for HTTP APIs standard (RFC 7807). Example: ```json { "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Amount must be between 100 and 1,000,000 JPY" } ``` [KB-6353c73b-fdb1-409c-9679-739f0ab68585], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] --- ## 3.6 Gaps - Bulk order creation and batch payment processing are not supported. [KB-564ae239-84b1-4d13-bb04-b7e829eb53b6], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] --- **End of Requirements Section**