Add md file features in region, route, store, fleet, pricing, procurement, SFA, promotions, returns, finance, reporting, notifications, integration, and mobile capabilities

2026-08-19 15:18:31 +05:30
parent 45f374133f
commit d2390e7b12
25 changed files with 1565 additions and 88 deletions
@@ -0,0 +1,66 @@
+# 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.