clqms-be/TODO.md

CLQMS REST API Development Checklist

Note: This checklist covers ONLY the REST API backend. UI/UX implementation is handled separately in the frontend project (clqms01-fe).

Legend

• DONE - Implemented and functional
• TODO - Not yet implemented
• [~] PARTIAL - Partially implemented

---

Phase 1: Core Infrastructure ✅ DONE

1.1 Base Framework

• BaseController with ResponseTrait
• BaseModel with auto UTC normalization
• Validation system with custom rules
• JWT authentication system
• CORS and security headers configuration
• Database migration system

1.2 Authentication & Security

• User login/logout (AuthController, AuthV2Controller)
• JWT token generation and validation
• Password change functionality
• Auth check endpoints
• Role-based access control (RBAC) preparation

---

Phase 2: Organization Management ✅ DONE

2.1 Account Management

• Account CRUD API (/api/organization/account)
• Account listing and search
• Parent-child Account relationships

2.2 Site Management

• Site CRUD API (/api/organization/site)
• SiteCode generation support
• Site type management (PHL, GL, PL)

2.3 Department Management

• Department CRUD API (/api/organization/department)
• Department-Discipline linking

2.4 Discipline Management

• Discipline CRUD API (/api/organization/discipline)
• Discipline hierarchy support

2.5 Workstation Management

• Workstation CRUD API (/api/organization/workstation)
• Workstation type management (primary/secondary)
• Workstation linking support

---

Phase 3: Personnel/Contact Management ✅ DONE

3.1 Contact Management

• Contact CRUD API (/api/contact)
• ContactDetail model (for site-specific roles)
• Patient-Contact association

3.2 Occupation Management

• Occupation CRUD API (/api/occupation)

3.3 Medical Specialty

• MedicalSpecialty CRUD API (/api/medicalspecialty)

---

Phase 4: Patient Management ✅ DONE

4.1 Patient Core

• Patient CRUD API (/api/patient)
• Patient search and filtering
• Patient identifier management (PatIdtModel)
• Patient comments (PatComModel)
• Patient attachments (PatAttModel)
• Patient check endpoint

4.2 Patient Visit (ADT)

• PatientVisit CRUD API (/api/patvisit)
• Get visits by patient
• PatVisitADT CRUD (/api/patvisitadt)
• Get ADT by visit
• Admission workflow (A01)
• Transfer workflow (A02)
• Discharge workflow (A03)
• Cancel admission/discharge

---

Phase 5: Location Management ✅ DONE

5.1 Location

• Location CRUD API (/api/location)
• Location hierarchy support

5.2 Area/Geography

• AreaGeo API (/api/areageo)
• Province listing
• City listing

---

Phase 6: Specimen Management ✅ DONE

6.1 Specimen Core

• Specimen CRUD API (/api/specimen)
• SID generation support

6.2 Container Management

• ContainerDef CRUD API (/api/specimen/container, /api/specimen/containerdef)

6.3 Specimen Workflow

• SpecimenPrep CRUD API (/api/specimen/prep)
• SpecimenStatus CRUD API (/api/specimen/status)
• SpecimenCollection CRUD API (/api/specimen/collection)

---

Phase 7: Test Management ✅ DONE

7.1 Test Definitions

• Tests CRUD API (/api/tests)
• Test mapping API (/api/test/testmap)
• Reference Range nested in Tests (RefNum, RefTxt via POST/PUT body)
• Test profile/group management
• Test discipline mapping

7.2 Test Ordering

• OrderTest CRUD API (/api/ordertest)
• Order status update endpoint
• Demo order creation (/api/demo/order)

7.3 Reference Range (Nested in Tests)

• RefNum model and controller integration (saveRefNumRanges())
• RefTxt model and controller integration (saveRefTxtRanges())
• Age range validation
• Gender-based reference ranges
• Text-based result interpretation
• Threshold (RefTHold) support
• ValueSet (RefVSet) support

Note: Reference ranges are managed as nested data within Tests API. POST/PUT /api/tests includes refRanges array in request body.

---

Phase 8: Result Management ✅ PARTIAL

8.1 Result Core

• Result listing endpoint (/api/result)
• [~] Result entry (manual)
• Result validation workflow
• Result flagging (H/L/A)
• Result correction workflow

8.2 Result ValueSets

• ResultValueSet CRUD API (/api/result/valueset)

---

Phase 9: ValueSet Management ✅ DONE

9.1 File-based ValueSets

