## Introduction

# Introduction

This document defines the requirements, constraints, and limitations for the current order management system, with a focus on CSV/batch import, order creation, payment processing, and notification handling. The scope includes both business and technical requirements, as well as system-level constraints that impact operational efficiency and scalability.

The order management system currently supports only single-entry order creation via REST API or the administrative user interface. There is no capability for bulk or batch order creation, and no functionality for importing orders from CSV or other file formats. All payment processing is handled on a per-order basis, with no batch payment API available. Similarly, notifications are sent individually for each order, with no bulk notification capability. These limitations have significant implications for organizations that need to process large volumes of orders, as each order requires a separate API call for creation, payment, and notification, resulting in slow throughput for high-volume operations.

The absence of batch processing, bulk import, and parallel execution mechanisms means that all cross-service operations (order creation, payment, notification) are executed sequentially. There is no mechanism for tracking the progress of multi-item operations, and error handling for batch operations is not implemented—if one item in a batch fails, there is no system-level continuation or reporting for the remaining items.

These requirements and constraints are based on the current system architecture and have been validated by business stakeholders and technical teams. Any features requiring capabilities beyond these limitations will necessitate architectural changes across multiple services.

This document is intended for use by development, QA, and operations teams involved in the maintenance, enhancement, or migration of the order management system. It provides a foundation for future system improvements and migration planning.

**References:**
- [KB-146a6a29-932f-485d-96d6-6a92ee610336]
- [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f]
- [KB-05b70fbd-4026-4ac9-b1e2-e21dabe7da5c]
- [KB-0f930ddc-3571-41a3-9aac-3588586dee43]
- [KB-0a7d4d64-4d48-4214-94eb-2f3f278ec66a]
- [KB-150eb89c-77b0-415b-a547-3ed0502eec24]
- [KB-10744011-e9ca-48b5-ac6d-4f9f3627b7e6]
- [KB-04a84995-0820-4319-9d26-c1582821058a]
- [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205]
- [KB-16181d30-2dd3-421e-bab0-939cd85255d2]
- [KB-1603dccf-0e13-426d-a4c3-527af9e69c16]
- [KB-155b5f4a-d232-4166-bb96-ba158f86ceb1]
- [KB-049c5f42-4f53-4566-bbd6-62b438d57b92]

## Getting Started

# 2. Getting Started

## 2.1 System Access Overview

The current order management system is a web-based application with a React single-page frontend and three backend microservices, each exposing REST APIs. All inter-service communication is synchronous REST over HTTP. There is no message broker or asynchronous event bus in use. User authentication is implemented via OAuth 2.0 Resource Server with Azure AD integration. Access to patient and order data is strictly controlled and audited to meet HIPAA and internal security requirements. [KB-050d0be4-11bc-4945-80e4-1f59d3187e45], [KB-0910e88e-c115-4412-a137-d96b5c1a2082], [KB-0667f620-e2f7-4030-8e28-f56315efb7d0]

## 2.2 Key Functional Limitations

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

| Limitation ID | Description                                                                                              | 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   |

[KB-146a6a29-932f-485d-96d6-6a92ee610336], [KB-0a7d4d64-4d48-4214-94eb-2f3f278ec66a], [KB-05b70fbd-4026-4ac9-b1e2-e21dabe7da5c], [KB-0f930ddc-3571-41a3-9aac-3588586dee43], [KB-04a84995-0820-4319-9d26-c1582821058a], [KB-10744011-e9ca-48b5-ac6d-4f9f3627b7e6]

**Important:** There is no UI or API for bulk order import (e.g., CSV upload, drag-and-drop, or batch creation form). All orders must be entered one at a time. [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f], [KB-16181d30-2dd3-421e-bab0-939cd85255d2]

## 2.3 Order Creation Process

To create an order, the following steps are required:

1. Use the single order creation form in the web UI or POST to the order creation endpoint.
2. Each order must specify customer information (name, email) and order details (item name, quantity, unit price).
3. The system automatically calculates the total order amount from the order details.
4. Upon order creation, the system triggers a payment transaction (one per order).
5. After successful payment, a notification is sent to the customer (one per order).

**Note:** All steps are executed sequentially. There is no parallel or batch processing. [KB-0e0f1dd0-0f46-4d13-a092-e3cdc6fdd205], [KB-033639ab-c6f8-4f72-a373-bf76d05dd6cf], [KB-150eb89c-77b0-415b-a547-3ed0502eec24]

## 2.4 Payment and Notification Constraints

