# 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.