SRV-21 — Field operations module — objectives, tours, visits, reports

SummaryCopy Anchor Link

Objectives, tour planning and lifecycle, visits with GPS check-in tolerance, checklists, photos, structured reports that create follow-ups, location pings, closing summary/KPIs, recommended visit order.

DescriptionCopy Anchor Link

Field operations are the second pillar of the cahier (§4.5, §6.1–§6.9; FLD-01…FLD-17, FLD-19): delegates follow planned tours, check in at points of sale, run checklists, take photos, write structured reports and close their day, while the back-office follows them live. This task implements objectives per delegate and period (ObjectiveMetric, ObjectivePeriod), tour planning with ordered stops, priorities, time slots and ordering mode (IMPOSED/RECOMMENDED with a nearest-neighbour recommendation), the TourStatus lifecycle (only the assigned delegate starts it; suspend/resume with reason), visits with the VisitStatus lifecycle and GPS check-in tolerance (150 m with accuracy ≤ 100 m by default), checklists per visit type, mandatory photos by type, notes, the structured VisitReport that creates follow-up CrmTasks automatically, not-done reasons, visit locking and unlock, location pings only while a tour is IN_PROGRESS (90-day retention), closing preview and definitive close with reopen, and delegate home, performance and reports. Business days are computed in Africa/Algiers. Out of scope: offline replay mechanics (SRV-23), invitations (SRV-22), field pages (DSH-08).

SubtasksCopy Anchor Link

DeliverablesCopy Anchor Link

• apps/server/src/modules/field/{objectives,tours,visits,checklists,reports,location,closing,delegates}.{service,router}.ts and jobs.ts
• packages/contracts/src/{delegate/day.ts,delegate/tours.ts,admin/field.ts}
• Field rules page /docs/srs/business-rules (field section) confirmed with the settings keys

Acceptance criteriaCopy Anchor Link

• Only the assigned delegate can start a tour; another delegate gets 403 OUT_OF_SCOPE (FLD-04)
• A check-in 220 m from the store with tolerance 150 m returns 422 CHECKIN_OUT_OF_TOLERANCE unless out-of-tolerance check-in is allowed, in which case the visit is flagged (FLD-07, FLD-08)
• Ending a visit of a type with mandatory photos and no photo returns 422 VISIT_PHOTO_REQUIRED; a not-done visit without reason is refused (FLD-08, FLD-09)
• A report with next action PHONE_FOLLOW_UP and a date creates a CrmTask for the delegate due that date (FLD-10)
• Closing a tour with visits still PLANNED returns 422 TOUR_HAS_OPEN_VISITS; a closed tour is read-only unless reopened (FLD-12)
• Location pings outside an IN_PROGRESS tour are rejected and pings older than 90 days are purged (FLD-15)
• The recommended order is the nearest-neighbour sequence from the start point (FLD-17)

Requirements coveredCopy Anchor Link

ScreensCopy Anchor Link

API surfaceCopy Anchor Link

Test measuresCopy Anchor Link

• Unit tests for tolerance, nearest-neighbour ordering and Africa/Algiers day boundaries
• DB tests for tour and visit lifecycles including suspend/resume and reopen
• E2E with the delegate app on staging: full tour from start to close

RisksCopy Anchor Link

• GPS accuracy in dense urban areas or indoors exceeds 100 m — allow-out-of-tolerance setting with a flag reviewed in the back-office instead of blocking the delegate
• Battery drain from location sampling — sampling only during IN_PROGRESS, every 5 min or 200 m, documented for Imad

KPICopy Anchor Link

• Delivered by Mon 19 Oct 2026 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.