Field operations

These pages plan and follow the field work of the delegates (délégués commerciaux) (cahier §4.5). Delegates work in the offline-first delegate app. The back-office creates zones, objectives and tours (tournées), which sync to the app (SYN-01). It receives positions, visits, reports and closings in return, live through the event stream. Tour and visit statuses are TourStatus and VisitStatus.

Defaults used on these pages (tunable settings, several still open decisions):

• GPS check-in tolerance 150 m, with accuracy of 100 m or better.
• Location sampled only while a tour is IN_PROGRESS, every 5 minutes or 200 m.
• Positions kept 90 days.
• One tour per delegate per day: the delegate app shows a single « tournée du jour » (delegate.tours.today).

ID	Screen	Section	Template	Release	Design	Build
BO-16	Delegates list	Field	template	V1	Day 19	DSH-08
BO-17	Delegate detail & performance	Field	bespoke	V1	Day 19	DSH-08
BO-18	Delegate create / edit	Field	template	V1	Day 19	DSH-08
BO-19	Zones (list + map editor)	Field	bespoke	V1	Day 19	DSH-08
BO-20	Objectives	Field	template	V1	Day 19	DSH-08
BO-21	Tour planner (calendar)	Field	bespoke	V1	Day 19	DSH-08
BO-22	Tour editor (stops, order, recommendation)	Field	bespoke	V1	Day 19	DSH-08
BO-23	Tour live detail	Field	bespoke	V1	Day 19	DSH-08
BO-24	Visits list	Field	template	V1	Day 19	DSH-08
BO-25	Visit detail	Field	template	V1	Day 19	DSH-08
BO-26	Visit types & checklist templates	Field	template	V1	Day 19	DSH-08

BO-16 — Delegates listCopy Anchor Link

Purpose. List the delegates with their zones, today's tour and their month to date.

Who uses it. Commercial admin, direction, super admin.

Entry points. Terrain › Délégués, and delegate names anywhere in the back-office.

Layout.

• Filters: q, zone, wilaya, accountStatus, onTourToday (yes/no).
• Default sort: displayName ascending.
• Row actions: « Ouvrir » (BO-17), « Modifier » (BO-18), « Planifier une tournée » (BO-22 prefilled), « Suspendre » / « Réactiver ».
• Export: XLSX / CSV.

Data. admin.delegates.crud (GET list, PATCH status).

Actions.

• « Suspendre »: « Suspendre Yacine M. ? Il ne pourra plus se connecter à l'application délégué ; ses tournées planifiées restent à réaffecter. ». A reason is required. Sessions are revoked and the action is audited STATUS_CHANGE.
• « Réactiver »: confirmation, then audited.

Rules.

• A suspended delegate is refused at sign-in with an explicit message (AUTH-02).
• Their future tours are flagged « Délégué suspendu » in BO-21.

Real-time. tour.started and tour.closed update the Tournée du jour column.

States. First use: « Aucun délégué », with « Nouveau délégué ».

Acceptance criteria.

• The visits column matches BO-24 for the delegate and the current month.
• Suspending a delegate signs them out of the app at the next request, and BO-21 flags their future tours.

BO-17 — Delegate detail & performanceCopy Anchor Link

Purpose. Measure one delegate's results against their objectives (cahier §4.5 « Planifier l'activité terrain et mesurer les résultats commerciaux »), and see their tours, visits, resellers and invitations.

Who uses it. Commercial admin (one-to-ones, coaching), direction.

Entry points. BO-16, the classement table of BO-05, delegate links, and BO-06.

Layout.

