## Requirements # 4. Requirements This section defines the functional and non-functional requirements for the Order Management, Payment, and Notification Services, including their interfaces, business rules, constraints, and cross-service interactions. All requirements are derived strictly from the provided source material and are structured in accordance with ISO/IEC/IEEE 29148. --- ## 4.1 Functional Requirements ### 4.1.1 Order Service | ID | Requirement | Priority | Reference | |--------|------------------------------------------------------------------------------------------------------------------|----------|-------------------------------------------------| | 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 total order amount as the sum of (quantity × unit price) for all items. | P1 | [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205] | | FR-003 | The system shall provide paginated order listing with skip and limit parameters (default limit: 20). | P1 | [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205] | | FR-004 | The system shall retrieve order details by order ID, including all order items. | P1 | [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] | | FR-005 | The system shall support order status transitions: PENDING → PROCESSING_PAYMENT → 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] | | FR-007 | Upon order cancellation, the system shall trigger a refund request to the Payment Service. | P1 | [KB-4651de1d-570d-4c49-8a65-ec5b22855797] | | FR-008 | Upon order cancellation, the system shall send a cancellation notification via the Notification Service. | P1 | [KB-4651de1d-570d-4c49-8a65-ec5b22855797] | ### 4.1.2 Payment Service | ID | Requirement | Priority | Reference | |--------|--------------------------------------------------------------------------------------------------------------|----------|-------------------------------------------------| | FR-013 | The system shall enforce a maximum limit of 1,000,000 JPY per single transaction. | P1 | [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] | | 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] | | FR-015 | The system shall reject duplicate payment requests for the same order. | P1 | [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] | | FR-016 | The system shall support refund processing for completed payments. | P1 | [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6] | ### 4.1.3 Notification Service | ID | Requirement | Priority | Reference | |--------|-----------------------------------------------------------------------------------------------------------------------|----------|-------------------------------------------------| | 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] | | 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] | --- ## 4.2 Interface Requirements ### 4.2.1 Order Service API | Endpoint | Description | Reference | |------------------------------------------------|--------------------------------------------------|-------------------------------------------------| | POST /api/v1/orders/ | Create a single order. Batch creation is not supported. | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] | | GET /api/v1/orders/ | List orders with pagination (skip, limit). | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] | | GET /api/v1/orders/{order_id} | Retrieve order details by ID. | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] | | PUT /api/v1/orders/{order_id}/status | Update order status; triggers shipment notification if set to SHIPPED. | [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] | | DELETE /api/v1/orders/{order_id} | Cancel order; triggers refund and cancellation notification. | [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] | | POST /api/v1/orders/{order_id}/webhook | Receive payment status updates from Payment Service. | [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] | ### 4.2.2 Payment Service API | Endpoint | Description | Reference | |------------------------------------------------|--------------------------------------------------|-------------------------------------------------| | POST /api/v1/payments/ | Process payment for a single order. No batch endpoint. | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | GET /api/v1/payments/{payment_id} | Retrieve payment details by payment ID. | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | GET /api/v1/payments/order/{order_id} | Retrieve payment for a specific order (1:1 relationship). | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | POST /api/v1/payments/refund | Process refund for a completed payment. | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | POST /api/v1/payments/webhook | Receive callbacks from external payment gateways. | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | ### 4.2.3 Notification Service API | Endpoint | Description | Reference | |------------------------------------------------|--------------------------------------------------|-------------------------------------------------| | POST /api/v1/notifications/email | Send a single email notification (rate limit: 10/sec). | [KB-582e7673-bd66-493e-b511-017708ae9326] | | POST /api/v1/notifications/sms | Send a single SMS notification. | [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] | | GET /api/v1/notifications/{notification_id} | Retrieve notification details by ID. | [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] | | GET /api/v1/notifications/order/{order_id} | Retrieve all notifications for a specific order. | [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] | --- ## 4.3 Business and Operational Constraints ### 4.3.1 Payment Constraints - Maximum payment amount per transaction: 1,000,000 JPY. - Minimum payment amount per transaction: 100 JPY. - Each order can have only one payment (1:1 relationship). - Duplicate payment requests for the same order are rejected. - Refunds are only supported for completed payments. - No batch payment endpoint exists; all payments must be processed individually. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] ### 4.3.2 Notification Constraints - Each notification (email/SMS) is sent per individual order; no batch notification endpoint is provided. - Notification templates use Jinja2 variable substitution and support Japanese content. - Notification delivery status is tracked as PENDING, SENT, or FAILED. - Notification Service rate limit: 10 requests per second for email. [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-3133bf0e-2d7b-4477-9e36-c8548c037b2c], [KB-79349dcb-8798-40ed-b5d7-4be4dd855565] ### 4.3.3 Order Service Constraints - Only single order creation is supported per API call; batch or bulk order creation is not available in the current implementation. [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c] --- ## 4.4 Cross-Service Interactions ### 4.4.1 Order Service → Payment Service | Trigger | Endpoint | Payload | On Failure | Reference | |-----------------|--------------------------------------------------|-------------------------------------------------|------------------------|-------------------------------------------------| | Order creation | POST http://localhost:8001/api/v1/payments | {"order_id": N, "amount": N.N, "currency": "JPY"} | Order status = PENDING | [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c] | ### 4.4.2 Payment Service → Order Service | Trigger | Endpoint | Payload | Reference | |----------------------|--------------------------------------------------------|-------------------------------------------------|-------------------------------------------------| | Payment status change| POST http://localhost:8000/api/v1/orders/{order_id}/webhook | {"payment_status": "completed", "transaction_id": "uuid"} | [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22] | ### 4.4.3 Order Service → Notification Service | Trigger | Endpoint | Payload | On Failure | Reference | |----------------------------|--------------------------------------------------|-----------------------------------------------------------------------------------------|------------------|-------------------------------------------------| | Order creation, status change, cancellation | POST http://localhost:8002/api/v1/notifications/email | {"order_id": N, "to_email": "...", "template_name": "...", "template_data": {...}} | Logged only | [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c] | --- ## 4.5 Error Handling - All error responses follow the Problem Details for HTTP APIs standard (RFC 7807). - Common error codes: - 400: Bad Request / Validation Error - 404: Resource Not Found - 422: Schema Validation Error - 500: Internal Server Error [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-6353c73b-fdb1-409c-9679-739f0ab68585] --- ## 4.6 Security and Access Control Requirements - Authentication: OAuth 2.0 Bearer tokens (JWT). - Authorization: @PreAuthorize with role and attribute checks. - Input validation: Bean Validation (JSR 380) on all DTOs. - Output filtering: PHI field filtering based on caller role. - Rate limiting: 100 req/min (user), 1000 req/min (service). - TLS 1.3 minimum. - CORS: Whitelist-based, per environment. - Audit logging: Every API call logged with correlation ID. - PHI must never be included in URLs or logs. [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b], [KB-7efc7991-042f-4250-a023-be3696c0d900] --- ## 4.7 [GAP: Missing data for Requirements] - Requirements for bulk order import, progress tracking, and partial failure handling are referenced in several blocks but are not fully implemented or available in the current system. [KB-16181d30-2dd3-421e-bab0-939cd85255d2], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] --- **End of Requirements Section**