# # NexGate Shipping Service — Build Plan Development How we build `docs/shipping/SHIPPING_SERVICE_DESIGN.md` (the "design", § numbers below point to it). Status: **plan agreed to start, nothing built yet.** Built on the Location Service (done: wards, shop locations, user addresses, frozen places). ## Ground rules for every step - **Talk first, then build** — each step starts with a short talk on its details, then code. - **Code standard**: new top-level package `shipping_service/` (same level as `location_service/`), the project's controller / service / service/impl / payload / entity / repo shape, no boilerplate, comments only where needed. - **Existing responses**: add fields; reshape only when agreed (dev phase) and always recorded. - **Every change recorded** in `commerce_logistics_changes.md` — before / after, examples, app to-do. - **Design doc kept true** — any decision that changes during a step is updated in the design. - **Settings**: fixed rules in properties (`shipping.*`), per-shipper agreement settings in the database (§6.7.1). - **Money**: every money move goes through the ledger; every step that moves money ends with the ledger balance check. - **Tested live** locally after each step (like the location steps), using the worked scenarios (§17) as test cases. - **Phase-0 hooks** (§15b) are built in from the start: attempt records, failure reason codes, the extra statuses, timers as data, reverse legs allowed — even though their rules come later. ## The order at a glance | Step | Delivers | Real-world result after the step | |---|---|---| | **0** | Foundations | nothing visible; ground ready | | **1** | Pickup, end to end (with codes and "✓ It's what I ordered") | **buyers can buy and collect at the shop** | | **2** | Native shipper registration (KYC + Service Setup basics) | delivery businesses can sign up | | **3** | Door coverage, pricing, ETA | businesses describe where / how much | | **4** | Engine: estimation + quotation (single door leg) | buyers see real delivery costs | | **5** | Cart / checkout / agreement, escrow per part | **buyers pay real delivery** | | **6** | Job flow: offers, codes, statuses, release | **first real door-to-door deliveries** | | **7** | Reassignment, switching, cancelling, bulky mismatch | unhappy-but-common cases handled | | **8** | Reliability, reviews, auto-pause, upcoming orders | trust and planning | | **9** | Stations (single leg) | intercity: collect at a station | | **10** | Multi-shipper chains | shop → bus → door | | **11** | Group purchase and installments | shipping inside group / installment buys | | **12** | Free shipping (seller rules + campaigns) | "Free delivery" badges and filter | | **13** | Bolt integration | boda on demand in town | | **14** | Admin dashboard (screens) | ops tooling — **last** | | later | Notifications set · unhappy paths (§15a/b) · staging deploy | after the build | --- ## Step 0 — Foundations **Goal:** everything later steps stand on, with no behaviour change. - Package `shipping_service/` with sub-packages from §2 (empty shells added as each step needs them). - `shipping.*` properties with every value from §6.7.1 (read through one settings class). - **Shared opening hours** (§6.3): weekly ranges, special days, temporarily closed, cut-off, EAT, overnight; "is open at", "next opening", "add opening hours" helpers. Attached to **shops** now (§6.4): shop hours endpoints, "Open now / Opens Sat 09:00" on shop responses; shop **pause modes** (keep selling / stop orders, `SHOP_CLOSED`). - **Escrow table**: `part` (ITEMS / LEG), `legId`, `orderId` filled, **provider payee** (§12.1) — new columns only, current payments keep working (they are "ITEMS" parts). - **Product `bulky`** field (§8.1) — default false; category pre-tick later. - **File Thunder**: new upload types *business document* (private) and *business logo* (separate repo, small). - **Codes service**: 4 random digits, hashed, never logged, 5 tries → locked, regenerate (§11). Replaces the old `DeliveryConfirmation` code generator (and its plain-code log line). **Check:** existing checkout / orders / cart-escrow tests still pass; shop hours + pause visible; a code can be generated, verified, locked after 5 wrong tries, and never appears in logs. ## Step 1 — Pickup, end to end **Goal:** a buyer can buy, the seller prepares, the buyer collects with a code, money is released on confirmation. - Move Step-4 `e_commerce/fulfillment` (JSON) into `shipping_service/fulfillment` as a **table**; orders link to it (§2, §3.5). Frozen places stay inside the record. - **Shipping agreement entity** (§4.8): `shipping_agreement` + parties + changes; states DRAFT → PENDING → AGREED → DONE / CANCELLED. For pickup the only parties are the buyer and the seller. **Escrow parts move only on agreement events** from here on. - Order flow: seller **accepts** (24 opening hours, else auto-cancel + refund) → **Ready** → buyer told → **pickup at the counter**: buyer's code, seller enters it → *collected* (§3.1, §10). - **"✓ It's what I ordered"** releases **all** escrow parts in one transaction; **"⚠ Report a problem"** freezes them (§12.2). - Account setting: **code or "received" button** (§11). - Pickup statuses `placed → accepted → ready → collected → completed` (+ cancelled / expired); optional **pickup time** (shop opening hours, inside the window; reminder that morning). - **14-day collection** expiry with reminders (§3.1). **Cancel before the seller accepts** (§3.4a). **Seller cancel** at once (pop-up "I have already informed the buyer"; pickup before collected, delivery before Ready). - Recent pins recorded **after payment**, not at checkout (§4.4). - Admin endpoints needed from now: manual **release / refund** of an escrow part (§6.7.2) — `SUPER_ADMIN`, reason, audit log. **Check:** scenario **A** (§17) live: pay → accept → ready → code → collected → confirm → seller paid; 14-day expiry; seller cancel refunds; cancel before accept refunds; problem report freezes; admin release works and is logged. ## Step 2 — Native shipper registration **Goal:** a delivery business can sign up and get approved automatically. - **KYC** (§6.2 part 1): name, contact phone, **office location** (pin), business licence (file + number + expiry, unique number), director's NIDA (file + number), LATRA (file + number + expiry) → auto-approved `KYC_APPROVED`. - **Service Setup basics** (§6.2 part 2): profile (logo, description, WhatsApp, email, badge), service type (door / station), **hours** (shared piece, default Mon–Sat 08:00–18:00), limits (max value, bulky + extra, response window, heads-up). Setup checklist endpoint. - Statuses `KYC_APPROVED → LIVE ⇄ PAUSED`, `SUSPENDED`; documents private (owner + admin). - "Delivery business" mode in the app (owner only, §6.6) — endpoints for the owner's own business. - Admin endpoints: **suspend / lift** (§6.7.2). **Check:** register with all documents → auto-approved; duplicate licence number refused; documents not visible to others; checklist shows what's missing; suspend / lift logged. ## Step 3 — Door coverage, pricing, ETA **Goal:** a business says where it works, how much, how long — and goes LIVE. - **Location helpers** (in `location_service`): regions → districts → wards lists + search; coverage outline for the map. - **Coverage** (§7.1): ticked areas (region / district / ward), trips `WITHIN_EACH` / `WITHIN_AND_ACROSS`, "both ends inside", fast **area-code matching** (the spec's second core function, `areaMatch`). - **Pricing** (§8.1): distance bands (price + time each, ×1.3, last band = max distance), flat, value add-on ladder + max value, bulky extra, rounding up to 100. - Goes **LIVE automatically** when service type + coverage + pricing exist. - Delivery commission fee type (0%) in the fee table + per-shipper override with start date (§6.7.1). **Check:** the §7.1 crossing table (Sinza → Mikocheni with WITHIN_EACH vs ACROSS…) as tests; band and add-on maths incl. rounding; business flips to LIVE when complete. ## Step 4 — Engine: estimation + quotation (single door leg) **Goal:** buyers see real delivery options and costs. - Engine (§9): where → who (coverage) → filter (distance, value, bulky, hours / cut-off, paused) → cost + ETA → clean-up (dominated, outliers 3×) → labels 💰 ⚡ ⭐ (⭐ = price + time at launch) → order, top 5, fairness. - **ETA** (§8.2): from "shop ready", ranges, closed hours. - **Estimation** `POST /api/v1/shipping/estimations` (§4.5): `cost {from,to}`, `eta {from,to}`, pickup area; Redis cache shop-area → buyer-area (1 h). - **Quotation** (§4.1): live options for a shop's parcel and a destination (§4.2: saved / recent / pin; station recognition comes with step 9). - Product detail: live quotation for the viewer's address. **Check:** scenario **L** (cards) and the engine walk-throughs from the master guide (A, B, E) reproduce; cache hit on the second call; closed shipper shifts ETA instead of disappearing. ## Step 5 — Cart, checkout, agreement, escrow per part **Goal:** buyers pay the real delivery cost; money split into items + leg. - Cart (§4.3, §4.4): one destination per cart, per-shop quotation **held 5 days**, add-to-cart `fulfillment` + `dropoff`, defaults for a new shop, unsaved pin on the cart, re-quote on changes. - Checkout → **agreement** (§4.1, §4.8) with its **legs** (each leg escrow part points to one): editable on the checkout screen until paid (re-quote, wallet re-check), **locked once paid**. Buy-now uses the sheet's quotation. - **Escrow per part** (§12.1): items part → seller, leg part → shipper owner; release all on confirm. - **Seller fee on items + tax only**; delivery commission from the leg (§8.3). - `shippingByShop` now real costs (replaces the 0 placeholder). - What the app keeps vs the server (§4.6) honoured. **Check:** scenario **B** up to payment: escrows created per part with the right payees and fees; quotation older than 5 days refreshed; edit at checkout re-quotes; ledger balance check passes. ## Step 6 — Job flow, codes, delivery **Goal:** the first real door-to-door delivery from offer to release. - Seller accepts → **heads-up**; **Ready** → **offer** with response window (counted while open), **closed-shipper 4 h rule** (§10). - **Ready pop-up**: "I have packed it well" + "label / number is on the package" (recorded). - **Parcel number** created when the seller accepts (QR label generated by the app, or written on the box); scanned / typed at pickup → "✓ yours / ✗ wrong parcel"; shippers see the parcel, never the order (§11, §6.6). - Shipper: accept / reject (reason), timeout; active job steps; **pickup code** (seller verifies) and **delivery code** (shipper submits) or the buyer's button (§11); optional handover photos. - Shipper accept = **signs the agreement**; all signed → AGREED, parcel moves (§4.8). - Statuses door ladder (§3.2) incl. **heading to the shop** + phase-0 statuses. - Release on "✓ It's what I ordered": items → seller, leg → shipper (one transaction). - Shipper app endpoints for offers / jobs / earnings (§6.6), live push. **Check:** scenario **B** end to end; scenario **M** (a shipper's day) step by step; timeout counted; codes locked after 5 tries. ## Step 7 — Reassignment, switching, cancelling, bulky mismatch **Goal:** the common unhappy-but-normal cases. - **Reassignment** (§10a): rejection / timeout → that leg only; tiers **1 km → same district → buyer**; same-or-cheaper and not slower = automatic (escrow re-pointed, difference refunded); dearer / none → buyer decides; **loop guard 3 per order**; **buyer silent 24 h → pickup**; **chain safety net 24 h**; free-shipping caps recalculated; history kept. - **Switching** (§3.4): pickup → delivery (fresh quotation, pay, offer at once if Ready); delivery → pickup (before any shipper accepted, refund). - **Cancelling** (§3.4a): shipping-only until pickup — free before **heading to the shop**, wasted-trip fee (50% / Bolt's charge) after; whole order when the chain failed. - **Agreement changes** (§4.8): propose → affected parties approve → default on silence; **destination change** (accept new cost / keep old price / decline; no withdraw after pickup). - **Bulky mismatch** (§8.4): report before pickup, bulky-only reassignment, seller pays difference + 50% wasted trip, auto-flag after 2. - **Badly packed** refusal (§8.5): before pickup, photo, seller repacks + Ready again, seller pays 50% wasted trip. - Admin endpoints: force **reassign / cancel** (§6.7.2). **Check:** scenarios **D, F, G, H, N, O, P**; loop guard; silent buyer → pickup after 24 h; ledger balanced after every adjustment. ## Step 8 — Reliability, reviews, auto-pause, upcoming orders - **Reliability counters** (acceptance, on time, failed, broke binding) and **auto-pause** levels with the §14 table, grace period 10 offers, reasons shown. - **Reviews** like shops, verified only, owner replies, moderation (§14); shown in quotations. - **Two-way private ratings** (shipper rates buyer / seller). - **Upcoming orders** on the shipper dashboard, area-only until accepted (§6.6). - Real delivery times recorded (for after-launch ETA). **Check:** the §14 trigger table as tests (2 / 3 missed, 3rd pause in 7 days → suspended…); new shipper not paused inside the grace period; upcoming card hides the exact pin until accepted. ## Step 9 — Stations (reached by a door leg) - Stations (§7.2): pins with counter name, phone, hours; ≥ 1 per ticked area; **lines**; **reach 30 km** (per business override). - **Station-pair table** (price + time, both ways, pre-filled pairs) (§8.1). - Handover points (§7.2a): leg 1 always starts with a collection at the shop (option A) — either the station business **collects from shops** (areas + flat fee, 0 = free; one leg) or a door shipper brings it to the station (the **two-leg chain** door → station, built here); buyer collects at the destination station (station staff enter the buyer's code). Step 10 extends it to 3 legs, editing and re-confirms. - Station ladder (§3.3); quotation **meeting-point recognition** ("collect at Mbeya Bus Stand", §4.2). **Check:** a Mbeya → Morogoro trip as boda → bus (two legs) and as a bus company collecting free (one leg, ranked cheapest); no door shipper at the shop → no station route; pin within 1 km of a station offers "collect there"; empty pair = not offered. ## Step 10 — Multi-shipper chains - Chain building (§4.7): up to 3 legs, meeting points within 1 km, always next to single-leg options. - Quotation editing per leg: stop early, swap a leg's shipper, change a meeting point. - **All legs offered at Ready, nothing moves until all accept**; **binding after accept**; **re-confirm** when an accepted leg's time moves > 4 h (§10a 7a). - Shipper → shipper handover: "handed over" / "received" + that handover's code, optional photo (§11). - One escrow part **per leg**; release all together (§12). **Check:** scenarios **C, D, E** with three legs; one leg rejecting while others accepted; re-confirm triggered by a > 4 h move. ## Step 11 — Group purchase and installments - Group (§5): each member's own fulfillment and fee with their payment; refunds on fail / withdraw; moves with a transferred payment; price frozen at payment. - Installments (§5): immediate = fee with the down payment; layaway = choose and pay after the last instalment (reuses switch-to-delivery). **Check:** scenarios **J** and **K**. ## Step 12 — Free shipping - Seller rules (areas, minimum, cap, product override) and NexGate campaigns (areas, dates, cap, audience, shops, budget reserved at payment, auto-stop) (§13). - Stacking, the cheapest qualifying option free, faster pays the difference; campaign ledger account; seller share from the items part at release. - Estimation `freeDelivery` + card badge + "Free delivery to my area" search filter. **Check:** scenario **I**; campaign budget never overspent under parallel checkouts; refund returns budget. ## Step 13 — Bolt integration - Adapter (§6.5): OAuth2 token cache, estimations (boda, non-bulky, in-city), book at Ready (re-estimate, held price = max + 2%), cancel, webhooks (3 IPs + token) and polling fallback, state mapping, tracking link + driver details. - **Bolt ledger account**, monthly settlement record, receipt differences; **kill-switch** and **daily spend limit** (§6.7); seller pays a shop no-show. - Built and tested in Bolt's **sandbox** first. **Check:** sandbox flow (estimate → create → states → completed → receipt); NO_DRIVER_FOUND → reassignment; spend limit blocks new Bolt quotations; kill-switch hides Bolt immediately. ## Step 14 — Admin dashboard (last) Screens on top of the existing admin endpoints (§6.7.3): shippers + KYC documents, Bolt status and settlement, operations board, campaigns, reports (by area), audit log, `STAFF_ADMIN` / `SUPER_ADMIN` split. ## After the build - **New dedicated shipping notifications** (one set, after the shipping service). - **Unhappy paths** (§15a / §15b): auto-confirm window, delivery attempts + office hold, returns, disputes. - **Staging / production**: PostGIS image + `CREATE EXTENSION`, ward file, settings — at deployment. - After-launch items (§16). ## Dependencies ``` 0 ─► 1 ─► 2 ─► 3 ─► 4 ─► 5 ─► 6 ─► 7 ─► 8 │ ├─► 9 ─► 10 │ ├─► 11 │ ├─► 12 │ └─► 13 └─────────────────────► 14 (last) ``` Steps 9, 11, 12, 13 can be reordered after step 6 (each only needs the single-leg flow). 10 needs 9.