nearle_pos/docs/sync-contract.md

# Terminal ↔ back office sync contract

What the till guarantees, and what the back office must do to hold up its end.
Everything here is enforced by tests in `test/unit/retention_test.dart`,
`test/unit/transport_test.dart` and `test/unit/sync_engine_test.dart`.

## The shape

```
Customer pays
     │
     ▼
One SQLite transaction: bill + stock + loyalty        ← never blocked on network
     │
     ▼
orders row lands at sync_status = 0                    ← this table IS the outbox
     │
     ▼
SyncEngine drains on: sale committed · network back · 5-min poll · head office
     │                asked · cashier pressed Sync
     ▼
Transport publishes a batch
     │
     ▼
Back office commits and names the ids it took
     │
     ▼
Those rows → sync_status = 1, folded into day_archive, kept 7 days, then purged
```

Anything the back office does not name stays at 0 and goes again.

## Non-negotiables

**1. Only an application acknowledgement counts.**
A broker PUBACK means "I hold these bytes". It is not evidence the ledger
accepted anything, and the terminal never treats it as such. The back office
must answer on the ack topic naming the order ids it committed.

**2. Silence is not acceptance.**
A `200 OK` with an empty body, or an ack with no `accepted` array, marks *zero*
bills synced. The terminal will send them again rather than guess.

**3. Delivery is at-least-once, so the back office must be idempotent.**
QoS 1 re-delivers, and a lost ack makes the terminal re-send the whole batch.
Every `order.id` is a UUID minted at the till. Put a unique index on it and
upsert. Without this you will double-count a day's takings the first time a
shop's line wobbles.

Invoice numbers are `INV-2608-T4A9-00042` — the terminal code is in there
because each till's sequence counter lives in its own database and starts at 1.
Unique per terminal, not globally sequential. Do not assume gaps mean missing
bills; a till that was replaced restarts its own series.

**4. A refusal is final, a failure is not.**
Naming an id in `rejected` halts the terminal's drain — it will not retry the
same bytes, and a person has to press Sync. Use it for "this bill is wrong"
(unknown product, duplicate invoice). For "I am having a bad minute", drop the
connection or return 5xx instead, and the terminal will back off and retry.

## MQTT topics

| Topic | Direction | QoS | Retained |
|---|---|---|---|
| `pos/{store}/{terminal}/order` | till → cloud | 1 | no |
| `pos/{store}/{terminal}/customer` | till → cloud | 1 | no |
| `pos/{store}/{terminal}/ack` | cloud → till | 1 | no |
| `pos/{store}/{terminal}/status` | till → cloud | 1 | **yes** |
| `pos/{store}/{terminal}/command` | cloud → till | 1 | no |
| `pos/{store}/catalogue` | cloud → all tills | 1 | **yes** |

`{store}` and `{terminal}` come from the device's own identity, minted on first
run and stored in its database. They are never literals — 100 tills sharing one
id would collide on every topic and evict each other from the broker, since a
second connection with the same client id kicks the first off.

`status` is also the Last Will. If a till loses power the broker publishes
`{"state":"offline"}` on its behalf — that is what makes a "which tills are
dark" board possible, and it is the only way to tell *closed for the night*
from *unplugged*.

### Running this on NATS

The MQTT gateway maps `/` to `.`, so the topics above arrive as subjects and a
JetStream consumer binds to them directly:

| Purpose | Subject |
|---|---|
| Every till's bills | `pos.*.*.order` |
| Every till's presence | `pos.*.*.status` |
| One store's bills | `pos.store-01.*.order` |
| Ack back to one till | `pos.store-01.T4A9.ack` |

`SyncConfig.asNatsSubject()` does the translation, so a consumer's subject can
be read off the terminal rather than guessed.

Two things to get right on the NATS side:

- **The stream must be durable and file-backed.** A memory stream loses a shop's
  bills on a server restart, and the till has already been told they landed.