- **Payment API:** Only supports one order per transaction. Minimum amount: 100 JPY, maximum: 1,000,000 JPY. There is no batch payment API.
- **Notification API:** Only supports sending one notification per API call. Rate limit: 10 notifications per second. No bulk notification endpoint exists.
- **Cross-Service Processing:** All operations (order creation, payment, notification) are executed in sequence. High-volume operations (e.g., 10,000 orders) will be extremely slow due to these constraints.

[KB-05a9aed3-6a71-4c74-ac19-6bfec293268b], [KB-06c5403a-d177-4525-b247-1d7ae37a86b8], [KB-04a84995-0820-4319-9d26-c1582821058a], [KB-0a7d4d64-4d48-4214-94eb-2f3f278ec66a], [KB-150eb89c-77b0-415b-a547-3ed0502eec24]

## 2.5 Security and Compliance

- All API endpoints require authentication via OAuth 2.0/Azure AD.
- Access is controlled at the method level using @PreAuthorize annotations.
- All PHI (Protected Health Information) is protected according to HIPAA requirements, including audit logging, encryption at rest and in transit, and strict error message handling (no PHI, stack traces, or internal details in production error responses).
- All responses containing PHI include `Cache-Control: no-store` and `Pragma: no-cache` headers.

[KB-0910e88e-c115-4412-a137-d96b5c1a2082], [KB-16e42083-f456-49a3-959d-419cdb9fc31d], [KB-10300d8a-a98a-4726-9be3-3957c2fe7bf4], [KB-140ca7f3-3348-4419-b06b-89561882a35e]

## 2.6 User Interface Notes

- The order management UI displays an amber warning banner indicating that CSV import is not available.
- The CSV Import button is disabled and labeled “CSVインポート（未実装）” (CSV Import [Not Implemented]).
- Orders can be searched and filtered client-side, but all creation and management is single-order only.

[KB-16181d30-2dd3-421e-bab0-939cd85255d2], [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f]

---

**Summary:**  
The current system supports only single-order entry and processing. There is no support for bulk order import, batch payment, or bulk notification. All operations are sequential and strictly controlled for security and compliance. For high-volume use cases, significant architectural changes will be required.

## Build and Test

# 6. Build and Test

## 6.1 Build Process

The system is built using a microservices architecture, primarily leveraging Spring Boot applications deployed on ECS Fargate clusters. Key backend components include the Order Service, Payment Service, and Notification Service, each exposing RESTful APIs for inter-service communication. The build process involves:

- Source code management and CI/CD pipeline integration (details not specified in the provided context)
- Database schema migrations managed via Flyway for PostgreSQL targets [KB-15aa67c7-0ace-4d42-8c36-b17874f98d95]
- Application packaging and deployment to AWS ECS Fargate clusters [KB-0e90d327-2678-405f-b35a-294b5435dc66]

**Note:** The legacy system is based on Visual Basic 6.0 and SQL Server 2012, while the target system uses Spring Boot, PostgreSQL 16, and modern security controls [KB-17a58f06-2387-412d-bf37-2f4d751e1d7e].

## 6.2 Test Strategy

Testing is performed at multiple levels to ensure compliance, reliability, and performance:

### 6.2.1 Unit and Integration Testing

- **Spring Boot service:** Must achieve ≥80% line coverage with unit tests [KB-0a1640fc-f63e-4c6b-8191-220e34d8af3f]
- **Integration tests:** Must pass against PostgreSQL [KB-0a1640fc-f63e-4c6b-8191-220e34d8af3f]
- **Security tests:** Authentication, authorization, and input validation are required [KB-0a1640fc-f63e-4c6b-8191-220e34d8af3f]

### 6.2.2 System and Acceptance Testing

- **User Acceptance Testing (UAT):** Conducted in phases by end users (front desk, billing staff, dentists, hygienists, office managers) with planned durations per module [KB-169a3eb6-41b7-4fce-a195-bdee1db5c1dd]
- **Parallel Run:** Both legacy and new systems are operated simultaneously for at least two weeks; comparison reports must show no critical discrepancies [KB-05e90e5d-09da-4f67-85af-8f2be11cd2ce]
- **Data Migration Verification:** Includes record count and checksum validation, as well as financial and clinical record reconciliation [KB-05e90e5d-09da-4f67-85af-8f2be11cd2ce], [KB-0368630b-7eb5-445e-aa3b-de044dd2e57a], [KB-092b662f-1233-4421-8d2d-ae9705639cfc]

### 6.2.3 Performance Testing

