Delegate app

The delegate app (dz.hoco.delegate) is the field tool of HOCO's délégués commerciaux (field sales delegates): the day's tournée (tour) of phone-accessory shops, GPS check-in, visit reports, prospect sign-up, invitation to the reseller app and first-order assistance (cahier §6, §6.1–§6.9). Imad builds it in Flutter in hoco-mobile (tasks MDA-01 to MDA-12 on the foundations MOB-05, MOB-09, MOB-10, MOB-11); Akram designs it on days 11 to 14 of the design plan.

The users work outdoors all day, on mid-range Android phones, with weak 3G/4G between shops. The app is therefore offline-first: everything the delegate does on a tour is written to the phone first and synchronised when the network allows (cahier §7.3, SYN-04, SYN-05, SYN-06).

How to read the screen specifications. Every screen has the same blocks: a fields table (French title, release, design day, build task, requirements, client reference), purpose, entry points and exits, layout, data (API source and offline source with its freshness rule), actions (endpoint, Idempotency-Key, occurredAt, what goes to the outbox, optimistic UI, feedback), rules, states, copy and acceptance criteria. Response paths follow the API reference baseline; where an API page differs, the API page — and from SRV-03 on, the OpenAPI document — wins. Local table names refer to the drift store of hoco_offline described in offline sync; location mechanics are in location and maps; components come from the design system.

The delegate's dayCopy Anchor Link

The client references show the same journey three times, at three zoom levels:

Navigation modelCopy Anchor Link

The references disagree on the bottom navigation bar:

Decision — variant A: Accueil · Tournée · Prospects · Rapports · Compte. Reasons:

1. The list and the map are one tour. FLD-06 requires the list and the map to show the same visits in the same order. One Tournée tab with a list/map toggle and a shared filter state guarantees it; B's separate Planning and Carte tabs invite two states that drift apart.
2. A visit is contextual, not a destination. A visit always belongs to a stop of today's tour. B's Visite tab would be empty most of the day and ambiguous when nothing is in progress. A gets the same one-tap return through the active-visit bar (below).
3. B has no home and no account. The objectives, counters and the start button (cahier §6.1) need a home; the profile, zone, settings, sync centre and sign-out (cahier §6) need an account tab.
4. Consistency and recognition. A appears on four of the five references that show a bar and matches the journey of delegate-02-home.
5. Five tabs is the Material maximum for a bottom bar; A uses it without hiding anything essential.

What happens to B's destinations: Planning → the Tournée tab (list); Carte → the list/map toggle and DA-08; Visite → the active-visit bar and the « Visiter » button of each stop; Prospect → the Prospects tab; Rapport → the Rapports tab.

Shared chrome. Every tab root has an app bar with the global sync indicator (cloud icon, see sync badges), the location-sharing chip while positions are being recorded, and the bell with the unread count (→ DA-23). The offline banner sits under the app bar. DA-28 states overlay any screen.

Active-visit bar. While a visit is CHECKED_IN or IN_PROGRESS, a 56 dp bar sits above the bottom navigation on every screen: store name, live duration and « Reprendre » (→ DA-10). Leaving DA-10 never ends the visit.

Back behaviour. Each tab keeps its own stack (go_router StatefulShellRoute). Android back on a tab root returns to Accueil; on Accueil a second back within 2 s leaves the app (« Appuyez encore pour quitter »). Forms with unsaved input (DA-14, DA-15, DA-17) keep a local draft instead of asking to discard.

Offline-first behaviourCopy Anchor Link

What works offlineCopy Anchor Link

How an action is recordedCopy Anchor Link

Rules that apply to every queued action:

1. One key per action. The Idempotency-Key is created when the action is recorded and reused on every retry, so a lost response never duplicates a check-in. A new attempt after a REJECTED item, or an item rebuilt by compaction, gets a new key — the same key with a different body answers 409 IDEMPOTENCY_KEY_REUSED.
2. occurredAt is the time of the action, not of the upload. The server refuses values more than 5 minutes in the future or older than sync.maxOfflineHours (72 h) with 422 OCCURRED_AT_OUT_OF_RANGE. The app warns from 48 h on (banner and local notification « Synchronisez vos données »).
3. Compaction of full-state edits. delegate.visits.checklist, delegate.visits.note, delegate.visits.report and delegate.tours.reorder send the whole state: a new edit replaces a still-QUEUED item for the same record (new key); an item already in flight is never modified.
4. Dependencies. Per record, items replay in order. Across records: everything about a client-created reseller waits for its delegate.resellers.create; delegate.visits.addPhoto waits for its file upload; delegate.visits.end waits for the visit's photos and report; every visit item waits for delegate.tours.start; delegate.tours.close is always last.
5. Server data never overwrites pending work. A delta for a record that still has outbox items is merged only into the fields those items do not touch; the rest is applied once the outbox for that record drains.
6. Online-only operations (sign-in, invitation creation, assisted-order pricing and sending, closing when sync is required, duplicate check) call the API directly with an Idempotency-Key generated at the tap and kept until a definitive answer; 409 IDEMPOTENCY_IN_PROGRESS is retried after 1 s with the same key.
7. Nothing is lost silently. Outbox items, uploads and location samples survive app kills, reboots and app updates (drift migrations are additive). Sign-out is refused while items are pending, except through an explicit destructive confirmation (DA-24).

