backend_fiesta/POS_TERMINAL_INGEST.md

# POS terminal ingest

How an in-store Nearle POS till reaches this backend. The terminal side of the
contract is specified in the POS repository at `docs/sync-contract.md`; this
covers what was built here and how to turn it on.

## What a terminal expects, and why it matters

A till stores every bill in its own SQLite database the moment a sale
completes, and keeps it for **seven days after we acknowledge it**. It marks a
bill synced if — and only if — the bill's id appears in the `accepted` list of
our reply.

That single rule drives every decision below:

- **Silence is not acceptance.** No reply, an empty reply, a 200 with no body:
  all leave the bill on the till, and it is sent again. This is the correct
  behaviour when we are struggling, and it is why a failing ingest never
  acknowledges.
- **A duplicate is a success.** Delivery is at-least-once. A lost ack makes a
  terminal re-send bills we already hold, and calling those failures would
  strand a day of takings. The ingest recognises them and accepts them without
  touching stock again.
- **A rejection is a decision.** Naming an id in `rejected` stops the till
  retrying it and waits for a person. Right for "this bill is malformed", wrong
  for "the database is having a bad minute".

## Two ways in, one code path

Both transports call `services.PosService`, so a bill arriving over MQTT and
one arriving over HTTP cannot diverge.

### Where a bill lands

Counter sales are written to **`pos_orders` / `pos_order_items`**, not to
`orders`. A bill is a different document from an app order: it carries a
cashier, a terminal, a rounding adjustment, promo campaigns, loyalty movement
and a payment split across several tenders, none of which `orders` has anywhere
to put. Forcing one into the other's shape loses whichever fields do not fit,
silently.

**Stock is not separate.** A counter sale writes the same `productstocks`
"out" rows an app order does, through the shared helpers in `stockLedger.go` —
the same row locks, the same availability check, the same availability re-sync.
Two stock ledgers would mean the catalogue pull sends a till figures that ignore
the till's own trading, and it would oversell.

Existing revenue queries were extended to include `pos_orders`
(`GetRevenueSummary`, `GetSalesSummary`), so dashboards do not understate a shop
that runs a counter. **Any new report has to remember to do the same** — that is
the standing cost of the split.

### HTTP

Base path: `/live/api/v1/pos`

**Written by a terminal** — bare-ack responses, see below.

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/orders` | Completed bills |
| `POST` | `/customers` | Shoppers registered at a till |
| `GET` | `/catalogue` | Product pull. Query: `store_id`, `since`, `page`, `page_size` |

**Read by the web app** — normal `{code, message, status, details}` envelope.

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/sales` | Bills for an outlet, newest first |
| `GET` | `/sales/detail` | One bill with its lines |
| `GET` | `/sales/summary` | Totals by tender, day and till |
| `GET` | `/health/terminal` | One till's live state |
| `GET` | `/health/location` | Every till at a shop |

`/sales` and `/sales/summary` take: **`locationid` (required)**, `fromdate`,
`todate` (YYYY-MM-DD, matched on `businessdate`), `terminalid`, `cashiername`,
`paymentmode`, `pageno`, `pagesize`.

`/sales/detail` takes `locationid` and `reference` — the terminal's order UUID,
the invoice number, or the `posorderid`, whichever the caller happens to have.

**`locationid` is the authorisation boundary.** Every read is scoped to one
outlet; omitting it is an error rather than a page through every shop's takings,
and asking for a bill under the wrong outlet returns 404 even when the reference
is valid.

Dates match `businessdate` — the day the sale was rung, not the day it reached
us. A till that was offline overnight uploads yesterday's bills this morning and
they belong to yesterday.

These answer with a **bare ack**, not the usual `{code, message, status}`
envelope — the terminal reads `accepted` from the top level of the body:

```json
{ "batch_id": "9f1c…", "accepted": ["order-uuid"], "rejected": {} }
```

Status codes carry the rest of the contract:

- **200** — batch processed. Individual bills may still be refused; the ack says which.
- **4xx** — the request is wrong (unknown outlet, bad store id). The till halts and shows a person.
- **5xx** — outcome unknown. The till keeps everything and retries with backoff.

### MQTT

The broker is **Eclipse Mosquitto 2.1.2** at `66.116.225.226:1883`, shared with
the rider app (`nearle/riders/#`) and the doormile project (`doormile/riders/#`).

There is **no NATS** in this deployment. NATS servers exist for other projects
on other hosts, but their ports are closed from here and their configs carry no
`mqtt {}` block, so they expose no MQTT gateway. The NATS consumer that briefly
lived in this package has been deleted rather than left to rot.

| Env | Purpose |
|---|---|
| `MQTT_URL` | `tcp://66.116.225.226:1883`. **Unset disables MQTT ingest** — HTTP still works |
| `MQTT_USER` / `MQTT_PASSWORD` | Broker credentials |
| `MQTT_CLIENT_ID` | Defaults to `nearle-pos-ingest`. **Must be unique per replica** — a second connection with the same id evicts the first, and the two would fight in a loop |

| Topic | Direction |
|---|---|
| `nearle/pos/+/+/order` | till → us |
| `nearle/pos/+/+/customer` | till → us |
| `nearle/pos/+/+/health` | till → us, every 30s |
| `nearle/pos/{loc}/{terminal}/ack` | us → till |
| `nearle/pos/{loc}/catalogue` | us → every till at a shop |

Subscribed with `CleanSession(false)` and a stable client id, so a brief restart
resumes rather than missing what arrived meanwhile. Re-subscribes on every
reconnect, because a broker that did not persist the session would otherwise
come back subscribed to nothing.

**Do not treat the broker as durable storage.** Two measured facts make that
unsafe:

- `max_queued_messages` is at its default of **1000**. If this backend is down
  long enough for a hundred tills to exceed that, Mosquitto silently drops the
  overflow.
- Mosquitto's `autosave_interval` defaults to **30 minutes**, so a hard kill can
  lose up to half an hour of persisted state.

Neither loses a bill, and that is the whole point of the acknowledgement design:
a dropped message is simply never acked, so the terminal keeps its copy and
sends it again. The broker is a transport, not a ledger.

**The store and terminal are read from the topic, never from the body.** A till
that could name its own store in the payload could redirect another counter's
acknowledgements.

## Configuring a terminal

Settings → Connectivity & sync → Configure.

| Field | Value |
|---|---|
| Store ID | **The numeric `locationid`.** Not a name — the tenant is resolved from it |
| Terminal name | Whatever staff call the till |
| Transport | `HTTP` or `MQTT` |
| Base URL (HTTP) | `https://your-host/live/api/v1/pos` |
| Broker host / port (MQTT) | `66.116.225.226`, port `1883`, **TLS off** (8883 is not configured) |

`store_id` carrying the locationid is load-bearing: `resolvePosStore` looks the
tenant up from it and refuses a location that is not registered. A terminal
cannot name its tenant.

## Mapping decisions

Worth knowing before the first bill lands.

- **Idempotency** is a unique index on `pos_orders.terminalorderid` — the UUID
  minted at the till — plus a Postgres advisory lock held for the life of the
  transaction, so a redelivery arriving concurrently waits and then sees the
  committed row rather than racing past the check.
- **`businessdate` is the day the sale was rung**, not the day it arrived. A
  till that was offline overnight uploads yesterday's bills this morning, and
  they belong to yesterday. Every daily figure keys on this.
- **Line amounts are scaled onto the bill total.** The till sends each line at
  its pre-apportionment value while the header carries the total after
  bill-level discounts. Left alone the item rows would sum to the subtotal and
  every report that adds up lines would disagree with the one reading the
  header.
- **Payment mode** is the largest tender on a split bill; the full split is
  kept verbatim in `paymentsjson` for drawer reconciliation.
