2.4 KiB
2.4 KiB
23 — Mobile & Offline Capability
Status: Not Started Depends On: 06 — Sale Ride Execution, 05 — Delivery Ride Execution
Goal
Covers mainPlan.md §17 in full — offline-first support for field agents (drivers/sales reps) whose connectivity can't be assumed during a ride.
Background / Context
There is no mobile client in this repository — this step is the server-side contract a future mobile client would sync against (queueing, conflict resolution, barcode resolution), not a client implementation itself.
Data Model Changes
Offline Action Queue Entry
DeviceId, UserId, ActionType (e.g. CreateFieldInvoice, RecordDelivery), Payload (JSON),
ClientCreatedAt, SyncedAt (nullable), ConflictStatus (None, Resolved, Unresolved).
API Endpoints
| Function reference | Endpoint intent |
|---|---|
queueOfflineOrder(orderData) |
Client-side only — server sees it as a normal write once synced |
syncOfflineQueue(deviceId) |
POST /api/sync?deviceId=... — batch endpoint accepting queued actions, applying them in order, returning per-action success/conflict |
scanBarcode(barcodeValue) |
GET /api/items/by-barcode/{barcodeValue} — resolves to an Item (needs a Barcode field added to Item, see 01_item_catalog.md) |
Business Rules
- Every action type accepted by
syncOfflineQueuemust be safely replayable (idempotent by a client-generated id) — a duplicate sync of the same queued action must not double-apply (e.g. double-decrement stock). - A sync conflict (e.g. stock sold twice from two devices while offline) must not silently pick a
winner — flagged
Unresolvedand surfaced to a supervisor, consistent with the reconciliation approach in 07_ride_reconciliation.md.
Open Questions
- Is a mobile client actually planned/being built by this team, or is offline support scoped for a hypothetical future client? This changes whether the sync contract needs to be finalized now or can wait.
- Does
Itemneed aBarcodefield added now (extends 01_item_catalog.md), or is barcode scanning deferred with the rest of this step?
Implementation Notes
Fill this section in during planning discussion before writing any code.