feat: Implement Phase 8 Delivery and Rider Management

- Introduced new Delivery and Rider API documentation.
- Added new models for RiderProfile, Shipment, ShipmentItem, ShipmentAssignment, ShipmentEvent, and ShipmentProof.
- Developed controllers for admin and rider logistics, including shipment management and rider actions.
- Created services for handling shipment creation, assignment, and state transitions.
- Implemented validation schemas for shipment and rider operations.
- Added new routes for admin and rider logistics, including tracking endpoints.
- Established a state machine for shipment status transitions.
- Created migration scripts for new database tables and relationships.
- Added unit tests for shipment state transitions and validation security.

Documentation/PHASE_8_DELIVERY_RIDER.md

@@ -0,0 +1,87 @@
+# 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.