301 lines
21 KiB
Markdown
301 lines
21 KiB
Markdown
# Reverse Logistics — Analysis & Implementation Plan
|
||
|
||
Status: **Phases 1–3 built 2026-10-05 (uncommitted, not deployed)** — see §10.
|
||
Drafted 2026-10-05.
|
||
Scope: `doormile_backend` (rules + endpoints), `krow_talent_app` (ops console),
|
||
and the rider app (Flutter, separate team). The customer app is touched only
|
||
where noted.
|
||
|
||
Defaults below are **proposals**; every one marked ⚑ is an open decision
|
||
listed in §9.
|
||
|
||
---
|
||
|
||
## 1. What exists today (verified in code)
|
||
|
||
| Area | Finding | Where |
|
||
|---|---|---|
|
||
| Return statuses | `RTO_Initiated`, `Returned_to_Sender` are defined and **allowed by the DB constraint** — but **nothing in the code ever sets them** | `doormile_backend/constants/constants.go:91-92`, `migrations/migrate.go:124` |
|
||
| Return fields on the parcel | `Consignment` already has `Returnreason`, `Returninitiatedat`, `Returndeliveredat`, `Parentconsignmentid` — **all unused** | `doormile_backend/models/audit.go:70-73` |
|
||
| Failed delivery | Rider taps *skip* → `MilerSkipDelivery` adds 1 to `Attemptcount`, logs `Delivery_Skipped` history. After **3** attempts it opens an `Undeliverable` exception — and stops there. The parcel stays `Out_for_Delivery` with the rider; no return leg, no owner, client not told | `doormile_backend/controllers/milerAppController.go:990-1070` |
|
||
| Exception types | `Receiver_Refused`, `Undeliverable`, `Damaged`, `Lost`, `Misrouted`, `Missing_Contents` exist | `constants.go:186-195` |
|
||
| Rider "what next" | `nextActionForConsignment` maps status → rider action. `RTO`/`Returned` fall into `none` ("past this rider's leg") — so a rider is never asked to bring a parcel back | `controllers/logisticsHandoverController.go:233-251` |
|
||
| Admin status change | `PUT /admin/consignments/:id/status` accepts **any** status string with no transition rules (a separate bug: it can set `Delivered` on a cancelled parcel) | `controllers/adminController.go:3133-3190` |
|
||
| Console | Only traces: an `rto` badge tone (`components/ds/StatusBadge.jsx:47`), `rto → skipped` mapping (`api/doormile/queries.js:110`), a comment in `lib/orderFlow.js:108`. Status update offers only Out_for_Delivery / Delivered / Cancelled | `krow_talent_app/src/...` |
|
||
| Pricing | `Pricing` has base/per-km/per-kg/handling — **no return charge** | `models` Pricing |
|
||
| Customer returns (reverse pickup) | Not present anywhere | — |
|
||
|
||
**Conclusion:** the data model is mostly ready; the lifecycle, the rules, the
|
||
endpoints, the console screens and the rider task are all missing.
|
||
|
||
---
|
||
|
||
## 2. Scope
|
||
|
||
| Flow | Description | Phase |
|
||
|---|---|---|
|
||
| **A. RTO — Return to Origin** | Delivery fails → parcel goes back to the sender's pickup point (⚑ or a hub) | **Phase 1–3 (this plan)** |
|
||
| **B. Customer return** | Receiver sends a delivered item back; rider picks up from receiver, returns to sender | Phase 5 (later) |
|
||
| **C. Exchange** | Deliver new + collect old in one visit | Out of scope for now |
|
||
|
||
---
|
||
|
||
## 3. RTO lifecycle (proposed)
|
||
|
||
```
|
||
Collected_By_Miler / Out_for_Delivery
|
||
│ failed attempt (rider skip) → Attemptcount++ (as today)
|
||
│
|
||
├─ attempts ≥ N (⚑ default 3) ─┐
|
||
├─ ops "Initiate RTO" (console) ─┼─▶ RTO_Initiated
|
||
└─ (⚑ later) client request ───┘ returnreason, returninitiatedat set
|
||
history: RTO_Initiated
|
||
rider next action: return_to_sender
|
||
│
|
||
┌──────────────┼───────────────────────────┐
|
||
▼ ▼ ▼
|
||
rider returns ops "Re-attempt delivery" ops "Mark returned"
|
||
to sender (cancels the RTO) (manual close, e.g. hub drop)
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
Returned_to_Sender Out_for_Delivery Returned_to_Sender
|
||
returndeliveredat (attempts kept) returndeliveredat
|
||
```
|
||
|
||
Rules:
|
||
- RTO only from `Collected_By_Miler`, `Out_for_Delivery` (or `Inwarded_at_Hub` ⚑).
|
||
- `Returned_to_Sender` is terminal.
|
||
- Every transition writes `ConsignmentHistory` with actor + reason.
|
||
- Opening RTO resolves the linked `Undeliverable` exception (if any) with
|
||
resolution "RTO initiated".
|
||
- COD: a returned parcel collects nothing; `Codcollected` stays 0.
|
||
|
||
---
|
||
|
||
## 4. Backend — `doormile_backend`
|
||
|
||
| # | Change | Detail |
|
||
|---|---|---|
|
||
| B1 | **Transition guard** | One function `canTransition(from, to)` used by every consignment status write; `PUT /admin/consignments/:id/status` refuses illegal moves (also fixes the any-status bug). |
|
||
| B2 | `POST /admin/consignments/:id/rto` `{reason, note}` | Staff only. Sets `RTO_Initiated`, `returnreason`, `returninitiatedat`; history; resolves the Undeliverable exception; publishes NATS `consignment.rto_initiated`; notifies the rider. Idempotent. |
|
||
| B3 | `POST /admin/consignments/:id/rto/cancel` `{note}` | Back to `Out_for_Delivery` (re-attempt). |
|
||
| B4 | `POST /admin/consignments/:id/rto/complete` `{note}` | Ops closes it manually → `Returned_to_Sender`, `returndeliveredat`. |
|
||
| B5 | `GET /admin/returns?status&from&to&tenantid&hubid&pageno` | List for the Returns page: tracking no, client, sender, reason, attempts, initiated/returned times, rider, age. Tenant-scoped like other admin lists. |
|
||
| B6 | **Auto-RTO** in `MilerSkipDelivery` | When `Attemptcount ≥ RTO_AUTO_AFTER_ATTEMPTS` (env, ⚑ default 3; `0` = off) → call the same B2 logic instead of only opening an exception. |
|
||
| B7 | **Rider task** | New next action `return_to_sender`; `nextActionForConsignment(RTO_Initiated)` returns it; rider queue includes the return stop (sender's pickup coords). New `POST /miler/consignments/:id/return-complete` `{lat, lon, photourl?, receivedby}` → `Returned_to_Sender`. **Behind flag `MILER_RTO_FLOW_ENABLED`** (default off) — the deployed rider app doesn't know `return_to_sender`, same pattern as `MILER_HUB_HANDOVER_ENABLED`. |
|
||
| B8 | Booking/customer stage | For customer-app bookings, record the return in `cxstage`. ⚠ The customer app renders unknown stage keys as `booked`, so a new "returning" stage needs a client release — until then do **not** add a new key. |
|
||
| B9 | Tests | Transition table, each endpoint's gates (staff/tenant/owner), auto-RTO at N attempts, flag off/on rider queue, idempotency. Postgres-gated tests for the SQL. |
|
||
|
||
Schema: **none for Phase 1–3** (columns exist). ⚑ Return-to-hub needs one
|
||
additive nullable column (`returnhubid`) — Phase 4.
|
||
|
||
---
|
||
|
||
## 5. Console — `krow_talent_app`
|
||
|
||
| # | Change | Where |
|
||
|---|---|---|
|
||
| C1 | API + hooks: `initiateRto`, `cancelRto`, `completeRto`, `getReturns` + `useInitiateRto` … with invalidation of deliveries/returns keys | `src/api/doormile/endpoints.js`, `src/lib/doormileHooks.js` |
|
||
| C2 | **Deliveries page actions**: on failed / out-for-delivery rows — *Initiate RTO* (reason picker: Receiver refused, Address not found, Customer unavailable, Attempts exhausted, Other + note), *Re-attempt*, *Mark returned*. Show attempt count | `src/pages/doormile/deliveries/Deliveries.jsx` |
|
||
| C3 | **Status tabs**: add *RTO* and *Returned* tabs/counts (today `rto` collapses into `skipped`) | `queries.js` status map, `StatusBadge` |
|
||
| C4 | **Returns page** `/doormile/returns`: tabs Initiated · In return · Returned; filters (date, client, hub, reason); age/SLA column; XLSX export; nav entry under Fleet Ops (staff) | new `src/pages/doormile/returns/Returns.jsx`, `App.jsx`, `AdminLayout.jsx` |
|
||
| C5 | **Exceptions page**: an `Undeliverable` / `Receiver_Refused` exception gets a *Start RTO* button | `src/pages/doormile/exceptions/Exceptions.jsx` |
|
||
| C6 | **Order / consignment timeline** shows attempts, RTO start, return | booking detail drawer |
|
||
| C7 | **Reports**: return rate per client and per reason on Orders Summary | `src/pages/doormile/reports/` |
|
||
| C8 | Client (tenant) logins: read-only view of their own returns (no actions) | Returns page + role check |
|
||
| C9 | Tests: actions call the right endpoints, reason required, tabs/counts, Returns filters, client read-only | `tests/integration/` |
|
||
|
||
---
|
||
|
||
## 6. Rider app (Flutter — separate team)
|
||
|
||
- Handle next action `return_to_sender`: show the return stop, navigate to the
|
||
sender, "Returned" button → `POST /miler/consignments/:id/return-complete`
|
||
with location (+ optional photo / receiver name).
|
||
- Release before turning on `MILER_RTO_FLOW_ENABLED`. Until then, ops close
|
||
returns from the console (B4) and riders are told by push.
|
||
|
||
---
|
||
|
||
## 7. Phases & order
|
||
|
||
| Phase | Content | Repos | Depends on |
|
||
|---|---|---|---|
|
||
| **1** | B1 guard, B2–B5 endpoints, B9 tests | backend | — |
|
||
| **2** | C1–C5, C9 | console | Phase 1 deployed |
|
||
| **3** | B6 auto-RTO, B7 rider task (flag off) + rider app release, then flag on | backend + rider app | Phase 1 |
|
||
| **4** | Return-to-hub option (`returnhubid`), C6 timeline, C7 reports, C8 client view, return charges | all | decisions ⚑ |
|
||
| **5** | Flow B — customer returns (reverse pickup booking linked by `Parentconsignmentid`) | all + customer app | product spec |
|
||
|
||
Rough effort: Phase 1 ≈ 1.5–2 days · Phase 2 ≈ 2 days · Phase 3 ≈ 1 day backend
|
||
(+ rider app team) · Phase 4/5 to estimate after decisions.
|
||
|
||
---
|
||
|
||
## 8. Risks
|
||
|
||
- **Rider app compatibility** — a new next action unknown to the deployed app
|
||
must stay behind a flag (B7).
|
||
- **Customer app stage keys** — unknown keys render as `booked` (B8).
|
||
- **Ops discipline** — until the rider task ships, returns depend on ops
|
||
closing them in the console.
|
||
- **Existing any-status endpoint** — B1 changes its behaviour: callers that
|
||
relied on setting arbitrary statuses will now get 400. The console only
|
||
sends Out_for_Delivery / Delivered / Cancelled, which stay allowed.
|
||
- **Deploy** — no migration in Phase 1–3; Phase 4 adds one nullable column
|
||
(needs approval).
|
||
|
||
---
|
||
|
||
## 9. Open decisions ⚑
|
||
|
||
1. **Flows first:** A (RTO) only, then B? *(proposed: yes)*
|
||
2. **Return destination:** sender's pickup point, nearest hub, or per client?
|
||
*(proposed: sender for Phase 1; hub option in Phase 4)*
|
||
3. **Who starts RTO:** auto after N attempts (N = ?), ops, client, or all?
|
||
*(proposed: ops + auto after 3; client later)*
|
||
4. **Can RTO start from a hub** (`Inwarded_at_Hub`)? *(proposed: yes)*
|
||
5. **Return charges:** billed to the client? Same rate, fixed fee, or free?
|
||
*(proposed: decide before Phase 4; Phase 1–3 record only)*
|
||
6. **Rider app:** is the Flutter team available for B7, and when?
|
||
7. **Client visibility:** may tenants see their own returns? *(proposed: read-only)*
|
||
|
||
---
|
||
|
||
## 10. Implementation status (2026-10-05)
|
||
|
||
Built with the proposed defaults: return to the **sender**, started by **ops or
|
||
automatically after 3 failed attempts**, rider task **behind a flag (off)**.
|
||
Nothing is committed or pushed.
|
||
|
||
### Backend — `doormile_backend`
|
||
| Item | Where |
|
||
|---|---|
|
||
| RTO core: `startRTO`, `completeRTO`, cancel → previous status (recorded as `[from:<status>]` in the history remark), exception auto-resolve, rider push | `controllers/consignmentReturn.go` |
|
||
| `POST /admin/consignments/:id/rto` · `/rto/cancel` · `/rto/complete` (Doormile staff only) | `routes/routes.go` |
|
||
| `GET /admin/returns?status=initiated\|returned\|all&from&to&pageno&pagesize` (tenant-scoped; client logins read their own) | same |
|
||
| `POST /miler/consignments/:id/return-complete` — 403 `RTO_FLOW_DISABLED` unless `MILER_RTO_FLOW_ENABLED=true` | same |
|
||
| Status guard on `PUT /admin/consignments/:id/status` (unknown status, leaving Delivered/Cancelled/Returned, RTO statuses → 400) | `controllers/adminController.go` |
|
||
| Auto-RTO after `RTO_AUTO_AFTER_ATTEMPTS` (default 3, `0` = off) | `MilerSkipDelivery` in `controllers/milerAppController.go` |
|
||
| `MilerSkipDelivery` ownership now multi-destination safe (`milerConsignmentForRider`) — fixes skip on orders 2..N | same |
|
||
| Next action `return_to_sender` (flagged); rider consignment read adds `returning`, `can_return`, `return_reason`, `return_to` | `constants`, `logisticsHandoverController.go`, `milerAppController.go` |
|
||
| Tests: 7 unit + 5 route-gate tests | `controllers/consignmentReturn_test.go`, `routes/routes_rto_test.go` |
|
||
|
||
New env vars: `RTO_AUTO_AFTER_ATTEMPTS` (default 3), `MILER_RTO_FLOW_ENABLED`
|
||
(default off). **No schema change.** No customer-app stage key added (B8).
|
||
|
||
### Console — `krow_talent_app`
|
||
| Item | Where |
|
||
|---|---|
|
||
| API + hooks: `initiateRto`, `cancelRto`, `completeRto`, `getReturns`, `RTO_REASONS`; `useReturns`, `useInitiateRto`, `useCancelRto`, `useCompleteRto` | `src/api/doormile/endpoints.js`, `src/lib/doormileHooks.js` |
|
||
| Status mapping: `RTO_Initiated → rto`, `Returned_to_Sender → returned` (legacy `rto`/`returned` keys unchanged) + counts | `src/api/doormile/queries.js` |
|
||
| Shared dialogs: Start return (reason + note, pre-select), Re-attempt / Mark returned | `src/components/doormile/RtoDialogs.jsx` |
|
||
| Deliveries: **In return** + **Returned** tabs; Return to sender / Re-attempt / Mark returned (staff only); status-update and cancel hidden on returning rows | `src/pages/doormile/deliveries/Deliveries.jsx` |
|
||
| **Returns page** `/doormile/returns` (tabs, date range, search, export, pagination; read-only for clients); nav under Fleet Ops | `src/pages/doormile/returns/Returns.jsx`, `App.jsx`, `AdminLayout.jsx` |
|
||
| Exceptions: **Start return** on open Undeliverable / Receiver_Refused | `src/pages/doormile/exceptions/Exceptions.jsx` |
|
||
| Tests: 13 new; deliveries counts test updated | `tests/integration/returns.test.jsx`, `tests/api/deliveries.test.js` |
|
||
|
||
### Verified / not verified
|
||
- ✅ `go build`, `go vet`, all 17 backend packages; console suites pass except
|
||
the 13 Agent Studio tests already failing since the 2026-09-30 redesign;
|
||
console production build OK.
|
||
- ✅ **End-to-end on a real database (2026-10-05).** This ran on a throwaway
|
||
local stack: PostgreSQL 17.10 on 127.0.0.1, the backend built from this tree
|
||
with `MILER_RTO_FLOW_ENABLED=true`, and the console on a local port pointed
|
||
at it. Production was not touched.
|
||
- Browser, as staff:
|
||
- Return to sender (reason + note), then Re-attempt (back to
|
||
Out_for_Delivery), then Start again, then Mark returned. Result:
|
||
`Returned_to_Sender`, the rider's assignment `Completed`, and the full
|
||
status history.
|
||
- Exceptions → Start return pre-selects the reason, and the exception
|
||
leaves the list.
|
||
- The Returns page lists rows with correct India times.
|
||
- API:
|
||
- 3 skips start RTO automatically and resolve the Undeliverable exception.
|
||
- The rider read gives `next_action=return_to_sender` with `return_to`
|
||
set to the sender's coordinates.
|
||
- Rider return-complete closes the assignment.
|
||
- Every guard answers 400 / `INVALID_STATE` as designed.
|
||
- Client login: no return buttons on Deliveries; Returns is read-only;
|
||
`rto/cancel` and `rto/complete` return 403.
|
||
- Bugs the browser test found, all fixed:
|
||
1. Notify rider showed on returned and delivered rows. It is now hidden.
|
||
2. Exceptions didn't refresh after Start return. `RETURN_KEYS` now includes
|
||
the exceptions key.
|
||
3. The dialog subtitle from Exceptions read "Order consignment #…". It now
|
||
uses a `label` prop.
|
||
- Backend review (2026-10-05), fixed:
|
||
1. **Race conditions.** Start, complete and cancel used to read the parcel
|
||
and then save the whole row. A rider delivering at the same moment, or
|
||
a double click, could be overwritten. Each one is now a compare-and-set
|
||
(`moveConsignment`: update only if the status is still the one read).
|
||
A lost race either becomes the same no-op as a repeat, or returns
|
||
"changed, refresh".
|
||
2. **Re-attempt clears the return.** `returnreason` and
|
||
`returninitiatedat` are cleared, so a parcel delivered afterwards doesn't
|
||
carry a stale reason. The history keeps the reason.
|
||
3. **"OTHER" check.** A reason sent as "OTHER" or "Other " skipped the
|
||
note-required check. The check now uses the normalised reason
|
||
(`rtoReasonText`).
|
||
4. **Note length.** The 500 limit is counted in characters, not bytes.
|
||
Before, 200 Tamil characters were refused even though the console
|
||
allows 500.
|
||
5. **Wrong rider notified.** Starting a return on a parcel already handed
|
||
over at a base pushed "do not attempt delivery" to its old pickup rider.
|
||
Now only a rider holding the parcel is notified
|
||
(`riderHoldsParcel`: Created, Collected_By_Miler, Out_for_Delivery).
|
||
- Impact on existing users (checked 2026-10-05). Decide these before
|
||
deploying:
|
||
- **Rider app (deployed build):** it shows a parcel from the *booking*
|
||
status, which a return doesn't change. So a parcel in return still looks
|
||
deliverable; tapping deliver or skip returns a 400. The rider also can't go
|
||
off duty until ops press **Mark returned**, because the assignment stays
|
||
open. Automatic return is **on by default** (3 attempts), so this starts
|
||
on deploy. Either set `RTO_AUTO_AFTER_ATTEMPTS=0` until the rider app
|
||
supports returns, or make sure ops close returns daily.
|
||
- **Console "Update status":** Delivered and Cancelled parcels can no longer
|
||
be changed (400). Before, ops could undo a wrong "Delivered" or reopen a
|
||
cancelled parcel. That is now refused by design.
|
||
- **Customer app:** a returned parcel keeps showing "Out for delivery"
|
||
(there is no customer stage for returns).
|
||
- **Rider pay:** closing a return marks the assignment Completed with 0 km
|
||
and 0 charges. The return trip isn't paid.
|
||
- **Not affected:** rider delivered counts and reports (Delivered only), the
|
||
hub console (a parcel in return simply drops out of its status-based
|
||
lists), the B2C booking flow, the existing status values, and the
|
||
database schema (no change).
|
||
- Tests added: `TestRiderHoldsParcel`, `TestRTOReasonText`, plus `controllers/consignmentReturn_pg_test.go`
|
||
(5 tests on real Postgres: lifecycle, refusals, no overwrite of a
|
||
concurrent delivery, 10 simultaneous starts → one return, cancel). These
|
||
skip unless `REGISTRY_TEST_DSN` is set, and passed on PostgreSQL 17.
|
||
- Timestamps stay `time.Now()`, not `utils.DBNow()`. `AutoMigrate` creates
|
||
`timestamptz` columns, where `DBNow()` would store a time 5 h 30 m ahead.
|
||
`time.Now()` is correct for both column types because the Dockerfile sets
|
||
`TZ=Asia/Kolkata`.
|
||
- Seen, not fixed (pre-existing, outside RTO): the Exceptions page shows
|
||
"Raised" times about 6 h ahead of IST.
|
||
- Not built: Phase 4 (return-to-hub, timeline, reports, charges), Phase 5
|
||
(customer returns), the rider-app UI (Flutter team).
|
||
|
||
## 11. Phase 4, first part (2026-10-07)
|
||
|
||
Built the two Phase 4 items that need no product decision. Uncommitted.
|
||
|
||
| Item | Where |
|
||
|---|---|
|
||
| `GET /admin/consignments/:id/history`: every event of one parcel, oldest first, with who did it and at which base. The `[from:<status>]` bookkeeping tag is removed from the remark and returned as `fromstatus`. Client logins read their own parcels only. | `doormile_backend/controllers/returnInsights.go`, `routes/routes.go` |
|
||
| `GET /admin/returns/summary?from&to`: of the parcels created in the period (cancelled ones excluded), the return rate overall, per client and per reason, plus the average days a completed return took. Defaults to the last 30 days. Client logins get their own figures only. | same |
|
||
| **C6 timeline:** shared `ConsignmentTimeline`, shown in the Deliveries order drawer and behind a **History** button on every Returns row (clients included). | `src/components/doormile/ConsignmentTimeline.jsx`, `Deliveries.jsx`, `Returns.jsx` |
|
||
| **C7 report:** a summary on the **Returns page** (KPIs, return rate by client, reasons), driven by the page's date range. Clients don't get the per-client table. Placed on Returns rather than Orders Summary so that clients see it too. | `src/pages/doormile/returns/Returns.jsx` |
|
||
| Tests: 2 Postgres route tests (timeline order, actor, hub, scoping; summary rates, reasons, window, scoping) and 4 console tests. | `routes/routes_return_insights_pg_test.go`, `tests/integration/returns.test.jsx` |
|
||
|
||
Verified in the browser against a throwaway local database: summary figures, per-client and per-reason tables, and the timeline drawer.
|
||
|
||
Decision 2026-10-07 on return charges (open decision 5): **none for now.** Returns are free for every client. Revisit after 2–3 months using the return rates the Returns summary now shows. If a charge is introduced later, it should be per client, only for receiver- or client-caused returns, and never for damage or Doormile errors.
|
||
|
||
Still open in Phase 4 (needs a decision ⚑): return-to-hub (the `returnhubid` column).
|
||
|
||
Decision 2026-10-07 on Phase 5 (customer returns after delivery): **deferred.** Current clients are mainly food and medicine businesses, where returns after delivery are rare, and refunds are handled by the client. Build it when a client asks for it or when parcel/e-commerce clients are onboarded. Until then, ops handle the rare case by booking a normal order with the customer's address as pickup and the client as drop. The return button appears only on active orders (RTO, before delivery); `Delivered` stays terminal.
|
||
|