Offline sync (delegate app)

Field networks are weak; the delegate app must keep a tour, its visits, notes and photos locally, replay them later without duplicates and show the user whether everything is synchronisé, en attente or en erreur (cahier §7.3, ADR-010). This page is the client half, built in hoco_offline (MOB-09) and surfaced in the sync centre (MDA-11). The server half — idempotency records, batch semantics, delta cursors — is the offline sync design; the wire format is on the sync API. Where this page and those pages differ, they win; the examples below follow the sync API page.

The write pathCopy Anchor Link

Every user action in the delegate app follows the same path, online or not:

1. The local change and its outbox item are written in the same transaction: either both exist or neither does. The screen reads the local tables only, so it shows the new state immediately.
2. The engine sends pending items as soon as a connection exists (cahier §7.3: « Les données critiques sont envoyées immédiatement lorsque la connexion est disponible »), in order, by batches.
3. Results update the local rows (server numbers such as VIS-2026-001234, computed distances, statuses) and the outbox item status.

Which operations are offline-capable is stated per operation on the API pages (tours and visits, prospects); the online-only list below summarises the exceptions.

Local databaseCopy Anchor Link

hoco_offline uses drift (SQLite, typed queries, streams, tested migrations). One database file per signed-in user (hoco_<userId>.sqlite), opened in a background isolate and shared with the WorkManager isolate through drift's isolate sharing — two isolates opening the same file independently end in database is locked.

Columns (types are SQLite/drift types; JSON columns use a converter):

enum OutboxStatus { pending, inFlight, applied, conflict, rejected, blocked, discarded }

@DataClassName('OutboxItem')
class Outbox extends Table {
  IntColumn get seq => integer().autoIncrement()();        // replay order (FIFO)
  TextColumn get id => text().unique()();                  // UUIDv7, also the batch item id
  TextColumn get userId => text()();                       // never replayed under another account
  TextColumn get opId => text()();                         // delegate.visits.arrive
  TextColumn get method => text()();                       // POST, PUT, PATCH, DELETE
  TextColumn get path => text()();                         // /delegate/visits/0193…/arrive
  TextColumn get body => text().map(const JsonMapConverter())();
  TextColumn get idempotencyKey => text()();               // UUIDv7, fixed at creation
  DateTimeColumn get occurredAt => dateTime()();           // device time of the action
  DateTimeColumn get createdAt => dateTime()();
  TextColumn get entityType => text()();                   // TOUR, VISIT, RESELLER, TASK, INVITATION
  TextColumn get entityId => text()();
  TextColumn get coalesceKey => text().nullable()();       // visit:0193…:checklist
  TextColumn get dependsOn => text().map(const StringListConverter())(); // idempotency keys, or upload:<id> (local only)
  IntColumn get attempts => integer().withDefault(const Constant(0))();
  DateTimeColumn get nextAttemptAt => dateTime().nullable()();
  TextColumn get status => textEnum<OutboxStatus>()();
  TextColumn get lastError => text().map(const JsonMapConverter()).nullable()(); // status, code, message, requestId
  TextColumn get result => text().map(const JsonMapConverter()).nullable()();    // response body once applied
  TextColumn get label => text()();                        // « Arrivée — Magasin El Wafa » for the sync centre
}

