# ZUMRI Phase 8 Delivery and Rider Management

## Objective
Add physical delivery and approved-return transportation after the paid Order boundary.

## Existing Components Reused
User/RIDER authentication, Order/OrderItem snapshots, ReturnRequest, ReferenceNumber, Upload, audit, notification foundations, and permissions.

## Shipment Architecture
Orders can have many CUSTOMER_DELIVERY shipments; returns have one RETURN_PICKUP. Shipment owns immutable destination and operational timestamps, never prices or payments.

## Shipment Items
ShipmentItem references OrderItem and supports partial allocation. Locked allocation checks prevent non-cancelled totals exceeding purchases.

## Shipment State Machine
Central legal transitions cover readiness, assignment, pickup, transit, delivery, failure, rescheduling, and cancellation. No generic status patch exists.

## Order Fulfillment Integration
Delivered shipment quantities derive UNFULFILLED, PARTIALLY_FULFILLED, or FULFILLED. Delivery never changes payment or initiates a refund.

## Rider Profile
Operational data attaches one-to-one to an existing RIDER User; authentication and identity remain on User.

## Rider Availability
ACTIVE/INACTIVE/SUSPENDED is separate from AVAILABLE/BUSY/OFFLINE. Assignment locks the rider and checks active capacity.

## Assignment Architecture
Append-preserved assignment rows record assignment, acceptance/rejection, unassignment, and completion. Shipment caches only the current rider.

## Dispatch
The dispatch view queries ready, active, failed, and rescheduled shipments without adding redundant persistence.

## Rider Workflow
Riders see and act only on their own current assignments through explicit legal action endpoints.

## Delivery Events
ShipmentEvent is append-only. Unique event IDs provide retry idempotency and chronological customer timelines.

## Proof of Delivery
Structured proof supports photo, signature, recipient confirmation, and return-pickup photo. Existing private Upload records are ownership/status/MIME checked.

## Failed Deliveries
Failure requires a reason code and increments attempts. It does not refund, cancel the Order, or restock.

## Rescheduling
Admin may schedule a failed delivery with bounded window/reason fields; no calendar optimizer is introduced.

## Customer Tracking
Authenticated ownership is mandatory. Safe projections exclude private rider/location and financial data.

## Location Privacy
Only latest optional coordinates are retained. They are operational data, absent from customer responses and broad audit metadata.

## Return Logistics
Physical transport remains separate from Phase 7 inspection, refund, and inventory decisions.

## Return Pickup
Only approved returns create an idempotent pickup. Delivery marks the request RECEIVED without premature refund/restock.

## Notifications
Existing Phase 2 infrastructure remains the integration boundary. Automated delivery notification fan-out needs durable outbox/worker hardening before production.

## Permissions
Shipment read/create/manage/assign, rider read/manage, dispatch read/manage, proof read, and return-logistics read/manage permissions were added.

## Audit
Creation, assignment, rider actions, cancellation, reschedule, and return pickup use stable Phase 2 activity types without precise location.

## Idempotency
Creation, assignment, and rider transitions use client keys mapped to unique ShipmentEvent IDs. Repeated delivery cannot duplicate proof/event/fulfillment changes.

## Concurrency
Transactions and row locks protect creation allocations, assignment, capacity, transitions, completion, and return-pickup uniqueness. Real multi-connection InnoDB tests remain required.

## Database Changes
Forward-only migration `20260909080000` creates six logistics tables with reference, event, lookup, and uniqueness indexes.

## Tests
Unit tests cover all primary legal/illegal transitions, owner-derived rider authorization, address injection rejection, failure reason validation, and location ranges.

## Remaining Known Issues
Real migrations/concurrency, durable notification fan-out, upload storage, pagination tuning, and assignment race testing require staging. No external courier or real-time GPS system exists.

## Phase 9 Prerequisites
Apply migrations on restored staging, seed permissions/rider profiles, validate real concurrent allocation/assignment/delivery requests, proof uploads, notification idempotency, and return receipt handoff.

Module 16 AI Customer Support Chatbot remains intentionally outside this backend and will be developed separately.