- **Publish the ack from the consumer, after the database commit** — not from an
  ingest handler that has merely queued the work. The ack is the terminal's
  only evidence, and it deletes its copy seven days later on the strength of it.

### Fleet presence

Every terminal publishes a retained record on its status topic on connect and
once a minute. Retained matters: a dashboard connecting at noon gets all 100
terminals' last state immediately instead of a blank board.

```json
{
  "schema": 1, "state": "online",
  "device_id": "…", "terminal_code": "T4A9", "terminal_name": "Counter 2",
  "store_id": "store-01", "app_version": "1.1.0",
  "reported_at": "2026-08-01T14:22:05Z",
  "pending_bills": 3, "last_upload_at": "…", "catalogue_revision": "rev-8821",
  "sync_halted": false, "sync_error": null, "consecutive_failures": 0,
  "transport": "mqtt"
}
```

The Last Will answers *is it reachable*. These fields answer *is it healthy* —
a till can be connected and still be holding 200 unsent bills or running last
month's price list, and only `pending_bills` and `catalogue_revision` will say
so.

## Payloads

**Uplink** — `pos/{store}/{terminal}/order`

```json
{
  "schema": 1,
  "batch_id": "9f1c…",
  "store_id": "store-01",
  "terminal_id": "T4A9",
  "sent_at": "2026-08-01T14:22:05.123Z",
  "orders": [ { "id": "…", "invoice_number": "…", "items": [ … ] } ]
}
```

**Ack** — `pos/{store}/{terminal}/ack`. Must echo `batch_id`; anything else is
ignored as belonging to a batch the terminal is no longer waiting on.

```json
{
  "batch_id": "9f1c…",
  "accepted": ["order-uuid-a", "order-uuid-b"],
  "rejected": { "order-uuid-c": "duplicate invoice number" }
}
```

No ack within `SyncConfig.ackTimeout` (20s default) → the outcome is unknown,
nothing is marked synced, and the batch goes again.

**HTTP equivalent** — `POST {base}/orders`, same body, ack shape as the 200
response. Carries an `idempotency-key` header that is stable across retries of
the same bills.

### Shopper registrations

**Uplink** — `pos/{store}/{terminal}/customer`, or `POST {base}/customers`.
Acked on the same topic and by the same rules: only ids you name are marked
sent.

```json
{
  "schema": 1,
  "batch_id": "3d7a…",
  "store_id": "store-01",
  "terminal_id": "T4A9",
  "customers": [
    {
      "id": "7a24e082-060f-5503-aa9e-da0ef42df047",
      "mobile": "9840012345",
      "name": "Meena",
      "email": null,
      "gender": "female",
      "date_of_birth": null,
      "registered_at": "2026-08-01T10:14:00.000Z",
      "registered_by_terminal": "T4A9"
    }
  ]
}
```

Three things about this payload are load-bearing:

- **`id` is derived from the mobile number**, not minted at random — a UUIDv5
  over the normalised ten-digit number in a fixed namespace. Two tills that
  register the same shopper independently produce *the same id*, so you
  deduplicate on a primary key rather than guessing at a merge later. Do not
  reassign it.
- **Treat it as insert-if-absent on `id`.** A registration is not a financial
  record: it is replayed freely, and it must never overwrite a profile
  corrected at head office. `ON CONFLICT (id) DO NOTHING`.
- **No loyalty figures are sent.** Points, lifetime spend and visit counts are
  absent on purpose — derive them from the bill stream, which is authoritative
  and idempotent. Accepting a terminal's local balance would make the last till
  to sync win, and a shopper who bought at two counters on the same day would
  end up with whichever figure happened to arrive second.

Registrations are uploaded *before* bills on every pass, so a bill naming a new
shopper arrives after the shopper does. A failure here is logged and does not
hold up the bills behind it.

Terminals that were trading before schema v8 carry shoppers with random ids
from the old scheme. Those are queued once by the migration and arrive with
their original ids — merge them onto the mobile number. It is a one-off for
existing stores; a new terminal never produces one.

