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.

tests/unit/logistics.state.test.js

@@ -0,0 +1 @@
+const state=require("../../app/services/logistics/shipmentState.service");describe("Phase 8 shipment state machine",()=>{test.each([["PENDING","READY_FOR_ASSIGNMENT"],["READY_FOR_ASSIGNMENT","ASSIGNED"],["ASSIGNED","PICKUP_PENDING"],["PICKUP_PENDING","PICKED_UP"],["PICKED_UP","IN_TRANSIT"],["IN_TRANSIT","OUT_FOR_DELIVERY"],["OUT_FOR_DELIVERY","DELIVERED"],["OUT_FOR_DELIVERY","DELIVERY_FAILED"],["DELIVERY_FAILED","RESCHEDULED"]])("allows %s -> %s",(a,b)=>expect(state.canTransition(a,b)).toBe(true));test.each([["DELIVERED","PICKED_UP"],["CANCELLED","DELIVERED"],["PENDING","DELIVERED"]])("rejects %s -> %s",(a,b)=>expect(()=>state.assertTransition(a,b)).toThrow(/Illegal shipment transition/));});

tests/unit/logistics.validation-security.test.js

@@ -0,0 +1 @@
+const s=require("../../app/validation/logistics.schemas"),{authorizedAccountType}=require("../../app/middleware/permission.middleware");const input=body=>({body,params:{},query:{}});describe("Phase 8 validation and rider scope",()=>{test("shipment address cannot be supplied by client",()=>expect(()=>s.shipment.parse(input({orderId:"o",items:[{orderItemId:"i",quantity:1}],address:{recipient:"attacker"}}))).toThrow());test("delivery failure requires a reason code",()=>expect(()=>s.reason.parse(input({note:"failed"}))).toThrow());test("location validates geographic ranges",()=>expect(()=>s.location.parse(input({latitude:100,longitude:80}))).toThrow());test("customer cannot enter rider routes",()=>{const req={user:{accountType:"customer"}},res={status:jest.fn().mockReturnThis(),json:jest.fn()},next=jest.fn();authorizedAccountType(["rider"])(req,res,next);expect(res.status).toHaveBeenCalledWith(403);});});