## Requirements

# 4. Requirements

## 4.1 Functional Requirements

### 4.1.1 Order Management

- The system shall support creation of a single order per API request. Bulk or batch order creation is not supported in the current implementation.  
  [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]

- Each order must include customer information (name, email), order details (product name, quantity, unit price), and currency.  
  [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]

- The total order amount shall be automatically calculated as the sum of (quantity × unit price) for all items.  
  [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-86e313b9-691a-4830-b560-a2097e138f34]

- The system shall provide paginated order listing (parameters: skip, limit; default limit=20).  
  [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-b5c3f64f00add]

- The system shall allow retrieval of order details by order ID, including line items.  
  [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f], [KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9]

- The system shall support order status transitions: PENDING → PROCESSING → PAID → SHIPPED → DELIVERED.  
  [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f]

- The system shall support order cancellation, updating the status to CANCELLED and triggering refund and notification workflows.  
  [KB-55d6e023-2c8e-49db-9409-68b9e9ed721f], [KB-4651de1d-570d-4c49-8a65-ec5b22855797], [KB-981308db-2c30-4894-ba6b-491bf40b1d24]

### 4.1.2 Payment Processing

- Payment processing is supported for a single order per API request. Batch payment processing is not supported.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-8ca26148-03e1-4184-a736-624e14448df9], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]

- The payment amount must be between 100 JPY and 1,000,000 JPY per transaction.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3]

- Each order can have only one payment (1:1 relationship). Duplicate payment requests for the same order are rejected.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6]

- Refund processing is supported for completed payments, triggered by order cancellation.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-981308db-2c30-4894-ba6b-491bf40b1d24]

- Payment Service notifies Order Service of payment status via webhook (single order callback, no batch webhook).  
  [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6], [KB-69d55b34-e506-4b4e-a043-ef842030f397]

### 4.1.3 Notification Service

- The system shall send email notifications for individual orders using templates.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-582e7673-bd66-493e-b511-017708ae9326]

- The system shall send SMS notifications for individual orders using templates.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4]

- The system shall support three notification templates: ORDER_CONFIRMATION, ORDER_SHIPPED, ORDER_CANCELLED.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]

- Templates shall use Jinja2-style variable substitution with Japanese language content.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-3133bf0e-2d7d-9e36-c8548c037b2c]

- The system shall track notification delivery status (PENDING, SENT, FAILED).  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8]

- The system shall retrieve notification history by notification ID and for a specific order.  
  [KB-6155f440-0799-44eb-851f-9a5b81fbbcf8], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4]

### 4.1.4 CSV Import (Bulk Order)

- [GAP: Missing data for Requirements]  
  *Note: The provided context describes business demand and operational impact for bulk CSV import (100–10,000 orders), but does not specify functional requirements for CSV upload, validation, or bulk order creation endpoints.*

## 4.2 Constraint Requirements

### 4.2.1 Payment Constraints

- Maximum payment amount per transaction is 1,000,000 JPY.  
  [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-8072a75f-d61d-49b1-a859-1be86806c449]

- Minimum payment amount per transaction is 100 JPY.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449]

- Batch payment processing is not supported; each order must be paid individually.  
  [KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-564ae239-84b1-4ef2-bb04-b7e829eb53b6]

### 4.2.2 Order Constraints

- Only one payment per order is allowed; duplicate payment requests are rejected.  
  [KB-299da2e5-721b-4ab1-9bb0-cd2d0f03c8c6], [KB-8072a75f-d61d-49b1-a859-1be86806c449]

## 4.3 Interface Requirements

### 4.3.1 Order Service API

| Endpoint                                  | Description                                        |
|--------------------------------------------|----------------------------------------------------|
| POST /api/v1/orders/                       | Create 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; triggers shipping notification|
| DELETE /api/v1/orders/{order_id}           | Cancel order; triggers refund and cancellation email|
| POST /api/v1/orders/{order_id}/webhook     | Receive payment status update (single order only)  |

[KB-459cbd85-fb6b-4a7e-8a36-e5f711cac6b9], [KB-4287fde1-e2d9-4e31-8f2f-b5c3f64f00add], [KB-981308db-2c30-4894-ba6b-491bf40b1d24]

### 4.3.2 Payment Service API

| Endpoint                                  | Description                                        |
|--------------------------------------------|----------------------------------------------------|
| POST /api/v1/payments/                     | Process payment for single order                  |
| GET /api/v1/payments/{payment_id}          | Retrieve payment details                          |
| GET /api/v1/payments/order/{order_id}      | Retrieve payment for specific order (1:1)         |
| POST /api/v1/payments/refund               | Process refund for completed payment              |

[KB-8072a75f-d61d-49b1-a859-1be86806c449], [KB-36050440-5a8a-4389-8690-8fd0a46f5cd3]

### 4.3.3 Notification Service API

| Endpoint                                  | Description                                        |
|--------------------------------------------|----------------------------------------------------|
| POST /api/v1/notifications/email           | Send email notification for single order           |
| POST /api/v1/notifications/sms             | Send SMS notification for single order             |
| GET /api/v1/notifications/{notification_id}| Retrieve notification details                     |
| GET /api/v1/notifications/order/{order_id} | Retrieve all notifications for an order            |

[KB-582e7673-bd66-493e-b511-017708ae9326], [KB-2414677b-6e22-47f5-917c-2ed718d86fd4]

## 4.4 Data Requirements

- Order data must include customer name, customer email, items (product name, quantity, unit price), currency, total amount, status, timestamps (created_at, updated_at).  
  [KB-1bfa4181-74da-4372-ba8f-acf6d7aa41c4], [KB-4c9591c9-34d5-42b1-a0e2-1de20131159c]

- Payment data must include order_id, amount, currency, status, payment method, transaction_id, timestamps.  
  [KB-90c1a181-8f6a-4efe-be94-d7a6c0e37f5a]

- Notification data must include order_id, channel (email/SMS), template_name, recipient, subject, body, status, sent_at, created_at.  
  [KB-258b5996-5aad-4f5f-acd2-8e458c49f884]

## 4.5 Business Requirements

- The system must improve operational efficiency for corporate customers by supporting high-volume order processing.  
  [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1], [KB-1603dccf-0e13-426d-a4c3-527af9e69c16], [KB-2183809f-cfa9-4b0b-a30d-320f78a4f161], [KB-94407aa3-d1ac-4455-a68c-265236fefec4], [KB-6ef0a78b-63b6-493a-a7b0-76398d5a2889]

- [GAP: Missing data for Requirements]  
  *Note: Bulk CSV import requirements are referenced as a business need but not specified in technical detail.*

---

**End of Requirements Section**