• Header: avatar, name, code, phone, zones, account status, today's tour pill, app version, last sync, location consent date. Actions: « Modifier », « Planifier une tournée », « Réaffecter ses revendeurs ».
• Period selector: week, month (default), quarter or a custom range.
• Tabs:
  • Performance (default):
    • KPI cards:
      • Visites réalisées / planifiées and rate.
      • Inscriptions (prospects created).
      • Installations (invitations reaching APP_INSTALLED).
      • Comptes créés.
      • Premières commandes: attributed to the delegate (ORD-09).
      • Commandes and CA HT: counted orders attributed to the delegate, same basis as BO-04.
      • Taux de conversion (prospects → first orders).
      • Kilomètres (from tour trails).
      • Durée moyenne de visite.
      • Check-ins dans la tolérance (%).
    • Objective bars per ObjectiveMetric (target, actual, %).
    • Trend chart (visits and revenue per week).
  • Tournées: tours table (number, date, status, stops done/planned, km, closing comment). A row opens BO-23.
  • Visites: the BO-24 table filtered on the delegate.
  • Revendeurs: assigned resellers (BO-09 columns), with bulk « Réaffecter ».
  • Invitations: the funnel sent → installed → account → verified → catalog → first order, with counts and conversion between steps, and the invitation list.
  • Profil: zones, communes covered, start point, devices.

Data.

• admin.delegates.crud (GET one).
• admin.delegates.performance (from, to).
• admin.objectives.crud.
• admin.tours.list and admin.visits.list with delegate=.
• admin.resellers.list with delegate=.
• admin.invitations.list with delegate=.

Actions. « Réaffecter ses revendeurs » calls admin.resellers.bulk (ASSIGN) after « Réaffecter 86 revendeurs de Yacine M. à Samir K. ? ». It is audited per reseller, and both delegates are notified.

Rules.

• The figures use the same definitions as BO-04 and the delegate app's performance screen (FLD-19), so both show the same numbers.
• Revenue and orders are attributed through the order's delegate snapshot.
• Kilometres sum the straight-line distance between consecutive pings of the period's tours.

Real-time. visit.completed and tour.closed for this delegate refresh the Performance cards (debounced 10 s).

States.

• No tour in the period: « Aucune tournée sur la période ».
• No objective: « Aucun objectif défini », with a link to BO-20.

Acceptance criteria.

• For a given month, the figures equal the delegate app's « Mes performances » for the same month.
• First orders attributed through assisted orders count for the source delegate, even after the reseller is reassigned.
• « Réaffecter » moves all assigned resellers and records one ResellerAssignment per reseller.

BO-18 — Delegate create / editCopy Anchor Link

Purpose. Create a delegate account with its profile, zones and start point, or edit them.

Who uses it. Commercial admin, super admin.

Entry points. « Nouveau délégué » on BO-16, « Modifier » on BO-16 and BO-17.

Layout.

Data. admin.delegates.crud (POST or PATCH, with version), admin.zones.crud (GET).

Actions.

• « Créer le délégué » creates the User (type DELEGATE, role DELEGATE) and its DelegateProfile, then sends the temporary password by SMS when the box is ticked. Audited CREATE.
• « Enregistrer » is audited UPDATE.
• Removing a zone that holds planned tours or assigned resellers asks: « Retirer la zone Oran Est ? 12 revendeurs et 3 tournées planifiées sont concernés. »

Rules.

• The phone is unique across all users: 409 PHONE_ALREADY_EXISTS names the existing account type.
• Zone changes sync to the app at the next delta: points of sale outside the new scope disappear from the app.
• The location consent itself is given by the delegate in the app (DA-04). The back-office only displays it.

Real-time. None.

States. Unsaved changes are guarded. SMS sending failure shows « Délégué créé, mais l'envoi du SMS a échoué — Renvoyer les accès » (via admin.users.resetPassword).

Acceptance criteria.

• A new delegate receives the SMS, signs in to the delegate app, and must change the temporary password.
• After a zone is removed, the delegate no longer sees that zone's points of sale after sync.
• Reusing a staff user's phone is refused with a clear message.

BO-19 — Zones (list + map editor)Copy Anchor Link

Purpose. Group wilayas and communes into commercial zones and assign them to delegates (cahier §4.5 « Attribution des wilayas, communes et points de vente »).

Who uses it. Commercial admin, super admin.

Entry points. Terrain › Zones, and zone links from BO-16 to BO-18.

Layout.

