# 23 — Mobile & Offline Capability

**Status**: Not Started
**Depends On**: 06 — Sale Ride Execution, 05 — Delivery Ride Execution

---

## Goal

Covers [mainPlan.md §17](./mainPlan.md#17-mobile--offline-capability) 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](./01_item_catalog.md)) |

---

## Business Rules

- Every action type accepted by `syncOfflineQueue` must 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 `Unresolved` and surfaced to a supervisor, consistent with the reconciliation
  approach in [07_ride_reconciliation.md](./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 `Item` need a `Barcode` field added now (extends [01_item_catalog.md](./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.