## Requirements # 3. Requirements This section defines the functional, interface, data, and constraint requirements for the Order Management, Payment, and Notification subsystems, including CSV bulk import, payment processing, and notification delivery. All requirements are derived strictly from the provided context and comply with ISO-29148 structure. --- ## 3.1 Functional Requirements ### 3.1.1 Order Management | ID | Requirement | Priority | Service | Acceptance Criteria | |---------|------------------------------------------------------------------------------------------------------------------|----------|-----------------|------------------------------------------------------------------| | FR-001 | The system shall allow creation of a single order with customer information (name, email) and order items. | P1 | Order Service | Order is created with specified details. | | FR-002 | The system shall automatically calculate the total order amount as the sum of (quantity × unit price) for items. | P1 | Order Service | Total amount matches itemized calculation. | | FR-003 | The system shall support paginated retrieval of order lists (parameters: skip, limit; default limit: 20). | P1 | Order Service | Orders are listed with correct pagination. | | FR-004 | The system shall retrieve order details, including line items, by order ID. | P1 | Order Service | Order details are returned for valid IDs. | | FR-005 | The system shall support order status transitions: PENDING → PROCESSING → PAID → SHIPPED → DELIVERED. | P1 | Order Service | Status updates follow defined transitions. | | FR-006 | The system shall support order cancellation and update status to CANCELLED. | P1 | Order Service | Cancelled orders are marked as such. | | FR-009 | On order cancellation, the system shall issue a refund request to the Payment Service. | P1 | Order Service | Refund is triggered on cancellation. | | FR-010 | On order cancellation, the system shall send a cancellation notification via Notification Service. | P1 | Order Service | Cancellation email is sent. | **References:** [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4651de1d-570d-4c49-8a65-ec5b22855797], [KB-4287fde1-e2d9-4e31-8f2d-97d5a3446d3c], [KB-981308db-2c30-4894-ba6b-491bf40b1d24] --- ### 3.1.2 CSV Bulk Import | ID | Requirement | Priority | Service | Acceptance Criteria | |---------------|----------------------------------------------------------------------------------------------------------------|----------|-----------------|------------------------------------------------------------------| | 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 | Order Service | File uploads succeed within limits. | | FR-BULK-002 | The system shall validate CSV structure, data types, and required fields. Errors must be reported per row. | P1 | Order Service | Validation results are displayed after upload. | | FR-BULK-003 | The system shall create orders in bulk from validated CSV data. Supports 100–10,000 orders per import. | P1 | Order Service | 10,000 orders created within 5 minutes. | | FR-BULK-004 | The system shall process payments for all created orders individually (no batch payment). | P1 | Payment Service | Each order triggers a single payment API call. | | FR-BULK-005 | The system shall send confirmation emails in bulk for all imported orders. | P2 | Notification Service | All customers receive confirmation emails. | | FR-BULK-006 | The system shall display real-time progress tracking for import (processed/total count). | P1 | Order Service | Progress bar updates in real time. | | FR-BULK-007 | The system shall handle partial failures: successful orders are retained; failed rows are downloadable. | P1 | Order Service | Failed rows are downloadable as error report. | | FR-BULK-009 | The system shall provide a downloadable CSV template in correct format. | P3 | Order Service | Template is downloadable and usable as-is. | | FR-BULK-010 | The system shall allow cancellation of in-progress imports; unprocessed orders are not created. | P2 | Order Service | Cancelled imports do not create further orders. | **References:** [KB-063a89e7-bb79-4435-993b-95ec7b9a9e4e], [KB-2d968f58-3ed8-4207-9d71-0c429c197cb4], [KB-35c9e00d-f446-4174-be65-d214ecbff895], [KB-1b4a5120-e114-4bb2-b423-43e981424088], [KB-0e28e3cb-6977-43b1-ba8e-1ed80f2de11e], [KB-89dddd9a-2e13-46e7-99a4-34c3fff47435], [KB-6aa21c29-11f1-4b6b-b8e8-2c9990900522] --- ### 3.1.3 Payment Processing | ID | Requirement | Priority | Service | Acceptance Criteria | |---------|--------------------------------------------------------------------------------------------------------------|----------|-----------------|------------------------------------------------------| | FR-013 | The system shall enforce a maximum payment amount of 1,000,000 JPY per transaction. | P1 | Payment Service | Payments above this limit are rejected. | | FR-014 | The system shall maintain a 1:1 relationship between order and payment (one payment per order). | P1 | Payment Service | Duplicate payments for the same order are rejected. | | FR-015 | The system shall reject duplicate payment requests for the same order. | P1 | Payment Service | Duplicate requests return error. | | FR-016 | The system shall support refunds for completed payments. | P1 | Payment Service | Refunds are processed and status updated. | **References:** [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6] --- ### 3.1.4 Notification Service | ID | Requirement | Priority | Service | Acceptance Criteria | |---------|---------------------------------------------------------------------------------------------------------------|----------|----------------------|------------------------------------------------------| | FR-019 | The system shall send email notifications for individual orders using templates. | P1 | Notification Service | Email sent per order using template. | | FR-020 | The system shall send SMS notifications for individual orders using templates. | P2 | Notification Service | SMS sent per order using template. | | FR-021 | The system shall support three notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED. | P1 | Notification Service | All templates are available and selectable. | | FR-022 | Templates shall support Jinja2-style variable substitution with Japanese language content. | P1 | Notification Service | Variables are rendered in Japanese content. | | FR-023 | The system shall track notification delivery status (PENDING, SENT, FAILED). | P1 | Notification Service | Status is updated and visible. | | FR-024 | The system shall retrieve notification history by notification ID. | P2 | Notification Service | Notification details are retrievable by ID. | | FR-025 | The system shall retrieve all notifications for a specific order. | P2 | Notification Service | All notifications for an order are retrievable. | **References:** [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-79cd66a7-e187-4f66-b53c-ded850690b2e], [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-4d364408-238b-4248-925a-97d5a3446d3c] --- ## 3.2 Interface Requirements ### 3.2.1 API Endpoints #### Order Service | Endpoint | Method | Description | Notes | |---------------------------------------------|--------|--------------------------------------|-----------------------------------------| | /api/v1/orders/ | POST | Create single order | No bulk/batch endpoint | | /api/v1/orders/ | GET | List orders (paginated: skip, limit) | Default limit: 20 | | /api/v1/orders/{order_id} | GET | Retrieve order details | Returns order with items | | /api/v1/orders/{order_id}/status | PUT | Update order status | SHIPPED triggers shipping notification | | /api/v1/orders/{order_id} | DELETE | Cancel order | Triggers refund and cancellation email | | /api/v1/orders/{order_id}/webhook | POST | Receive payment status update | Single order per webhook | **References:** [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2d-97d5a3446d3c], [KB-69d55b34-e506-4b4e-a043-ef842030f397] #### Payment Service | Endpoint | Method | Description | Notes | |---------------------------------------------|--------|--------------------------------------------|-------------------------------------------| | /api/v1/payments/ | POST | Create payment for single order | Amount: 100–1,000,000 JPY | | /api/v1/payments/{payment_id} | GET | Retrieve payment by payment ID | | | /api/v1/payments/order/{order_id} | GET | Retrieve payment by order ID (1:1) | | | /api/v1/payments/refund | POST | Process refund for completed payment | Requires payment_id and reason | | /api/v1/payments/webhook | POST | Receive external payment gateway callbacks | | **References:** [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3] #### Notification Service | Endpoint | Method | Description | Notes | |---------------------------------------------|--------|----------------------------------------------|----------------------------------------| | /api/v1/notifications/email | POST | Send single email notification | One email per request; rate limit: 10/s| | /api/v1/notifications/sms | POST | Send single SMS notification | One SMS per request | | /api/v1/notifications/{notification_id} | GET | Retrieve notification by ID | | | /api/v1/notifications/order/{order_id} | GET | Retrieve all notifications for an order | | **References:** [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4] --- ## 3.3 Data Requirements - Order data must include customer name, email, itemized products (name, quantity, unit price), total amount, currency, and status. - Payment data must include order_id, amount, currency, payment status, payment method, transaction_id, timestamps. - Notification data must include order_id, channel (email/SMS), template_name, recipient, subject, body, status, sent_at, created_at. - CSV bulk import must support UTF-8 and Shift_JIS encodings, with a maximum file size of 50MB. - Import history must record file name, record count, success/failure count, executor, and timestamp. **References:** [KB-1bfa4181-74da-4372-ba8e-acf6d7aa41c4], [KB-258b5996-5aad-4f5f-acd2-8e458c49f884], [KB-89dddd9a-2e13-46e7-99a4-34c3fff47435] --- ## 3.4 Constraint Requirements - Only single order creation and payment per API call; no batch endpoints for order creation or payment exist. Bulk import is implemented as repeated single-order operations. - Maximum payment per transaction: 1,000,000 JPY. - Each order must have a unique payment (1:1 relationship); duplicate payments are rejected. - CSV import supports 100 to 10,000 orders per file. - All notification template rendering is per-notification; no batch rendering optimization. - Notification Service rate limit: 10 requests/second per endpoint. - Partial failures in bulk import must not affect successful records; failed records are reported and downloadable. - In-progress bulk imports can be cancelled; unprocessed orders are not created. **References:** [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-3133bf0e-2d7b-4bc1-97de-61d50bd37e57], [KB-6aa21c29-11f1-4b6b-b8e8-2c9990900522] --- ## 3.5 Business Requirements - The system must support bulk order import (100–10,000 orders) via CSV to improve operational efficiency for corporate customers. - The current system only supports single order creation via REST API or admin UI; bulk import addresses customer demand for high-volume order processing. - Bulk import, payment, and notification flows must be fully auditable and traceable. **References:** [KB-0300f3b7-a279-4396-bf18-c17f413ebe6d], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08], [KB-5bd83fdc-f7d5-4953-bd1e-e9b287f0bf96] --- ## 3.6 [GAP: Missing data for Requirements] - No requirements for user interface (UI/UX) specifics for the CSV import screen, error display, or progress bar design. - No requirements for authentication, authorization, or audit logging in this context section. - No requirements for localization/internationalization beyond Japanese CSV and notification content. --- **End of Requirements Section**