## 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 specifying customer information (name, email) and order items (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 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 → PAID → SHIPPED → DELIVERED.         | P1       |
| FR-006 | The system shall support order cancellation, updating 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-4651de1d-570d-4c49-8a65-ec5b22855797]

### 4.1.2 Payment Service

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

### 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-79cd66a7-f8fb-49eb-8181-2e231c58f49d], [KB-582e7673-bd66-493e-b511-017708ae9326]

### 4.1.4 CSV Import and Bulk Order Processing

| ID            | Requirement                                                                                                                           | Priority |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------|----------|
| FR-BULK-001   | The system shall allow users to upload CSV files for bulk order creation. Maximum file size: 50MB. Supported encodings: UTF-8, Shift_JIS. | P1       |
| FR-BULK-002   | The system shall validate CSV structure, data types, and required fields. Error rows shall be identified and reported.                 | P1       |
| FR-BULK-003   | The system shall create orders in bulk from validated CSV data. Supports 100–10,000 orders.                                           | P1       |
| FR-BULK-004   | The system shall process payments in bulk for created orders. Each order payment is processed individually (no batch payment endpoint). | P1       |
| FR-BULK-005   | The system shall send confirmation emails in bulk to all order recipients after import.                                                | P2       |
| FR-BULK-006   | The system shall display real-time progress tracking of import processing (processed count/total count).                              | P1       |
| FR-BULK-007   | The system shall handle partial failures; successful orders are retained, failed orders are listed for download.                      | P1       |
| FR-BULK-009   | The system shall allow download of a correctly formatted CSV template for import.                                                     | P3       |
| FR-BULK-010   | The system shall allow cancellation of ongoing imports; unprocessed orders are not created.                                           | P3       |

[KB-063a89e7-bb79-4435-993b-95ec7b9a9e4e], [KB-2d968f58-3ed8-4207-9d71-0c429c197cb4], [KB-35c9e00d-f446-4174-be65-d214ecbff895], [KB-89dddd9a-2e13-46e7-99a4-34c3bd37e57], [KB-6aa21c29-11f1-4b6b-b8e8-2c9990900522]

### 4.1.5 API Endpoints

| Endpoint                                 | Description                                                                                      |
|-------------------------------------------|--------------------------------------------------------------------------------------------------|
| POST /api/v1/orders/                      | Create a single order. Bulk/batch creation not supported.                                        |
| GET /api/v1/orders/                       | Retrieve paginated list of orders (skip, limit; default limit=20).                               |
| GET /api/v1/orders/{order_id}             | Retrieve details for a specific order.                                                           |
| PUT /api/v1/orders/{order_id}/status      | Update order status. Setting status to SHIPPED triggers shipment notification.                   |
| DELETE /api/v1/orders/{order_id}          | Cancel order. Triggers refund via Payment Service and cancellation email via Notification Service.|
| POST /api/v1/orders/{order_id}/webhook    | Receive payment status update from Payment Service. Updates order status accordingly.             |
| POST /api/v1/payments/                    | Process payment for a single order. Amount must be between 100 and 1,000,000 JPY.                |
| GET /api/v1/payments/{payment_id}         | Retrieve payment details by payment ID.                                                          |
| GET /api/v1/payments/order/{order_id}     | Retrieve payment for a specific order (1:1 relationship).                                        |
| POST /api/v1/payments/refund              | Process refund for a completed payment.                                                          |
| POST /api/v1/notifications/email          | Send single email notification (rate limit: 10/sec).                                             |
| POST /api/v1/notifications/sms            | Send single SMS notification.                                                                    |
| 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-8072a75f-d61d-49b1-a859-1be86806c449], [KB-582e7673-bd66-493e-b511-017708ae9326], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4], [KB-4d364408-238b-4248-925a-97d5a3446d3c], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-981308db-2c30-4894-ba6b-491bf40b1d24]

## 4.2 Constraints

- Only single order creation, payment, and notification per API request; no batch endpoints for these operations.
- Maximum payment amount per transaction is 1,000,000 JPY.
- Bulk order import requires individual payment processing for each order; no aggregated batch payment endpoint.
- CSV file uploads are limited to 50MB and must be UTF-8 or Shift_JIS encoded.
- Rate limits apply: Notification Service (10 emails/sec), Payment Service (100 req/min per user, 1000 req/min per service).
- Error responses follow RFC 7807 Problem Details for HTTP APIs.

[KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c], [KB-6353c73b-fdb1-409c-9679-739f0ab68585]

## 4.3 Business Requirements

- The system must support operational efficiency for corporate customers by enabling bulk order import via CSV (100–10,000 orders).
- Bulk import must provide progress tracking, partial failure handling, and notification delivery for all successfully imported orders.
- Corporate customers require CSV import to streamline business processes, as current order creation is limited to single orders via REST API or admin interface.

[KB-0300f3b7-a279-4396-bf18-c17f413ebe6d], [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-2b0238e6-fb8b-4c64-bbb0-73de35f73a08], [KB-6ef0a78b-63b6-493a-a7b0-76398d5a2889], [KB-94407aa3-d1ac-4455-a68c-265236fefec4]

## 4.4 Data Requirements

- Order data must include customer name, customer email, item details (product name, quantity, unit price), total amount, currency, and timestamps.
- Notification data must include order ID, channel (email/SMS), template name, recipient, subject, body, status, and timestamps.
- Payment data must include order ID, amount, currency, status, payment method, transaction ID, and timestamps.

[KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4], [KB-258b5996-5aad-4f5f-acd2-8e458c49f884], [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a]

## 4.5 Interface Requirements

- Order Service, Payment Service, and Notification Service must interact via defined REST API endpoints.
- Webhook mechanism is used for Payment Service to notify Order Service of payment status changes.
- Notification Service templates use Jinja2 syntax for variable substitution.

[KB-1a8a8c49-5d2d-4747-b2de-4e95950cdf44], [KB-3133bf0e-2d7b-46bc-ae60-dac1a20281ed]

## 4.6 Performance Requirements

- Bulk order creation (up to 10,000 orders) must be completed within 5 minutes.
- Real-time progress tracking must be available during bulk import.
- Notification delivery must respect rate limits and provide delivery status tracking.

[KB-35c9e00d-f446-4174-be65-d214ecbff895], [KB-0e28e3cb-6977-43b1-ba8e-1ed80f2de11e]

---

[GAP: Missing data for Requirements] — If additional requirements (e.g., security, audit, reporting) are needed, please provide further context.