SRV-10 — Geography & zones module
Wilaya/commune reference endpoints with ETag caching, zones and their membership, distance helpers.
| Field | Details |
|---|---|
| Task code | SRV-10 |
| Phase | P1 — V1 build & integration |
| Product scope | V1 |
| Status | Done (Mon 19 Oct 2026) |
| Start | Mon 19 Oct 2026 |
| Due | Mon 19 Oct 2026 |
| Responsible | Anis — Full-stack developer |
| Co-responsible | — |
| Effort | 0.25 person-day(s) planned · 2 from scratch · size XS |
| Area · app | Server · server |
| Depends on | SRV-06 |
| Unblocks | SRV-14 |
| Milestones | — |
Summary
Wilaya/commune reference endpoints with ETag caching, zones and their membership, distance helpers.
Description
Addresses, zones, delegate scopes, support regions and maps all rely on the official geography (GEO-01…GEO-03, cahier §4.1, §4.5, §6). This task exposes the wilaya and commune reference (reference.wilayas, reference.communes, public, FR/AR names, with ETag and long Cache-Control so apps cache them), implements zones as groups of wilayas and communes (Zone, ZoneArea) assigned to delegates (DelegateZone) through admin.zones.crud, and provides geo helpers: the GPS capture schema (lat, lng, accuracy, capturedAt), haversine distance, and nearest-commune resolution from coordinates using commune centroids (used by check-in tolerance in SRV-21 and by the device-location fallback of the regional WhatsApp button in SRV-24). Out of scope: the zone map editor UI (DSH-08, BO-19) and support regions (SRV-24).
Subtasks
| # | Subtask | Owner |
|---|---|---|
| 1 | reference.wilayas and reference.communes with FR/AR names, codes, centroids, ETag and Cache-Control: max-age | Anis |
| 2 | Commune centroid dataset seeded and versioned | Anis |
| 3 | Zone and ZoneArea model services (membership by wilaya or by commune, overlap detection) and admin.zones.crud | Anis |
| 4 | DelegateZone assignment with history; zone resolution for a reseller from their commune | Anis |
| 5 | Shared GpsFix Zod schema (lat, lng, accuracyM, capturedAt) and plausibility checks | Anis |
| 6 | Geo helpers: haversine distance, nearest commune from coordinates (bounding-box prefilter + distance), commune → wilaya | Anis |
| 7 | Zone change events consumed by delegate scope cache and sync.delta | Anis |
Deliverables
- apps/server/src/modules/geo/{reference.router.ts,zones.service.ts,zones.router.ts,geo.ts}
- packages/shared/src/geo.ts (GpsFix schema, haversine)
- packages/db/src/seed/data/communes.json with centroids
Acceptance criteria
- reference.communes returns 304 Not Modified when the client sends the current ETag
- Every commune belongs to exactly one wilaya and has FR and AR names (GEO-01)
- Creating a zone that overlaps another delegate's zone returns a warning in details but is allowed only with field.administer
- Nearest-commune resolution returns the right wilaya for sample points in Algiers, Oran, Constantine and Ouargla
- Haversine distance matches a reference implementation within 1 m over 10 km
Requirements covered
| Requirement | Title | Release |
|---|---|---|
| GEO-01 | Official wilaya and commune reference (FR/AR names) used by addresses, zones and filters | V1 |
| GEO-02 | Zones grouping wilayas and communes, assigned to delegates | V1 |
| GEO-03 | GPS capture standard (lat/lng, accuracy, timestamp) and distance computation | V1 |
| GEO-04 | Address geocoding / reverse geocoding through the maps provider | V1 |
Screens
| Screen | Name | App |
|---|---|---|
| BO-19 | Zones (list + map editor) | BO |
API surface
| Endpoint group | Operations |
|---|---|
| Me, devices, app config & reference data | 9 |
| Field operations | 20 |
Test measures
- Unit tests for haversine and nearest-commune on fixed coordinates
- Integration test for zone membership and delegate scope resolution against Postgres
Risks
- Centroid-based resolution is wrong near wilaya borders — acceptable for support routing (user can pick a wilaya) and not used for anything legal
KPI
- Delivered by Mon 19 Oct 2026 within 0.25 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-19 — Promotions & banners module
Promotions (percent, amount, fixed price) on products/categories/brands, targeting, schedule, stock cap, stacking rules, daily offers and banners, applied by the cart engine.
SRV-14 — CRM module — resellers, prospects, lifecycle, tasks
Reseller records, unique normalised phone, lifecycle automation from events, assignment, segments, interaction timeline, follow-up tasks, documents/photos, validation queue.