## Requirements # 4. Requirements This section defines the functional, interface, business, and constraint requirements for the Order, Payment, and Notification Services, as well as CSV import and bulk order processing, based strictly on the provided context. All requirements are structured per ISO-29148 and cited with full block IDs. --- ## 4.1 Functional Requirements ### 4.1.1 Order Service | ID | Requirement | Priority | Source | |--------|---------------------------------------------------------------------------------------------------------------|----------|--------| | FR-001 | The system shall allow creation of a single order 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 from 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 (parameters: skip, limit; default limit: 20). | P1 | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] | | FR-004 | The system shall retrieve order details by order ID, including item details. | 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, transitioning status to CANCELLED. | P1 | [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f] | ### 4.1.2 Payment Service | ID | Requirement | Priority | Source | |--------|---------------------------------------------------------------------------------------------------------------|----------|--------| | FR-013 | The system shall enforce a maximum amount 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 | 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] | | 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.1.4 CSV Import and Bulk Order Processing | ID | Requirement | Priority | Source | |---------------|------------------------------------------------------------------------------------------------------------|----------|--------| | FR-BULK-001 | The system shall allow users to upload CSV files. Maximum file size: 50MB. Supported encodings: UTF-8, Shift_JIS. | P1 | [KB-063a89e7-bb79-4435-993b-95ec7b9a9e4e] | | FR-BULK-002 | The system shall validate CSV structure, data types, and required fields. Error rows shall be identified and reported. | P1 | [KB-2d968f58-3ed8-4207-9d71-0c429c197cb4] | | FR-BULK-003 | The system shall create bulk orders from validated CSV data, supporting 100–10,000 orders per import. Orders shall be created within 5 minutes for 10,000 entries. | P1 | [KB-35c9e00d-f446-4174-be65-d214ecbff895] | | FR-BULK-004 | The system shall process payments for all created orders individually (no batch payment endpoint). | P1 | [KB-35c9e00d-f446-4174-be65-d214ecbff895], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] | | FR-BULK-005 | The system shall send confirmation emails in bulk for imported orders, considering rate limits and using a send queue. | P2 | [KB-1b4a5120-e114-4bb2-b423-43e981424088] | | FR-BULK-006 | The system shall display real-time progress tracking of import processing (processed count/total count). | P1 | [KB-0e28e3cb-6977-43b1-ba8e-1ed80f2de11e] | | FR-BULK-007 | The system shall handle partial failures: successful orders are retained, failed orders are listed and downloadable. | P1 | [KB-0e28e3cb-6977-43b1-ba8e-1ed80f2de11e] | | FR-BULK-009 | The system shall allow downloading a correctly formatted CSV template for import. | P3 | [KB-89dddd9a-2e13-46e7-99a4-34c3fff47435] | | FR-BULK-010 | The system shall allow cancellation of ongoing imports; unprocessed orders shall not be created. | P3 | [KB-89dddd9a-2e13-46e7-99a4-34c3fff47435] | --- ## 4.2 Interface Requirements ### 4.2.1 API Endpoints #### Order Service | Endpoint | Description | Source | |------------------------------------------|------------------------------------------------|--------| | POST /api/v1/orders/ | Create a single order (no batch support). | [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9] | | GET /api/v1/orders/ | List orders with pagination (skip, limit). | [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] | | GET /api/v1/orders/{order_id} | Retrieve order details by ID. | [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add] | | PUT /api/v1/orders/{order_id}/status | Update order status; triggers shipment notification on 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], [KB-186b33d7-f985-455b-8117-0cd019912510] | | POST /api/v1/orders/{order_id}/webhook | Receive payment status update from Payment Service. | [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-69d55b34-e506-4b4e-a043-ef842030f397] | #### Payment Service | Endpoint | Description | Source | |------------------------------------------|------------------------------------------------|--------| | POST /api/v1/payments/ | Process payment for a single order. | [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] | | GET /api/v1/payments/{payment_id} | Retrieve payment by payment ID. | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | GET /api/v1/payments/order/{order_id} | Retrieve payment for specific order (1:1 relationship). | [KB-8072a75f-d61d-49b1-a859-1be86806c449] | | POST /api/v1/payments/refund | Process refund for completed payment. | [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3] | #### Notification Service | Endpoint | Description | Source | |------------------------------------------|------------------------------------------------|--------| | POST /api/v1/notifications/email | Send single email notification (rate limit: 10/sec). | [KB-582e7673-bd66-493e-b511-017708ae9326] | | POST /api/v1/notifications/sms | Send single SMS notification. | [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] | | GET /api/v1/notifications/{notification_id} | Retrieve notification history 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 Requirements ### 4.3.1 Bulk Order Import - The system shall support CSV bulk import for corporate customers, enabling import of 100–10,000 orders per file, to improve operational efficiency and support business processes. [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-94407aa3-d1ac-4455-a68c-265236fefec4], [KB-6ef0a78b-63b6-493a-a7b0-76398d5a2889], [KB-9722c127-de97-4494-bb8d-1d840efa8899] --- ## 4.4 Constraint Requirements ### 4.4.1 Payment Constraints - Maximum payment amount per transaction: 1,000,000 JPY. [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] - Minimum payment amount per transaction: 100 JPY. [KB-8072a75f-d61d-49b1-a859-1be86806c449] - No batch payment processing; payments must be processed individually for each order. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] - Duplicate payments for the same order are rejected. [KB-8072a75f-d61d-49b1-a859-1be86806c449] ### 4.4.2 CSV Import Constraints - Maximum CSV file size: 50MB. [KB-063a89e7-bb79-4435-993b-95ec7b9a9e4e], [KB-2d968f58-3ed8-4207-9d71-0c429c197cb4] - Supported encodings: UTF-8, Shift_JIS. [KB-063a89e7-bb79-4435-993b-95ec7b9a9e4e], [KB-2d968f58-3ed8-4207-9d71-0c429c197cb4] - CSV validation must check column structure, data types, and required fields; errors must be reported per row. [KB-2d968f58-3ed8-4207-9d71-0c429c197cb4] ### 4.4.3 Notification Constraints - Email notifications are sent one per request; rate limit is 10 emails per second. [KB-582e7673-bd66-493e-b511-017708ae9326] - SMS notifications are sent one per request. [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] - Notification templates use Jinja2 syntax; variable substitution is per-notification (no batch rendering optimization). [KB-3133bf0e-2d9b-46e7-9b60-dac1a20281ed] --- ## 4.5 Data Requirements ### 4.5.1 Order Data Model Example response for order creation: ```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} ] } ``` [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4] ### 4.5.2 Payment Data Model Example response for payment creation: ```json { "id": 1, "order_id": 1, "amount": 183100.0, "currency": "JPY", "status": "completed", "payment_method": "credit_card", "transaction_id": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2025-12-01T10:00:00Z", "updated_at": "2025-12-01T10:00:01Z" } ``` [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a] ### 4.5.3 Notification Data Model Example response for email notification: ```json { "id": 1, "order_id": 1, "channel": "email", "template_name": "ORDER_CONFIRMATION", "recipient": "tanaka@example.co.jp", "subject": "ご注文確認 — 注文番号 #1", "body": "田中太郎 様\n\nご注文ありがとうございます。...", "status": "sent", "sent_at": "2025-12-01T10:00:01Z", "created_at": "2025-12-01T10:00:01Z" } ``` [KB-258b5996-5aad-4f5f-acd2-8e458c49f884] --- ## 4.6 Error Handling Requirements - All error responses must follow RFC 7807 Problem Details for HTTP APIs. [KB-6353c73b-fdb1-409c-9679-739f0ab