From f531b424563cac15ffafcc35ba8c63cd851f69eb Mon Sep 17 00:00:00 2001 From: dharaneesh-r Date: Mon, 7 Sep 2026 16:52:44 +0530 Subject: [PATCH] updates on the md files --- docs/CHANGELOG.md | 80 ++++++++++++++++++++++++++++++++++++++++++ docs/DEV_ONBOARDING.md | 4 +++ docs/miler-app-api.md | 5 +-- 3 files changed, 87 insertions(+), 2 deletions(-) create mode 100644 docs/CHANGELOG.md diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 0000000..cbe9996 --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,80 @@ +# 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. diff --git a/docs/DEV_ONBOARDING.md b/docs/DEV_ONBOARDING.md index 537edfd..83ac70b 100644 --- a/docs/DEV_ONBOARDING.md +++ b/docs/DEV_ONBOARDING.md @@ -13,6 +13,10 @@ things a new dev (or a fresh Claude session on another machine) needs: Related docs already in this repo: - [`CLAUDE.md`](../CLAUDE.md) — the full project memory (architecture, data model, route surface). Start there for *what the system is*. +- [`docs/CHANGELOG.md`](CHANGELOG.md) — summary of recent backend changes and new endpoints. +- [`docs/customer-app-api.md`](customer-app-api.md) — Customer App v1 API design and endpoint specs. +- [`docs/customer-api-testing.md`](customer-api-testing.md) — step-by-step test guide and curl references for customer endpoints. +- [`docs/openapi-customer.yaml`](openapi-customer.yaml) — OpenAPI 3.0 specification for customer API. - [`docs/doormile-flow.md`](doormile-flow.md) — end-to-end booking/assignment flow. - [`docs/miler-app-api.md`](miler-app-api.md), [`docs/express-console-api.md`](express-console-api.md) — API contracts. - [`docs/logistics-base-handover.md`](logistics-base-handover.md) — the pickup-source diff --git a/docs/miler-app-api.md b/docs/miler-app-api.md index 845e0b3..391fa9d 100644 --- a/docs/miler-app-api.md +++ b/docs/miler-app-api.md @@ -48,13 +48,14 @@ Credential endpoints share a **10/min** rate limit. --- -## Profile & device +## Profile, device & uploads | Method | Path | Body | |---|---|---| -| GET | `/miler/profile` | | +| GET | `/miler/profile` | Exposes `tenantname`, profile details, vehicle info | | PUT | `/miler/profile` | `{ displayname, profilephotourl, defaultvehicletype, phone }` | | PUT | `/miler/device-token` | `{ "device_token": "..." }` — snake_case | +| POST | `/miler/uploads/sign` | `{ "content_type": "image/jpeg", "kind": "pod" }` → `{ "upload_url": "...", "key": "..." }` | ## Location & availability