2026-02-15 21:05:25 +07:00
|
|
|
# CLQMS REST API Development Checklist
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
**Note**: This checklist covers ONLY the REST API backend. UI/UX implementation is handled separately in the frontend project (clqms01-fe).
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
## Legend
|
|
|
|
|
- [x] **DONE** - Implemented and functional
|
|
|
|
|
- [ ] **TODO** - Not yet implemented
|
|
|
|
|
- [~] **PARTIAL** - Partially implemented
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
---
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
## Phase 1: Core Infrastructure ✅ DONE
|
feat(api): transition to headless architecture and enhance order management
This commit marks a significant architectural shift, transitioning the CLQMS backend to a fully headless REST API. All view-related components have been removed to focus solely on providing a robust, stateless API for clinical laboratory workflows.
### Architectural Changes
- **Headless API Transition:**
- Removed all view files (`app/Views/v2`), associated page controllers (`PagesController`), and routes (`Routes.php`). The application no longer serves a front-end UI.
- The root endpoint (`/`) now returns a simple "Backend Running" status message.
- **Developer Tooling & Guidance:**
- Replaced `CLAUDE.md` with `GEMINI.md` to provide updated context and instructional guidelines for Gemini agents.
- Updated `.serena/project.yml` with project configuration.
### Feature Enhancements
- **Advanced Order Management (`OrderTestModel`):**
- **Test Expansion:** The `createOrder` process now automatically expands `GROUP` (panel) tests into their individual components and recursively includes all parameter dependencies for `CALC` (calculated) tests.
- **Order Comments:** Added support for attaching comments to an order via the `ordercom` table.
- **Status Tracking:** Order status updates are now correctly recorded in the `orderstatus` table.
- **Schema Alignment:** Switched from `OrderID` to `InternalOID` as the primary key for internal operations.
- **Reference Range Refactor (`TestsController`):**
- Simplified reference range logic by consolidating `refthold` and `refvset` into the main `refnum` and `reftxt` tables.
- Standardized `RefType` handling to support `NMRC`, `TEXT`, `THOLD`, and `VSET` codes from the `reference_type` ValueSet.
### Other Changes
- **Documentation:**
- `PRD.md`, `README.md`, and `TODO.md` were updated to reflect the headless architecture, refined scope, and current project priorities.
- **Database:**
- Removed obsolete `RefTHoldID` and `RefVSetID` columns from the `patres` table migration.
- **Testing:**
- Added new feature tests for `ContactController`, `OrganizationController`, and `TestsController`.
2026-01-31 09:27:32 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 1.1 Base Framework
|
|
|
|
|
- [x] BaseController with ResponseTrait
|
|
|
|
|
- [x] BaseModel with auto UTC normalization
|
|
|
|
|
- [x] Validation system with custom rules
|
|
|
|
|
- [x] JWT authentication system
|
|
|
|
|
- [x] CORS and security headers configuration
|
|
|
|
|
- [x] Database migration system
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 1.2 Authentication & Security
|
|
|
|
|
- [x] User login/logout (AuthController, AuthV2Controller)
|
|
|
|
|
- [x] JWT token generation and validation
|
|
|
|
|
- [x] Password change functionality
|
|
|
|
|
- [x] Auth check endpoints
|
|
|
|
|
- [x] Role-based access control (RBAC) preparation
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
---
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
## Phase 2: Organization Management ✅ DONE
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 2.1 Account Management
|
|
|
|
|
- [x] Account CRUD API (`/api/organization/account`)
|
|
|
|
|
- [x] Account listing and search
|
|
|
|
|
- [x] Parent-child Account relationships
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 2.2 Site Management
|
|
|
|
|
- [x] Site CRUD API (`/api/organization/site`)
|
|
|
|
|
- [x] SiteCode generation support
|
|
|
|
|
- [x] Site type management (PHL, GL, PL)
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 2.3 Department Management
|
|
|
|
|
- [x] Department CRUD API (`/api/organization/department`)
|
|
|
|
|
- [x] Department-Discipline linking
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 2.4 Discipline Management
|
|
|
|
|
- [x] Discipline CRUD API (`/api/organization/discipline`)
|
|
|
|
|
- [x] Discipline hierarchy support
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 2.5 Workstation Management
|
|
|
|
|
- [x] Workstation CRUD API (`/api/organization/workstation`)
|
|
|
|
|
- [x] Workstation type management (primary/secondary)
|
|
|
|
|
- [x] Workstation linking support
|
2026-01-12 16:53:41 +07:00
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
## Phase 3: Personnel/Contact Management ✅ DONE
|
|
|
|
|
|
|
|
|
|
### 3.1 Contact Management
|
|
|
|
|
- [x] Contact CRUD API (`/api/contact`)
|
|
|
|
|
- [x] ContactDetail model (for site-specific roles)
|
|
|
|
|
- [x] Patient-Contact association
|
|
|
|
|
|
|
|
|
|
### 3.2 Occupation Management
|
|
|
|
|
- [x] Occupation CRUD API (`/api/occupation`)
|
|
|
|
|
|
|
|
|
|
### 3.3 Medical Specialty
|
|
|
|
|
- [x] MedicalSpecialty CRUD API (`/api/medicalspecialty`)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Phase 4: Patient Management ✅ DONE
|
|
|
|
|
|
|
|
|
|
### 4.1 Patient Core
|
|
|
|
|
- [x] Patient CRUD API (`/api/patient`)
|
|
|
|
|
- [x] Patient search and filtering
|
|
|
|
|
- [x] Patient identifier management (PatIdtModel)
|
|
|
|
|
- [x] Patient comments (PatComModel)
|
|
|
|
|
- [x] Patient attachments (PatAttModel)
|
|
|
|
|
- [x] Patient check endpoint
|
|
|
|
|
|
|
|
|
|
### 4.2 Patient Visit (ADT)
|
|
|
|
|
- [x] PatientVisit CRUD API (`/api/patvisit`)
|
|
|
|
|
- [x] Get visits by patient
|
|
|
|
|
- [x] PatVisitADT CRUD (`/api/patvisitadt`)
|
|
|
|
|
- [x] Get ADT by visit
|
|
|
|
|
- [x] Admission workflow (A01)
|
|
|
|
|
- [x] Transfer workflow (A02)
|
|
|
|
|
- [x] Discharge workflow (A03)
|
|
|
|
|
- [x] Cancel admission/discharge
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Phase 5: Location Management ✅ DONE
|
|
|
|
|
|
|
|
|
|
### 5.1 Location
|
|
|
|
|
- [x] Location CRUD API (`/api/location`)
|
|
|
|
|
- [x] Location hierarchy support
|
|
|
|
|
|
|
|
|
|
### 5.2 Area/Geography
|
|
|
|
|
- [x] AreaGeo API (`/api/areageo`)
|
|
|
|
|
- [x] Province listing
|
|
|
|
|
- [x] City listing
|
|
|
|
|
|
2026-01-12 16:53:41 +07:00
|
|
|
---
|
|
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
## Phase 6: Specimen Management ✅ DONE
|
|
|
|
|
|
|
|
|
|
### 6.1 Specimen Core
|
|
|
|
|
- [x] Specimen CRUD API (`/api/specimen`)
|
|
|
|
|
- [x] SID generation support
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 6.2 Container Management
|
|
|
|
|
- [x] ContainerDef CRUD API (`/api/specimen/container`, `/api/specimen/containerdef`)
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 6.3 Specimen Workflow
|
|
|
|
|
- [x] SpecimenPrep CRUD API (`/api/specimen/prep`)
|
|
|
|
|
- [x] SpecimenStatus CRUD API (`/api/specimen/status`)
|
|
|
|
|
- [x] SpecimenCollection CRUD API (`/api/specimen/collection`)
|
2026-01-12 16:53:41 +07:00
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
## Phase 7: Test Management ✅ DONE
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 7.1 Test Definitions
|
|
|
|
|
- [x] Tests CRUD API (`/api/tests`)
|
|
|
|
|
- [x] Test mapping API (`/api/test/testmap`)
|
|
|
|
|
- [x] **Reference Range nested in Tests** (RefNum, RefTxt via POST/PUT body)
|
|
|
|
|
- [x] Test profile/group management
|
|
|
|
|
- [x] Test discipline mapping
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 7.2 Test Ordering
|
|
|
|
|
- [x] OrderTest CRUD API (`/api/ordertest`)
|
|
|
|
|
- [x] Order status update endpoint
|
|
|
|
|
- [x] Demo order creation (`/api/demo/order`)
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 7.3 Reference Range (Nested in Tests)
|
|
|
|
|
- [x] RefNum model and controller integration (`saveRefNumRanges()`)
|
|
|
|
|
- [x] RefTxt model and controller integration (`saveRefTxtRanges()`)
|
|
|
|
|
- [x] Age range validation
|
|
|
|
|
- [x] Gender-based reference ranges
|
|
|
|
|
- [x] Text-based result interpretation
|
|
|
|
|
- [x] Threshold (RefTHold) support
|
|
|
|
|
- [x] ValueSet (RefVSet) support
|
|
|
|
|
|
|
|
|
|
**Note**: Reference ranges are managed as nested data within Tests API. POST/PUT `/api/tests` includes `refRanges` array in request body.
|
2026-01-12 16:53:41 +07:00
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
## Phase 8: Result Management ✅ PARTIAL
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 8.1 Result Core
|
|
|
|
|
- [x] Result listing endpoint (`/api/result`)
|
|
|
|
|
- [~] Result entry (manual)
|
|
|
|
|
- [ ] Result validation workflow
|
|
|
|
|
- [ ] Result flagging (H/L/A)
|
|
|
|
|
- [ ] Result correction workflow
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 8.2 Result ValueSets
|
|
|
|
|
- [x] ResultValueSet CRUD API (`/api/result/valueset`)
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
---
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
## Phase 9: ValueSet Management ✅ DONE
|
|
|
|
|
|
|
|
|
|
### 9.1 File-based ValueSets
|
|
|
|
|
- [x] ValueSet listing (`/api/valueset`)
|
|
|
|
|
- [x] Specific value set retrieval (`/api/valueset/{type}`)
|
|
|
|
|
- [x] ValueSet refresh endpoint
|
|
|
|
|
|
|
|
|
|
### 9.2 Database ValueSets
|
|
|
|
|
- [x] ValueSet items CRUD (`/api/valueset/user/items`)
|
|
|
|
|
- [x] ValueSet definitions CRUD (`/api/valueset/user/def`)
|
2026-01-12 16:53:41 +07:00
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
## Phase 10: Infrastructure & Support ✅ DONE
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 10.1 Counter Management
|
|
|
|
|
- [x] Counter CRUD API (`/api/counter`)
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
### 10.2 Edge Integration (Instrument)
|
|
|
|
|
- [x] Edge results endpoint (`/api/edge/results`)
|
|
|
|
|
- [x] Edge orders retrieval (`/api/edge/orders`)
|
|
|
|
|
- [x] Order acknowledgment (`/api/edge/orders/{id}/ack`)
|
|
|
|
|
- [x] Status update endpoint (`/api/edge/status`)
|
2026-01-12 16:53:41 +07:00
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
## 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
|
2026-01-12 16:53:41 +07:00
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
## Phase 12: Documentation & Testing ⏳ TODO
|
|
|
|
|
|
|
|
|
|
### 12.1 API Documentation
|
|
|
|
|
- [x] 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
|
2026-01-12 16:53:41 +07:00
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
## 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)**
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
---
|
2026-01-12 16:53:41 +07:00
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
## 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
|
2026-01-12 16:53:41 +07:00
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
2026-02-15 21:05:25 +07:00
|
|
|
**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
|