clqms-be/TODO.md

# CLQMS MVP Todo List

> Clinical Laboratory Quality Management System - Minimum Viable Product

## Quick Start: Create Order with Minimal Master Data

You **don't need** all master data finished to create an order. Here's what's actually required:

### Minimum Required (2 Tables)

These are the only tables that need database entries for a minimal setup. System lookups (status, priority, etc.) are handled by the `ValueSet` library using static JSON files in `app/Libraries/Data/`.

```sql
-- 1. Patient (already exists in codebase)
-- Just need at least 1 patient

-- 2. Counter for Order ID
INSERT INTO counter (CounterName, CounterValue) VALUES ('ORDER', 1);
```

### API Endpoints (No Auth Required for Testing)

```bash
# Create demo order (auto-creates patient if needed)
POST /api/demo/order
{
  "PatientID": "PT001",
  "NameFirst": "John",
  "NameLast": "Doe",
  "Gender": "1",
  "Birthdate": "1990-05-15",
  "Priority": "R",
  "OrderingProvider": "Dr. Smith"
}

# List orders
GET /api/demo/orders

# Create order (requires auth)
POST /api/ordertest
{
  "InternalPID": 1,
  "Priority": "R",
  "OrderingProvider": "Dr. Smith"
}

# Update order status
POST /api/ordertest/status
{
  "OrderID": "00250112000001",
  "OrderStatus": "SCH"
}
```

## Core Workflow
Order → Collection → Reception → Preparation → Analysis → Verification → Review → Reporting

---

## Phase 1: Order Management (Immediate Priority)

### 1.1 Order Management
- [x] Complete `OrderTestController` create/update/delete
- [x] Implement order ID generation (LLYYMMDDXXXXX format)
- [x] Implement order comment handling (ordercom table)
- [ ] Implement order attachment handling (orderatt table)
- [x] Add order status tracking (ORD→SCH→ANA→VER→REV→REP)
- [x] Create order test mapping (using patres table)
- [x] Add calculated test parameter auto-selection & Group expansion

## Phase 2: Specimen & Result Management (Later)

### 2.1 Specimen Management
- [ ] Complete `SpecimenController` API
- [ ] Implement specimen ID generation (OrderID + SSS + C)
- [ ] Build specimen collection API (Collection status)
- [ ] Build specimen transport API (In-transport status)
- [ ] Build specimen reception API (Received/Rejected status)
- [ ] Build specimen preparation API (Centrifuge, Aliquot, Pre-treatment)
- [ ] Build specimen storage API (Stored status)
- [ ] Build specimen dispatching API (Dispatch status)
- [ ] Implement specimen condition tracking (HEM, ITC, LIP flags)

### 2.2 Result Management
- [ ] Complete `ResultController` with full CRUD
- [ ] Implement result entry API (numeric, text, valueset, range)
- [ ] Implement result verification workflow (Technical + Clinical)
- [ ] Add reference range validation (numeric, threshold, text, valueset)
- [ ] Implement critical value flagging (threshold-based)
- [ ] Implement result rerun with AspCnt tracking
- [ ] Add result report generation API

### 2.3 Patient Visit
- [ ] Complete `PatVisitController` create/read
- [ ] Implement patient visit to order linking
- [ ] Add admission/discharge/transfer (ADT) tracking
- [ ] Add diagnosis linking (patdiag table)
---

## Phase 3: Instrument Integration (Later)

### 3.1 Edge API
- [ ] Complete `EdgeController` results endpoint
- [ ] Implement edgeres table data handling
- [ ] Implement edgestatus tracking
- [ ] Implement edgeack acknowledgment
- [ ] Build instrument orders endpoint (/api/edge/orders)
- [ ] Build order acknowledgment endpoint (/api/edge/orders/:id/ack)
- [ ] Build status logging endpoint (/api/edge/status)

### 3.2 Test Mapping
- [ ] Implement test mapping CRUD (TestMapModel)
- [ ] Build instrument code to LQMS test mapping
- [ ] Add many-to-one mapping support (e.g., glucose variations)

---

## Phase 4: Quality Management (Should Have)

### 3.1 Quality Control
- [ ] Build QC result entry API
- [ ] Implement QC result storage (calres table)
- [ ] Add Levey-Jennings data preparation endpoints
- [ ] Implement QC validation (2SD auto-validation)
- [ ] Add Sigma score calculation endpoint

### 3.2 Calibration
- [ ] Build calibration result entry API
- [ ] Implement calibration factor tracking
- [ ] Add calibration history endpoint
- [ ] Implement calibration validation

