## Requirements # 3. Requirements This section defines the functional and interface requirements for the Order, Payment, and Notification services, as well as constraints and cross-service interactions. All requirements are derived strictly from the provided context and are structured to comply with ISO-29148. --- ## 3.1 Functional Requirements ### 3.1.1 Order Service | ID | Requirement | Priority | |---------|-------------------------------------------------------------------------------------------------------------|----------| | FR-001 | The system shall allow creation of a single order by specifying customer information (name, email) and order details (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 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 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-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-4651de1d-570d-4c49-8a65-ec5b22855797], [KB-4287fde1-e2d9-4e31-8a36-e5f711cac6b9] --- ### 3.1.2 Payment Service | ID | Requirement | Priority | |---------|--------------------------------------------------------------------------------------------------------------|----------| | FR-013 | The system shall enforce a maximum amount of 1,000,000 JPY per transaction. | P1 | | FR-014 | The system shall maintain a 1:1 relationship between order and payment (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], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a], [KB-9b61fb5a-8a89-4024-a535-ca56b147a8c8] --- ### 3.1.3 Notification Service | 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-3133bf0e-2d7b-46bc-ae60-dac1a20281ed], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e] --- ### 3.1.4 CSV Import (Bulk Order Creation) — [Planned/Requested] | ID | Requirement | Priority | |--------------|------------------------------------------------------------------------------------------------------|----------| | FR-BULK-001 | The system shall allow users to upload CSV files for bulk order import. Maximum file size: 50MB. Supported encodings: UTF-8, Shift_JIS. | P1 | | FR-BULK-002 | The system shall validate CSV column structure, data types, and required fields. Errors shall be reported with row-level detail. | P1 | | FR-BULK-003 | The system shall create orders in bulk from validated CSV data. Supported volume: 100–10,000 orders per import. | P1 | | FR-BULK-004 | The system shall process payments for all created orders individually (no batch payment endpoint). | P1 | | FR-BULK-005 | The system shall send confirmation emails in bulk to all order recipients (rate limits apply). | P2 | | FR-BULK-006 | The system shall display real-time progress tracking (processed/total count) for bulk imports. | P1 | | FR-BULK-007 | The system shall handle partial failures: successful orders are retained, failed orders are downloadable as an error list. | P1 | | FR-BULK-009 | The system shall provide a downloadable CSV template in the correct format. | P3 | | FR-BULK-010 | The system shall allow cancellation of an in-progress import; unprocessed orders will not be created. | P3 | **References:** [KB-063a89e7-bb79-4435-993b-95ec7b9a9e4e], [KB-2d968f58-3ed8-4207-9d71-0c429c197cb4], [KB-35c9e00d-f446-4174-be65-d214ecbff895], [KB-89dddd9a-2e13-46e7-99a4-34c3fff47435], [KB-6aa21c29-11f1-4b6b-b8e8-2c9990900522] --- ## 3.2 Interface Requirements ### 3.2.1 Order Service API | Endpoint | Description | |------------------------------------------------|----------------------------------------------------------------------------------------------| | POST /api/v1/orders/ | Create a single order. No bulk/batch creation endpoint exists. | | GET /api/v1/orders/ | Retrieve paginated list of orders (parameters: skip, limit; default limit: 20). | | GET /api/v1/orders/{order_id} | Retrieve order details including items. | | PUT /api/v1/orders/{order_id}/status | Update order status. Setting status to SHIPPED triggers shipping notification. | | DELETE /api/v1/orders/{order_id} | Cancel order. Triggers refund via Payment Service and cancellation email via Notification Service. | | POST /api/v1/orders/{order_id}/webhook | Receives payment status updates from Payment Service. Updates order status accordingly. | **References:** [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8a36-e5f711cac6b9], [KB-97f5aa4c-231b-4f00-b6cd-a5ed85f4b1e7], [KB-981308db-2c30-4894-ba6b-491bf40b1d24] --- ### 3.2.2 Payment Service API | Endpoint | Description | |------------------------------------------------|----------------------------------------------------------------------------------------------| | POST /api/v1/payments/ | Process payment for a single order. Validates amount (100–1,000,000 JPY), enforces uniqueness of order_id. | | GET /api/v1/payments/{payment_id} | Retrieve payment details 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. | **References:** [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] --- ### 3.2.3 Notification Service API | Endpoint | Description | |------------------------------------------------|----------------------------------------------------------------------------------------------| | POST /api/v1/notifications/email | Send a single email notification. One email per request. Rate limit: 10/sec. | | POST /api/v1/notifications/sms | Send a single SMS notification. One SMS per request. | | GET /api/v1/notifications/{notification_id} | Retrieve notification details by notification ID. | | GET /api/v1/notifications/order/{order_id} | Retrieve all notifications for a specific order. | **References:** [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4], [KB-258b5996-5aad-4f5f-acd2-8e458c49f884] --- ### 3.2.4 Cross-Service Integration | Caller Service | Endpoint Called | Trigger | Payload/Contract | Expected Response | On Failure/Timeout | |-------------------|-------------------------------------------------------------|--------------------------|----------------------------------------------------------------------------------|-------------------|-----------------------------------| | Order Service | Payment Service: POST /api/v1/payments | Order creation | {"order_id": N, "amount": N.N, "currency": "JPY"} | 201 Created | Order status reverts to PENDING | | Payment Service | Order Service: POST /api/v1/orders/{order_id}/webhook | Payment status change | {"payment_status": "completed", "transaction_id": "uuid"} | 200 OK | Retry up to timeout | | Order Service | Notification Service: POST /api/v1/notifications/email | Order creation, status change, cancellation | {"order_id": N, "to_email": "...", "template_name": "...", "template_data": {...}} | 201 Created | Logged, order creation continues | **References:** [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22], [KB-69d55b34-e506-4b4e-a043-ef842030f397] --- ## 3.3 Constraints - Only single order creation and payment are supported per API call. No batch/bulk endpoints exist for order or payment creation. Bulk order import (CSV) is a requested feature, not currently implemented. [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] - Maximum payment amount per transaction is 1,000,000 JPY. [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] - 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] - Notification templates use Jinja2 syntax and are rendered per-notification; there is no batch template rendering optimization. [KB-3133bf0e-2d7b-46bc-ae60-dac1a20281ed] - Notification Service rate limit: 10 emails per second. [KB-582e7673-bd66-493e-b511-017708ae9326] --- ## 3.4 Gaps - Bulk order creation and payment processing via CSV import are requested by business stakeholders but are not implemented in the current API. [KB-16181d30-2dd3-421e-bab0-939cd85255d2], [KB-2d968f58-3ed8-4207-9d71-0c429c197cb4], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] - [GAP: Missing data for Requirements] — No implementation details for CSV import endpoints, progress tracking endpoints, or error download endpoints. --- **End of Requirements Section**