- **Performance requirements:** Must meet or exceed legacy baselines for response time, throughput, and system availability [KB-0a1640fc-f63e-4c6b-8191-220e34d8af3f], [KB-0d9e59c7-0414-46c2-b302-2f4cbc1e9e88]
- **API response times:** Measured at various percentiles (p50, p95, p99) with targets defined [KB-0d9e59c7-0414-46c2-b302-2f4cbc1e9e88]

### 6.2.4 Security and Compliance Testing

- **PHI audit logging:** Must be implemented and verified [KB-0a1640fc-f63e-4c6b-8191-220e34d8af3f]
- **Access control parity:** Checked to ensure no privilege escalation during migration [KB-1554a441-9086-4371-85f6-cb4d7472ee1b]
- **Audit trail continuity:** Ensured between legacy and new system logs [KB-1554a441-9086-4371-85f6-cb4d7472ee1b]
- **De-identification:** All test/dev environments must use de-identified data per Safe Harbor standards [KB-03f9d790-a1e6-46b9-8aeb-0fc45505be6a]
- **Security review:** Code review by a senior developer and a dedicated security review are required [KB-0a1640fc-f63e-4c6b-8191-220e34d8af3f]

### 6.2.5 Accessibility Testing

- **Accessibility compliance:** Verified to meet WCAG 2.1 AA standards for the React UI [KB-0a1640fc-f63e-4c6b-8191-220e34d8af3f]

### 6.2.6 Rollback and Disaster Recovery Testing

- **Rollback plan:** Must be tested, including blue/green deployment rollback, database backup restoration, and full migration rollback in staging [KB-0e7db777-ce75-42c0-aac9-256614f5e8a4], [KB-04c5b64b-0ba0-40cd-864f-395e17b12504]
- **Disaster recovery:** Regular DR tests are scheduled for backup restoration, read replica promotion, and full failover [KB-0ad2d5a6-1c32-426e-b9db-8c8bd6d32e36]

#### Rollback Testing Schedule

| Test                              | Frequency     | Last Test   | Next Test   | Result   |
|-----------------------------------|---------------|-------------|-------------|----------|
| Blue/green deployment rollback    | Monthly       | 2025-07-15  | 2025-08-15  | Pass     |
| Database backup restoration       | Monthly       | 2025-07-15  | 2025-08-15  | Pass     |
| Full migration rollback (staging) | Quarterly     | 2025-06-01  | 2025-09-01  | Pass     |
| Service-level rollback            | Monthly       | 2025-07-15  | 2025-08-15  | Pass     |

[KB-0e7db777-ce75-42c0-aac9-256614f5e8a4]

## 6.3 Test Completion Criteria

- All automated and manual tests must pass with no critical or high-severity defects open.
- Data migration must be verified by record count, checksum, and financial/clinical reconciliation.
- UAT must be completed and signed off by designated user groups.
- Performance, security, and accessibility requirements must be met or exceeded.
- Rollback and disaster recovery procedures must be validated in the target environment.
- All compliance checks (audit, access control, de-identification) must be documented and passed.

## 6.4 Outstanding Gaps

[GAP: Missing data for Build and Test] if additional details on CI/CD pipeline, specific test tools, or build automation are required.

---

**References:**  
[KB-0a1640fc-f63e-4c6b-8191-220e34d8af3f]  
[KB-05e90e5d-09da-4f67-85af-8f2be11cd2ce]  
[KB-0368630b-7eb5-445e-aa3b-de044dd2e57a]  
[KB-092b662f-2b03-418b-8931-ae9705639cfc]  
[KB-0e7db777-ce75-42c0-aac9-256614f5e8a4]  
[KB-04c5b64b-0ba0-40cd-864f-395e17b12504]  
[KB-0ad2d5a6-1c32-426e-b9db-8c8bd6d32e36]  
[KB-1554a441-9086-4371-85f6-cb4d7472ee1b]  
[KB-03f9d790-a1e6-46b9-8aeb-0fc45505be6a]  
[KB-169a3eb6-41b7-4fce-a195-bdee1db5c1dd]  
[KB-0d9e59c7-0414-46c2-b302-2f4cbc1e9e88]  
[KB-17a58f06-2387-412d-bf37-2f4d751e1d7e]  
[KB-15aa67c7-0ace-4d42-8c36-b17874f98d95]

## Contribute

# Contribute

## System Limitations and Constraints

The current system architecture imposes significant constraints on bulk order processing, payment, and notification capabilities. These limitations directly impact the ability to contribute enhancements or new features related to batch operations. The following table summarizes the key constraints:

