The role split was right; only its source was wrong. Signing in matched what
was typed against two constants compiled into the app — admin@nearle.in and
cashier@nearle.in — so which shell a person got was a property of the *build*.
A shop could not add a third person, revoke either of the two it had, or stop
anyone with the APK reading both passwords out of it.
TerminalLogin survives unchanged in shape, because the shape was the good part:
one flag the shell reads, a session that decides it, and a cashier sign-out that
takes the catalogue with it while a supervisor's leaves it behind. Every
consumer — visibleModulesProvider, resolvedModuleProvider, the sidebar, the page
header, the sign-out dialog — is untouched. What changed is that the enum is now
only constructible from a session the back office signed, so there is no path
left where the terminal grants itself a permission the server did not send.
It reads `can_manage_staff` rather than the role name or id. app_roles holds six
rows for four distinct roles, a great many accounts carry a roleid that is not
in the table at all, and the name comes back blank for most of them. Matching on
either would mean shipping a copy of the role table in the app and keeping the
two in step for ever. One boolean, decided server-side, cannot drift. It
defaults to false, which matters on the restore path: a session saved by a build
that predates the field comes back as a cashier, never silently as an admin.
This also restores the sign-in layer itself — pos_auth_api, pos_session,
session_store, the staff import and the bearer token — which an earlier commit
removed wholesale from a stale checkout. Its parent was the commit that added
them, so the deletion was a bad merge rather than a decision; the terminal has
been running on the two constants since.
The login screen loses its role tabs and its credential prefill. You do not
choose what you are on the way in.
The opener is now matched on the back office user id rather than on the first
account with a matching role, so the first bill of a shift is attributed to
whoever actually signed in.
Tests: the smoke suite pinned only the supervisor shell, and it was passing for
the wrong reason — the fake session omitted can_manage_staff, and the sidebar it
asserted on was there because the role was hardcoded. Both halves are pinned now
and the fake is parameterised. widget_test.dart was the stock Flutter counter
template, restored by the same bad merge, testing a MyApp that has never existed
in this repo.
292 tests pass; analyzer reports no errors and no warnings.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign-in compared `admin@nearle.in` / `nearle123` — a compile-time const — after
a 600ms delay standing in for a network call that was never made. Two things
followed, and the second was the serious one.
Every install of a build shared one password, and changing it meant a rebuild.
Worse: because nothing was checked with the back office, the *outlet* could not
come from the sign-in. It came from a store id typed into Settings, so the till
asserted which shop it belonged to and the server took its word. One field on
one screen moved a terminal into another tenant's books.
Now a person signs in with their own back-office account and the outlet arrives
as a consequence — sealed in a signed token, checked server-side on every
request, and not editable from this device. `DemoCredentials` is gone, along
with the prefilled fields and the "Demo account" hint that printed the password
on the login screen.
The pieces:
- `PosSession` — what the back office answers with. The token is opaque on
purpose: the till must not parse it or reason about what it appears to say.
- `SessionStore` — the whole session to the platform keystore, not SQLite. The
token is a bearer credential and SQLite here is a file behind a shop counter.
An expired session reads back as absent, so no caller has to remember to
check.
- `SyncConfig.bearerToken` — one accessor rather than the same `??` at each
call site, because the request that forgot it would be the one silently
sending no credentials. The session beats a static API key: the key says the
request came from our fleet, the session says which outlet it came from, and
only the second can stop a till reaching another tenant's books.
- Restore runs in `syncBootstrapProvider` *before* the engine starts. A drain
that began first would upload the day's bills unauthenticated. A till trades
all day; a reboot mid-shift must not put a login screen in front of a queue.
- An outlet picker, shown only when the account genuinely reaches several. Not
dismissable — defaulting silently to the first outlet is how a day's takings
end up filed against the wrong shop.
Store name, address, GSTIN and phone now come down with the session and are
written on sign-in. They were compile-time constants, and on a GST invoice
those fields are a legal requirement rather than decoration.
The smoke test signs in through a fake client and inside `runAsync`: sign-in
reaches SQLite now, and real disk I/O cannot complete on a widget test's fake
clock — pumping alone leaves it suspended for ever.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three changes, all driven by what the back office turned out to need.
The broker is shared with the rider fleet on nearle/riders/…, so topics
move under nearle/pos/{locationid}/{terminal}/… — one ACL rule per
system, and it is obvious from a topic which one owns it. Store ID now
carries the back office's numeric location id; the tenant is resolved
from it server-side and never taken from the wire.
A till publishes a heartbeat every 30 seconds on its own topic. The Last
Will already answers "is it dead", which is not enough to run a hundred
shops on: the failure that costs money is a terminal that is connected,
selling, and quietly holding two hundred bills it has never uploaded. So
the beat carries queue depth, the age of the oldest thing waiting,
today's trading, and printer reachability. Not retained — the back
office holds it under a TTL, and a retained beat would leave an
unplugged till looking alive until something overwrote it.
Bills now carry tax_breakdown, the GST slab split the cart already
computes. A tax return is filed per slab, and recomputing the split
server-side would mean redoing the discount apportionment and getting
exactly the same answer — or else the filed figure stops matching the
paper the shopper was handed.
Docs rewritten against the real deployment: Eclipse Mosquitto 2.1.2, no
NATS anywhere reachable, no TLS, and a broker whose queue and autosave
defaults mean it must not be treated as durable storage.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two defects that share a shape: a figure landing on the wrong record.
Bill-level discounts were apportioned across every line by a single
factor, so "20% off Beverages" pulled tax out of the atta line as well.
The bill total was right either way, which is what made it easy to ship
— only the slab split on a filed return was wrong. Targeted campaigns
now reduce the lines they name, and bill-wide reductions still spread
pro rata, so the arithmetic is unchanged wherever it was already right.
Shoppers registered at a till only ever reached the back office as three
fields riding along on a bill. Somebody who signed up and bought nothing
existed on one terminal and nowhere else, and two tills registering the
same mobile each minted their own row. Customers are now an outbox of
their own on pos/{store}/{terminal}/customer, and the id is a UUIDv5
over the normalised mobile number — so a hundred terminals agree on who
a shopper is without talking to each other.
Registrations go up before bills, and a failure there cannot strand a
day's takings. No loyalty figures are sent: they belong to the bill
stream, which is idempotent and knows about every counter.
Two things found while building it. Numbers were keyed on raw digits, so
a cashier typing +91 forked a shopper as effectively as a random id
would. And the sale path wrote the customer with ConflictAlgorithm
.replace, which is a DELETE and an INSERT — every column absent from the
row reverts to its schema default, so the new sync flag would have been
cleared by the shopper's next purchase.
Schema v8. Existing customers are queued rather than assumed sent: the
terminal cannot tell an imported row from a locally registered one, and
only one of those mistakes loses somebody.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Answers "which of my 100 tills are alive and healthy", and fixes three things
that were fine on one device and broken on a hundred.
Terminal identity (lib/data/local/terminal_identity.dart)
- Every device mints a UUID on first run, stored in its own database, plus a
short code (T4A9) derived from it. Renaming keeps the device id, so history
keeps pointing at the same physical till.
- Replaces the literal 'TERM-01', which was hardcoded in five places. The whole
fleet reported as one terminal: shift reports merged, MQTT topics collided,
and a second connection with the same client id evicts the first from the
broker — so two tills would have knocked each other offline in a loop.
Invoice numbers now carry the terminal code
- INV-2608-T4A9-00042. The sequence counter lives in each till's own database
and starts at 1, so without this every terminal in the fleet minted
INV-2608-00001 for its first sale of the month. The order UUID kept the data
distinct; the number a customer quotes on a receipt was not.
SQLite pragmas
- WAL, so the product grid refreshing does not block the sale being written,
and the file is never left mid-rewrite by a power cut.
- busy_timeout 5s, so a contended lock waits instead of throwing "database is
locked" — which at checkout is a failed sale with a customer standing there.
- synchronous NORMAL, the right trade under WAL for a till.
Fleet presence (lib/data/sync/presence_reporter.dart)
- Retained status record on connect and once a minute: device id, code, name,
app version, pending bill count, last upload, catalogue revision, sync halt
state. Retained so a dashboard connecting at noon gets all 100 terminals
immediately rather than a blank board.
- The Last Will already said "reachable". A till can be connected and still be
holding 200 unsent bills or running last month's prices; only pending_bills
and catalogue_revision say so.
NATS
- The MQTT gateway maps / to . so the existing transport works unchanged.
SyncConfig.asNatsSubject() exposes the translation, and the contract doc
gives the JetStream subjects (pos.*.*.order, pos.*.*.status) plus the two
server-side requirements: a file-backed stream, and the ack published by the
consumer after commit rather than by the ingest handler.
Tests: 129 -> 140. New coverage for identity minting and stability, per-device
invoice uniqueness, topic and client-id separation, NATS subject mapping, and
the two pragmas. Suite run three times clean.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Turns the orders table into a queue that empties itself. Bills were only
uploaded when a cashier pressed Sync at end of day; a till that was never
pressed held a day's takings indefinitely.
Drain engine (lib/data/sync/sync_engine.dart)
- Triggers on sale committed, network regained, 5-minute poll, head-office
request, and the manual button.
- Single flight: a busy till firing a trigger per sale would otherwise have
several passes reading the same pending rows and send every bill twice.
A trigger arriving mid-drain is queued and replayed, so nothing is dropped.
- Exponential backoff with +/-20% jitter to a 5-minute ceiling. The jitter
matters: a store's terminals all fail at the same instant when the line
drops, and would retry in lockstep without it.
- Halts rather than loops on a failure retrying cannot fix (bad credential,
refused batch). Pressing Sync clears the halt.
Transports (lib/data/remote/)
- OrderTransport interface; MQTT, HTTP and simulated implementations. The
repository does not know which is in use.
- MQTT: QoS 1 uplink, application-level ACK correlated by batch_id on a return
topic, retained Last Will for terminal-offline detection, downlink for
catalogue pushes and remote sync requests.
- A broker PUBACK is never treated as acceptance. It means the broker holds
the bytes, not that the ledger took the sale. Only ids the back office names
are marked synced; silence leaves a bill pending.
- HTTP carries a stable idempotency key across retries of the same bills.
Retention
- Accepted bills are kept 7 days instead of deleted, so a batch the back
office later loses can be re-sent in full. Purged after that; archived
totals stay forever.
- forBusinessDate now reads pending rows only. A retained bill exists in both
the orders table and day_archive, and summing both would overstate the day.
Fixes found while building this
- SyncEngine._refreshPending wrote state.copyWith(pending: await ...). Dart
evaluates the receiver before the awaited argument, so a connectivity drop
during the wait was silently overwritten by the stale snapshot. Caught by
the first run of the new engine tests.
- PrinterSettingsController wrote state after four awaits with no mounted
check, throwing "used after dispose" when Settings was left mid-load. This
was pre-existing and reached the cashier as a red screen.
Also
- Header pill now reports real sync state: LIVE / n QUEUED / SYNCING /
SYNC HALTED, with an explanation of where the bills are.
- Settings shows the route, last upload, next retry and retention window.
- docs/sync-contract.md states what the back office must implement, including
the idempotency requirement that at-least-once delivery makes mandatory.
Tests: 90 -> 129 passing. New coverage for backoff shape and jitter band,
single flight, halting, ACK correlation and partial acceptance, at-least-once
duplicate handling, retention and purge, and no double-counting after a sync.
Suite run six times clean.
Not addressed: bills already synced by an older build went up overstated and
still need server-side reconciliation. Broker credentials have no Settings
editor yet.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