• Left panel: the zone list (name, colour, delegates, number of communes, resellers, prospects), « Nouvelle zone » and a search field.
• Right: the map editor.
  • Commune polygons, coloured by zone. A commune outside any zone shows hatched grey.
  • Click a commune to toggle it in the selected zone. Shift-click selects a range. « Ajouter toute la wilaya » sits in the wilaya tooltip.
  • Above the map, a tree list (wilaya ▸ communes, with checkboxes) mirrors the map for keyboard use.
• Zone form (drawer):
  • Nom: required, unique.
  • Code: required, unique.
  • Couleur.
  • Délégués: multi-select.
  • Description.
  • Counts: communes, resellers, prospects, active resellers.

Data.

• admin.zones.crud.
• reference.wilayas and reference.communes.
• Commune boundaries come from a static GeoJSON shipped with the dashboard. Assumption — the dataset is still to choose; without polygons, the editor falls back to the tree list and commune centroids.

Actions.

• « Enregistrer la zone » (PATCH with the commune list) shows a summary first: « +4 communes, −1 commune ; 37 revendeurs changent de zone. »
• « Supprimer » is allowed only for a zone without delegates and without planned tours. Otherwise it is refused, with « Désactivez ou videz la zone d'abord ».
• Both are audited.

Rules.

• A commune belongs to at most one zone. Selecting a commune owned by another zone asks « Déplacer Bir El Djir de Oran Ouest vers Oran Est ? ». Assumption — overlapping zones are not supported in V1.
• Changing a zone updates the zone of the resellers it contains. Delegates' scopes follow at their next sync.

Real-time. None.

States. First use: « Créez votre première zone en sélectionnant des communes sur la carte. » A failed GeoJSON load falls back to the tree list.

Acceptance criteria.

• A commune cannot be in two zones at once.
• Adding a commune to a zone makes its points of sale visible to the zone's delegates after sync.
• The resellers count of a zone equals BO-09 filtered on that zone.

BO-20 — ObjectivesCopy Anchor Link

Purpose. Set targets per delegate and period for visits, sign-ups, installs, orders, first orders and revenue (cahier §4.5 « Objectifs de visites, inscriptions, installations et commandes »), and follow how far each delegate has got.

Who uses it. Commercial admin. Direction reads it.

Entry points. Terrain › Objectifs, and the objective bars of BO-17.

Layout.

• A matrix view:
  • Rows are delegates and columns are ObjectiveMetric values (Visites, Inscriptions, Installations, Premières commandes, Commandes, CA HT).
  • Each cell shows target, actual and a % bar (danger below 50 % past mid-period, success at 100 % or more).
  • The period picker (ObjectivePeriod: day, week, month) defaults to the current month.
• A list view toggle shows one row per objective.
• Drawer « Objectif »:
  • Délégué, or « Tous les délégués de la zone » (bulk create).
  • Indicateur, Période, Début de période.
  • Cible: integer 1 or more; amount in DA for revenue.
• Header action: « Reprendre les objectifs du mois précédent » (copies targets to the selected month).

Data. admin.objectives.crud. Actuals come with the list.

Actions.

• Create, edit and delete are audited. Deleting a running objective asks for confirmation.
• Copying shows « Créer 48 objectifs pour novembre 2026 à partir d'octobre ? »

Rules. Metric definitions:

• VISITS: visits DONE.
• SIGNUPS: prospects created by the delegate.
• APP_INSTALLS: invitations reaching APP_INSTALLED.
• FIRST_ORDERS: first orders attributed to the delegate.
• ORDERS and REVENUE: counted orders attributed to the delegate, net HT (same basis as BO-04).

An objective is unique per delegate, metric, period and start: 409 on a duplicate. Objectives sync to the delegate app (DA-22).

Real-time. None. Actuals refresh on focus.

States. No objective for the period: « Aucun objectif pour novembre 2026 », with the copy action.

Acceptance criteria.

• The actual of VISITS for a delegate and month equals BO-24's done count for the same filters.
• Copying last month's objectives creates exactly one objective per delegate and metric that existed.
• Duplicates are refused.

BO-21 — Tour planner (calendar)Copy Anchor Link

Purpose. Plan tours daily, weekly or monthly (cahier §4.5 « Planification quotidienne, hebdomadaire ou mensuelle »). See at a glance who works where and when, how far today's tours have got, and which points of sale still need a visit.