Migrations. Every schema change bumps schemaVersion with a step-by-step migration and a migration test generated from schema snapshots (drift's make-migrations workflow). An app update must never lose the outbox: a lost outbox is lost field data (git workflow).

Encryption at rest. V1 relies on the app sandbox and Android file-based encryption. If HOCO's privacy review (D-11) asks for more, SQLCipher can be added to drift at the cost of a larger APK — decide before the pilot, not after.

The outboxCopy Anchor Link

On start-up, every IN_FLIGHT item goes back to PENDING (the app may have been killed mid-batch); replaying it with the same key is safe — the server answers REPLAYED with the original result.

Ordering and dependenciesCopy Anchor Link

The engine sends items in seq order and the server applies a batch in order. On top of FIFO, explicit dependencies prevent a later item from overtaking an earlier one across batches or retries:

An item is ready when it is PENDING, its nextAttemptAt has passed and all its dependencies are APPLIED. When a dependency becomes REJECTED or DISCARDED, its dependents become BLOCKED and the sync centre shows them under the failed item.

Replay through sync.batchCopy Anchor Link

loop while ready items exist and the network answers:
  take up to 50 ready items in seq order, total body at most 1 MB (a dependency must be earlier in the batch or already sent)
  mark them IN_FLIGHT
  POST /sync/batch with Idempotency-Key = batchKey(items)
  apply each result, then continue with the next batch

/// Same set of items → same key, so a retried batch is replayed by the server;
/// a different set (new item, coalesced save) → a different key.
String batchKey(List<OutboxItem> items) =>
    const Uuid().v5(_hocoBatchNamespace, items.map((i) => i.idempotencyKey).join(','));

Request and response, shaped as on the sync API (SyncItem, SyncItemOutcome; a full worked example is on that page):

{
  "items": [
    {
      "idempotencyKey": "0193a40b-1c2d-7e3f-8a90-b1c2d3e4f502",
      "method": "POST",
      "path": "/delegate/visits/0193a2f0-5b6c-7e8d-9f01-23456789ab11/arrive",
      "body": {
        "occurredAt": "2026-11-03T08:12:00Z",
        "location": { "lat": 35.71143, "lng": -0.57262, "accuracy": 12, "capturedAt": "2026-11-03T08:11:58Z" },
        "isMockLocation": false
      },
      "occurredAt": "2026-11-03T08:12:00Z"
    },
    {
      "idempotencyKey": "0193a40b-1c2d-7e3f-8a90-b1c2d3e4f504",
      "method": "POST",
      "path": "/delegate/visits/0193a2f0-5b6c-7e8d-9f01-23456789ab11/start",
      "body": { "occurredAt": "2026-11-03T08:14:00Z" },
      "occurredAt": "2026-11-03T08:14:00Z",
      "dependsOn": ["0193a40b-1c2d-7e3f-8a90-b1c2d3e4f502"]
    }
  ]
}

{
  "results": [
    { "idempotencyKey": "0193a40b-1c2d-7e3f-8a90-b1c2d3e4f502", "result": "APPLIED", "status": 200, "body": { "visitId": "0193a2f0-5b6c-7e8d-9f01-23456789ab11", "status": "CHECKED_IN", "distanceMeters": 32, "gpsCheck": "WITHIN_TOLERANCE" }, "receivedAt": "2026-11-03T10:02:09Z" },
    { "idempotencyKey": "0193a40b-1c2d-7e3f-8a90-b1c2d3e4f504", "result": "APPLIED", "status": 200, "body": { "visitId": "0193a2f0-5b6c-7e8d-9f01-23456789ab11", "status": "IN_PROGRESS" }, "receivedAt": "2026-11-03T10:02:10Z" }
  ],
  "serverTime": "2026-11-03T10:02:11Z"
}

The batch request is always 200 when well-formed; per-item outcomes carry the result. Whole-request errors: 413 BATCH_TOO_LARGE (split the batch), 409 IDEMPOTENCY_KEY_REUSED (a client bug in batchKey), 409 IDEMPOTENCY_IN_PROGRESS (the same batch is still running — wait and resend).

Triggers and backoffCopy Anchor Link

Backoff for RETRY items and failed batches: 2 s, 4 s, 8 s … capped at 5 minutes, ± 20 % jitter; reset when connectivity changes. After 8 failed attempts the item shows En erreur in the sync centre but keeps retrying at the cap — the user can force a retry.

One engine at a time. The UI isolate and the WorkManager isolate share the database; a lease row in sync_state (engine.lease: owner and expiry, renewed every 20 s, taken in a transaction) prevents two engines from sending the same items.

Clock. The sync operations, the today snapshot and appConfig.get all return serverTime; the app stores the offset (clock.offsetMs) and stamps occurredAt with the device clock corrected by it (sync API › conventions). If the device clock is more than 5 minutes off, the app also warns (« L'heure du téléphone est incorrecte — activez l'heure automatique », app config). Durations (visit timer) use a monotonic stopwatch, not wall-clock differences.

The 72-hour wall. Items older than 48 hours trigger a persistent banner and a local notification (« Des actions attendent depuis plus de 48 h — connectez-vous à un réseau »); past sync.maxOfflineHours the server rejects them, and the sync centre explains why.

Delta pulls and merge rulesCopy Anchor Link

The app downloads today's tour as a snapshot (delegate.tours.today) and keeps everything else fresh with sync.delta: changes and tombstones since a cursor for the scopes tours (today − 7 days to today + 30 days), visits, resellers (every point of sale in scope, as ResellerCard), tasks, referenceLists and announcements. The first cursor comes with the today snapshot (deltaCursor). Pull order: push first (so the server already has local actions), then pull pages (limit up to 1 000) while hasMore is true, storing nextCursor after each page in the same transaction as the page's rows.

Photo queueCopy Anchor Link

Photos are taken with the camera only for visit proof (no gallery), saved as JPEG (quality 85, longest edge 2560 px) in the app's documents directory with their capture time and position, and recorded in uploads. The queue runs independently of sync.batch, because binaries never travel in a batch:

1. files.createUpload with the stored createKey → fileId, upload URL (status CREATED).
2. PUT to the URL with the returned headers (status UPLOADED). A 403 means the 10-minute URL expired: call createUpload again with the same key — the server returns the same fileId with a fresh URL (files).
3. files.completeUpload with completeKey (status COMPLETED), then the fileId is written into the body of the waiting addPhoto outbox item, which becomes ready.
4. Once that item is APPLIED, the local file is deleted.

At most two uploads run at a time; on a metered or weak network the queue waits between files. Pending files not attached within 24 hours are deleted by the server, so a photo that waited longer simply restarts at step 1 with new keys. If free storage drops under 200 MB the camera button warns before capturing.

Location pingsCopy Anchor Link

Samples recorded while a tour is IN_PROGRESS go to location_pings, not to the outbox, and are sent in batches to sync.locationPings — every 15 minutes or 20 samples, whichever comes first, in chunks of at most 200 (413 BATCH_TOO_LARGE above), with an idempotency key written on the rows (batchKey) before sending so a retry resends the same body; samples listed in dropped (outside the tour interval, too old) are deleted. Pings older than 72 hours are dropped. Sampling itself is on location and maps.

What stays online-onlyCopy Anchor Link

Sync centre and conflictsCopy Anchor Link

The sync centre (DA-27) is reachable from the account tab and from the status chip shown in the header of the home, tour and visit screens (Synchronisé · En attente (3) · En erreur (1)), SYN-06.

• Header: connection state, last successful push and pull, « Synchroniser maintenant ».
• Needs attention (conflicts, rejected, blocked) first, grouped by record (Magasin El Wafa — visite VIS-2026-001234), each with the server message, the requestId (copyable for support) and the actions above. Discarding asks for confirmation and is logged (Sentry breadcrumb plus the diagnostics buffer).
• Pending: label, time of the action, attempts, next retry.
• Synchronised today: the last items applied, for reassurance.
• Photos: per-file progress and size, total waiting.
• The tour-closing screen links here when it is blocked; sign-out is refused while items are pending (sign-out rule).

Sign-out, account switch and updatesCopy Anchor Link

• Sign-out is refused while the outbox or the upload queue holds anything; the user is sent to the sync centre. A forced sign-out (lost phone handled by the back-office revoking the session) keeps the database file; the next sign-in of the same user replays it.
• Another user signs in on the same phone: the previous user's database is kept, never replayed under the new session. If it still holds pending items, the app tells the new user and the back-office (diagnostic event) — the previous delegate must sign in again to flush it.
• Session expired offline: work continues locally; the first 401 pauses the engine and asks for the password; after sign-in by the same user, replay resumes with the same keys.
• App update: migrations run before the engine starts; the forced-update gate never deletes local data.

Storage limits and purgeCopy Anchor Link

The purge runs at start-up and after each successful pull, inside the engine lease.

Test matrixCopy Anchor Link

Unit tests cover the outbox (coalescing, dependency resolution, batch building, key stability), result handling and merge rules with an in-memory drift database. These scenarios run as integration tests against a fake server, then by hand on a phone against staging, and again in the field test (MOB-13):