## Requirements # 3. Requirements This section defines the functional and interface requirements for the Order Service, Payment Service, and Notification Service, including constraints and business rules. All requirements are derived strictly from the provided context and are structured to comply with ISO-29148. --- ## 3.1 Order Service Requirements ### 3.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 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 retrieval of order lists with pagination (parameters: skip, limit; default limit: 20). | P1 | | FR-004 | The system shall support retrieval of order details, including all items, by order ID. | P1 | | FR-005 | The system shall support order status transitions: PENDING → PROCESSING → PAID → SHIPPED → DELIVERED. | P1 | | FR-006 | The system shall support order cancellation, updating the status to CANCELLED. | P1 | | FR-009 | On order cancellation, the system shall send a refund request to the Payment Service. | P1 | | FR-010 | On order cancellation, the system shall send a cancellation notification to the Notification Service. | P1 | **References:** [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f], [KB-4651de1d-570d-4c49-8a65-ec5b22855797] --- ### 3.1.2 Interface Requirements | Endpoint | Description | |---------------------------------------------------|--------------------------------------------| | POST /api/v1/orders/ | Create a single order | | GET /api/v1/orders/ | List orders (pagination: skip, limit) | | GET /api/v1/orders/{order_id} | Retrieve order details | | PUT /api/v1/orders/{order_id}/status | Update order status | | DELETE /api/v1/orders/{order_id} | Cancel order (triggers refund and notification) | | POST /api/v1/orders/{order_id}/webhook | Receive payment status update (single order only) | **References:** [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-981308db-2c30-4894-ba6b-491bf40b1d24] --- ### 3.1.3 Constraints - Only single-order creation per request is supported; bulk or batch order creation is not implemented. - Order cancellation triggers both refund processing and notification. - All deletes are logical (soft deletes) using a `deleted_at` timestamp; hard deletes are prohibited for PHI compliance. **References:** [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-713a0d6c-18a7-4a3a-806c-0dccb0b9ad09] --- ## 3.2 Payment Service Requirements ### 3.2.1 Functional Requirements | ID | Requirement | Priority | |---------|-------------------------------------------------------------------------------------------------|----------| | FR-013 | The system shall enforce a maximum payment 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-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] --- ### 3.2.2 Interface Requirements | Endpoint | Description | |------------------------------------------|-----------------------------------------------------| | POST /api/v1/payments/ | Process payment for a single order | | GET /api/v1/payments/{payment_id} | Retrieve payment details by payment ID | | GET /api/v1/payments/order/{order_id} | Retrieve payment details by order ID | | POST /api/v1/payments/refund | Process refund for a payment | **References:** [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] --- ### 3.2.3 Constraints - Only single-order payments are supported; batch or bulk payments are not allowed. - Payment amounts must be between 100 JPY and 1,000,000 JPY (inclusive). - Duplicate payments for the same order are rejected. - Refunds are only processed for completed payments. **References:** [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] --- ## 3.3 Notification Service Requirements ### 3.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-3133bf0e-2d7b-46bc-ae60-dac1a20281ed], [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-258b5996-5aad-4f5f-acd2-8e458c49f884], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4], [KB-4d364408-238b-4248-925a-97d5a3446d3c] --- ### 3.3.2 Interface Requirements | Endpoint | Description | |----------------------------------------------|----------------------------------------------------------| | POST /api/v1/notifications/email | Send a single email notification (rate limit: 10/sec) | | POST /api/v1/notifications/sms | Send a single SMS notification | | 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], [KB-4d364408-238b-4248-925a-97d5a3446d3c] --- ### 3.3.3 Constraints - Each notification request processes a single notification; batch notification sending is not supported. - Jinja2 template rendering is performed for each notification individually. - Notification delivery status must be tracked and retrievable. - Rate limiting applies: maximum 10 email notifications per second. **References:** [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-3133bf0e-2d7b-46bc-ae60-dac1a20281ed], [KB-79349dcb-8798-40ed-b5d7-4be4dd855565] --- ## 3.4 Cross-Service Integration Requirements | Source Service | Target Service | Trigger/Event | Action/Endpoint | |------------------|------------------|-------------------------------------|------------------------------------------------------| | Order Service | Payment Service | Order creation | POST /api/v1/payments/ | | Payment Service | Order Service | Payment status change | POST /api/v1/orders/{order_id}/webhook | | Order Service | Notification Service | Order creation, status change, cancellation | POST /api/v1/notifications/email (or /sms) | | Order Service | Payment Service | Order cancellation | POST /api/v1/payments/refund | **References:** [KB-5a54adc1-e1bc-4649-9fe6-237c50ce768c], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22], [KB-1a8a8c49-5d2d-4747-b2de-4e95950cdf44], [KB-531d0e2e-8232-44c5-bb97-31abf9e53c85] --- ## 3.5 Error Handling - All error responses must follow the Problem Details for HTTP APIs standard (RFC 7807). - Common error codes: 400 (Bad Request/Validation Error), 404 (Not Found), 422 (Schema Validation Error), 500 (Internal Server Error). **References:** [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-4bd8168d-aed4-41eb-8733-2ab9d82daa22], [KB-6353c73b-fdb1-409c-9679-739f0ab68585] --- ## 3.6 Security and Compliance Requirements - All API endpoints must enforce authentication and authorization as specified in the security architecture. - All deletes must be logical (soft delete) for PHI compliance. - No PHI may be included in URLs or logs; only resource IDs are permitted. - All API calls must be logged with a correlation ID. **References:** [KB-713a0d6c-18a7-4a3a-806c-0dccb0b9ad09], [KB-7efc7991-042f-4250-a023-be3696c0d900], [KB-64681fc4-a9bf-458e-bc2d-eb3fb009161b] --- ## 3.7 Current Limitations - Bulk or batch order creation and payment processing are not supported. - Batch webhook or batch status update mechanisms do not exist. - All integrations and notifications are processed per single order/request. **References:** [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397] --- If any required requirement is missing, please refer to "[GAP: Missing data for Requirements]".