Who uses it. Commercial admin (planning, usually on Thursday for the next week), super admin. Direction reads it.

Entry points. Terrain › Tournées, « Planifier une tournée » on BO-16 and BO-17, and the tour links of BO-06.

LayoutCopy Anchor Link

• Toolbar:
  • Views « Jour », « Semaine » (default), « Mois ».
  • Previous / « Aujourd'hui » / next.
  • Filters Zone (zone), Délégué (delegate, multi), Statut (status), « Avec arrêts prioritaires ».
  • Primary action « Planifier une tournée ».
  • « Série récurrente ».
• Week view (resource timeline):
  • One row per delegate (avatar, name, zone) and one column per day, Sunday to Saturday. Friday and Saturday are shaded but still plannable. Today is outlined.
  • Tour chip in a cell:
    • TRN-2026-000045 and the TourStatus pill.
    • « 12 arrêts » (« 7 / 12 » once started).
    • The ordering-mode icon (padlock for IMPOSED, shuffle for RECOMMENDED).
    • « 2 prioritaires » when there are HIGH stops.
    • « Délégué suspendu » in danger when relevant.
  • An empty cell shows « + Planifier » on hover.
• Day view: one row per delegate with planned start, stops, km estimate, live progress bar and last-position age. A click opens BO-23.
• Month view: calendar grid with a small chip per tour, coloured by status (one delegate selected), or counts per day (several delegates).
• Right drawer « À planifier » (toggle):
  • Points of sale needing a visit in the filtered zone, in four groups:
    • follow-ups of type VISIT due by the end of the shown period (CRM-08);
    • prospects NEW_PROSPECT, TO_CONTACT or INTERESTED never visited;
    • resellers not visited for more than 30 days;
    • accounts awaiting validation (new points of sale).
  • Each item can be dragged onto a tour chip (adds a stop) or onto an empty cell (creates a tour with that stop).

ActionsCopy Anchor Link

A required free-text reason accompanies every cancellation.

RulesCopy Anchor Link

• One tour per delegate per day. A second tour on the same date is refused (409; Assumption: code TOUR_ALREADY_PLANNED), and its drop target is disabled.
• Dates: tours are planned for today or later. Past days are read-only.
• Statuses:
  • The PLANNED → TO_START transition is made by the 00:05 job on the tour's day (TourStatus).
  • Only the assigned delegate can start a tour (FLD-04). The back-office never starts, suspends or closes one.
• Moving tours: only PLANNED and TO_START tours can be moved or cancelled. The delegate cannot be changed on an existing tour (create a new one and cancel the old).
• Stops must be points of sale in the delegate's zones or assigned to them (403 OUT_OF_SCOPE otherwise), since the delegate could not open them in the app (ACL-03).
• Recurring series create independent tours; editing one does not change the others.
• Suspended delegates keep their tours, which are flagged for reassignment.

Data. admin.tours.list (from, to, zone, delegate, status), admin.delegates.crud, admin.tasks.list (type=VISIT), admin.resellers.list (backlog filters).

Real-time.

• tour.started and tour.closed update the chip pill.
• visit.completed updates « 7 / 12 ».
• No reload is needed, and an open drawer is not disturbed.

States.

• Loading: a skeleton grid with delegate rows.
• No delegate in the filtered zone: « Aucun délégué dans cette zone », with a link to BO-18.
• Empty week: « Aucune tournée planifiée cette semaine », with « Dupliquer la semaine précédente » (creates the same tours one week later, skipping dates that already have a tour).
• Drop refused: the chip shakes, with a tooltip giving the reason (out of scope, already planned, past date).

Acceptance criteriaCopy Anchor Link

• Week, day and month views show the same tours for the same filters. Each tour appears exactly once per day.
• Planning a second tour for the same delegate and day is impossible, both by drag and from BO-22.
• Dragging an overdue Nouvelle visite follow-up onto Monday's chip adds the stop. After sync, the delegate's app shows it in Monday's programme.
• When a delegate starts a tour, its chip turns En cours within 5 s.
• A recurring series every Sunday and Tuesday for 4 weeks creates 8 tours with the template's stops.

