625275e55b
Add the Healthcare platform backend (phases 13.0–13.7) with Alembic migration revision fix, production deploy script, validation reports, shared UI exports, and loyalty list page client directives so Next.js build succeeds. Co-authored-by: Cursor <cursoragent@cursor.com>
119 lines
3.9 KiB
Markdown
119 lines
3.9 KiB
Markdown
# Healthcare API Connection Report
|
||
|
||
**Service:** `healthcare-service` v0.13.7.0
|
||
**BFF:** `/api/healthcare/*` → port 8010
|
||
**Client:** `frontend/src/modules/healthcare/services/healthcare-api.ts`
|
||
|
||
---
|
||
|
||
## Connection Architecture
|
||
|
||
```
|
||
Browser (portal page)
|
||
→ healthcareApi.* (tenant + JWT headers)
|
||
→ /api/healthcare/* (Next.js route handler)
|
||
→ healthcare-service:8010/api/v1/*
|
||
```
|
||
|
||
All mutations use optimistic invalidation of TanStack Query keys scoped by tenant.
|
||
|
||
---
|
||
|
||
## API Surface Used by UI
|
||
|
||
### Foundation (Phase 13.0)
|
||
|
||
| Resource | List | Get | Create | Update | Delete | UI Screen |
|
||
|----------|------|-----|--------|--------|--------|-----------|
|
||
| clinics | ✅ | ✅ | ✅ | ✅ | ✅ | `ClinicsResourcePage` |
|
||
| branches | ✅ | ✅ | ✅ | ✅ | ✅ | `BranchesResourcePage` |
|
||
| departments | ✅ | ✅ | ✅ | ✅ | ✅ | `DepartmentsResourcePage` |
|
||
| doctors | ✅ | ✅ | ✅ | ✅ | ✅ | `DoctorsResourcePage` |
|
||
| patients | ✅ | ✅ | ✅ | ✅ | ✅ | `PatientsResourcePage` |
|
||
| external_providers | ✅ | ✅ | ✅ | ✅ | ✅ | `ExternalProvidersResourcePage` |
|
||
| settings | ✅ | — | upsert | upsert | — | `SettingsResourcePage` |
|
||
| audit | ✅ | — | — | — | — | `AuditExplorerPage` |
|
||
| permissions/catalog | ✅ | — | — | — | — | `PermissionsCatalogPage` |
|
||
|
||
### Appointments & Visits (13.1–13.2)
|
||
|
||
| Resource | Operations wired in UI |
|
||
|----------|------------------------|
|
||
| appointments | list, book, **confirm**, **cancel**, **no-show** |
|
||
| waiting_list | list, create |
|
||
| visit_sessions | list, create, **start**, **finish**, **defer**, **callNext** |
|
||
| schedules | list, create |
|
||
| availability_windows | list, create |
|
||
| doctor_panel/dashboard | doctor dashboard stats |
|
||
| visit_notes | via doctor encounters (create in records flow) |
|
||
|
||
### Clinic Admin (13.3)
|
||
|
||
| Resource | UI |
|
||
|----------|-----|
|
||
| clinic_services | CRUD create + list |
|
||
| staff_assignments | CRUD create + list |
|
||
| clinic_policies | CRUD create + list |
|
||
| operating_hours_policies | list (via resources) |
|
||
|
||
### Patient Portal (13.4)
|
||
|
||
| Endpoint | UI Page |
|
||
|----------|---------|
|
||
| patient-portal/me | Patient profile |
|
||
| patient-portal/appointments | upcoming / past / cancel |
|
||
| POST patient-portal/appointments | book wizard |
|
||
| patient-portal/documents | lab results, reviews, attachments |
|
||
| patient-portal/notification-preferences | notifications toggle |
|
||
|
||
### Medical Records (13.5–13.6)
|
||
|
||
| Endpoint | UI |
|
||
|----------|-----|
|
||
| medical-records POST/GET | lookup panel + create |
|
||
| clinical-lists + conditions/allergies/medications/immunizations | tabs + add |
|
||
| encounters create/update/finalize | encounters panel |
|
||
| prescription-orders full pipeline | doctor + pharmacy portals |
|
||
| pharmacies | admin + pharmacy dashboard |
|
||
|
||
### Delivery (13.7)
|
||
|
||
| Endpoint | UI |
|
||
|----------|-----|
|
||
| delivery-integrations | pharmacy delivery page |
|
||
| delivery-job-intents | pharmacy delivery page |
|
||
|
||
### Integrations (accounting / CRM / communication)
|
||
|
||
Mapped via `external_providers` filtered by `provider_kind` on payments, messages, income pages.
|
||
|
||
---
|
||
|
||
## Headers & Auth
|
||
|
||
| Header | Source |
|
||
|--------|--------|
|
||
| `Authorization` | Keycloak JWT via `getValidAccessToken()` |
|
||
| `X-Tenant-ID` | `useTenantId()` |
|
||
| `X-Patient-ID` | patient portal routes only |
|
||
|
||
401 triggers silent refresh via `refreshSession()`.
|
||
|
||
---
|
||
|
||
## Validation
|
||
|
||
| Check | Result |
|
||
|-------|--------|
|
||
| All entity screens call `healthcareApi` | ✅ |
|
||
| No hardcoded mock arrays in module pages | ✅ |
|
||
| BFF route exists | `app/api/healthcare/[...path]/route.ts` |
|
||
| Error mapping | `HealthcareApiError` with code + message |
|
||
|
||
---
|
||
|
||
## Gaps (backend)
|
||
|
||
- Collection list for `medical-records` and `encounters` not in client API — UI uses ID lookup / create flows.
|
||
- Dedicated insurance, laboratory, imaging request resources not in v0.13.7 OpenAPI — documented as future endpoints.
|