# System Requirements Specification

| Field | Value |
|-------|-------|
| Document ID | SRS-ECOM-001 |
| Version | 1.0 |
| Date | 2025-12-01 |
| Status | Approved |
| Author | Tanaka Taro (Project Manager) |
| Reviewer | Suzuki Ichiro (Technical Director) |

---

## 1. System Overview

The E-Commerce Order Management Platform is a microservice-based system that handles order lifecycle management including creation, payment processing, and customer notifications. The system consists of three independently deployable services communicating via REST APIs.

### 1.1 Service Architecture

| Service | Port | Responsibility |
|---------|------|----------------|
| Order Service | 8000 | Order CRUD, status management, cross-service orchestration |
| Payment Service | 8001 | Payment processing, refunds, amount validation |
| Notification Service | 8002 | Email/SMS notifications via templates |
| Frontend Admin Dashboard | 5173 | Web-based admin UI (React SPA), connects to all 3 services |

### 1.2 Stakeholders

| Stakeholder | Role | Interests |
|-------------|------|-----------|
| Operations Team | Order management | Efficient order processing, status tracking |
| Development Team | System maintenance | Clean APIs, testability, maintainability |
| Customers | End users | Accurate orders, timely notifications |
| Finance Team | Payment oversight | Accurate payment records, refund tracking |

---

## 2. Functional Requirements

### 2.1 Order Service

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-001 | The system shall allow creation of a single order with customer details (name, email) and one or more order items (product name, quantity, unit price). | P1 |
| FR-002 | The system shall calculate total order amount by summing (quantity × unit_price) for all items. | P1 |
| FR-003 | The system shall list orders with pagination (skip, limit parameters). Default limit: 20. | P1 |
| FR-004 | The system shall retrieve a single order by ID, including all order items. | P1 |
| FR-005 | The system shall support order status transitions: PENDING → PAYMENT_PROCESSING → PAID → SHIPPED → DELIVERED. | P1 |
| FR-006 | The system shall support order cancellation, transitioning status to CANCELLED. | P1 |
| FR-007 | Upon order creation, the system shall automatically call Payment Service to process payment. | P1 |
| FR-008 | Upon order creation, the system shall automatically call Notification Service to send a confirmation email. | P1 |
| FR-009 | Upon order cancellation, the system shall request a refund via Payment Service. | P1 |
| FR-010 | Upon order cancellation, the system shall send a cancellation notification via Notification Service. | P1 |

### 2.2 Payment Service

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-011 | The system shall process payment for a single order with amount validation. | P1 |
| FR-012 | The system shall enforce minimum payment amount of 100 JPY per transaction. | P1 |
| FR-013 | The system shall enforce maximum payment amount of 1,000,000 JPY per single transaction. | P1 |
| FR-014 | The system shall maintain a 1:1 relationship between payments and orders (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 |
| FR-017 | The system shall retrieve payment details by payment ID or order ID. | P1 |
| FR-018 | The system shall notify Order Service of payment status changes via webhook callback. | P2 |

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

---

## 3. Non-Functional Requirements

| ID | Category | Requirement | Target |
|----|----------|-------------|--------|
| NFR-001 | Performance | Order creation throughput | 100 orders/minute |
| NFR-002 | Performance | Payment processing latency | < 30 seconds per transaction |
| NFR-003 | Performance | Notification delivery latency | < 5 seconds per notification |
| NFR-004 | Performance | API response time (read operations) | < 200ms P95 |
| NFR-005 | Availability | System uptime | 99.5% |
| NFR-006 | Reliability | Data consistency across services | Eventual consistency |
| NFR-007 | Security | API input validation | All endpoints validate input |
| NFR-008 | Scalability | Notification rate limit | 10 notifications/second |

---

## 4. Current System Limitations

> **IMPORTANT:** The following limitations define the boundaries of the current system. Any feature that requires capabilities beyond these limitations will need architectural changes across multiple services.

| ID | Limitation | Impact Area | Severity |
|----|-----------|-------------|----------|
| LIM-001 | **Order creation is single-entry only.** No bulk or batch order creation capability exists. Orders can only be created one at a time via the REST API. | Order Service | High |
| LIM-002 | **No CSV/file-based order import functionality.** There is no endpoint or mechanism to upload and process order data from files (CSV, Excel, etc.). | Order Service | High |
| LIM-003 | **Payment processing handles one transaction at a time.** No batch payment API exists. Each order requires an individual payment API call. | Payment Service | High |
| LIM-004 | **Notifications are sent individually per order.** No bulk notification capability exists. Each notification requires a separate API call. | Notification Service | Medium |
| LIM-005 | **Cross-service calls are sequential.** Order creation flow (Order → Payment → Notification) executes sequentially. No parallel processing of payment and notification. | All Services | Medium |
| LIM-006 | **No progress tracking for batch operations.** The system has no mechanism to track progress of multi-item operations because no batch operations exist. | All Services | Medium |

### 4.1 Limitation Details

**LIM-001 & LIM-002 — No Bulk Order Import:**
The Order Service database schema has no `batch_id`, `csv_source`, or `bulk_import_group` columns. The `POST /api/v1/orders/` endpoint accepts a single order payload. To process 1,000 orders, a client must make 1,000 individual API calls sequentially.

**LIM-003 — No Batch Payment:**
The Payment Service enforces a unique constraint on `order_id` (1:1 payment-to-order relationship). The maximum amount per single transaction is 1,000,000 JPY. There is no aggregated payment endpoint. Processing 1,000 orders requires 1,000 individual payment calls.

**LIM-004 — No Bulk Notification:**
The Notification Service processes one notification per API call, rate-limited to 10 notifications per second. Sending confirmations for 1,000 orders would take at minimum 100 seconds (1.7 minutes) sequentially.

**LIM-005 — Sequential Processing:**
For each order, the system makes calls in sequence: save order → call payment → call notification. There is no retry mechanism or circuit breaker. If Payment Service is slow, order creation is blocked.

---

## 5. Future Considerations

The following capabilities have been identified as potential future enhancements:

1. **Bulk Order Import from CSV** — Allow enterprise customers to upload CSV files containing 100–10,000 orders for batch processing. This would require changes across all three services (Order, Payment, Notification) and new database schema additions.

2. **Batch Payment Processing** — Aggregate multiple order payments into batch transactions to reduce processing overhead and potentially bypass single-transaction amount limits.

3. **Queue-Based Notification** — Replace synchronous notification sending with an async queue to handle bulk notifications without hitting rate limits.

4. **Progress Tracking Dashboard** — Real-time tracking of batch operation progress including success/failure counts.

> **Note:** These features are in the planning stage. No design documents or implementation stories have been created yet.