| 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     |

*Source: [KB-146a6a29-932f-485d-96d6-6a92ee610336], [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f], [KB-0a7d4d64-4d48-4214-94eb-2f3f278ec66a], [KB-05b70fbd-4026-4ac9-b1e2-e21dabe7da5c]*

## Architectural and Data Model Barriers to Contribution

- **No Bulk Import UI or API:** There is no user interface or backend endpoint for uploading or importing orders in bulk (e.g., via CSV). Any contribution requiring batch creation must address this fundamental gap ([KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f], [KB-16181d30-2dd3-421e-bab0-939cd85255d2]).
- **Schema Limitations:** The orders table lacks fields such as `batch_id`, `csv_source`, or `bulk_import_group`, making it impossible to track or group orders as part of a batch import. There is no mapping from CSV row numbers to imported records ([KB-0f930ddc-1f3a-4014-a015-49fe1808f8d8], [KB-02c65582-456a-4ffe-8f7b-7d37af08e656]).
- **1:1 Payment–Order Constraint:** The payments table enforces a unique constraint on `order_id`, preventing grouping of multiple orders under a single payment transaction ([KB-11739ab0-b209-41e4-b73e-7d7e0c4338b2]).
- **API Rate Limits:** Notification and payment APIs are rate-limited (e.g., 10 requests/second), and each API call processes only a single order or notification. Bulk operations would require significant time for large datasets (e.g., 10,000 orders require 10,000 API calls, taking at least 17 minutes for notifications alone) ([KB-04a84995-0820-4319-bd26-c1582821058a], [KB-06c5403a-d177-4525-b247-1d7ae37a86b8], [KB-150eb89c-77b0-415b-a547-3ed0502eec24]).
- **No Parallel Processing:** All cross-service calls (Order → Payment → Notification) are executed sequentially, further increasing processing time for bulk operations ([KB-033639ab-c6f8-4f72-a373-bf76d05dd6cf], [KB-150eb89c-77b0-415b-a547-3ed0502eec24]).
- **No Retry or Circuit Breaker:** Failures in cross-service calls are not retried, and there is no circuit breaker mechanism. This increases the risk of partial failures during attempted bulk operations ([KB-01305cb3-d331-4b4b-ba02-69ada467b41d], [KB-150eb89c-77b0-415b-a547-3ed0502eec24]).

## Impact on Feature Contributions

Due to these constraints, contributors must be aware that:

- **Bulk order import, batch payment, and mass notification features cannot be implemented without major architectural changes** across multiple services and database schemas.
- **Any attempt to contribute such features must include proposals for:**
  - Schema extensions (e.g., batch/group identifiers)
  - New or revised API endpoints for batch operations
  - UI/UX changes to support file upload and batch progress tracking
  - Enhanced error handling and partial failure management
  - Parallel processing and rate limit management strategies

## Contribution Guidance

- **Scope of Contribution:** Contributions should align with the current system boundaries. Features requiring batch or bulk capabilities must be proposed as architectural enhancements, not minor feature additions.
- **Backward Compatibility:** Any schema or API changes must consider backward compatibility and migration impact.
- **Documentation:** All contributions must be thoroughly documented, including rationale for architectural changes, migration plans, and operational impacts.

## [GAP: Missing data for Contribute]  
If further details on contribution processes, code review, or approval workflows are required, please refer to the system’s contribution policy documentation or contact the architecture team.

---

**References:**  
- [KB-146a6a29-932f-485d-96d6-6a92ee610336]  
- [KB-0a36efdc-f63e-4c6b-8191-220e34d8af3f]  
- [KB-0a7d4d64-4d48-4214-94eb-2f3f278ec66a]  
- [KB-05b70fbd-4026-4ac9-b1e2-e21dabe7da5c]  
- [KB-0f930ddc-1f3a-4014-a015-49fe1808f8d8]  
- [KB-02c65582-456a-4ffe-8f7b-7d37af08e656]  
- [KB-11739ab0-b209-41e4-b73e-7d7e0c4338b2]  
- [KB-04a84995-0820-4319-bd26-c1582821058a]  
- [KB-06c5403a-d177-4525-b247-1d7ae37a86b8]  
- [KB-033639ab-c6f8-4f72-a373-bf76d05dd6cf]  
- [KB-01305cb3-d331-4b4b-ba02-69ada467b41d]  
- [KB-150eb89c-77b0-415b-a547-3ed0502eec24]  
- [KB-16181d30-2dd3-421e-bab0-939cd85255d2]