# Phase 18 — Interoperability, continuity of care and notification workflows

## 1. DHIS2 outbound integration queue
- Existing local indicator-to-DHIS2 organisation-unit/data-element mappings retained.
- Export preview still validates unmapped indicators and unsupported period spans.
- Submission now creates an `integration_outbox` record rather than making a direct HTTP request from the initial form action.
- Payloads receive a deterministic SHA-256 idempotency key; identical payloads are queued once.
- Separate manual dispatch/retry action sends to the configured DHIS2 `/api/dataValueSets` endpoint.
- HTTPS is required.
- Maximum five dispatch attempts and a 15-minute retry backoff after failure.
- Request/response metadata is recorded in `integration_logs` and the outbox.

**Limit:** dispatch is a manual synchronous HTTP operation. It is not a scheduled worker, does not poll DHIS2 import summaries asynchronously, and requires the operator to verify successful import in the target DHIS2 instance.

## 2. Limited FHIR R4 read-only resources
FHIR capability metadata now advertises:
- Patient (read/search).
- Encounter (read/search).
- Observation (search).
- Immunization (search).
- ServiceRequest (search; used as a referral representation).

All routes use Sanctum authentication, active-account and forced-password-change middleware. Queries are scoped to the user's facility unless the role has LCDA-wide access. Only signed encounters are exposed through the Observation search.

**Limit:** this is a limited read-only facade, not a complete FHIR R4 server. It does not support create/update/delete, subscriptions, SMART on FHIR, terminology validation, full profile conformance, FHIR Bulk Data, or conformance testing against a national implementation guide. Local text codes are not falsely represented as validated LOINC/SNOMED codes.

## 3. Maternal continuity follow-up
- Moderate/high-risk maternal register from staff-entered risk status.
- Follow-up task types: clinical review, ANC follow-up, referral, phone follow-up, home visit and other.
- Due date, priority, assignment and completion outcome tracking.

Risk is not algorithmically inferred. This is a staff workflow, not an obstetric risk calculator.

## 4. Immunisation schedule and defaulter tracking
- Configurable vaccine/dose schedule rules with due age, grace days, schedule version and approved protocol reference.
- Due/overdue listing compares child age with configured schedule rules and existing immunisation records.
- No vaccine schedule is seeded by default.

**Limit:** due lists are only as reliable as the schedule configured by an authorised user. Validate schedule version and eligibility rules against the current Nigerian national/state immunisation programme before use. This is not a coverage-rate calculation.

## 5. Patient communications and SMS reminder outbox
- Patient-specific SMS appointment reminder opt-in/opt-out preference.
- Opt-in requires a phone number and consent evidence reference.
- Reminder generation selects scheduled appointments 1–3 days ahead and only includes patients with active opt-in.
- Deterministic appointment-based idempotency key prevents duplicate reminder queue entries.
- Outbox status is visible to authorised facility users.

**Limit:** no SMS is sent. No SMS gateway provider, sender ID, delivery receipt, opt-out keyword processing or telecom retry worker is configured. The outbox is a preparation queue only. Do not enable live messaging until privacy/legal approval and an approved provider are in place.

## 6. Acceptance test source
- `Dhis2OutboxAcceptanceTest`: identical DHIS2 payloads are queued once.
- `CommunicationConsentAcceptanceTest`: reminders are not queued without explicit opt-in and are queued after opt-in.

## 7. Remaining integration work
- Scheduled queue worker and exponential retry with dead-letter handling.
- DHIS2 import-summary polling and reconciliation.
- National FHIR implementation-guide validation and code-system mappings.
- FHIR Observation/Immunization/ServiceRequest profile conformance.
- Offline sync APIs for appointments, encounters and referrals with conflict rules.
- SMS gateway integration, delivery receipts, STOP/opt-out and failed-message recovery.
- Immunisation catch-up logic and cohort-based coverage denominators.
- Referral receipt confirmation and closed-loop clinical handover.
- Security/privacy assessment for all cross-facility data exchange.

No external integration, SMS delivery, database migration or PHPUnit runtime test is claimed as completed in this source-only environment.
