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

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

# 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

• Complete OrderTestController create/update/delete
• Implement order ID generation (LLYYMMDDXXXXX format)
• Implement order comment handling (ordercom table)
• Implement order attachment handling (orderatt table)
• Add order status tracking (ORD→SCH→ANA→VER→REV→REP)
• Create order test mapping (using patres table)
• 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

• 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