- **Fractional quantities round *up* for stock.** `productstocks.quantity` is an
  integer column, so 1.5 kg of onions cannot be recorded exactly. Rounding up
  never under-deducts, so recorded stock is never higher than the shelf. The app
  order path truncates instead (1.5 → 1), which under-deducts; that behaviour was
  left untouched rather than silently changed for live traffic. **Making the
  column numeric is the real fix.**
- **Customers** match on `contactno` within the outlet's `applocationid`, so a
  shopper registered at a till and one who installed the app become one row.
  Registrations are **insert-if-absent** — never an update, so a profile
  corrected at head office is not reverted by a terminal replaying an old
  capture.
- **Catalogue** answers a snapshot or a change set, decided by the `since`
  revision — see below.
- **Barcodes** come from `products.productsku` — there is no barcode column.
  Scanning at the till matches on it, so SKUs must be the scannable code for
  barcode scanning to work.

## Catalogue: snapshots and deltas

`GET /catalogue?store_id=1135` with no `since` returns a **full snapshot**. The
response carries a `revision`; the terminal stores it and sends it back next
time as `since=`, and then gets only what changed.

A product is included in a change set when any of three things moved: the
product row (name, tax, brand), its row at this outlet (price, availability), or
its stock ledger. Stock counts because a shop's figure drifts from a till's on
every sale rung at another counter, and a delta that ignored it would let that
drift persist until someone forced a full pull.

**The one rule that matters.** A response marked `is_delta: false` is treated as
a snapshot, and the terminal **withdraws every product it does not mention**. A
filtered result labelled `false` therefore empties the shop's shelf. The filter
and the flag are computed from a single value in `Catalogue()` — there is no
path that filters without also setting the flag, and that is deliberate.

**A revision that cannot be read falls back to a full snapshot.** Malformed,
empty, or issued to a different outlet — all yield a zero cutoff and a complete
response. The other direction would leave a terminal permanently missing every
change it had not already seen, with nothing to indicate it.

**The revision only advances on the final page.** A terminal that abandons a
paginated pull half way gets back the revision it already had — or an empty one,
meaning the next pull is a snapshot. Both are recoverable; a prematurely
advanced revision is not.

**A delta cannot withdraw a deleted product.** A row removed from
`productlocations` leaves no tombstone, so nothing tells the change set to
retire it. Only a snapshot collects those, which is why a terminal should pull
without a revision periodically — the morning import is the natural moment.

## Terminal health

Every till publishes a heartbeat to `nearle/pos/{loc}/{terminal}/health` every
**30 seconds**. It is stored in Redis, never in Postgres.

| Env | Purpose |
|---|---|
| `REDIS_HOST` / `REDIS_PORT` | **Unset disables presence.** Point at the same Redis the express backend uses |
| `REDIS_USER` / `REDIS_PASSWORD` / `REDIS_DB` | Defaults `default`, empty, `0` |

```
pos:terminal:{terminalcode}          HASH, TTL 90s
pos:location:{locationid}:terminals  SET,  no TTL
```

The TTL is the whole design. A heartbeat is a fact with an expiry date: a till
that loses power stops refreshing, the key expires, and it disappears from the
board with nothing having to notice. In Postgres this would need ~288,000 writes
a day across a hundred tills *and* a reaper job, because a row saying "online"
cannot age out by itself.

90 seconds is three missed beats. Two would make an ordinary GPRS hiccup look
like a dead till; five would take two and a half minutes to notice a real one.

The set has **no TTL**, mirroring `city:{tenantid}:active_deliveries` in the
express backend: it is an index of what exists, not a claim that any of it is
alive. Membership means "this till has been seen here"; liveness is whether the
hash still exists.

Keys are namespaced `pos:*` and do not collide with express's `delivery:*`,
`city:*` or `rider_*`. **Worth keeping that way** — a shared datastore only stays
safe while each writer's keys are obviously its own.

A heartbeat is **never acknowledged**. Presence is fire-and-forget: a till that
stopped selling because a dashboard was busy would be a self-inflicted outage.

Read it back:

| Method | Path |
|---|---|
| `GET` | `/live/api/v1/pos/health/terminal?terminal_id=T4A9` |
| `GET` | `/live/api/v1/pos/health/location?location_id=12` |

A till whose key has expired comes back marked `offline` rather than being
omitted — omitting it would make a dead terminal indistinguishable from one that
was never installed, and the dead one is exactly what somebody is looking for.

What a heartbeat carries: identity and app version; **queue depth**
(`pending_bills`, `pending_registrations`, `oldest_pending_at`) — the numbers
that make a silent sync failure visible; **today's trading** (`today_bills`,
`today_amount`, `last_bill_at`) — a till that is connected but has rung nothing
in three hours is usually a jammed printer or an absent cashier; and device
state.

## Not built

- **Loyalty coming back down.** The uplink deliberately carries no points or
  spend — those belong to the bill stream, which is idempotent and sees every
  counter. Nothing yet computes them centrally and sends them to the tills, so
  a shopper's balance at a till is that till's view.
- **Device authentication.** A terminal is trusted with a locationid. Signed
  device tokens are the obvious next step before this is exposed publicly.
- **Battery and free storage in the heartbeat.** The reporter has a hook for
  them, but this build collects neither — they need platform packages a desktop
  build has no use for. Fields that are not collected are **omitted**, not sent
  as zero: a board showing every till at 0% battery is worse than one showing
  nothing.

## Broker accounts

Applied 2026-08-03 on `66.116.225.226`. Two scoped accounts now exist alongside
`admin`, with an ACL at `/mosquitto/config/acl` referenced from
`mosquitto.conf`.

| User | May publish | May subscribe |
|---|---|---|
| `pos_terminal` | `nearle/pos/+/+/{order,customer,status,health}` | `nearle/pos/+/+/{ack,command}`, `nearle/pos/+/catalogue` |
| `pos_ingest` | `nearle/pos/+/+/{ack,command}`, `nearle/pos/+/catalogue` | `nearle/pos/+/+/{order,customer,health,status}` |
| `admin` | everything — **deliberately unchanged** | everything |

A till therefore cannot publish to `nearle/riders/#` or `doormile/#`, and cannot
write its own ack topic — only the ingest may do that. Verified by publishing as
`pos_terminal` to all four and watching which arrived: the order did, the other
three did not.

**`admin` was left unrestricted on purpose.** Its credentials are compiled into
the rider app, so narrowing it here would cut off the live rider fleet without
warning. The right next step is:

```conf
user admin
topic readwrite nearle/riders/#
topic readwrite doormile/#
```

but only once someone has confirmed nothing else authenticates as `admin`.
Until then the ACL changes nothing for it — which is why applying it was safe.

Rollback, if ever needed:

```bash
cp /root/Mqtt/backup-<timestamp>/{mosquitto.conf,passwd} /root/Mqtt/config/
docker restart mqtt_broker
```

**Still outstanding on the broker:**

- **No TLS.** Port 8883 is not configured. Bills carry customer names and mobile
  numbers, and they travel in the clear. Traefik on the same host already
  terminates 443, so certificates exist to borrow from.
- **`passwd` is world-readable.** Mosquitto warns about it and future versions
  will refuse to load it. Tightening it means `chown 1883:1883` as well as
  `chmod`, because the broker runs as uid 1883 and a root-owned 0600 file would
  stop it starting.
- **Credentials in source.** `admin` is in the rider APK, Redis is hardcoded in
  the express backend, and Postgres was in this repository's git history until
  2026-08-03. The POS accounts above are the only ones not in any source tree —
  keep it that way.

## Capacity

Current load, measured: **~0.9 msg/s inbound**, 5 connected clients, 112
retained messages totalling 8 KB.

A hundred tills add roughly 3.3 msg/s steady (a 1 KB heartbeat each per 30s)
plus bursts of up to ~50 KB when a sale batch goes up. That is 3–4× current
traffic and well within what Mosquitto handles on any VPS. The broker will not
be the bottleneck; Postgres write throughput on bill ingest is the thing to
watch instead.