BO-22 — Tour editor (stops, order, recommendation)Copy Anchor Link

Purpose. Compose one tour: the ordered stops with their priority, time slot and visit type, an imposed or recommended order, and the nearest-neighbour recommendation (cahier §4.5 « Ordre manuel ou recommandé des visites »; §6.2).

Who uses it. Commercial admin.

Entry points. BO-21 (« Planifier », chip « Modifier »), « Planifier une visite » from BO-09, BO-10 and BO-11 (stops preselected), and « Modifier » on BO-23.

LayoutCopy Anchor Link

• Header form:

• Left panel, the stops list (drag handles, numbered):
  • Each row:
    • point of sale (name, REV, status pill, commune);
    • Priorité toggle (NORMAL / HIGH « Prioritaire »);
    • Créneau (from–to, optional);
    • Type de visite (select, defaulting to the visit type set in settings);
    • Objectif de l'arrêt (200 characters max);
    • distance from the previous stop (km, straight line);
    • estimated arrival time;
    • remove (✕).
  • Stops already DONE or NOT_DONE (tour in progress) are locked and greyed, with their status pill.
• Map (centre and right):
  • The start marker and numbered stop markers in list order, joined by a polyline.
  • Candidate points of sale of the delegate's scope as grey dots: click to add, lasso to add several.
  • Markers flash when their row is hovered, and the other way round.
• « Ajouter des arrêts » panel (tabs):
  • « Recherche »: scope-filtered search.
  • « Relances dues »: VISIT tasks due by the tour date.
  • « Prospects à visiter ».
  • « Non visités depuis 30 j ».
  • « Sélection carte ».
• Totals bar: number of stops, total straight-line distance, estimated duration (travel + visit durations), estimated end time.
• Warnings shown in the totals bar:
  • more than 25 stops (« Journée chargée »);
  • stops without GPS;
  • a stop already in another tour that day;
  • a time slot that cannot be met by the estimate.
• Footer: « Recommander l'ordre » (secondary), « Annuler », « Enregistrer la tournée » (primary).

Recommended orderCopy Anchor Link

1. « Recommander l'ordre » calls admin.tours.recommendOrder with the current stops and the start point. For a new tour, the draft is saved first.
2. The server returns an ordered list using a nearest-neighbour heuristic from the start point over stops that have GPS (FLD-17):
   • stops without GPS are appended at the end and flagged;
   • with « Garder les prioritaires en tête » ticked, HIGH stops are ordered first (by nearest neighbour among themselves), then the others. Assumption — the operation accepts a priorityFirst flag.
3. A preview dialog shows the old and new order side by side, with « Distance estimée : 48,6 km → 31,2 km ». Choices: « Appliquer » or « Garder mon ordre ».
4. Applying changes the list only. « Enregistrer » persists it.

Time slots are not optimised in V1. Routing with time windows is V2 (FLD-18).

Estimates use straight-line distance × 1.3 at 30 km/h, plus each visit type's default duration. They are labelled « estimation » everywhere. Assumption — the factors are to tune during the pilot.

Data.

• admin.tours.get (edit), admin.tours.create, admin.tours.update (header).
• admin.tours.setStops: the ordered stops[] with resellerId, priority, timeSlot, visitTypeId and note.
• admin.tours.recommendOrder.
• admin.resellers.list and admin.resellers.map (candidates, scope-filtered).
• admin.tasks.list, admin.visitTypes.crud (GET).

Actions.

RulesCopy Anchor Link

• What can be edited, by status:
  • PLANNED and TO_START tours are fully editable.
  • For IN_PROGRESS and SUSPENDED tours, only the remaining PLANNED stops can be added, removed or reordered; visited stops are locked. Assumption — confirm with the field team; header fields are frozen (admin.tours.update is limited to planned tours).
  • COMPLETED and CANCELLED tours open read-only and redirect to BO-23.
• Stops:
  • Stops must be in the delegate's scope (403 OUT_OF_SCOPE).
  • A point of sale appears at most once per tour.
  • A tour holds 1 to 40 stops. Assumption — the 40 cap is to confirm.
