# Backend changes & current flow — for Dharaneesh (2026-09-16)

Covers three things landed on `main` today: the **miler self-set-PIN** login
flow (needs app work), the **fixes made to the merged customer-app / base-handover
commits**, and the **test data seeded on the live DB**. `git pull` before you
start.

Commits: `ba2cd22` (review fixes), `dd0fa75` (miler PIN flow), `5e5230e` (seed).

---

## 1. Miler login — self-set PIN on first login  *(app change needed)*

Riders now **create their own PIN the first time they log in**, instead of the
console assigning a shared `1234`. The login endpoint tells the app which screen
to show.

### Flow

```mermaid
flowchart TD
    A["Rider enters phone number"] --> B["POST /miler/login"]
    B --> C{"account found & active?"}
    C -- "not found" --> D["404 — no miler account"]
    C -- "inactive / not a miler" --> E["403"]
    C -- "yes" --> F{"pin_set ?"}
    F -- "pin_set: false" --> G["Show SET-PIN screen"]
    F -- "pin_set: true" --> H["Show ENTER-PIN screen"]
    G --> I["POST /miler/set-pin {phone, new_pin}"]
    I --> J["200 — logged in (token + user)"]
    H --> K["POST /miler/verify-pin {phone, pin}"]
    K --> L["200 — logged in (token + user)"]
```

### Endpoints

**`POST /miler/login`** — unchanged request, new `pin_set` field in the response.

Request:
```json
{ "phone": "8000000001", "configid": 1001 }
```
Response (200):
```json
{
  "success": true,
  "message": "PIN verification required",
  "phone": "8000000001",
  "pin_set": false
}
```
- `pin_set: false` → route to the **Set-PIN** screen.
- `pin_set: true`  → route to the **Enter-PIN** screen (existing behaviour).
- `404` = phone not registered; `403` = account inactive / not a miler.

**`POST /miler/set-pin`** — NEW. First-time PIN creation, self-service.

Request:
```json
{ "phone": "8000000001", "new_pin": "1234", "configid": 1001, "device_token": "<fcm>" }
```
Response (200) — **the rider is logged in immediately**, same shape as verify-pin:
```json
{
  "success": true,
  "token": "<jwt>",
  "tenantid": 1,
  "tenantname": "Doormile Coimbatore Logistics",
  "user": { "userid": 46, "authname": "...", "contactno": "...", "profile": { ... } }
}
```
- `409` if the account **already has a PIN** — send the rider to Enter-PIN instead.
- `404` phone not registered; `403` inactive / not a miler.

**`POST /miler/verify-pin`** — unchanged. Used when `pin_set: true`.

### Notes for the app
- Branch on the **`pin_set` boolean**, not on the message string.
- `set-pin` returns a full session (token + user) — no need to call `verify-pin`
  afterwards.
- The console **no longer sends a PIN** when creating a rider (the backend
  ignores any `password` field on `CreateMiler`). New riders always start with
  no PIN and set it on first login.
- The **6 existing riders keep their current `1234` PIN** (deliberate) — they
  report `pin_set: true` and go straight to Enter-PIN. Only newly created riders
  use the set-PIN screen.

### Security note (for later)
`set-pin` is self-service and can't overwrite an existing PIN, so it can't take
over an active account. The only residual gap is a brand-new, never-logged-in
account being claimed by whoever knows the phone first. Close it by OTP-gating
`set-pin` **once the SMS gateway is live**.

---

## 2. Fixes to the merged customer-app / base-handover work

Reviewed the 10 merged commits — the OTP/auth, IDOR/tenant scoping, CHECK
constraints and pagination were solid. These defects were fixed (`ba2cd22`):

| Severity | What was wrong | Fix |
|---|---|---|
| **HIGH (money)** | `CreateCxBooking` let the request body's `estimate` set the billed price with no server check; it flows into `Estimatedprice` → `ridercharges` (miler pay + tenant bill). `estimate:{min:1,max:1}` settled a delivery at ₹1. | Client estimate is honoured only when within **15%** of the server quote; otherwise the server quote stands. |
| MED | Multi-destination handover freed the rider and closed the booking assignment after the **first** parcel, dropping the remaining stops and crediting one leg. | Assignment closes / rider frees only when **no parcel of the booking is still in their hands**. |
| MED | `inwardedat` / `completedat` written with `time.Now()` (UTC) instead of `DBNow()` (IST) → ~5h30 off, skewing earnings/reconcile windows. | Switched to `DBNow()` in the handover, inbound-scan, reconcile and pickup-complete paths. |
| MED | Customers got **two** "miler assigned" pushes on auto-assign (two token stores) and **none** on manual assign. | One `cxstage.Notify` on both paths. |
| LOW | `ReconcileHubInbound` could return 200 with a silently-missing audit row. | Wrapped in a transaction; audit inserts checked. |
| LOW | `CxLogout` returned `signedOut:true` even when the token revoke failed. | Returns 500 on a failed revoke. |
| LOW | A rider-named handover base far from their location silently rerouted the parcel to another city. | Rejected when the named base is >50 km from the rider's reported position. |

### One thing to confirm your side
The `CX_STAGING_OTP` fixed-code OTP bypass is gated only on `ENV == "production"`.
Confirm the live k8s manifest sets `ENV=production` **exactly**, or the bypass is
reachable in prod.

---

## 3. Test data seeded on the live DB

`scratch/seed_test_data.go` (committed, idempotent, safe to re-run) has been run
against live. Available now:

- **Test riders — NO PIN** (for the set-PIN flow): phones `8000000001`,
  `8000000002`, `8000000003` (Coimbatore).
- **Test customer:** phone `9000000001`.
- **Sample multi-destination booking `DM-SEED-CX-001`** — one Coimbatore pickup →
  two destinations (Chennai, Bengaluru), two consignments in the rider's hands,
  assigned to `8000000001`. Use it to test the base-handover fix: inwarding the
  first parcel must **not** free the rider while the second is still carried.
- Reference serviceable **states / districts** (TN, KA, KL; CBE, CHN, BLR, EKM),
  the base/hub network, a tenant location, and pricing.

---

## Quick test path

1. Miler app → enter `8000000001` → expect `pin_set: false` → Set-PIN screen →
   set a PIN → land logged in.
2. That rider sees booking `DM-SEED-CX-001` with two destinations.
3. Hand over parcel #1 at a base → rider stays on the job (assignment open).
4. Hand over parcel #2 → assignment closes, rider freed, both legs credited.