SRV-37 — V2 — Tour optimisation & stock-system sync
Routing-engine based visit ordering with time windows; API synchronisation with HOCO's stock system.
| Field | Details |
|---|---|
| Task code | SRV-37 |
| Phase | P4 — V2 evolutions |
| Product scope | V2 |
| Status | Planned |
| Start | Sun 7 Feb 2027 |
| Due | Tue 9 Feb 2027 |
| Responsible | Anis — Full-stack developer |
| Co-responsible | — |
| Effort | 2.5 person-day(s) planned · 6 from scratch · size M |
| Area · app | Server · server |
| Depends on | SRV-34 |
| Unblocks | SRV-38 |
| Milestones | — |
Summary
Routing-engine based visit ordering with time windows; API synchronisation with HOCO's stock system.
Description
Two V2 items complete field and stock automation (cahier §11, §14.2; FLD-18, STK-09): automatic tour optimisation and API synchronisation with HOCO's existing stock system. Tour optimisation replaces the V1 nearest-neighbour recommendation with a routing engine that accounts for road distances, visit time windows, priorities and visit durations, behind the same admin.tours.recommendOrder operation. Stock sync replaces the V1 file import with a scheduled and/or webhook-based exchange: levels pulled from HOCO's system, platform movements pushed back, a reconciliation report and an explicit conflict policy. Out of scope: changes to the delegate app beyond consuming the same visit order.
Subtasks
| # | Subtask | Owner |
|---|---|---|
| 1 | Routing engine choice and setup (self-hosted OSRM/VROOM or a hosted routing API) with cost and data review | Anis |
| 2 | Optimisation request builder: start point, stops with coordinates, time windows, priorities, durations; result mapped to visit order | Anis |
| 3 | admin.tours.recommendOrder switched to the engine with fallback to nearest-neighbour on failure | Anis |
| 4 | Stock-system connector: authentication, level pull, movement push, retry and idempotency | Anis |
| 5 | Conflict policy (source of truth per field) and reconciliation report of differences | Anis |
| 6 | Sync schedule and monitoring (last sync, errors, drift alerts) | Anis |
Deliverables
- apps/server/src/modules/field/optimisation/{engine.ts,request-builder.ts}
- apps/server/src/modules/integrations/stock-sync/{connector.ts,reconcile.job.ts}
- Integration specification agreed with HOCO's stock system provider
Acceptance criteria
- For a sample tour the optimised order is never longer in road distance than the nearest-neighbour order and respects time windows (FLD-18)
- If the routing engine fails, the recommendation falls back to nearest-neighbour with a warning
- A stock change in HOCO's system is reflected in platform availability within the agreed sync interval (STK-09)
- Every reconciliation run produces a report and no movement is applied twice
Requirements covered
| Requirement | Title | Release |
|---|---|---|
| FLD-18 | Automatic tour optimisation (routing engine) | V2 |
| STK-09 | Synchronisation with the client's existing stock system (V1 import, V2 API) | V2 |
API surface
| Endpoint group | Operations |
|---|---|
| Field operations | 20 |
| Stock | 8 |
Test measures
- Benchmark on recorded V1 tours comparing distances
- Integration tests against the stock system sandbox or a recorded mock
Risks
- HOCO's stock system has no usable API — keep the V1 scheduled file import as the integration path
KPI
- Delivered by Tue 9 Feb 2027 within 2.5 person-day(s).
- Every acceptance criterion above demonstrated before hand-off; linked requirements' acceptance criteria pass.
- Zero open critical defects, permission gaps or data-integrity regressions at sign-off.
Generated from content/plan/tasks.json by scripts/generate-team-tasks.mjs. Dates are computed by the scheduler (Sunday–Thursday weeks, holidays excluded) — change the plan, not this page.
SRV-34 — V2 — Carrier API & WhatsApp Business integrations
Shipment creation and tracking webhooks with the selected carrier(s); WhatsApp Business templates for confirmations and reminders.
SRV-38 — V2 — Advanced analytics
Cohorts, reseller activity scoring, delegate benchmarking, demand trends by zone.