doormile_backend/docs/CHANGELOG.md

Doormile Backend — Changelog & Summary of Recent Changes

This document provides a comprehensive log of the major features, architectural upgrades, schema modifications, and API changes recently implemented in the doormile_backend.

---

1. Customer App v1 API Rebuild (doormile_cx)

The customer-facing surface was completely rebuilt from the legacy single-destination / PIN-based flow to the production Customer App v1 contract.

Key Additions & Refactorings:

• Authentication (controllers/cxAuthController.go):
  • Replaced legacy PIN authentication with 4-digit OTP verification via SMS/Email (/customer/auth/send-otp, /customer/auth/verify-otp).
  • Refresh token rotation and session management (/customer/auth/refresh, /customer/auth/logout, /customer/auth/logout-all).
  • Profile management and saved delivery locations (/customer/profile, /customer/locations).
• Multi-Destination Booking & Fanout (controllers/cxBookingController.go, controllers/cxPickupFanout.go):
  • Support for multi-stop pickups and multi-destination consignments under single parent bookings.
  • Pickup fanout algorithm ensuring correct route clustering and assignment creation.
• Dynamic Fare Engine (controllers/cxFareController.go):
  • Automated distance-based, weight-tiered, and peak-hour pricing calculations (/customer/fare/estimate).
• Stage Rollup & Tracking Lifecycle (internal/cxstage/stage.go, controllers/cxBookingView.go):
  • Unified lifecycle status machine mapping complex internal consignment and hub states to simplified customer stages (created, assigned, arrived, picked_up, at_hub, out_for_delivery, delivered, cancelled).
  • Strict 5-minute cancellation window enforced server-side.
• Public Reference Obfuscation (controllers/cxIdentifiers.go, controllers/cxIdentifierScramble.go):
  • Replaced sequential database ID leaks in public endpoints with collision-resistant Sqids/hash tokens.
• Catalogue, Serviceability & Places (controllers/cxCatalogueController.go, controllers/cxPlacesController.go):
  • Dynamic serviceability limits, slot schedules, and parcel category catalog queries (/customer/catalogue, /customer/serviceability/limits, /customer/serviceability/slots).
  • Places autocomplete proxy and reverse geocoding (/customer/places/autocomplete, /customer/places/reverse-geocode).
• Push Device Token Registry (controllers/cxDeviceController.go):
  • FCM/APNS device token registration for push notifications (/customer/devices/register, /customer/devices/deregister).
• Ops Staging Overrides (controllers/cxOpsController.go):
  • Development and QA testing endpoint for simulating order stage transitions in non-production environments (POST /ops/bookings/:ref/stage).

---

2. Logistics Base Handover & Hub Routing

• Logistics Handover (controllers/logisticsHandoverController.go):
  • Handover workflows between milers and logistics bases / hubs.
  • Audit logging of parcel check-ins and handoffs.
• Hub Inbound Processing (controllers/hubInboundController.go):
  • Bag scanning, parcel inwarding, and multi-hub dispatch reconciliation.
• Leg Optimizer & Routing (internal/legs/legs.go, internal/routing/optimizer.go):
  • Multi-hop inter-hub routing and transit leg calculations.

---

3. Miler App & Assignment Enhancements

• Arrival Confirmation Facts:
  • Added support for reachedat / arrivedat timestamps on booking assignments and miler action payloads.
• Miler POD S3/Spaces Upload (internal/storage/spaces.go):
  • Presigned upload URL generation (/miler/uploads/sign) allowing milers to upload Proof of Delivery photos directly to object storage.
• Tenant Context:
  • Exposed tenantname in verify-pin and miler profile responses.
• Consignment Status Check Expansion:
  • Updated database checks to permit Collected_By_Miler and Cancelled statuses.

---

4. Middleware, Observability & Core Utilities

• Request ID & Structured Logging (middlewares/requestid.go, middlewares/logger.go):
  • Correlation IDs attached to incoming requests and structured log entries.
• Epoch Timestamp Conversions (utils/epoch.go):
  • Standardized millisecond/second epoch converters for unified JSON responses.
• Database Migrations & Models (models/customer_app.go, migrations/migrate.go):
  • Database schema migrations for customer auth tokens, devices, OTP logs, and extended booking columns.

---

5. Comprehensive Test Suite

Added automated test suites covering all new and modified packages:

• controllers/cxCustomerApp_test.go — Customer auth, booking creation, and validation tests.
• controllers/cxHttp_test.go — End-to-end HTTP endpoint tests.
• routes/routes_customer_test.go — Route registration and regression guards.
• internal/cxstage/stage_test.go — Lifecycle state rollup logic and cancellation-window enforcement.
• utils/epoch_test.go — Epoch timestamp validation.
• controllers/logisticsHandover_test.go & controllers/logisticsRouting_test.go — Handover and routing tests.