### 3.3 Audit Trail
- [ ] Add audit logging middleware
- [ ] Implement data change tracking (what/who/when/how/where)
- [ ] Build audit query endpoint
- [ ] Add security log endpoints

---

## Phase 4: Master Data (Already Have - Need Completion)

### 4.1 Test Definitions ✅ Existing
- [ ] Test definitions (testdefsite)
- [ ] Technical specs (testdeftech)
- [ ] Calculated tests (testdefcal)
- [ ] Group tests (testdefgrp)
- [ ] Test parameters

### 4.2 Reference Ranges ✅ Existing
- [x] Numeric ranges (refnum)
- [x] Threshold ranges (refthold)
- [x] Text ranges (reftxt)
- [x] Value set ranges (refvset)

### 4.3 Organizations ✅ Existing
- [ ] Sites (SiteController)
- [ ] Departments (DepartmentController)
- [ ] Workstations (WorkstationController)
- [ ] Disciplines (DisciplineController)

### 4.4 Value Sets ✅ Existing
- [ ] Value set definitions (ValueSetDefController)
- [ ] Value set values (ValueSetController)

---

## Phase 5: Inventory & Billing (Nice to Have)

### 5.1 Inventory
- [ ] Build counter management API
- [ ] Implement product catalog endpoints
- [ ] Add reagent tracking
- [ ] Implement consumables usage logging

### 5.2 Billing
- [ ] Add billing account linking
- [ ] Implement tariff selection by service class
- [ ] Build billing export endpoint

---

## Priority Matrix

| Priority | Feature | Controller/Model | Status |
|----------|---------|-----------------|--------|
| P0 | Order CRUD | OrderTestController + OrderTestModel | ✅ Done |
| P0 | Specimen Status | SpecimenController | ⚠️ Needs API |
| P0 | Result Entry | ResultController | ❌ Empty |
| P0 | Result Verification | ResultController | ❌ Empty |
| P1 | Visit Management | PatVisitController | ⚠️ Partial |
| P1 | Instrument Integration | EdgeController | ⚠️ Partial |
| P1 | Reference Range Validation | RefNumModel + API | ⚠️ Need API |
| P2 | QC Results | New Controller | ❌ Not exist |
| P2 | Audit Trail | New Model | ❌ Not exist |
| P3 | Inventory | CounterController | ⚠️ Partial |
| P3 | Billing | New Controller | ❌ Not exist |

---

## Quick Test: Does Order Creation Work?

```bash
# Test 1: Create demo order (no auth required)
curl -X POST http://localhost:8080/api/demo/order \
  -H "Content-Type: application/json" \
  -d '{"NameFirst": "Test", "NameLast": "Patient"}'

# Expected Response:
{
  "status": "success",
  "message": "Demo order created successfully",
  "data": {
    "PatientID": "DEMO1736689600",
    "InternalPID": 1,
    "OrderID": "00250112000001",
    "OrderStatus": "ORD"
  }
}

# Test 2: Update order status
curl -X POST http://localhost:8080/api/ordertest/status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"OrderID": "00250112000001", "OrderStatus": "SCH"}'
```

---

## Success Criteria

### Functional
- [x] Patient registration works
- [ ] Test ordering generates valid OrderID and SID
- [ ] Specimens track through collection → transport → reception → preparation → analysis
- [ ] Results can be entered with reference range validation
- [ ] Results verified through VER → REV → REP workflow
- [ ] Instruments can send results via Edge API

### Non-Functional
- [ ] JWT authentication required for all endpoints
- [ ] Soft delete (DelDate) on all transactions
- [ ] UTC timezone for all datetime fields
- [ ] Audit logging for data changes
- [ ] < 2s response time for standard queries

---

## Current Codebase Status

### Controllers (Need Work)
- [ ] OrderTestController - placeholder code, incomplete
- [ ] ResultController - only validates JWT
- [x] PatientController - complete
- [x] TestsController - complete
- [x] PatVisitController - partial

### Models (Good)
- [x] PatientModel - complete
- [x] TestDef* models - complete
- [x] Ref* models - complete
- [x] ValueSet* models - complete
- [x] SpecimenModel - exists, needs API

### Missing Controllers
- [ ] SpecimenController - need full implementation
- [ ] ResultController - need full implementation
- [ ] QualityControlController - not exist
- [ ] CalibrationController - not exist
- [ ] AuditController - not exist
- [ ] BillingController - not exist