• Ordering mode: in IMPOSED mode the delegate cannot reorder (delegate.tours.reorder is refused). In RECOMMENDED mode they can reorder the remaining stops, and the new order shows here.
• Sync: the same order appears in the app's list and map (FLD-06). Changes reach the app through sync.delta.
• Concurrency: the tour carries version. When the delegate reordered meanwhile, saving returns 409 VERSION_CONFLICT. A dialog then shows the delegate's order, with « Recharger » or « Écraser avec mon ordre » (the latter only for PLANNED stops not yet visited).

Real-time. visit.checked_in and visit.completed for this tour lock the corresponding stop rows live.

States.

• Empty tour: « Ajoutez des points de vente depuis la carte ou la liste ».
• Recommendation failure: « Recommandation impossible », and the order is unchanged.
• Delegate without GPS-located stops: the recommendation button is disabled with a tooltip.
• Map provider failure: list-only editing.

Acceptance criteriaCopy Anchor Link

• After « Recommander l'ordre » and « Appliquer », saving persists the recommended order. The delegate app's list and map show the stops in that order after sync.
• With IMPOSED, the delegate app offers no reorder action. With RECOMMENDED, it does, and a reorder made in the app is visible here on reload.
• Adding a point of sale outside the delegate's zones is refused with « Ce point de vente n'est pas dans le périmètre du délégué ».
• On a tour in progress, visited stops cannot be moved or removed, and a new stop added at the end reaches the app.
• The preview shows the total distance before and after, and the applied order matches the server's response.

BO-23 — Tour live detailCopy Anchor Link

Purpose. Follow one tour live and review it afterwards (cahier §4.5 « Suivi du démarrage, des visites, des positions et de la clôture »):

• start time and position;
• each check-in with its distance to the point of sale;
• visit durations, photos and reports;
• the position trail;
• the closing summary with its comment.

The cahier's acceptance « La visite apparaît en temps réel dans le back-office » (§6.4) is checked here.

Who uses it. Commercial admin (live supervision, next-day review), direction.

Entry points. BO-06 (delegate popover, tours list), BO-21 chips, BO-17 Tournées, and BO-25 (link to its tour).

LayoutCopy Anchor Link

• Header:
  • TRN-2026-000045, the TourStatus pill and the ordering-mode pill.
  • The delegate (link to BO-17, « Appeler »), the date, and planned versus actual start.
  • Progress « 7 / 12 visitées · 1 non réalisée ».
  • Km travelled, last position age with its accuracy, and the sync badge (« 3 actions hors ligne reçues en différé »).
  • Actions: « Modifier » (BO-22; PLANNED, TO_START, or remaining stops while in progress), « Annuler » (PLANNED, TO_START), « Rouvrir » (COMPLETED, with field.validate).
• Main area: the map, two thirds of the width.
  • Planned stops are numbered markers coloured by VisitStatus, with derived « En retard » in danger.
  • The live delegate marker sits on top, with a pulse while IN_PROGRESS.
  • The trail is a polyline of the location pings (admin.tours.track), coloured by time. Gaps longer than 15 min are dashed.
  • Check-in markers show a tolerance circle (150 m) around each point of sale, with a line to the actual check-in position labelled « 86 m » (success) or « 412 m » (danger). Low accuracy (over 100 m) is labelled « précision 140 m ».
  • Toggles: « Trajet », « Check-ins », « Tolérance ».
• Right panel, the stop timeline:
  • Each stop shows:
    • its planned slot;
    • check-in time and distance, start/end, duration;
    • its status pill;
    • photo count (thumbnails);
    • report summary (interest level, next action);
    • the not-done reason (VISIT_NOT_DONE_REASON label).
  • A click selects the marker. « Voir la visite » opens BO-25.