Sync badgesCopy Anchor Link

The cahier asks that the user sees « synchronisé, en attente ou en erreur » (cahier §7.3, SYN-06).

« En attente » is reserved for synchronisation: no business status of a visit, tour or prospect uses that label in the delegate app (order statuses keep their own label En attente, always inside an order pill).

Global indicator (app bar, tap → DA-27): « Synchronisé · il y a 2 min » · « 3 en attente » · « 1 erreur » (red) · « Hors ligne » (with the pending count) · « Synchronisation… » (animated while a batch is in flight).

Freshness classesCopy Anchor Link

Every data block in the screen specs names one of these classes.

Local storeCopy Anchor Link

Tables of the drift database referenced in the specs (the schema itself is owned by offline sync).

Location and consentCopy Anchor Link

The position of a delegate is personal data: the cahier limits its use to « les règles validées par le client » (§6.3) and asks for consent and transparency (§10; FLD-15, SEC-07). Frequency, tolerance and retention are settings still to be validated with HOCO (cahier §8, §15).

1. Consent first. No position is read before the delegate accepts the location notice (DA-04). The acceptance is stored with its version through me.update (consents.locationTracking). Without consent the delegate can consult everything but cannot start a tour; withdrawing consent (DA-26) stops sampling at once.
2. One-shot reads happen only on an explicit action: tour start, « Je suis arrivé », visit end, « Visite non réalisée » (when available), GPS capture of a new prospect, and the blue dot on the map (shown, never stored).
3. Sampling only while the tour is IN_PROGRESS: one sample every field.locationIntervalSeconds (300 s) or field.locationDistanceMeters (200 m), whichever comes first. It starts at « Commencer » or « Reprendre » and stops at « Suspendre », at closing, at sign-out, on consent withdrawal, and when the server suspends a forgotten tour at 21:00 (job field.autoSuspendOpenTours, proposal). Never before the tour starts, never after it ends.
4. Android mechanics. A foreground service of type location with a permanent notification, started from the visible app; only the while in use precise permission (ACCESS_FINE_LOCATION) — no ACCESS_BACKGROUND_LOCATION. Samples go to location_pings and are sent in batches through sync.locationPings (every 10 min or 20 samples, and at each visit event). One-shot reads use high accuracy; sampling uses balanced accuracy to save battery.
5. Retention. field.locationRetentionDays (90 days) on the server; samples are deleted from the phone once acknowledged.
6. Mock locations are refused for check-in (422 GPS_MOCK_LOCATION) and flagged on samples.

Outdoor readability and one-hand useCopy Anchor Link

Delegates read the screen in direct sun, often with one hand while holding a bag or a phone box. These rules complete the design system for this app; Akram checks them on a real phone outdoors in DQA-03 and Imad in the accessibility pass MOB-17 (NFR-07).

Settings the app readsCopy Anchor Link

Business settings are edited on BO-64 and reach the app two ways, both stored in app_config: the public subset through appConfig.get (settings.*), and the field settings of the day through delegate.tours.today (fieldSettings: tolerance, accuracy, out-of-tolerance switch, report rule, closing rule, note length, photo limit, location policy) so that they apply offline. Defaults below; the settings catalogue is authoritative.

To align — the sampling distance is named field.locationDistanceMeters in appConfig.get and field.locationMinDistanceMeters on the tours API page (fieldSettings.location.minDistanceMeters); the settings catalogue should keep one key. field.visitUnlockHours and field.reopenMaxDays are not sent to the app: it reads their effect from unlockedUntil and the reopening notification.

Error codes shown by the appCopy Anchor Link

The app shows the server's localised error.message; the French strings below are its fallbacks when the message is missing (offline evaluation, old cache). The error registry is authoritative.

Deep links and notification targetsCopy Anchor Link

Routes of the app's router (MOB-05). Push payloads carry a route that is opened after the splash; a target outside the delegate's scope or deleted falls back to Accueil with « Élément introuvable ou retiré de votre périmètre ».

Notifications received by the delegate (from the notifications matrix, which owns the wording):

While the app is open and online it also listens to events.stream (notification.created) to refresh the bell and the open order without waiting for a push.

Reference screens: decisions on inconsistenciesCopy Anchor Link

API surfaceCopy Anchor Link

Screen indexCopy Anchor Link