## Requirements

# 4. Requirements

## 4.1 Functional Requirements

### 4.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 each item. | P1       |
| FR-003 | The system shall support paginated retrieval of order lists using skip and limit parameters.                   | P1       |
| FR-004 | The system shall allow retrieval of order details (including line 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 and update the 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       |

[KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-4651de1d-570d-4c49-8a65-ec5b22855797]

### 4.1.2 Payment Service

| ID     | Requirement                                                                                                    | Priority |
|--------|---------------------------------------------------------------------------------------------------------------|----------|
| FR-013 | The system shall enforce a maximum limit of 1,000,000 JPY per single transaction.                             | P1       |
| FR-014 | The system shall maintain a 1:1 relationship between payment and order (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       |

[KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a], [KB-36050440-5a8a-4389-8690-8e458c49f884], [KB-186b33d7-f985-455b-8117-0cd019912510], [KB-981308db-2c30-4a19-ac30-457c4c49753b]

### 4.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       |

[KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c], [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-1c5832cc-4e41-483e-9898-60c735170444], [KB-258b5996-5aad-4f5f-acd2-8e458c49f884], [KB-4d364408-238b-4248-925a-97d5a3446d3c]

### 4.1.4 Bulk Order Import (CSV)

| ID            | Requirement                                                                                              | Priority | Impacted Service      | Acceptance Criteria                                         |
|---------------|---------------------------------------------------------------------------------------------------------|----------|----------------------|------------------------------------------------------------|
| FR-BULK-001   | The system shall allow users to upload CSV files. Max file size: 50MB. Supported encodings: UTF-8, Shift_JIS. | P1       | Order Service        | Upload succeeds if file is valid.                          |
| 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 shown 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 in bulk for created orders.                                            | P1       | Payment Service      | All payments processed individually; partial failures handled. |
| FR-BULK-005   | The system shall send confirmation emails in bulk for imported orders.                                   | P2       | Notification Service | Confirmation emails sent to all customers.                 |
| FR-BULK-006   | The system shall display real-time progress tracking for import processing (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 orders downloadable.    | P1       | Order Service        | Failed order list available for download.                  |
| FR-BULK-009   | The system shall allow download of a correctly formatted CSV template.                                   | P3       | Order Service        | Template CSV downloadable and usable as-is.                |
| FR-BULK-010   | The system shall allow cancellation of ongoing imports; unprocessed orders are not created.              | P2       | Order Service        | Import can be cancelled; only processed orders created.    |

[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-34c3bd37e57], [KB-6aa21c29-11f1-4b6b-b8e8-2c9990900522]

### 4.1.5 API Endpoints and Integration

| Endpoint                                      | Description                                                                   |
|-----------------------------------------------|-------------------------------------------------------------------------------|
| POST /api/v1/orders/                          | Create single order (no batch creation).                                      |
| GET /api/v1/orders/                           | List orders with pagination (skip, limit; default limit=20).                  |
| GET /api/v1/orders/{order_id}                 | Retrieve order details by ID.                                                 |
| PUT /api/v1/orders/{order_id}/status          | Update order status; SHIPPED triggers shipment notification.                  |
| DELETE /api/v1/orders/{order_id}              | Cancel order; triggers refund and cancellation notification.                   |
| POST /api/v1/orders/{order_id}/webhook        | Receive payment status update from Payment Service.                            |
| POST /api/v1/payments/                        | Create payment for single order; validates amount and uniqueness.              |
| GET /api/v1/payments/{payment_id}             | Retrieve payment details by payment ID.                                        |
| GET /api/v1/payments/order/{order_id}         | Retrieve payment details for specific order.                                   |
| POST /api/v1/payments/refund                  | Process refund for completed payment.                                          |
| POST /api/v1/notifications/email              | Send email notification for single order; rate limit: 10/sec.                  |
| POST /api/v1/notifications/sms                | Send SMS notification for single order.                                        |
| GET /api/v1/notifications/{notification_id}   | Retrieve notification history by notification ID.                              |
| GET /api/v1/notifications/order/{order_id}    | Retrieve all notifications for a specific order.                               |

[KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-5c3f64f00add], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4], [KB-4d364408-238b-4248-925a-97d5a3446d3c]

## 4.2 Constraints

- Only single order creation, payment, and notification per API request; batch/bulk endpoints are not supported for these operations. [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], [KB-8072a75f-d61d-49b1-a859-1be86806c449]
- Duplicate payments for the same order are rejected. [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3]
- CSV bulk import supports 100–10,000 orders per file; max file size 50MB; UTF-8 and Shift_JIS encoding only. [KB-063a89e7-bb79-4435-993b-95ec7b9a9e4e], [KB-2d968f58-3ed8-4207-9d71-0c429c197cb4]
- Bulk payment processing executes individual payment API calls for each order; no aggregate/batch payment endpoint exists. [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]
- Notification Service rate limit: 10 emails per second. [KB-582e7673-bd66-493e-b511-017708ae9326]
- Template rendering uses Jinja2 syntax; rendering is performed per-notification. [KB-3133bf0e-2d7c-4477-9e36-c8548c037b2c]

## 4.3 Business Requirements

- The system must support operational efficiency for corporate customers by enabling bulk order import via CSV (100–10,000 orders). [KB-0300f3b7-a279-4396-bf18-c17f413ebe6d], [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-2183809f-cfa9-4b0b-a30d-320f78a4f161], [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08], [KB-5bd83fdc-f7d5-4953-bd1e-e9b287f0bf96], [KB-9722c127-de97-4494-bb8d-1d840efa8899], [KB-94407aa3-d1ac-4455-a68c-265236fefec4], [KB-2b07b017-3e2f-47a4-9b03-d2be4a0e5644], [KB-2708f598-e5da-4cca-91f0-fd3d267de542], [KB-5a963d29-d4ed-4859-ba71-d355620aa5bc], [KB-1ac0c309-d977-46d8-9523-c7d212164f65]
- Bulk import must improve workflow and business process for corporate clients. [KB-0300f3b7-a279-4396-bf18-c17f413ebe6d], [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1]

## 4.4 Data Requirements

- CSV import must validate required fields, data types, and report errors per row. [KB-2d968f58-3ed8-4207-9d71-0c429c197cb4], [KB-35c9e00d-f446-4174-be65-d214ecbff895]
- Order, payment, and notification data models must support retrieval by unique identifiers. [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a], [KB-258b5996-5aad-4f5f-acd2-8e458c49f884]

## 4.5 Interface Requirements

- All API endpoints must conform to single-entity processing per request (no batch endpoints for order, payment, or notification creation). [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]
- Bulk import endpoints must support CSV upload, validation, progress tracking, and partial failure handling. [KB-063a89e7-bb79-4435-993b-95ec7b9a9e4e], [KB-0e28e3cb-6977-43b1-ba8e-1ed80f2de11e], [KB-35c9e00d-f446-4174-be65-d214ecbff895]

## 4.6 Performance Requirements

- Bulk order creation (up to 10,000 orders) must complete within 5 minutes. [KB-35c9e00d-f446-4174-be65-d214ecbff895]
- Real-time progress tracking must be provided for bulk import operations. [KB-0e28e3cb-6977-43b1-ba8e-1ed80f2de11e]

## 4.7 Usability Requirements

- CSV template must be downloadable and usable as-is for bulk import. [KB-89dddd9a-2e13-46e7-99a4-34c3bd37e57], [KB-6aa21c29-11f1-4b6b-b8e8-2c9990900522]
- Failed orders during bulk import must be downloadable for review and correction. [KB-0e28e3cb-6977-43b1-ba8e-1ed80f2de11e], [KB-35c9e00d-f446-4174-be65-d214ecbff895]

---

[GAP: Missing data for Requirements] — If further requirements are needed (e.g., non-functional, regulatory, or additional business rules), please provide additional context.