• Tabs:
  • Visites (default).
  • Trajet: pings table with time, lat/lng, accuracy, speed, and gaps.
  • Clôture: the closing summary (FLD-12), as the delegate submitted it:
    • visits done / planned, not-done count with reasons;
    • new prospects, invitations, installs, accounts, first orders;
    • orders and revenue HT;
    • km;
    • end-of-day comment;
    • objectives achievement and conversion;
    • closing time.
  • Historique: TourStatusChange entries (planned, to start, started with position, suspended with TOUR_SUSPEND_REASON, resumed, completed, reopened), plus edits made in the back-office.

Data.

• admin.tours.get: visits, check-ins, distances, photos, reports, closing summary, history and version.
• admin.tours.track: the position trail.
• admin.tours.reopen, admin.tours.cancel.
• files.downloadUrl for photos.

Actions.

Rules.

• Who drives the tour: only the delegate starts, suspends, resumes and closes it (FLD-04). The back-office observes, cancels before the start, and reopens after closing.
• Location:
  • Positions exist only while IN_PROGRESS; sampling stops while SUSPENDED (FLD-15).
  • Trails older than 90 days are deleted by retention. The trail tab of an older tour reads « Trajet supprimé (conservation 90 jours) », while check-in positions and distances stay with the visit.
• Offline actions arrive with occurredAt (device time) and receivedAt. The timeline orders by occurredAt and badges entries received more than 10 min late (« saisi hors ligne »).
• Closing requires a reason for every unvisited stop and all offline data synced (cahier §6.9). The closing is definitive unless reopened by a holder of field.validate.

Real-time.

