Issue, call-next, serve, and complete tickets locally so Care Pro no longer needs QUEUE_API_* when CARE_QUEUE_DRIVER=native (default). Remote Ladill Queue remains available for cutover; PHPUnit keeps the remote driver for existing fakes. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
isaacclad
@@ -0,0 +1,288 @@
|
||||
# Care Queue Engine + Specialty Modules — Unified Plan
|
||||
|
||||
**Status:** Phase 1 in progress
|
||||
**Date:** 2026-07-18
|
||||
**Repos:** ladill-care (primary), ladill-queue (healthcare removal)
|
||||
**Related:** `docs/specialty-module-design-standard.md`
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 notes (implementation)
|
||||
|
||||
- Config: `CARE_QUEUE_DRIVER=native` (default) | `remote` (legacy Ladill Queue HTTP)
|
||||
- Tables: `care_service_queues`, `care_service_points`, `care_queue_tickets`
|
||||
- Service: `App\Services\Care\CareQueueEngine`
|
||||
- Bridge / provisioner route to native when driver is `native`; PHPUnit sets `remote` so legacy Http::fake tests keep working
|
||||
- Exit criterion: Care Pro demo issues / call-next / complete with `QUEUE_API_*` unset
|
||||
|
||||
---
|
||||
|
||||
## 1. Decision
|
||||
|
||||
| Decision | Choice |
|
||||
| --- | --- |
|
||||
| Care waiting lines / call-next / service points | **Built into Ladill Care** as a first-party **Care Queue Engine** |
|
||||
| Ladill Queue dependency for Care | **Removed** — Care never requires Queue API keys or Pro “Queue integration” |
|
||||
| Healthcare in Ladill Queue | **Removed** — Queue becomes general-purpose multi-industry QMS only |
|
||||
| Specialty modules | Built **on top of** Care Queue Engine + Visit/workflow/billing — not on Ladill Queue |
|
||||
|
||||
**Product framing**
|
||||
|
||||
- **Ladill Care** = clinical ops (patients, visits, specialties, in-app queues, billing).
|
||||
- **Ladill Queue** = generic ticket QMS (banks, retail, hospitality, …) with **no clinical/Care packaging**.
|
||||
|
||||
---
|
||||
|
||||
## 2. Goals & non-goals
|
||||
|
||||
### Goals
|
||||
|
||||
1. One in-app Care queue substrate used by consultation, lab, pharmacy, billing, Emergency, Blood Bank, and all specialty modules.
|
||||
2. Specialty modules follow the design standard (shell, workflow, queues, billing) without a second queue product.
|
||||
3. Clean cutover: existing Care tenants keep working without Ladill Queue.
|
||||
4. Queue product remains valuable for non-healthcare industries after healthcare surfaces are stripped.
|
||||
|
||||
### Non-goals (this program)
|
||||
|
||||
- Rebuilding displays/kiosks/voice as feature-parity with Queue Day 1 (phase later if needed).
|
||||
- Shared database between Care and Queue.
|
||||
- Keeping a permanent dual-write to Ladill Queue.
|
||||
|
||||
---
|
||||
|
||||
## 3. Current state (why this plan)
|
||||
|
||||
Today Care is a **remote adapter** to Queue:
|
||||
|
||||
- `QueueClient` → `CareQueueBridge` / `CareQueueProvisioner`
|
||||
- Clinical entities mirror `queue_ticket_*` fields; ticket **truth** lives in Queue
|
||||
- Specialty activate provisions Queue stubs over HTTP
|
||||
- Pro feature flag `queue_integration` + `QUEUE_API_KEY_CARE`
|
||||
|
||||
Specialty modules are a **thin layer** (catalog → departments → waiting list page). The specialty design standard needs a real local queue engine — building that *and* keeping Ladill Queue would double work.
|
||||
|
||||
---
|
||||
|
||||
## 4. Target architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Ladill Care │
|
||||
│ Patients · Visits · Consultations · Lab · Pharmacy · Bills │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────────┐ │
|
||||
│ │ Care Queue Engine (in-app) │ │
|
||||
│ │ ServiceQueue · ServicePoint · Ticket · Call-next │ │
|
||||
│ │ Contexts: consultation, lab, pharmacy, billing, │ │
|
||||
│ │ specialty:{key}, emergency, blood_bank │ │
|
||||
│ └────────────────────────────────────────────────────────┘ │
|
||||
│ ▲ │
|
||||
│ │ │
|
||||
│ ┌────────────────────────────────────────────────────────┐ │
|
||||
│ │ Specialty Module Shell (shared) │ │
|
||||
│ │ Dashboard · Workflow · Clinical workspace · Billing │ │
|
||||
│ └────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
Ladill Queue (decoupled)
|
||||
Generic QMS only — no healthcare package, no Care API path
|
||||
```
|
||||
|
||||
**Care Queue Engine owns**
|
||||
|
||||
- Queues per `(organization, branch, context)`
|
||||
- Service points (rooms / desks / chairs) with `shared_pool` vs `assigned_only`
|
||||
- Tickets (number, status, priority, wait time, assigned staff/point)
|
||||
- Call next / recall / skip / complete / transfer (Care-flavored)
|
||||
- Sync from clinical waiters (appointments, Rx, labs, bills) into tickets
|
||||
|
||||
**Specialty modules own**
|
||||
|
||||
- Clinical forms, stage maps, KPIs, documents, alerts
|
||||
- Mapping specialty stages → Care Queue contexts/points
|
||||
- Service catalog → Billing Engine line items
|
||||
|
||||
**Visit** remains the episode unit (per specialty standard). Tickets attach to visit/appointment/entity — not a parallel patient chart.
|
||||
|
||||
---
|
||||
|
||||
## 5. Phased program (one roadmap)
|
||||
|
||||
### Phase 0 — Spec freeze (short)
|
||||
|
||||
Deliverables:
|
||||
|
||||
- This plan accepted
|
||||
- Care Queue Engine domain model + API sketch (tables, statuses, contexts)
|
||||
- Specialty shell IA locked (from design standard)
|
||||
- Queue healthcare removal checklist signed off
|
||||
|
||||
Exit: engineering can implement without re-litigating product boundaries.
|
||||
|
||||
---
|
||||
|
||||
### Phase 1 — Care Queue Engine (MVP)
|
||||
|
||||
Replace remote QMS for Care’s core lines **inside Care**.
|
||||
|
||||
**Data model (illustrative)**
|
||||
|
||||
- `care_service_queues` — org, branch, context, name, prefix, active
|
||||
- `care_service_points` — queue_id, name, kind (practitioner/desk), staff/member/practitioner refs, routing mode
|
||||
- `care_queue_tickets` — queue_id, point_id?, entity type/id, visit_id?, ticket_number, status, priority, called_at, completed_at, metadata
|
||||
- Keep or migrate mirror columns on appointments/Rx/labs/bills to point at **local** ticket IDs (drop remote UUIDs over time)
|
||||
|
||||
**Engine capabilities (MVP)**
|
||||
|
||||
- Issue ticket when patient enters a wait line
|
||||
- Call next (shared pool + assigned_only for doctors)
|
||||
- Serve / complete / recall
|
||||
- Backfill waiters without tickets
|
||||
- UI: queue ops on consultation / lab / pharmacy / billing pages (same UX patterns as today, local backend)
|
||||
|
||||
**Adapter rewrite**
|
||||
|
||||
- `CareQueueBridge` talks to **local** engine (same method surface where possible)
|
||||
- `QueueClient` / HTTP provisioner become dead code → delete
|
||||
- Remove `queue_integration` Pro flag; Care queues are **always available** on Pro clinical modules (or Free waiting list + Pro ticket numbers — product call: recommend tickets on Free for consultation only, full multi-context on Pro)
|
||||
|
||||
**Migration**
|
||||
|
||||
- Tenants with remote Queue UUIDs: import open tickets if API still up **or** re-issue local tickets from current waiters (prefer re-issue for simplicity; archive remote history)
|
||||
- Demo seed: stop calling Queue HTTP entirely
|
||||
|
||||
Exit: Care Pro demo runs call-next / tickets with `QUEUE_API_*` unset.
|
||||
|
||||
---
|
||||
|
||||
### Phase 2 — Specialty shell on Care Queue Engine
|
||||
|
||||
Implement the specialty design standard **once**, for all modules.
|
||||
|
||||
1. **Shared specialty shell** — KPI dashboard, left nav (Overview / Visits / History / Module Tabs), standard patient header, action panel
|
||||
2. **Visit-backed specialty visits** — not appointment-only waiting lists
|
||||
3. **Patient header + timeline components** — reused on patient chart
|
||||
4. **Specialty stage maps** in config (per module) → Care Queue contexts/points (e.g. Dentistry: Waiting → Chair → Procedure → Recovery)
|
||||
5. **Service catalog → billing** — activate module seeds billable services; invoices via Billing Engine
|
||||
6. **Emergency & Blood Bank** — already `default_on_paid_plans`; first modules to get full shell + local queues (templates for the rest)
|
||||
|
||||
Exit: Emergency (and ideally Dentistry) demonstrate the full standard on the in-app engine; remaining modules are catalog + stage map + forms on the same shell.
|
||||
|
||||
---
|
||||
|
||||
### Phase 3 — Roll specialties onto the shell
|
||||
|
||||
Per-module work becomes incremental:
|
||||
|
||||
1. Stage map + queue points
|
||||
2. Clinical forms / structured records
|
||||
3. Service catalog items
|
||||
4. Alerts + documents + KPIs
|
||||
5. Role matrix
|
||||
|
||||
Order suggestion: **Emergency → Blood Bank → Dentistry → Radiology → Maternity → …** (volume / demo story first).
|
||||
|
||||
Do **not** invent new queue backends per specialty.
|
||||
|
||||
---
|
||||
|
||||
### Phase 4 — Remove healthcare from Ladill Queue
|
||||
|
||||
Parallelizable after Phase 1 starts; finish once Care no longer calls Queue.
|
||||
|
||||
**Remove from Queue**
|
||||
|
||||
- `industry_packages.healthcare` and related templates/priorities
|
||||
- Care integration: `QUEUE_API_KEY_CARE`, `care_enabled`, Care provision defaults, Care settings UI, Care tests
|
||||
- Clinic DemoWorld branding (Ridge Clinic / Care staff) → neutral industry demos
|
||||
- Care-oriented marketing copy (“Care & Frontdesk API” → generic integrations)
|
||||
|
||||
**Keep in Queue**
|
||||
|
||||
- Generic QMS, other industry packages, Frontdesk/POS/CRM integration pattern, assigned_only routing as generic features
|
||||
|
||||
**Suite docs / DemoWorld**
|
||||
|
||||
- Stop listing Queue as required for Care Pro
|
||||
- Care staff demos no longer include `queue` app by default (optional)
|
||||
|
||||
Exit: Queue CI green without healthcare/Care paths; Care CI green without Queue env vars.
|
||||
|
||||
---
|
||||
|
||||
### Phase 5 — Hard delete Care→Queue code & polish
|
||||
|
||||
- Delete `QueueClient`, remote provisioner paths, sync artisan that hits Queue API
|
||||
- Remove env keys from Care `.env.example`
|
||||
- Optional later: Care TV display / voice (only if product needs; not blocking)
|
||||
|
||||
---
|
||||
|
||||
## 6. How this maps to the specialty design standard
|
||||
|
||||
| Standard requirement | Provided by |
|
||||
| --- | --- |
|
||||
| Workflow-driven stages | Specialty stage maps + Visit workflow |
|
||||
| Queues per specialty | **Care Queue Engine** contexts/points |
|
||||
| Episode / visit | Care `Visit` |
|
||||
| Timeline | Shared timeline component (Phase 2) |
|
||||
| Dashboard KPIs | Specialty shell (Phase 2) |
|
||||
| Billing | Care Billing Engine + specialty service catalog |
|
||||
| Call Next / Start Consultation / … | Shared actions → engine + clinical controllers |
|
||||
| No standalone specialty apps | One shell, many module configs |
|
||||
|
||||
---
|
||||
|
||||
## 7. Risks & mitigations
|
||||
|
||||
| Risk | Mitigation |
|
||||
| --- | --- |
|
||||
| Ticket history only in Queue DB | Prefer re-issue open waiters locally; don’t block on full history import |
|
||||
| Demo Pro broken mid-cutover | Feature flag `care_native_queue` during Phase 1; default on for new seeds |
|
||||
| Specialty work forks before engine ready | Freeze deep specialty UIs until Phase 1 MVP + Phase 2 shell |
|
||||
| Queue customers using healthcare package | Migrate them to Care **or** keep package until date-certain deprecation notice |
|
||||
| Scope creep (kiosks/voice) | Explicitly Phase 5+ / optional |
|
||||
|
||||
---
|
||||
|
||||
## 8. Success criteria
|
||||
|
||||
1. Care runs full clinical + specialty queues with **no** Ladill Queue dependency.
|
||||
2. Specialty modules share one shell and one queue engine.
|
||||
3. Ladill Queue has **no** healthcare package or Care integration surface.
|
||||
4. Docs/demo accounts reflect the split.
|
||||
5. Tests: Care queue + specialty shell coverage; Queue industry suite without healthcare.
|
||||
|
||||
---
|
||||
|
||||
## 9. Suggested ownership & sequencing
|
||||
|
||||
```
|
||||
Week focus (indicative):
|
||||
|
||||
[Phase 0] Spec freeze
|
||||
↓
|
||||
[Phase 1] Care Queue Engine MVP ──┬── parallel: Queue healthcare deprecation notice
|
||||
↓ │
|
||||
[Phase 2] Specialty shell │
|
||||
↓ │
|
||||
[Phase 3] Emergency / Blood Bank / Dentistry on shell
|
||||
↓ ↓
|
||||
[Phase 4] Strip healthcare from Queue (hard remove)
|
||||
↓
|
||||
[Phase 5] Delete Care remote Queue adapter
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Immediate next implementation slice
|
||||
|
||||
When ready to code (first PR):
|
||||
|
||||
1. Migrations for `care_service_queues`, `care_service_points`, `care_queue_tickets`
|
||||
2. `CareNativeQueue` service with issue / call-next / complete
|
||||
3. Point `CareQueueBridge` at native service behind a config flag
|
||||
4. Consultation queue page uses native tickets when flag on
|
||||
5. Document flag + cutover in this file’s changelog
|
||||
|
||||
Specialty shell follows once native consultation queue is green in demo.
|
||||
@@ -220,3 +220,13 @@ Specialty modules today are a **thin Pro enablement layer**, not the full clinic
|
||||
5. **Queue + clinical workspace entry points** — stage-aware queue → open consultation/assessment with specialty context.
|
||||
|
||||
Do not implement dentistry, maternity, cardiology, etc. as separate apps until that shared shell and Visit/queue/billing bridges exist.
|
||||
|
||||
---
|
||||
|
||||
## Care Queue Engine (product decision)
|
||||
|
||||
Ladill Care uses an **in-app Care Queue Engine**, fully decoupled from Ladill Queue.
|
||||
|
||||
- Specialty queues, call-next, and service points are Care-native.
|
||||
- Ladill Queue remains a general-purpose QMS; healthcare / Care packaging is removed from Queue.
|
||||
- Unified program plan: [`docs/care-queue-engine-and-specialty-plan.md`](care-queue-engine-and-specialty-plan.md).
|
||||
|
||||
Reference in New Issue
Block a user