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 (4 Tables)

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

-- 2. Order Status Values (VSetID=11)
INSERT INTO valueset (VID, VSetID, VValue, VDesc, VOrder) VALUES
(1, 11, 'ORD', 'Ordered', 1),
(2, 11, 'SCH', 'Scheduled', 2),
(3, 11, 'ANA', 'Analysis', 3),
(4, 11, 'VER', 'Verified', 4),
(5, 11, 'REV', 'Reviewed', 5),
(6, 11, 'REP', 'Reported', 6);

-- 3. Priority Values (VSetID=10)
INSERT INTO valueset (VID, VSetID, VValue, VDesc, VOrder) VALUES
(1, 10, 'S', 'Stat', 1),
(2, 10, 'R', 'Routine', 2),
(3, 10, 'A', 'ASAP', 3);

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

-- Run seeder: php spark db:seed MinimalMasterDataSeeder
```

### 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: Core Lab Workflow (Must Have)

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

### 1.2 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)

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

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

---

## Phase 2: Instrument Integration (Must Have)

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

### 2.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 3: 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
- [ ] Numeric ranges (refnum)
- [ ] Threshold ranges (refthold)
- [ ] Text ranges (reftxt)
- [ ] 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
- 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
- ✅ PatientController - complete
- ✅ TestsController - complete
- ✅ PatVisitController - partial

### Models (Good)
- ✅ PatientModel - complete
- ✅ TestDef* models - complete
- ✅ Ref* models - complete
- ✅ ValueSet* models - complete
- ✅ 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