MDA-05 — Delegate app — visit flow
Visit detail with GPS validation, start/end, live duration, checklist, quick note, photos, call; not-done reason sheet. Works offline.
| Field | Details |
|---|---|
| Task code | MDA-05 |
| Phase | P1 — V1 build & integration |
| Product scope | V1 |
| Status | Planned |
| Start | Thu 3 Dec 2026 |
| Due | Sun 6 Dec 2026 |
| Responsible | Imad — Mobile developer (Flutter) |
| Co-responsible | — |
| Effort | 1.5 person-day(s) planned · 5 from scratch · size S |
| Area · app | Delegate app · mobile |
| Depends on | DES-13, MOB-11 |
| Unblocks | — |
| Milestones | — |
Summary
Visit detail with GPS validation, start/end, live duration, checklist, quick note, photos, call; not-done reason sheet. Works offline.
Description
The visit is the core field record: check-in time and position, duration, checklist, note, photos and call, locked once finished (FLD-08), or a mandatory reason when it did not happen (FLD-09) — all of it must work with no network (SYN-04). Scope: visit detail DA-10 with the GPS validation banner from the arrive result, start/end, live duration timer, checklist, quick note (≤ 300 characters), photos with capture position, call action and the requirement check before ending; and the not-done reason sheet DA-11. Every action is an outbox mutation (delegate.visits.start|checklist|note|addPhoto|end|notDone) with occurredAt; photos go through the MOB-11 upload queue first. It needs SRV-21 visit rules (VisitType requirements, VISIT_REQUIREMENTS_NOT_MET with details.missing, VISIT_LOCKED) and Akram's DES-13 frames. MDA-06 adds the report that the end-of-visit check may require; MDA-10 reads visit states at closing.
Subtasks
| # | Subtask | Owner |
|---|---|---|
| 1 | VisitDetailScreen (DA-10) on GET /delegate/visits/{id} with drift fallback: point of sale, visit type, checklist template, report config, VisitStatus | Imad |
| 2 | GPS validation banner bound to the arrive result: « Position validée (42 m) », « Hors tolérance — justification envoyée », or « À confirmer » for offline check-ins | Imad |
| 3 | « Commencer la visite » → delegate.visits.start through the outbox; visit timer provider restored from startedAt in the local visits table after app kill | Imad |
| 4 | Checklist widget writing PUT /delegate/visits/{id}/checklist to the outbox (unsent checklist mutations for the same visit coalesced into the latest state) | Imad |
| 5 | Quick note field (300-character counter) saved with PUT /delegate/visits/{id}/note, debounced and coalesced | Imad |
| 6 | Photo capture → MOB-11 upload queue → POST /delegate/visits/{id}/photos with client photo id, capture position and time; thumbnails with per-photo sync state | Imad |
| 7 | « Appeler » action logging a CALL interaction on the reseller timeline | Imad |
| 8 | End-of-visit requirement check (mandatory checklist items, VisitType.minPhotos, report when required) before delegate.visits.end; server VISIT_REQUIREMENTS_NOT_MET details.missing mapped to the same checklist | Imad |
| 9 | Locked visit UI after end: read-only fields, « Visite terminée à 10:42 — durée 18 min »; edits replayed after lock rejected with VISIT_LOCKED and shown in the sync centre | Imad |
| 10 | Not-done reason sheet (DA-11) with the VISIT_NOT_DONE_REASON list from cached reference.lists, comment required for « Autre », position when available → delegate.visits.notDone | Imad |
Deliverables
- apps/delegate/lib/src/features/visit/ (DA-10 detail, timer, checklist, note, photos; DA-11 not-done sheet)
- Outbox mutation types delegate.visits.start, .checklist, .note, .addPhoto, .end, .notDone with dependsOn on arrive
- integration_test/visit_offline_test.dart
- Firebase App Distribution build 0.4.0 (staging) of the delegate app with the visit flow
Acceptance criteria
- A complete visit (arrive, start, checklist, note, 2 photos, end) done in airplane mode survives an app kill and syncs in order on reconnection (FLD-08, SYN-04)
- The timer shows the right elapsed time after the app is killed and reopened mid-visit
- « Terminer la visite » is refused locally with the list of missing items when mandatory checklist items, photos or the report are missing; the server's VISIT_REQUIREMENTS_NOT_MET shows the same list
- After end the visit is read-only; an edit made offline after the end is rejected with VISIT_LOCKED and listed in the sync centre
- A visit cannot be marked not done without a reason, and « Autre » requires a comment (FLD-09)
- Uploaded photos carry their capture position and time, without EXIF metadata in the file
Requirements covered
| Requirement | Title | Release |
|---|---|---|
| FLD-08 | Visit and check-in: time and position at check-in, duration, checklist, note, photos (mandatory by visit type), call; finished visit locked | V1 |
| FLD-09 | A visit not carried out requires a reason | V1 |
| SYN-04 | Delegate app keeps the tour, visits, notes and photos locally under weak network | V1 |
Screens
API surface
| Endpoint group | Operations |
|---|---|
| Tours & visits | 19 |
| File uploads & downloads | 3 |
Test measures
- integration_test of the full offline visit with kill/relaunch and replay against Prism or staging
- Unit tests of mutation coalescing (checklist, note) and of the requirement checker
- Widget tests of DA-10 in PLANNED, CHECKED_IN, IN_PROGRESS, DONE (locked) and NOT_DONE states
Risks
- Coalescing mutations could drop an intermediate state the server expects — coalesce only unsent mutations of idempotent PUT types (checklist, note), never start/end/photos
- Clock changes on the phone distort durations — store monotonic elapsed time alongside occurredAt and let the server's plausibility check flag outliers
KPI
- Delivered by Sun 6 Dec 2026 within 1.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.
MDA-04 — Delegate app — point-of-sale sheet & prospects list
POS sheet (contact actions, history, tasks, photos) and the prospects/resellers list with search, status filters and distance sort, list/map toggle.
MDA-06 — Delegate app — visit report & follow-ups
Structured report with chips/multi-selects, next action and follow-up date, attachments; follow-ups list with complete/reschedule.