## Requirements # 4. Requirements This section specifies the functional and interface requirements for the Order, Payment, and Notification Services, as well as related business rules and constraints. All requirements are derived solely from the provided context. --- ## 4.1 Order Service Requirements ### 4.1.1 Functional Requirements | ID | Requirement | Priority | |--------|---------------------------------------------------------------------------------------------------------------|----------| | 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 | | FR-002 | The system shall automatically calculate the total order amount as the sum of (quantity × unit price) for all items. | P1 | | FR-003 | The system shall support paginated retrieval of order lists using skip and limit parameters (default limit: 20). | P1 | | FR-004 | The system shall allow retrieval of order details, including all items, by order ID. | P1 | | FR-005 | The system shall support order status transitions: PENDING → PROCESSING_PAYMENT → PAID → SHIPPED → DELIVERED. | P1 | | FR-006 | The system shall support order cancellation, updating the status to CANCELLED. | P1 | | FR-009 | Upon order cancellation, the system shall send a refund request to the Payment Service. | P1 | | FR-010 | Upon order cancellation, the system shall send a cancellation notification to the Notification Service. | P1 | **References:** [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205] [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] [KB-4651de1d-570d-4c49-8a65-ec5b22855797] --- ### 4.1.2 Interface/API Requirements | Endpoint | Description | Notes | |--------------------------------------------|---------------------------------------------|---------------------------------------------------| | POST /api/v1/orders/ | Create a single order | Bulk/batch creation is NOT supported | | GET /api/v1/orders/ | List orders (paginated: skip, limit) | Default limit: 20 | | GET /api/v1/orders/{order_id} | Retrieve order details by ID | Returns order and item details | | PUT /api/v1/orders/{order_id}/status | Update order status | Setting to SHIPPED triggers shipping notification | | DELETE /api/v1/orders/{order_id} | Cancel order | Triggers refund and cancellation notification | | POST /api/v1/orders/{order_id}/webhook | Receive payment status update (webhook) | Single order callback only | **References:** [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] [KB-981308db-2c30-4894-ba6b-491bf40b1d24] --- ### 4.1.3 Data Model **Order Response Example:** ```json { "id": 1, "customer_email": "tanaka@example.co.jp", "customer_name": "田中太郎", "status": "paid", "total_amount": 183100.0, "currency": "JPY", "created_at": "2025-12-01T10:00:00Z", "updated_at": "2025-12-01T10:00:01Z", "items": [ {"id": 1, "product_name": "ノートPC", "quantity": 2, "unit_price": 89800.0}, {"id": 2, "product_name": "マウス", "quantity": 1, "unit_price": 3500.0} ] } ``` **Reference:** [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4] --- ## 4.2 Payment Service Requirements ### 4.2.1 Functional and Constraint Requirements | ID | Requirement | Priority | |--------|------------------------------------------------------------------------------------------------------|----------| | FR-013 | The system shall enforce a maximum payment amount of 1,000,000 JPY per single transaction. | P1 | | FR-014 | The system shall maintain a 1:1 relationship between orders and payments (one payment per order). | P1 | | FR-015 | The system shall reject duplicate payment requests for the same order. | P1 | | FR-016 | The system shall support refund processing for completed payments. | P1 | **References:** [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] [KB-8072a75f-d61d-49b1-a859-1be86806c449] --- ### 4.2.2 Interface/API Requirements | Endpoint | Description | Notes | |------------------------------------------|-----------------------------------------------|-------------------------------------------| | POST /api/v1/payments/ | Process payment for a single order | Amount: 100–1,000,000 JPY, unique order_id| | GET /api/v1/payments/{payment_id} | Retrieve payment by payment ID | | | GET /api/v1/payments/order/{order_id} | Retrieve payment for a specific order | 1:1 relationship | | POST /api/v1/payments/refund | Process refund for a completed payment | Requires payment_id and reason | **References:** [KB-8072a75f-d61d-49b1-a859-1be86806c449] [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3] [KB-8e5c6600-75fa-4e87-a6f5-0d06b21d8625] [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] --- ### 4.2.3 Payment Processing Flow - Amount validation: 100–1,000,000 JPY per transaction. - Duplicate order_id check: Reject if payment already exists for the order. - On success: Status updated to "completed", webhook callback sent to Order Service. - No batch payment processing is supported; each order requires an individual payment call. **References:** [KB-8072a75f-d61d-49b1-a859-1be86806c449] [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] [KB-60767bfc-9ce5-4341-b8d2-cfbb24f66dc0] --- ## 4.3 Notification Service Requirements ### 4.3.1 Functional Requirements | ID | Requirement | Priority | |--------|------------------------------------------------------------------------------------------------------------|----------| | FR-019 | The system shall send email notifications for individual orders using templates. | P1 | | FR-020 | The system shall send SMS notifications for individual orders using templates. | P2 | | FR-021 | The system shall support three notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED. | P1 | | FR-022 | Templates shall support Jinja2-style variable substitution with Japanese language content. | P1 | | FR-023 | The system shall track notification delivery status (PENDING, SENT, FAILED). | P1 | | FR-024 | The system shall retrieve notification history by notification ID. | P2 | | FR-025 | The system shall retrieve all notifications for a specific order. | P2 | **References:** [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8] [KB-79cd66a7-f8fb-49eb-8181-2e231c58f49d] --- ### 4.3.2 Interface/API Requirements | 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 | | **References:** [KB-582e7673-bd66-493e-b511-017708ae9326] [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] [KB-4d364408-238b-4248-925a-97d5a3446d3c] --- ### 4.3.3 Notification Template Rendering - Templates use Jinja2 syntax. - Variables are passed via `template_data` in the API request. - Rendering is performed per notification (no batch rendering optimization). **Reference:** [KB-3133bf0e-2d7b-46bc-ae60-dac1a20281ed] --- ## 4.4 Integration and Workflow Requirements ### 4.4.1 Order-Payment-Notification Workflow 1. Order creation triggers payment processing (single order only). 2. Payment Service validates and processes payment, then sends webhook callback to Order Service. 3. Order Service updates order status based on payment status. 4. Notification Service is called to send order confirmation, shipping, or cancellation notifications as appropriate. **References:** [KB-71ff9c60-13e4-4194-88e5-a67607551893] [KB-77ed901f-0149-4b9e-838d-6f8fda48ab51] [KB-531d0e2e-8232-44c5-bd1e-e9b287f0bf96] [KB-49bae945-5563-4372-bafa-d95b1b74ce7e] --- ### 4.4.2 Error Handling - If payment amount is below 100 JPY or above 1,000,000 JPY, return 400 Bad Request. - If duplicate order_id is detected in payment, return 400 Bad Request. - All error responses follow RFC 7807 Problem Details for HTTP APIs. **References:** [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3] [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] [KB-6353c73b-fdb1-409c-9679-739f0ab68585] --- ## 4.5 Constraints - **Bulk Operations:** No bulk or batch order creation or payment processing is supported. Each order and payment must be processed individually, including in high-volume scenarios (e.g., 10,000 orders require 10,000 API calls). - **Webhook:** Payment status updates are communicated per order via webhook; no batch webhook or batch status update exists. **References:** [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] [KB-69d55b34-e506-4b4e-a043-ef842030f397] [KB-8072a75f-d61d-49b1-a859-1be86806c449] --- ## 4.6 Gaps - [GAP: Missing data for Requirements] — No requirements for bulk order creation or bulk payment processing are defined in the current system. - [GAP: Missing data for Requirements] — No requirements for order update or notification batch processing. --- **End of Requirements Section**