## Catalogue pull

The other direction: products and customers coming down.

```
GET {base}/catalogue?since={revision}&page={n}&store_id=…&terminal_id=…
Authorization: Bearer {apiKey}
```

```json
{
  "revision": "rev-8821",
  "is_delta": true,
  "has_more": false,
  "products":  [ { "id": "…", "name": "…", "barcode": "…", "price": 62.0, … } ],
  "customers": [ { "id": "…", "name": "…", "mobile": "…", … } ],
  "retired_product_ids": ["sku-9912"]
}
```

**Paged.** A supermarket catalogue is tens of thousands of rows; one response
times out on a shop's line and stalls the UI while it decodes. Answer
`has_more: true` and the terminal asks for the next page, up to 200 — past that
it stops rather than looping against the shop's connection.

**`since` is the revision the terminal already holds.** Answer with what has
moved and set `is_delta: true`. On a normal morning that is a handful of price
changes rather than the whole book. A server that cannot do deltas ignores the
parameter and answers `is_delta: false`; the terminal reads the flag rather
than assuming, so both work.

**The flag matters more than it looks.** A full snapshot withdraws every product
it does not mention. A delta must not — read as a snapshot, the first morning
price change would empty the shelf. Withdraw items in a delta with
`retired_product_ids`; the terminal marks them inactive rather than deleting,
because order lines already recorded point at them.

**Send stock only when you mean it.** Any product in the payload has its count
overwritten by the server's figure, which predates sales this terminal has rung
but not yet uploaded. The terminal replays those sales — but only for products
the payload actually carried. A delta that ships a stale count for an untouched
product will quietly empty a shelf that is full.

### Field handling

| Field | Missing | Notes |
|---|---|---|
| `id`, `name`, `barcode`, `price` | **import fails** | A dropped product is a shelf item that scans to nothing |
| `sku` | falls back to `id` | |
| `stock` | `0` | Means "not tracked" |
| `gst_rate` | 18% | Accepts `18` or `0.18` — both read the same |
| `category` | Grocery | An unrecognised one also falls back; the item still sells |
| `unit` | piece | Matched by name or symbol |
| `is_active` | `true` | An omitted flag is not a withdrawn catalogue |

Dates are ISO 8601 or epoch milliseconds; both are accepted.

### Pushing a change mid-day

Publish to `pos/{store}/catalogue` (retained) and every terminal in the shop
pulls immediately instead of waiting for tomorrow morning. The message body is
only a nudge — the catalogue itself still comes over HTTP, because a broker is
the wrong shape for tens of thousands of rows.

## Retention on the terminal

Accepted bills stay for 7 days (`OrderDao.retentionWindow`) so a batch the
back office later loses can be re-sent in full. After that only the archived
day totals survive, and a lost bill's line items are gone for good.

While a bill is retained it exists in two places — its own row and
`day_archive`. `forBusinessDate` therefore reads **pending rows only**; without
that filter every synced bill would be counted twice and the shift report would
overstate the day.

## What is deliberately not built

- **Downlink beyond catalogue-changed and sync-requested.** The plumbing routes
  unknown commands to the events log rather than dropping them, so adding one
  is a server change plus a case arm.
- **Historical correction.** Bills already synced by an older build went up
  with an overstated total. Nothing here fixes that; it needs a server-side
  reconciliation against `bill_discount`.
- **Loyalty balances coming back down.** Points and lifetime spend are computed
  per terminal from the bills that terminal rang. A shopper who buys at two
  stores has two partial balances until the back office derives the real one
  from the bill stream and sends it down in a catalogue pull. The uplink
  deliberately does not carry local balances, so nothing is corrupted by this —
  but a shopper's points at the till are that till's view, not the group's.
- **Merging pre-v8 shoppers.** Terminals that traded before the customer outbox
  carry rows with random ids. They are uploaded once by the migration, but
  collapsing them onto the mobile number is the back office's job.