• ValueSet listing (/api/valueset)
• Specific value set retrieval (/api/valueset/{type})
• ValueSet refresh endpoint

9.2 Database ValueSets

• ValueSet items CRUD (/api/valueset/user/items)
• ValueSet definitions CRUD (/api/valueset/user/def)

---

Phase 10: Infrastructure & Support ✅ DONE

10.1 Counter Management

• Counter CRUD API (/api/counter)

10.2 Edge Integration (Instrument)

• Edge results endpoint (/api/edge/results)
• Edge orders retrieval (/api/edge/orders)
• Order acknowledgment (/api/edge/orders/{id}/ack)
• Status update endpoint (/api/edge/status)

---

Phase 11: Missing Features ⏳ TODO

11.1 Equipment Management

• ProductCatalog CRUD
• ProductCatalogExt CRUD
• ProductExt (Equipment) CRUD
• Equipment lifecycle tracking (installation, maintenance, decommissioning)
• Equipment-instrument mapping

11.2 Calibration Management

• Calibrator CRUD
• Calibration results API
• Calibration factor tracking
• Calibration validation endpoints
• Cumulative calibration view

11.3 Quality Control (QC) Management

• QC material CRUD
• QC results API
• Levey-Jennings data endpoints
• QC validation workflow
• Westgard rules implementation

11.4 Inventory Management

• Inventory receiving API
• Consumables tracking endpoints
• Stock monitoring API
• Expiry date alerts

11.6 Audit Trail

• Patient audit log API (patreglog)
• Visit audit log API (patvisitlog)
• Specimen audit log API (specimenlog)
• Security event logging API

11.7 Advanced Features

• Multi-site patient linking API
• Patient merge/unlink endpoints
• Archiving API
• Data warehouse integration endpoints
• Report generation API (PDF/JSON)
• HL7 message generation endpoints
• Instrument test mapping API
• Rerun management API
• Critical value alerts API

11.8 SMCRM Integration

• CRM sync webhooks
• Bidirectional data sync endpoints
• Equipment activity sync

---

Phase 12: Documentation & Testing ⏳ TODO

12.1 API Documentation

• Swagger/OpenAPI documentation endpoint (/swagger)
• Complete API documentation for all endpoints
• Request/response examples
• Authentication documentation

12.2 Testing

• PHPUnit test suite setup
• Unit tests for models
• Integration tests for controllers
• API endpoint tests
• HL7 message tests

---

Summary

Category	Done	Partial	Todo	Total
Core Infrastructure	5	0	0	5
Organization	5	0	0	5
Personnel	3	0	0	3
Patient	8	0	0	8
Location	2	0	0	2
Specimen	4	0	0	4
Test	9	0	0	9
Result	2	1	5	8
ValueSet	2	0	0	2
Infrastructure	2	0	0	2
Missing Features	0	0	32	32
Documentation	1	0	3	4
TOTAL	43	1	40	84

Completion: ~51% (43/84 items done)

---

Priority Next Steps

🔴 CRITICAL - Blockers for Production

1. Result validation workflow
   • Flag generation based on reference ranges (H/L/A)
   • Result interpretation logic
   • Must be completed before production deployment

High Priority (Core Lab Functions)

2. Equipment Management (ProductExt, Equipment lifecycle)
3. Calibration Management (Calibrator, Calibration results)
4. QC Management (QC material, QC results)
5. Result entry and correction workflow

Medium Priority (Important)

6. Audit Trail (Patient, Visit, Specimen logs)
7. HL7 message generation
8. Report generation API
9. Inventory Management
10. Rerun management API

Low Priority (Future Enhancement)

11. SMCRM Integration
12. Data warehouse integration
13. Archiving API
14. Critical value alerts
15. Multi-site patient linking

---

Last Updated: 2026-02-15 (Revised: RefRange is DONE - nested in Tests API) Project: CLQMS Backend REST API Version: 1.2.0

Architecture Notes

Nested Data Pattern

Some entities are managed as nested data within parent APIs rather than standalone endpoints:

• Reference Range → Nested in /api/tests (POST/PUT body includes refRanges array)

  • RefNum (numeric ranges with age/gender filters)
  • RefTxt (text interpretations)
  • RefTHold (threshold/cut-off values)
  • RefVSet (ValueSet-based ranges)

• Test Mapping → Nested in /api/tests

  • Instrument-to-LIS test code mapping
  • Many-to-one test relationships

• Test Groups/Profiles → Nested in /api/tests

  • Group definitions
  • Panel structures