# 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
- [x] **DONE** - Implemented and functional
- [ ] **TODO** - Not yet implemented
- [~] **PARTIAL** - Partially implemented

---

## Phase 1: Core Infrastructure ✅ DONE

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

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

---

## Phase 2: Organization Management ✅ DONE

### 2.1 Account Management
- [x] Account CRUD API (`/api/organization/account`)
- [x] Account listing and search
- [x] Parent-child Account relationships

### 2.2 Site Management
- [x] Site CRUD API (`/api/organization/site`)
- [x] SiteCode generation support
- [x] Site type management (PHL, GL, PL)

### 2.3 Department Management
- [x] Department CRUD API (`/api/organization/department`)
- [x] Department-Discipline linking

### 2.4 Discipline Management
- [x] Discipline CRUD API (`/api/organization/discipline`)
- [x] Discipline hierarchy support

### 2.5 Workstation Management
- [x] Workstation CRUD API (`/api/organization/workstation`)
- [x] Workstation type management (primary/secondary)
- [x] Workstation linking support

---

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

---

## Phase 6: Specimen Management ✅ DONE

### 6.1 Specimen Core
- [x] Specimen CRUD API (`/api/specimen`)
- [x] SID generation support

### 6.2 Container Management
- [x] ContainerDef CRUD API (`/api/specimen/container`, `/api/specimen/containerdef`)

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

---

## Phase 7: Test Management ✅ DONE

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

### 7.2 Test Ordering
- [x] OrderTest CRUD API (`/api/ordertest`)
- [x] Order status update endpoint
- [x] Demo order creation (`/api/demo/order`)

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

---

## Phase 8: Result Management ✅ PARTIAL

### 8.1 Result Core
- [x] Result listing endpoint (`/api/result`)
- [~] Result entry (manual)
- [ ] Result validation workflow
- [ ] Result flagging (H/L/A)
- [ ] Result correction workflow

### 8.2 Result ValueSets
- [x] ResultValueSet CRUD API (`/api/result/valueset`)

---

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

---

## Phase 10: Infrastructure & Support ✅ DONE

### 10.1 Counter Management
- [x] Counter CRUD API (`/api/counter`)

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

---

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

---

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