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)

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

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

# 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