• delegate.position moves the marker and extends the trail (only for this tour's delegate).
• visit.checked_in turns the stop Arrivé, draws the check-in line, and flashes the row.
• visit.completed turns the stop Visité or Non réalisée, adds photo and report counts, and updates progress.
• tour.started and tour.closed update the header and open the Clôture tab on close.
• All without a page reload.

States.

• Not started (PLANNED / TO_START): planned markers only, with « La tournée n'a pas encore démarré ».
• Suspended: a banner gives the reason and time; the last position is greyed.
• Position stale for more than 15 min while IN_PROGRESS: amber header chip « Position non mise à jour depuis 18 min ».
• Stream lost: a banner; admin.tours.get is polled every 30 s.
• Cancelled: a read-only banner with the reason.

Acceptance criteriaCopy Anchor Link

• A check-in made in the delegate app appears here within 5 s with its distance to the point of sale. A check-in beyond 150 m is shown in danger with its distance.
• The trail shows the pings of the tour only while it was IN_PROGRESS, with gaps during suspensions.
• After closing, the Clôture tab shows the delegate's summary and comment exactly as submitted, and the indicators of BO-04 and BO-17 are recalculated (cahier §6.9 acceptance).
• « Rouvrir » requires field.validate and a reason. The delegate app then allows completing the tour again.
• Visits recorded offline show at their occurredAt time with the « saisi hors ligne » badge.

BO-24 — Visits listCopy Anchor Link

Purpose. Analyse all visits across tours: what was done, where, how long, with which outcome, and why visits were not done (cahier §4.5 « Validation des nouveaux points de vente et analyse des rapports »).

Who uses it. Commercial admin, direction.

Entry points. Terrain › Visites, the Visites réalisées card on BO-04, BO-17 and BO-11.

Layout.

• Filters: from / to (default this week), delegate, zone, wilaya, status, visitType, interestLevel, issueTag, notDoneReason, outOfTolerance=true, reseller, hasReport.
• Export: XLSX / CSV.

Data. admin.visits.list, reference.lists (VISIT_NOT_DONE_REASON, VISIT_ISSUE_TAG).

Actions. A row opens BO-25. « Exporter ».

Rules.

• A NOT_DONE visit always has a reason (FLD-09). The column is never empty for them.
• Distances are computed by the server from the check-in position to the point of sale's GPS (GEO-03).

Real-time. visit.checked_in and visit.completed show the banner « 3 nouvelles visites — Actualiser » rather than inserting rows.

States. First use: « Les visites apparaîtront dès la première tournée. »

Acceptance criteria.

• outOfTolerance=true lists exactly the visits whose check-in distance exceeds the tolerance setting.
• Every NOT_DONE row shows its reason label.
• The count for a delegate and day equals BO-23's progress for that tour.

BO-25 — Visit detailCopy Anchor Link

Purpose. Everything about one visit: check-in proof, timing, checklist, note, photos and the structured report that triggered the follow-up (cahier §6.4, §6.8).

Who uses it. Commercial admin.

Entry points. BO-24, BO-23 timeline, BO-11 Visites, and the validation queue (origin visit of a new point of sale).

Layout.

• Header:
  • VIS-2026-001234, the VisitStatus pill and a « Verrouillée » badge once finished.
  • Delegate, point of sale (link to BO-11), tour (link to BO-23), visit type.
  • Times: check-in, start, end, duration.
  • The « saisi hors ligne » badge with occurredAt / receivedAt when relevant.
• Check-in card: a mini-map with the point of sale, the tolerance circle and the check-in position; distance and accuracy; the result « Dans la tolérance » or « Hors tolérance ».
• Sections:
  • Checklist: items of the template snapshot, ticked or not, with required items marked.
  • Note: 300 characters max.
  • Photos: gallery with capture time and position, opened through signed URLs.
  • Rapport (FLD-10):
    • person met (PERSON_ROLE);
    • interest level (InterestLevel);
    • products and promotions presented;
    • issues (VISIT_ISSUE_TAG) and needs;
    • next action (NextAction) and follow-up date, with a link to the created task;
    • comments and attachments.
  • Non réalisée: reason and comment, instead of the sections above.
  • Historique: status changes and unlock events.

Data. admin.visits.get, admin.visits.unlock, admin.tasks.create, files.downloadUrl.

Actions.

• « Déverrouiller pour correction » (field.validate): confirmation « Autoriser Yacine M. à corriger cette visite ? La modification sera journalisée. ». A reason is required.
  • It is audited UPDATE and notifies the delegate (push).
  • The visit becomes editable in the app until it is finished again.
• « Créer une tâche » opens the BO-14 drawer, prefilled.

Rules.

• A finished visit is locked (FLD-08, cahier §6.4 « Une visite terminée ne peut être modifiée sans permission »). Corrections after unlocking keep the previous values in the history.
• Photos may be mandatory per visit type (BO-26). A finished visit of such a type always has them.

Real-time. visit.completed for this visit (after an unlock) reloads the page data.

States. Photos still uploading from the delegate's queue: « 2 photos en cours de synchronisation ». Missing point-of-sale GPS: « Distance non calculable : point de vente sans position GPS ».

Acceptance criteria.

• The detail shows check-in position, distance, times, checklist, note, photos and report as recorded in the app.
• The follow-up created by the report's next action is linked and opens in BO-14.
• Unlocking requires field.validate and a reason, and the change made by the delegate afterwards appears in the history with before/after values.

BO-26 — Visit types & checklist templatesCopy Anchor Link

Purpose. Configure what each kind of visit requires: photos, report sections and checklist (cahier §6.4 « Les photos peuvent être obligatoires selon le type de visite », §6.8 « Les champs affichés peuvent dépendre du type de visite »).

Who uses it. Commercial admin, super admin.

Entry points. Terrain › Types de visite.

Layout. Two tabs, each a list with a drawer editor.

Data. admin.visitTypes.crud, admin.checklists.crud.

Actions. Save each drawer, audited CREATE / UPDATE. Deactivating a type used by planned tours asks: « 14 visites planifiées utilisent ce type ; elles le conservent. Désactiver ? »

Rules.

• Nothing is deleted (no DELETE in the contract); types and templates are deactivated.
• Visits keep a snapshot of the checklist labels (VisitChecklistItem), so editing a template never changes past visits.
• Changes reach the delegate app through sync.delta. Visits already started keep the rules they started with.

Real-time. None.

States. First use: the seeded types (« Prospection », « Visite de suivi », « Aide à la première commande ») are listed. Assumption — the seed is to validate with HOCO.

Acceptance criteria.

• With Photos obligatoires = 1 Façade on a type, the delegate app refuses to finish such a visit without a façade photo (delegate.visits.end).
• Editing a checklist does not change the checklist shown on past visits in BO-25.
• Only one type can be the default.