# Phase: Delivery Integration

| Field | Value |
| --- | --- |
| Identifier | `healthcare-13-7` |
| Status | Planned |
| Owner | Platform |
| Module(s) | `healthcare.delivery_integration`, `healthcare.delivery_job_intents` |
| Service(s) | `healthcare` |
| Depends On | `healthcare-13-6`, Delivery platform (`delivery-10.0+`) |
| ADR(s) | TBD; aligns with [ADR-015](../../architecture/adr/ADR-015.md) |
| Manifest | [phase-manifest.yaml](../../ai-framework/phase-manifest.yaml) |
| Framework | [ADR-013](../../architecture/adr/ADR-013.md) · [ADR-018](../../architecture/adr/ADR-018.md) · [ADR-019](../../architecture/adr/ADR-019.md) |

## Objective

Integrate prescription and medical-supply home delivery via Delivery platform contracts: register delivery integration, emit delivery job intents from ready prescription orders, consume status events/webhooks, and notify patients — without owning drivers, fleet, dispatch, or routing (Delivery service domain).

## Enterprise Phase Discovery

> **Required before Implementation.**

| Field | Value |
| --- | --- |
| Discovery date | TBD at implementation |
| Inputs reviewed | Phase 13.6 prescription ready state · [ADR-015](../../architecture/adr/ADR-015.md) · Delivery merchant connector phases |

### Target Responsibility (this phase when Complete)

- DeliveryIntegrationRegistration per tenant/clinic/pharmacy
- DeliveryJobIntent aggregate referencing PrescriptionOrder (UUID ref, no cross-DB FK)
- Submit intent → Delivery API contract (mock in tests until Delivery 10.9+)
- Inbound status sync: queued → picked_up → in_transit → delivered / failed
- Patient notification via Communication on milestone statuses
- Permissions `healthcare.delivery_integration.*`
- Events `healthcare.delivery_job_intent.*`

### Explicitly Excluded

- Driver/fleet/dispatch/routing aggregates (Delivery)
- Proof-of-delivery binary storage (Delivery + Storage)
- Restaurant/Hospitality order types
- Duplicate tracking timeline (subscribe to Delivery events only)

### Boundary Confirmations

- [x] Healthcare does not own logistics domain
- [x] No cross-database foreign keys to `delivery_db`
- [x] Job intake follows Delivery merchant connector pattern

## Business Analysis

| Item | Detail |
| --- | --- |
| Actors | Pharmacy staff, patient, delivery dispatcher (Delivery UI) |
| Business capabilities | Request delivery for ready prescriptions; surface status to patient |
| Success metrics | Idempotent job creation; status mirrors Delivery without duplication |
| Non-goals | Cold-chain IoT, route optimization, driver payroll |

## Scope

### In Scope

- Aggregates: DeliveryIntegrationRegistration, DeliveryJobIntent, DeliveryJobStatusSnapshot
- Commands: create_intent, cancel_intent (before pickup)
- Webhook/event handler stubs for Delivery status updates
- Alembic `0008_phase_137_delivery_integration`; version `0.13.7.0`
- Capability flag `delivery_integration`

### Providers

| Interface | Owning service | Notes |
| --- | --- | --- |
| DeliveryProvider | Delivery | Job submit + status read |
| CommunicationProvider | Communication | Patient SMS/push on status |

### APIs (planned)

| Method | Path | Permission | Notes |
| --- | --- | --- | --- |
| POST | `/api/v1/delivery-integrations` | `healthcare.delivery_integration.manage` | Register |
| POST | `/api/v1/prescription-orders/{id}/delivery-intents` | `healthcare.delivery_integration.submit` | Create job intent |
| GET | `/api/v1/delivery-job-intents` | `healthcare.delivery_integration.view` | List/filter |
| POST | `/api/v1/webhooks/delivery-status` | signed webhook | Status ingest |

## Out of Scope

- Implementing Delivery dispatch engine
- Driver mobile app
- Accounting delivery fees posting (future Accounting integration)
- Frontend tracking map

## Completion Criteria

- [ ] Job intent idempotency tests
- [ ] Status sync from mocked Delivery provider
- [ ] Boundary tests (no delivery model imports)
- [ ] Handover + registry at `0.13.7.0`

## Architecture Impact

- Confirms Healthcare ↔ Delivery integration boundary in module-boundaries.md at implementation

## Related Documents

- [Phase 13.6](phase-13-6-pharmacy-network.md)
- [Delivery Roadmap](../../delivery-roadmap.md)
- [ADR-015](../../architecture/adr/ADR-015.md)
- [Healthcare Roadmap](../../healthcare-roadmap.md)
- [Module Registry](../../module-registry.md#healthcare)