nearle_daily/backend_fiesta
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: nearle_daily:5d9879657b9d6763e7d325d722764cd0d8676208
Branches Tags
nearle_daily:main
...
compare: nearle_daily:main
Branches Tags
nearle_daily:main

26 Commits
5d9879657b ... main

Author SHA1 Message Date
Suriya
5864204d32 Zero the produce rates, on the owner's instruction 
The eight fresh lines at 1135 held 8, 12 and 18. Fresh unbranded fruit and
chilled fish are nil-rated under Indian GST, so those were overcharging.

Held back on the first pass and reported as REVIEW, because every one is a
reduction of a live tax rate and that is a decision for whoever signs the
returns rather than something a script should quietly do. Put to the owner and
released explicitly.

Two readings are assumed and are worth checking against what the counter
actually sells. Maceral and Tuna are taken as fresh or chilled — frozen,
branded or packaged fish is 5%. Hatsun curd was already 0 and stays there as
plain curd; flavoured yoghurt would be 5%.

The undo SQL for all eight is in the tool's output and restores the previous
rates exactly.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-05 20:51:56 +05:30
Suriya
d0c3cb751e Document the sale-date contract, and rate the packaged goods 
parsePosSaleDate needed no change — RFC3339Nano already accepts the offset the
terminal now sends, and Format("2006-01-02") on a zoned time still yields the
till's own trading day rather than UTC's. But the ordering of those layouts is
load-bearing and nothing said so, and the two bare layouts are a legacy that
should be recognisable as one: they exist for terminals built before the offset,
whose bills record an instant wrong by the offset with nothing in the payload to
recover it from. Two tests pin both halves, including the case that motivated
this — 00:30 IST, where UTC has not yet rolled into the same day.

The GST script writes only the four packaged lines at 1185, which sat at 0 and
were being billed with no tax at all.

It deliberately does not touch the produce at 1135. That was written believing
every rate was 0 — read from a field name that does not exist in the response,
so the check silently returned nothing. The rows in fact hold 8, 12 and 18, and
under Indian GST fresh unbranded fruit and chilled fish are nil-rated, so
several look like overcharging. Every correction there is a reduction of a live
rate, which belongs to whoever signs the returns rather than to a script. They
are reported as REVIEW and left as found.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-05 20:18:17 +05:30
Suriya
11595ad415 Record the probes that touched live data 
seedprices is the only account of what the 15 seeded retail prices were and how
to put the zeros back — products at 1135 and 1185 were all at 0, so nothing was
sellable and the terminal could not be exercised at all. It refuses to overwrite
a price a human already set, so re-running it is safe.

termfixcleanup removes the one bill posted to prove the terminalid fix against
production. Named by its own terminalorderid rather than by date or by "the
newest row": pos_orders holds real takings and is not a table to run an
unbounded DELETE against.

healthproof carries a warning it did not have when it was written. MQTT_USER in
.env is pos_ingest, which the ACL denies publish on the health topic, and
Mosquitto answers an ACL-denied QoS 1 publish with a PUBACK before discarding
it. So the tool connects, reports success, and nothing arrives — indistinguishable
from a dead consumer, which is how it read for an hour.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-05 18:48:24 +05:30
Suriya
ec672a3087 Add an HTTP heartbeat, and file bills under the till that rang them 
Two faults found while checking whether today's live bills had landed. They
had — 17 of them, complete — but both of these were sitting in the same data.

**Health existed only over MQTT.** The consumer subscribes to the health topic
and has done since startup, but a terminal on the HTTP route has no way to
reach it. Today's terminal was on HTTP, so it reported nothing and the board
showed "online 0 of 1" while the till was demonstrably alive and selling.
POST /pos/health now takes the same payload the broker carries, into the same
Redis record, so the board cannot tell the two routes apart and does not need
to. It answers 202 and swallows failures: a till that cannot say how it is must
still sell.

**terminalid was empty on 16 of 17 bills.** The consumer backfills a missing
terminal code from the topic, but onto the batch, while the row was built from
the order — the two never met, and importPosOrder was not handed the batch's
value at all. Over HTTP there was no topic to fall back on either. So the
invoice numbers read INV-2608-T5EDD-000NN while the column they should have
matched was blank, and `byterminal` on the sales summary grouped almost
everything under "". The bill's own terminal now wins with the batch's as the
fallback, trimmed, so whitespace is not mistaken for a code.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-05 18:48:24 +05:30
abhishek
bddd8fa265 product price 2026-08-04 10:58:26 +05:30
Suriya
8aa4d86eb6 Add a POS integration handover 
An API reference and rationale for whoever picks this up next. The
endpoints are the easy half; what is not obvious from reading the code is
why an ack is only published after the commit, why a duplicate counts as
a success, and why is_delta false on a filtered catalogue empties a
shop's shelf. Those are written down here because each one costs a shop
money when someone changes it without knowing.

Covers the GET endpoints in full — request parameters, real response
shapes, and the cases that surprise people: values coming back as
strings from a Redis hash, a quiet till answering 200 rather than 404,
and a bill at another outlet returning 404 even though the reference is
valid.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-03 20:22:11 +05:30
Suriya
b0caacd90a pos 2026-08-03 20:19:04 +05:30
Suriya
b9f389fcdf Process the MQTT ingest on a bounded worker pool 
paho delivers on one goroutine, so bills were committed strictly one
after another. Each is a full Postgres transaction — advisory lock,
dedup, stock row locks, availability check, four inserts, commit — which
is 10-30ms, so the ceiling was roughly 30-100 bills a second and a
shop's backlog draining after an outage took minutes to land.

A fixed pool behind a bounded queue, rather than a goroutine per
message. Unbounded concurrency would open a transaction per message and
exhaust the connection pool under a storm, stalling every one of them at
once — a slow minute turned into a dead one. When the queue fills,
submit blocks: paho stops acknowledging, the broker's in-flight window
fills, it stops sending, and the backpressure reaches the till, which
holds its bills and retries. Slow, but nothing is dropped.

Heartbeats get their own pool. Sharing one would let a backlog of bills
delay presence, so every till would appear to go dark at exactly the
moment the system was busiest — the worst time to be blind to which
counters are alive.

Payloads are copied on the way in. paho reuses its buffer once a handler
returns and the work now happens after that, so a queued bill would
otherwise be read as whatever message arrived next — silently, and as
valid JSON often enough to commit the wrong sale.

One bug found by its own test: submit-after-stop selected between a
done-channel and the job channel, and once both were ready Go picks at
random. Picking the send panics on a closed channel. It would have shown
up in production as an occasional crash during shutdown and nowhere
else. Now guarded by an RWMutex held across the send, so the queue
cannot be closed under one in progress.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-03 19:53:39 +05:30
Suriya
1e3386fac8 Elect a single MQTT consumer among replicas 
Deployed as a StatefulSet with three replicas, and MQTT has no queue
groups — every subscriber receives every message. All three pods would
commit the same bill and publish three acks. Nothing double-counts,
because the ingest deduplicates on the till's UUID and holds an advisory
lock, but it is three times the database work and three times the
traffic for one sale.

Ordinal 0 consumes; the others stay idle. A StatefulSet already
guarantees stable unique ordinals, so this is a deterministic election
with no lock, no lease and no new dependency. If that pod dies the set
recreates it and tills hold their bills meanwhile, which is what they
are built to do.

POS_MQTT_CONSUMER=always/never overrides it for deployments that are not
a StatefulSet. Anything without an ordinal name — a Deployment pod, a
bare container, local development — consumes, because a lone instance
that silently refused to would be a far more confusing failure than one
that did.

The client id now defaults to the pod name rather than a constant. Two
connections sharing an id evict each other in a reconnect loop that
looks exactly like a flapping network, and takes a while to recognise as
anything else.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-03 19:44:47 +05:30
Suriya
fc81df14e4 Answer the catalogue as a delta when the terminal sends a revision 
Every pull was a full snapshot, so a shop with a thousand products
re-sent all of them to correct one price. The response now carries a
revision the terminal stores and hands back, and a pull that supplies
one gets only what moved: the product row, its row at that outlet, or
its stock ledger. Stock is included because a shop's count 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 dangerous part is the flag, not the filter. A response marked
is_delta:false tells the terminal to withdraw every product it does not
mention — so a filtered result carrying that label empties the shelf.
Both are now derived from one value, and there is no path through the
function that filters without also setting the flag.

Everything ambiguous resolves toward the snapshot. A revision that is
malformed, empty, or issued to another outlet yields a zero cutoff and a
complete response; the opposite would leave a terminal permanently
missing changes with nothing to show for it. The revision advances only
on the final page, so a terminal that abandons a paginated pull cannot
end up holding one that claims it saw pages it never received. And the
stamp is taken a second in the past, because a product written during
the same second the query ran would otherwise fall on the wrong side of
the next cutoff and be skipped for good.

A delta still cannot withdraw a deleted product — removing a row from
productlocations leaves no tombstone — so a periodic pull without a
revision is what collects those.

Verified against the live outlet: a full pull of 12, a delta returning
only the one product whose price had changed, and pagination that stays
exact now that productid <= 0 is excluded in SQL rather than after the
LIMIT.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-03 19:26:01 +05:30
Suriya
8709556704 Add read endpoints for counter sales 
The ingest only ever wrote. A bill that reached pos_orders was safe and
completely unreachable — no screen in the product could show it, and the
only way to see a day's counter takings was to query the database by
hand.

Three endpoints: a paged bill list, one bill with its lines, and a
summary split the three ways somebody actually asks for — by tender for
reconciling a drawer, by day for a chart, by till for an outlet running
several counters.

locationid is required on all of them and is the authorisation boundary,
so a caller cannot page through another shop's takings by omitting a
parameter. Fetching a bill under the wrong outlet returns 404 even when
the reference is a real one.

Dates match businessdate rather than arrival, because a till that was
offline overnight uploads yesterday's bills this morning and they belong
to yesterday. The list is ordered by billedat for the same reason —
sorting by arrival would interleave a recovered backlog through today.

Unlike the ingest handlers these answer in the usual envelope: they are
read by the web app, not by a terminal, and nothing about them is bound
to the till's contract.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-03 19:17:03 +05:30
Suriya
ef647d3395 Give the POS its own broker accounts 
Two scoped users, pos_terminal and pos_ingest, with an ACL that keeps a
till to its own topics: it can publish its bills, registrations and
heartbeats, read its own acks, and nothing else. It cannot reach
nearle/riders/# or doormile/#, and cannot forge an ack — only the ingest
writes those.

admin is deliberately left unrestricted. Its credentials are compiled
into the rider app, so narrowing it would cut off the live fleet without
warning; that change needs someone to confirm nothing else uses it
first. Because admin's entry grants everything, applying the ACL changed
nothing for existing traffic — verified by watching riders 852 and 1114
keep publishing battery, speed and periodic logs throughout.

The scoping was verified by publishing as pos_terminal to four topics
and observing which arrived: the order did, the rider topic, the
doormile topic and its own ack topic did not.

Config and password file were backed up first; the rollback is one cp
and a container restart.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-03 18:01:05 +05:30
Suriya
64a219e7da Stop tracking .env 
It has been in the repository since the initial commit carrying the live
database host, user and password. Removing it from the index stops that
getting worse; the credentials are still in history and should be
rotated, which needs coordinating with everything that reads them.

Deployments should pass configuration as container environment rather
than shipping a file — a file on disk is one `git add -f` away from
being committed again.

Also closes the last untested path: a shopper registration published
over the broker rather than posted over HTTP. All three MQTT topics —
order, customer and health — have now been fired against the live
Mosquitto instance and acknowledged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-03 17:56:09 +05:30
Suriya
27fbbf0422 Merge remote-tracking branch 'origin/main' 2026-08-03 17:48:21 +05:30
Suriya
e3459a0f1c Ingest counter sales from the POS terminals, over MQTT and HTTP 
A till holds every bill in its own SQLite database and keeps it for
seven days after we acknowledge it, marking one synced only when its id
comes back in an ack. Everything here follows from that.

Silence is not acceptance, so a failing ingest publishes nothing at all
and the terminal simply sends again. A duplicate is a success, because
at-least-once delivery means a lost ack legitimately re-delivers bills
we already hold, and calling those failures would strand a day of
takings on the till. Deduplication is a unique index on the terminal's
UUID plus an advisory lock held for the transaction.

Bills land in pos_orders / pos_order_items rather than orders: a counter
bill carries a cashier, a terminal, a rounding adjustment, promos,
loyalty movement and a payment split that orders has nowhere to put, and
forcing one into the other loses whatever does not fit. Stock is *not*
split — a counter sale writes the same productstocks rows an app order
does, through helpers extracted from createOrderTx so the rule that
prevents overselling has one implementation rather than two.
GetRevenueSummary and GetSalesSummary were extended to union the new
table in; any new report has to remember the same.

Terminal health goes to Redis under a 90-second TTL, sharing the
instance the express backend uses. A heartbeat is a fact with an expiry
date: a till that loses power stops refreshing and ages off the board by
itself, where a Postgres row would need ~288k writes a day and a reaper.

Proven end to end against the live estate before commit: a bill over
HTTP and one over the real Mosquitto broker, the same bill three times
producing one row and one stock movement, and a heartbeat arriving on
the health endpoint. All probe data was removed afterwards.

Four things that only surfaced against real data. An unset jsonb column
failed the very first bill. Product SKUs are unusable as barcodes — 6,245
products share 93 SKUs and "1" covers 5,794 of them — against the till's
unique index, so barcodes fall back to the product id. A taxpercent of
-1 exists and would have put negative GST in a filed slab. And a product
with id 0 exists, which can never be billed and is now skipped.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-03 17:48:00 +05:30
abhishek
5d2e1fca9b store based coustmers 2026-08-03 15:12:13 +05:30
abhishek
481be667db Register the rider push-notification route 
/utils/notifyuser has been commented out since the initial commit, so every
rider push the admin consoles have ever sent returned 404. Riders were
assigned deliveries and never told, and the failure surfaced as a generic
"notification failed" that read like a transient network fault.

Nothing else was missing. The handler, the FcmNotification model, the
Firebase service account and the Dockerfile line that copies that account
into the image were all already in place — only the route registration was
absent, which is why the gap survived this long.

Verified against Google: with the route registered, FCM authenticates the
service account and returns a specific rejection for a deliberately invalid
token rather than a 404. No push was sent to a real rider, so the final hop
to a device is still unproven.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-07-31 12:48:36 +05:30
abhishek
c290e1729a Route offline sales by the branch named on each spreadsheet row 
The offline-sales import required one workbook per outlet and a store
picked in the UI. A merchant running several branches had to download,
fill and upload a file per branch, and the picker defaulted to the
tenant's first outlet — so an admin who never touched it silently
credited the wrong store, which no validation could catch because the
file and the selection agreed with each other.

One workbook now covers every branch. getsaletemplate takes locationid=0
(the default) to span the tenant, stamping tenantid, locationid and the
store name onto every row, and that row's locationid is what decides
which branch a sale is deducted from. The INNER JOIN on tenantlocations
confines it to outlets the tenant owns, so a template can never disclose
another merchant's catalogue.

uploadofflinesales accordingly takes locationid on each bill. The
locationid on the request itself becomes a scope constraint rather than
a destination: left at 0 the bills go where their rows say, and set to a
branch it pins the upload there and refuses anything else. That is what
holds a store user to their own store — the pin comes from their session,
so editing the locationid column in the spreadsheet changes nothing.
Every branch referenced is checked against the tenant regardless.

Branch context and catalogue are resolved once per branch and reused; a
workbook covering six outlets would otherwise re-run both queries for
every bill in it.

Duplicate detection is now per branch. Bill numbers only have to be
unique within a store, since counter books at different outlets
routinely restart numbering at 1, and treating a shared number as a
repeat would have silently dropped a real sale.

Verified against tenant 1087, whose two branches both stock product
6998 at 100 units: a single upload of two bills moved 1097 to 97 and
1135 to 95 independently; the same bill number at both branches imported
as two separate orders; an upload pinned to 1097 imported its own bill
and refused the 1135 one; a row naming another tenant's outlet was
refused; and re-uploading the file deducted nothing. All five test
orders were cancelled afterwards and both branches confirmed back at 100.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-07-31 12:17:52 +05:30
abhishek
583cd89063 new api for offline sales 2026-07-30 17:25:09 +05:30
abhishek
a11c4843ca Allocate order numbers atomically instead of read-then-increment 
Order ids were duplicating in production: 160 distinct (tenant, orderid) pairs
are shared by more than one order, worst of them "1135-1" on 108 orders, and
every order tenant 1147 has ever placed is numbered "1147-1".

getSequenceno read MAX(seqno)+1 and updateSeqno incremented, both against
r.db rather than the order's transaction and separated by the whole order
insert. Two concurrent orders therefore read the same number before either
wrote, and an order that rolled back still consumed one. Three further
defects made it worse:

  - A NULL orderseqno made COALESCE(MAX(orderseqno) + 1, 1) evaluate
    NULL + 1 = NULL and fall through to a hardcoded "<tenantid>-1". The
    increment then computed NULL + 1 = NULL too, so the counter could never
    leave NULL and every subsequent order reused that same id.

  - Tenants with several ordersequences rows (tenant 1135 has ~25) hit a
    GROUP BY returning multiple rows, of which Scan kept the first
    arbitrarily, while the increment updated all of them.

  - A tenant with no row at all fell back to "<tenantid>-1" indefinitely,
    because nothing ever created one.

nextSequenceNo replaces both functions with a single UPDATE ... RETURNING run
inside the caller's transaction, so the counter row stays locked until the
order commits and concurrent orders queue rather than collide. A NULL seeds
from the tenant's existing order count — at least as high as any number
already issued, so recovery cannot reissue a used id — the counter is pinned
to the tenant's lowest sequenceid so reads and writes address one row, and a
missing row is created on first use.

Verified against production data in rolled-back transactions: tenant 1147
(NULL) now yields 1147-9, 1147-10, ...; tenant 1135 (NULL plus duplicate rows)
1135-356 onward; tenant 916 keeps its 916-2024115209 subprefix format; an
unknown tenant creates its row and starts at 1. Eight concurrent allocations
produced eight distinct ids. Two real orders through the API returned 1147-9
and 1147-10, then were cancelled with stock restoring to its baseline.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-07-29 13:13:43 +05:30
abhishek
c94ddd34c7 Stop stock receipts clobbering products.productstatus 
products.productstatus is a per-product lifecycle field holding
"Active"/"Inactive". CreateProductStock overwrote it with "available" on every
stock receipt — an availability value written into a lifecycle column — which
destroyed the real lifecycle state of the rows it touched. 136 products now
read "available" and 12 "outofstock" with no way to recover what they were.

A single column on products cannot express availability anyway: the same
product can be stocked at one outlet and empty at another. That fact belongs
to productlocations.status, which SyncProductLocationStatus already derives
from the ledger, so the receipt path now updates only that and leaves
productstatus alone. UpdateProductStatus remains available as an explicit
admin operation; it is simply no longer called as a side effect of stock
movement.

GetProductCount counted available/outofstock off the same corrupted column and
returned near-nonsense as a result: across 6245 products it matched
'available' on 136 and 'outofstock' on 12, leaving 6097 — the real answer —
uncounted under "Active". It now derives both from the ledger, counting a
product available when it holds positive stock at any of the tenant's outlets,
so total = available + outofstock (6245 = 22 + 6223).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-07-29 13:08:35 +05:30
abhishek
3b60a90009 Derive stock and availability from the ledger, not stored fields 
Stock shown in the console did not match the productstocks ledger, and two
product endpoints were failing outright. Every cause was on the read side or
in how the availability flag was maintained; the ledger writes themselves
(CreateOrder's "out" entry, cancellation's "in" entry) were already correct.

Read fixes, repositories/productRepository.go:

- GetProductStocks returned SQLSTATE 42803 on every call: bare a.tenantid /
  a.stocktype / a.status under GROUP BY a.productid. The per-ledger-row
  columns are now aggregated and the grouping covers the identity columns.

- FetchFilteredProducts filtered on an alias `e` that no query defines, so
  every /getallproducts call carrying a locationid failed with SQLSTATE 42P01
  instead of returning products.

- FetchFilteredProducts joined productlocations on productid alone and joined
  a (productid, locationid)-grouped stock subquery on productid alone, so a
  product carried by three outlets came back three times, each row showing
  another outlet's quantity and status. Both are now tenant-scoped subqueries
  collapsed to one row per product and scoped to the outlet when one is given.

- GetProductStocks and FetchFilteredProducts compared stocktype = 'in'
  case-sensitively. Production holds 'in' and 'IN' both, so uppercase receipts
  were silently dropped from the balance: one outlet reported 0 for a product
  holding 50, another reported 0 for twelve products holding 200-840.

- GetStockStatement summed opening over stockdate <= CURRENT_DATE, making it
  arithmetically identical to closing. The Inventory ledger showed the same
  number in both columns on every row, which reads as stock never moving.

Availability flag:

productlocations.status was maintained by two different rules — the order path
derived it from the balance, the receiving path set 'available' on any "in"
entry regardless of the resulting balance. A partial restock that left the
balance at or below zero marked a product sellable, and a flag set by an old
order never cleared for stock that arrived by a route the API did not own.

Both paths now derive the flag from the live balance through one rule:
SyncProductLocationStatus (receiving side) and syncProductLocationStatus
(order side, inside the caller's transaction). ReactivateProductLocations is
replaced by the former; the service no longer filters refs by stocktype, since
the direction of the movement is no longer what decides the flag. A row that
has already drifted now repairs itself on its next ledger entry.

Verified against the live database: all four stock endpoints return matching
balances, /getallproducts no longer duplicates rows, and the flag sync was
exercised in both directions inside a rolled-back transaction.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-07-29 12:14:59 +05:30
abhishek
a913077da0 Fixed GetProducts 2026-07-28 15:57:46 +05:30
abhishek
139ce5cda2 product quantity 2026-07-28 15:37:04 +05:30
abhishek
c2f7d2481c stocks change 2026-07-27 18:54:40 +05:30
abhishek
f57127444f Lock productlocations rows before checking stock in CreateOrder 
The order-placement stock check (read available qty, then insert an "out"
deduction) had no row lock, so two concurrent orders for the same product
could both pass the availability check before either committed its
deduction, overselling the item. Locks each ordered product's
productlocations row with SELECT ... FOR UPDATE up front, in a fixed
(productid, locationid) order across all items so overlapping concurrent
orders contend for locks in the same sequence instead of deadlocking.
 2026-07-27 18:48:10 +05:30
46 changed files with 7862 additions and 319 deletions
Expand all files Collapse all files

21
.env
View File

@@ -1,21 +0,0 @@
APP_PORT=1009
DB_HOST=66.116.207.225
DB_PORT=5433
DB_NAME=nearledb
DB_USER=admin
DB_PASSWORD="Package@123#"
# --- Catalogue Postgres / pgvector (separate DB, read-only integration) ---
CATALOGUE_DB_HOST=31.97.228.132
CATALOGUE_DB_PORT=6054
CATALOGUE_DB_NAME=pgvector
CATALOGUE_DB_USER=admin
CATALOGUE_DB_PASSWORD="'Package@321#'"
# --- DigitalOcean Spaces (S3-compatible), catalogue product images ---
USE_S3=true
S3_ACCESS_KEY=DO801G8Q8JAZKF49U3WJ
S3_SECRET_KEY=lBQExYfkVqH+ybmGVmQH5MkThBbrIohA/VQLgcPUvug
S3_ENDPOINT=https://nearle.sgp1.digitaloceanspaces.com
S3_BUCKET=nearle
S3_REGION=sgp1

8
.gitignore vendored
View File

@@ -48,3 +48,11 @@ Thumbs.db
*.mov
*.wmv
# Local configuration. Tracked until 2026-08-03, which put the database
# credentials in this repository's history — removing it from the index stops
# that getting worse, but the existing history still has them and the password
# should be rotated.
.env
.env.*
!.env.example

458
POS_API.md Normal file
View File

@@ -0,0 +1,458 @@
# POS integration — handover
Everything a developer needs to work on, extend or debug the in-store POS
integration. Companion to [`POS_TERMINAL_INGEST.md`](POS_TERMINAL_INGEST.md),
which covers deployment and broker setup.
Base path for everything below: **`/live/api/v1/pos`**
---
## 1. What this is
Retail tills run a Flutter POS app. Each one holds its own SQLite database and
keeps working with no network at all. When a connection is available it
publishes completed bills to an MQTT broker; a consumer in this backend commits
them to Postgres and acknowledges.
```
Cashier completes sale
│
▼
Till's SQLite ───────────────────── one transaction, before any network
sync_status = 0 survives crash, power cut, dead wifi
│
▼
MQTT broker ──────────────────────── transit only, holds nothing you can rely on
nearle/pos/{loc}/{terminal}/order
│
▼
fiesta consumer (messaging/posmqtt.go)
│
▼
POSTGRES ─────────────────────────── the permanent record
pos_orders, pos_order_items
productstocks (stock deducted here)
│
▼
ack → nearle/pos/{loc}/{terminal}/ack
│
▼
Till marks it synced, keeps its copy 7 more days, then purges
```
**Health** takes a separate path: every till publishes a heartbeat every 30
seconds, which lands in **Redis** under a 90-second TTL. Never in Postgres.
---
## 2. The four rules everything rests on
Break any of these and shops lose money. They are not stylistic.
**1. Only an application acknowledgement counts.**
A broker PUBACK means "I hold these bytes". It is not evidence the database
accepted anything. The ack is published *after* the transaction commits, never
from a handler that has merely queued the work.
**2. Silence is not acceptance.**
No ack, an empty ack, 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.
**3. A duplicate is a success.**
Delivery is at-least-once. A lost ack makes a terminal re-send bills we already
hold. Reporting those as failures would strand a day of takings. Deduplication
is a unique index on `pos_orders.terminalorderid` — the UUID minted at the till
— plus a Postgres advisory lock held for the transaction.
**4. Store and terminal come from the topic, never the body.**
A till that could name its own store in a payload could redirect another
counter's acknowledgements.
---
## 3. Endpoints written by a terminal
These answer with a **bare body**, not the usual `{code, message, status}`
envelope — the till reads `accepted` from the top level and marks a bill synced
only if its id is there. Wrapping it would leave every terminal queueing for
ever.
### `POST /orders`
```json
{
"schema": 1,
"batch_id": "9f1c…",
"store_id": "1135",
"terminal_id": "T4A9",
"orders": [{
"id": "99999999-8888-4777-8666-555555555555",
"invoice_number": "INV-2608-T4A9-00002",
"created_at": "2026-08-03T17:29:00Z",
"cashier": "Divya",
"customer": {"id": "…", "mobile": "9840099999", "name": "Ravi"},
"subtotal": 60.0, "discount": 0.0, "tax": 4.44,
"tax_breakdown": {"0.08": 4.44},
"round_off": 0.0, "total": 60.0,
"points_earned": 0, "points_redeemed": 0,
"payments": [{"method": "upi", "amount": 60.0, "reference": "TXN123"}],
"items": [{
"product_id": "6988", "barcode": "6988", "name": "Mysore Banana",
"quantity": 1, "unit_price": 60.0, "discount": 0.0,
"gst_rate": 0.08, "tax": 4.44, "line_total": 60.0
}]
}]
}
```
Response:
```json
{ "batch_id": "9f1c…", "accepted": ["99999999-…"], "rejected": {} }
```
Status codes carry the other half of the contract:
| Code | Meaning | Terminal does |
|---|---|---|
| `200` | batch processed; ack says which bills landed | marks the named ids synced |
| `4xx` | the request is wrong — unknown outlet, bad store id | **halts** and shows a person |
| `5xx` | outcome unknown | keeps everything, retries with backoff |
### `POST /customers`
Same envelope with a `customers` array. **Insert-if-absent on id** — never an
update, so a profile corrected at head office is not reverted by a terminal
replaying an old capture.
The id is a **UUIDv5 over the normalised ten-digit mobile**, so two tills
registering the same shopper independently produce the same row. Do not
reassign it.
No loyalty figures travel upward — points and spend are derived from the bill
stream, which is idempotent and sees every counter.
---
## 4. GET endpoints — for the web app
**These use the normal `{code, message, status, details}` envelope.**
### `GET /sales` — bills for an outlet
```bash
curl "$BASE/sales?locationid=1135&fromdate=2026-08-01&todate=2026-08-03"
```
| Parameter | |
|---|---|
| `locationid` | **required** — the authorisation boundary |
| `fromdate`, `todate` | `YYYY-MM-DD`, matched on `businessdate` |
| `terminalid` | e.g. `T4A9` |
| `cashiername` | exact match |
| `paymentmode` | `cash`, `card`, `upi`, `wallet` |
| `pageno` | 0-based, default 0 |
| `pagesize` | default 50, max 500 |
```json
{
"code": 200, "status": true,
"details": {
"total": 137, "pageno": 0, "pagesize": 50,
"bills": [{
"posorderid": 7,
"terminalorderid": "99999999-8888-4777-8666-555555555555",
"invoicenumber": "INV-2608-T4A9-00002",
"tenantid": 1087, "locationid": 1135,
"terminalid": "T4A9", "cashiername": "Divya",
"customerid": 6847, "customermobile": "9840099999", "customername": "Ravi",
"billedat": "2026-08-03T17:29:00Z",
"businessdate": "2026-08-03",
"subtotal": 60, "discount": 0, "taxamount": 4.44,
"roundoff": 0, "total": 60,
"pointsearned": 0, "pointsredeemed": 0,
"itemcount": 1, "paymentmode": "upi",
"paymentsjson": "[{\"method\":\"upi\",\"amount\":60,\"reference\":\"TXN123\"}]",
"promosjson": "[]",
"taxbreakdownjson": "{\"0.08\":4.44}",
"batchid": "batch-mqtt-0001",
"receivedat": "2026-08-03T17:29:11Z"
}]
}
}
```
Line items are **not** included — a page of 50 bills would drag hundreds of rows
behind it and a list screen shows none of them. Use `/sales/detail`.
Ordered by `billedat` descending, not by id: a backlog uploaded after an outage
arrives out of order, and sorting by arrival would interleave yesterday's bills
through today's.
### `GET /sales/detail` — one bill with its lines
```bash
curl "$BASE/sales/detail?locationid=1135&reference=INV-2608-T4A9-00002"
```
`reference` accepts **any of three**: the terminal's order UUID, the invoice
number, or the `posorderid`. A support call starts from whichever the caller
happens to be looking at.
```json
{
"code": 200, "status": true,
"details": {
"posorderid": 7,
"invoicenumber": "INV-2608-T4A9-00002",
"…": "all the fields above, plus:",
"items": [{
"posorderitemid": 12, "posorderid": 7,
"productid": 6988, "productname": "Mysore Banana",
"barcode": "6988", "unitname": "kg",
"quantity": 1, "unitprice": 60,
"discountamount": 0, "gstrate": 0.08,
"taxamount": 4.44, "linetotal": 60
}]
}
}
```
Returns **404** if the reference does not belong to that `locationid` — even
when the reference is a real bill at another outlet.
### `GET /sales/summary` — totals
```bash
curl "$BASE/sales/summary?locationid=1135&fromdate=2026-08-01&todate=2026-08-03"
```
Takes the same filters as `/sales`.
```json
{
"code": 200, "status": true,
"details": {
"locationid": 1135,
"fromdate": "2026-08-01", "todate": "2026-08-03",
"billcount": 137, "itemcount": 402,
"grosssales": 18450.50, "taxcollected": 1204.30,
"discountgiven": 320.00, "roundoff": -1.50,
"averagebill": 134.68,
"bypaymentmode": [
{"paymentmode": "cash", "billcount": 80, "amount": 9200.00},
{"paymentmode": "upi", "billcount": 57, "amount": 9250.50}
],
"byday": [
{"businessdate": "2026-08-01", "billcount": 44, "amount": 5900.00}
],
"byterminal": [
{"terminalid": "T4A9", "billcount": 137, "amount": 18450.50}
]
}
}
```
Three breakdowns because they answer three different questions: **by tender**
for reconciling a drawer, **by day** for a chart, **by till** for an outlet
running several counters.
### `GET /health/terminal` — one till
```bash
curl "$BASE/health/terminal?terminal_id=T4A9"
```
```json
{
"code": 200, "status": true,
"details": {
"terminal_id": "T4A9", "location_id": "1135",
"store_name": "Ragul stores Selvapuram",
"app_version": "1.1.0", "status": "online",
"pending_bills": "0", "pending_registrations": "0",
"oldest_pending_at": "",
"today_bills": "2", "today_amount": "170",
"last_bill_at": "",
"printer_reachable": "0",
"reported_at": "2026-08-03T12:04:21Z",
"received_at": "2026-08-03T12:04:21Z"
}
}
```
Values are **strings** — it is a Redis hash. A till that has not reported inside
its TTL returns `200` with `status: "offline"`, not a 404: it exists, it is
simply quiet.
Fields the till does not collect are **absent, not zero**. A board showing every
terminal at 0% battery is worse than one showing nothing.
`pending_bills` is the number worth watching. A shop quietly accumulating
unsynced takings looks completely normal from the floor.
### `GET /health/location` — the "which counters are dark" board
```bash
curl "$BASE/health/location?location_id=1135"
```
```json
{
"code": 200, "status": true,
"details": {
"location_id": "1135", "total": 3, "online": 2,
"terminals": [
{"terminal_id": "T4A9", "status": "online", "today_bills": "37", "…": "…"},
{"terminal_id": "T7B2", "status": "offline", "reason": "no heartbeat within 90s"}
]
}
}
```
A till whose key expired comes back marked **offline rather than 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.
### `GET /catalogue` — the till's product pull
Bare body, no envelope. Used by terminals, not the web app.
```bash
curl "$BASE/catalogue?store_id=1135&page_size=500"
curl "$BASE/catalogue?store_id=1135&since=loc1135-20260803T135407Z"
```
No `since` → **full snapshot**. With a valid `since` → **change set**.
```json
{
"revision": "loc1135-20260803T135407Z",
"is_delta": false,
"has_more": false,
"products": [{
"id": "6988", "name": "Mysore Banana",
"barcode": "6988", "sku": "",
"category": "grocery", "price": 60, "stock": 750,
"unit": "kilogram", "gst_rate": 0.08, "is_active": true
}],
"customers": [],
"retired_product_ids": []
}
```
**`is_delta` is the dangerous field.** `false` means the terminal withdraws
every product the response does not mention. A filtered result labelled `false`
empties the shelf. In `Catalogue()` the filter and the flag are derived from one
value, so no code path can set one without the other.
Anything ambiguous resolves toward the snapshot: a revision that is malformed,
empty, or issued to a different outlet yields a full response.
The revision **only advances on the final page**, so a terminal that abandons a
paginated pull cannot end up holding one claiming it saw pages it never got.
A delta **cannot withdraw a deleted product** — removing a row from
`productlocations` leaves no tombstone. Only a snapshot collects those, so tills
should pull without a revision periodically.
---
## 5. MQTT topics
| Topic | Direction | Retained |
|---|---|---|
| `nearle/pos/{loc}/{terminal}/order` | till → us | no |
| `nearle/pos/{loc}/{terminal}/customer` | till → us | no |
| `nearle/pos/{loc}/{terminal}/health` | till → us, 30s | no |
| `nearle/pos/{loc}/{terminal}/ack` | us → till | no |
| `nearle/pos/{loc}/{terminal}/status` | till → us | **yes** (Last Will) |
| `nearle/pos/{loc}/catalogue` | us → all tills at a shop | **yes** |
`{loc}` is the numeric `tenantlocations.locationid`. The tenant is resolved from
it server-side and never taken from the wire.
Namespaced under `nearle/` alongside the rider fleet's `nearle/riders/…`.
---
## 6. Database
**`pos_orders`** — one row per counter bill. Separate from `orders` because a
bill carries a cashier, terminal, rounding, promos, loyalty and a payment split
that `orders` has nowhere to put.
**`pos_order_items`** — one row per line.
**`productstocks`** — stock is **not** separate. A counter sale writes the same
`out` rows an app order does, through helpers in `repositories/stockLedger.go`.
Two stock ledgers would mean the catalogue pull sends a till figures that ignore
its own trading.
**`customers`** — registrations, matched on `contactno`.
**Redis** — `pos:terminal:{code}` (hash, 90s TTL) and
`pos:location:{id}:terminals` (set, no TTL). Namespaced `pos:*` so they cannot
collide with express's `delivery:*`, `city:*`, `rider_*`.
> **Reporting:** counter sales are unioned into `GetRevenueSummary` and
> `GetSalesSummary`. **Any new report must do the same**, or it will silently
> understate every shop that runs a till. That is the standing cost of the split.
---
## 7. Code map
| File | |
|---|---|
| `models/pos.go` | wire types — matches the till's JSON exactly |
| `models/posorder.go` | `pos_orders` / `pos_order_items` |
| `models/poshealth.go` | heartbeat |
| `repositories/posRepository.go` | ingest + catalogue |
| `repositories/posSalesRepository.go` | the GET reads |
| `repositories/posPresence.go` | Redis presence |
| `repositories/stockLedger.go` | **shared** stock helpers |
| `messaging/posmqtt.go` | MQTT consumer |
| `messaging/posworkers.go` | bounded worker pools |
| `controllers/posController.go` | HTTP handlers |
| `routes/posroutes.go` | routes |
---
## 8. Operational notes
**Only `fiesta-0` consumes.** MQTT has no queue groups, so all replicas would
receive every message and commit the same bill three times. Ordinal 0 is
elected; the others log *"not the elected consumer"*. Override with
`POS_MQTT_CONSUMER=always|never`.
**Worker pools**: `POS_INGEST_WORKERS` (default 8), `POS_HEALTH_WORKERS`
(default 2). Heartbeats have their own pool so a backlog of bills cannot make
every till look dark at the busiest moment. A full queue **blocks**, pushing
backpressure to the broker and the till — slow, never lossy.
**Startup check**: three `pos: subscribed to nearle/pos/+/+/…` lines on
`fiesta-0`. Without them, MQTT ingest is not running and tills queue silently.
**The broker is not durable storage.** Mosquitto's `max_queued_messages` is 1000
and it flushes every 30 minutes. Fine, because a till keeps its copy until we
acknowledge — but nobody may ever ack on the broker's behalf.
---
## 9. Known gaps
- **No product prices.** Every product at loc 1135 is ₹0, so nothing is
sellable. Unpriced products come down as `is_active: false` so a till cannot
ring up a ₹0 item.
- **The Flutter app has never been run.** All testing used a Go program
impersonating a till.
- **No TLS** on port 1883. Bills carry customer names and mobile numbers.
- **No device authentication.** A terminal is trusted with a location id.
- **Loyalty does not come back down.** Balances at a till are that till's view.
- **`productstocks.quantity` is an integer** but tills sell in kg. POS rounds
**up** so it never under-deducts; the app-order path truncates, which was left
alone rather than silently changed. Making the column numeric is the real fix.
- **Broker credentials in source** — `admin` is in the rider APK and still
unrestricted. The two POS accounts are the only ones not in a source tree.

362
POS_TERMINAL_INGEST.md Normal file
View File

@@ -0,0 +1,362 @@
# 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.

95
SECURITY_HANDOFF.md Normal file
View File

@@ -0,0 +1,95 @@
# Handoff: Broken Access Control (IDOR) audit & fixes — Fiesta backend
Repo: `backend_fiesta` (Go + Fiber + GORM), consumed by `nearledaily/daily_merchant_web` (React/TS) and a mobile app (not in this repo).
## 1. The root problem (still not fully fixed — read this first)
**There is no authentication system in this backend.** Grep confirms:
- No JWT/session token is ever issued. `Login`, `TenantLogin`, `TenantWebLogin`, `AppLogin` (in `controllers/userController.go`) just look up the user/tenant and return their info in the JSON body — no token.
- No auth middleware exists anywhere. `routes/routes.go` / `main.go` only wire up CORS middleware. Every route is wide open — anyone who can reach the API can call any endpoint with any query params.
Because of that, every endpoint trusts client-supplied query params (`tenantid`, `customerid`, `partnerid`, etc.) as the sole source of "who is asking." There is currently **nothing stopping a logged-in store admin for tenant 1135 from just requesting `?tenantid=1136`** and getting another tenant's data — the frontend happens to always send the logged-in user's own tenantid, but the backend never checks it.
**This session's fixes only close one specific hole**, described below. The real fix — deriving identity server-side from a verified token instead of trusting query params — has not been started. Whoever picks this up should treat that as the actual next milestone.
## 2. The specific bug that was found and fixed this session
Pattern found repeatedly across the codebase: repository functions build SQL dynamically, e.g.
```go
query := "SELECT ... FROM orders WHERE 1=1"
if tenantID != 0 {
query += " AND tenantid = ?"
params = append(params, tenantID)
}
// ...similar optional blocks for partnerid, customerid, etc.
```
**If none of the scoping params were supplied (0 / empty), the query silently fell through to "no WHERE clause" and returned every row in the table across every tenant.** This was directly reachable — e.g. `orders/getorders` with no `tenantid` returned all ~300 orders in the DB rather than 400ing, which is how the user first noticed this (logged in as a store admin, expected only their store's orders, saw everyone's).
### Fix pattern applied
Rather than rewriting every repository query (large surface area, higher regression risk), a **controller-level guard** was added to each affected endpoint: if none of the valid scoping ids are present in the query string, return `400` immediately instead of calling the service/repo at all.
Standard error shape used everywhere:
```json
{ "status": false, "code": 400, "message": "<specific message>" }
```
## 3. Endpoints fixed (8 total)
| # | Endpoint | File / function | Guard added |
|---|---|---|---|
| 1 | `GET /v1/web/orders/getorders` (+ mob) | `controllers/orderController.go` `GetOrders` (line 24) | requires one of `tenantid`, `partnerid`, `customerid`, `applocationid`, `appuserid` — else 400 (line ~102-110). Previously the `else` branch called `GetAllOrders` (unscoped). |
| 2 | `GET /v1/web/orders/getordersummary` | `controllers/orderController.go` `GetOrderSummary` (line 129) | requires one of `tenantid`, `partnerid`, `customerid`, `locationid` (line 137-143) |
| 3 | `GET /v1/web/orders/getlocationsummary` | `controllers/orderController.go` `GetlocationOrderSummary` (line 163) | requires `tenantid` (line 167-173) |
| 4 | `GET /v1/web/users/getallusers` | `controllers/userController.go` `GetAllUsers` (line 22) | requires `tenantid` (line 29-35). Note: this endpoint's query selects `a.pin` (login PIN) — this was a high-severity leak (PINs across all tenants) before the fix. |
| 5 | `GET /v1/web/deliveries/getdeliveries` (+ mob) | `controllers/deliveriesController.go` `GetDeliveries` (line 194) | requires one of `tenantid`, `partnerid`, `customerid`, `applocationid`, `userid`, `appuserid` (line 212-218) |
| 6 | `GET /v1/web/partners/getriders` (+ mob) | `controllers/partnerController.go` `GetActiveRiders` (line 19) | requires one of `tenantid`, `partnerid`, `applocationid`, `userid` (line 25-31). Lower severity — underlying repo query defaults to `userid = 0` rather than a full dump, but fixed for consistency. |
| 7 | `GET /v1/web/partners/getriderlogs` (+ mob) | `controllers/partnerController.go` `GetRiderLogs` (line 121) | requires one of `partnerid`, `applocationid` (line 127-133). **Also fixed an unrelated bug in the same function**: `tdate` was reading `c.Query("fromdate")` (copy-paste error) so the end of any date range was always silently overwritten with the start date. Now correctly reads `c.Query("todate")` (line 125). |
| 8 | `POST /v1/mob/orders/getcustomerorders` | `controllers/orderController.go` `GetCustomerOrders` (line 374) | requires `customerid` (line 394-400) |
### Also fixed alongside #2: SQL injection in `GetOrderSummary`
`repositories/orderRepository.go` `GetOrderSummary` previously built the date filter by **string-concatenating** `fdate`/`tdate` directly into raw SQL. Rewritten to use parameterized `?` placeholders passed through `r.db.Raw(query, params...)`. The `strconv` import was removed from that file since it became unused after the rewrite (verified via grep no other usage remained).
## 4. Reviewed and explicitly NOT changed (don't re-flag these)
Same `WHERE 1=1` pattern exists elsewhere but was judged not to be a bug, or already safe:
- **`repositories/tenantRepository.go` `GetAllTenants`** — intentionally lists all tenants for a platform/super-admin console. The gap here is "no RBAC to restrict who can call this," which is the same root-cause auth gap from section 1, not a scoping bug to patch individually.
- **`repositories/productRepository.go` `GetProductSubCategory`** — has an explanatory comment: subcategories are intentionally shared/global master data plus tenant-owned overrides. Not a bug.
- **`repositories/productRepository.go` `GetProductCount`** — returns aggregate counts only (no PII), low severity, left as-is.
- **`repositories/utilsRepository.go` `GetSubcategories`** — global taxonomy/reference data; the model has no tenant field at all.
- **`repositories/orderRepository.go` `GetAdminOrders`** — has `WHERE 1=1` internally but is safe because its only caller (`GetOrders` controller) only invokes it when `applocationid != 0`.
- **`repositories/orderRepository.go` `GetAllOrders`** — now dead code (unreachable) after fix #1 above; confirmed via grep it's no longer called anywhere. Could be deleted as cleanup but left in place.
- **`repositories/tenantRepository.go` `GetTenantLocations`** — already always filters `WHERE tenantid = ?`. Safe, unchanged.
## 5. Known pre-existing bug found during this audit, NOT yet fixed anywhere
**Frontend/backend path mismatch on rider logs.** In `nearledaily/daily_merchant_web/src/services/fiestaApi.ts`, `getRiderLogs()` (~line 1132) calls:
```ts
fiestaGet('riders/getriderlogs', {...})
```
`FIESTA_BASE` is `https://fiesta.nearle.app/live/api/v1/web`, so this resolves to `.../v1/web/riders/getriderlogs`. But the backend only registers this route under the `partners` group (`routes/partnerroutes.go`): `partner.Get("/getriderlogs", ...)` on `api.Group("/v1/web/partners")`, i.e. the real path is `.../v1/web/partners/getriderlogs`. Confirmed via grep there is no `/v1/web/riders` route group anywhere in the backend.
**This means `getRiderLogs()` in the web console has likely been 404ing already, independent of anything fixed this session.** Fix is a one-line FE change: `'riders/getriderlogs'` → `'partners/getriderlogs'`. Not fixed yet because it's a frontend-repo change and wasn't the scope of this backend security pass — flagging it here so it isn't lost.
## 6. Frontend compatibility check (already done, no FE changes needed for the 8 fixes above)
Checked `daily_merchant_web/src/services/fiestaApi.ts` against every fix — the web console already sends the now-required params in all cases:
- `getOrders`, `getAllUsers`, `getDeliveries`, `getOrderSummary`, `getLocationSummary` — all declare `tenantid: number` as a **required** (non-optional) TS field already.
- `getRiders` — always sends `applocationid: opts.applocationid ?? FIESTA_APPLOCATION_ID` (never zero/undefined) plus required `tenantid`.
- `getRiderLogs` — sends `tenantid`/`applocationid` when available, but see the path bug in section 5 — worth re-verifying once that's fixed.
- **`mob/orders/getcustomerorders`** (fix #8) is called from the **mobile app**, which is not in this repo — whoever owns that codebase needs to verify every call site always sends `customerid`. Not verified in this session.
## 7. Environment note
**No Go toolchain is available in the sandbox this session ran in** (`command not found: go`). All edits above were manually reviewed (imports, syntax, call sites checked via Read/grep) but **never compiled**. Run `go build ./...` and the existing test suite (if any) before deploying any of this.
## 8. Suggested next steps for whoever picks this up
1. `go build ./...` and smoke-test all 8 changed endpoints (call with and without the required param, confirm 200 vs 400).
2. Fix the `riders/getriderlogs` → `partners/getriderlogs` path bug in `fiestaApi.ts` (section 5).
3. Verify the mobile app always sends `customerid` to `mob/orders/getcustomerorders` before this ships, since that's the one fixed endpoint not verified from a frontend contract.
4. Scope and plan the real fix: JWT/session auth issuance + middleware, so `tenantid`/`customerid`/etc. are derived from a verified server-side identity instead of trusted from query params. Until that lands, the 8 fixes in this doc only prevent the "forgot to pass an id → get everything" failure mode — they do **not** prevent a malicious or buggy client from passing a *different* tenant's/customer's/partner's real id and getting their data.

70
controllers/orderController.go
View File

@@ -1,6 +1,7 @@
package controllers
import (
"fmt"
"log"
"nearle/models"
"net/http"
@@ -371,6 +372,75 @@ func (ctl *OrderController) CreateOrderv3(c *fiber.Ctx) error {
})
}
// UploadOfflineSales imports a spreadsheet of in-store counter sales.
//
// The response is 200 whenever the batch was processed, even if individual
// bills were rejected, because a partial import is a normal outcome for a
// spreadsheet and the per-bill results carry the detail. A non-200 means
// nothing at all was attempted — a malformed body, or an outlet the caller has
// no claim on.
func (ctl *OrderController) UploadOfflineSales(c *fiber.Ctx) error {
var input models.OfflineSalesUpload
if err := c.BodyParser(&input); err != nil {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest,
"message": "could not read the upload: " + err.Error(),
"status": false,
})
}
// locationid is optional: 0 means the bills carry their own branch, which
// is how one workbook covers every outlet a merchant runs. Supplying it
// pins the upload to that branch and rejects anything else in the file.
if input.Tenantid <= 0 {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest,
"message": "tenantid is required",
"status": false,
})
}
if len(input.Bills) == 0 {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest,
"message": "no sales rows found in the upload",
"status": false,
})
}
result, err := ctl.orderService.UploadOfflineSales(input)
if err != nil {
log.Println("UploadOfflineSales service error:", err)
// An outlet the caller doesn't own is a permission problem, not a
// server fault, and is reported as one so the UI can say so plainly.
statusCode := http.StatusInternalServerError
if strings.Contains(strings.ToLower(err.Error()), "does not belong to tenant") {
statusCode = http.StatusForbidden
}
return c.Status(statusCode).JSON(fiber.Map{
"code": statusCode,
"message": err.Error(),
"status": false,
})
}
message := fmt.Sprintf("%d bill(s) imported", result.Imported)
if result.Duplicate > 0 {
message += fmt.Sprintf(", %d already imported", result.Duplicate)
}
if result.Failed > 0 {
message += fmt.Sprintf(", %d failed", result.Failed)
}
return c.Status(http.StatusOK).JSON(fiber.Map{
"code": http.StatusOK,
"message": message,
"status": true,
"details": result,
})
}
func (ctl *OrderController) GetCustomerOrders(c *fiber.Ctx) error {
customerID := c.Query("customerid")
tenantID := c.Query("tenantid")

378
controllers/posController.go Normal file
View File

@@ -0,0 +1,378 @@
package controllers
import (
"fmt"
"log"
"net/http"
"strconv"
"strings"
"nearle/models"
"nearle/services"
"github.com/gofiber/fiber/v2"
)
// HTTP face of the POS terminal ingest.
//
// These handlers break this codebase's house style in one respect, on purpose:
// they answer with a bare ack rather than the usual
// `{code, message, status, details}` envelope. The terminal reads `accepted`
// from the top level of the body and marks a bill synced only if its id is
// there — wrapping the ack would leave every till queueing for ever.
//
// The status code carries the other half of the contract:
//
// - **200** — the batch was processed. Individual bills may still have been
// refused; the ack says which.
// - **4xx** — the request itself is wrong (unreadable body, unknown outlet).
// The terminal treats these as non-retryable and halts, so a person is
// told rather than the broker hammered.
// - **5xx** — the outcome is unknown. The terminal keeps every bill and
// retries with backoff. This is the right answer when the database is
// having a bad minute: *never* ack a batch that did not commit.
type PosController struct {
posService services.PosService
}
func NewPosController(posService services.PosService) *PosController {
return &PosController{posService: posService}
}
// IngestOrders receives a batch of completed counter bills.
func (ctl *PosController) IngestOrders(c *fiber.Ctx) error {
var batch models.PosOrderBatch
if err := c.BodyParser(&batch); err != nil {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest,
"message": "could not read the batch: " + err.Error(),
"status": false,
})
}
if strings.TrimSpace(batch.Storeid) == "" {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest,
"message": "store_id is required",
"status": false,
})
}
ack, err := ctl.posService.IngestOrders(batch)
if err != nil {
return posIngestError(c, "IngestOrders", err)
}
return c.Status(http.StatusOK).JSON(ack)
}
// IngestCustomers receives shoppers registered at a till.
func (ctl *PosController) IngestCustomers(c *fiber.Ctx) error {
var batch models.PosCustomerBatch
if err := c.BodyParser(&batch); err != nil {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest,
"message": "could not read the batch: " + err.Error(),
"status": false,
})
}
if strings.TrimSpace(batch.Storeid) == "" {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest,
"message": "store_id is required",
"status": false,
})
}
ack, err := ctl.posService.IngestCustomers(batch)
if err != nil {
return posIngestError(c, "IngestCustomers", err)
}
return c.Status(http.StatusOK).JSON(ack)
}
// IngestHealth records one heartbeat from a till.
//
// The same heartbeat the broker carries, over HTTP, because presence was
// previously reachable *only* over MQTT — a terminal configured for the HTTP
// route reported bills perfectly and never appeared on the fleet board at all,
// with nothing anywhere to say why. A monitoring feature that silently does not
// exist on one of two supported transports is worse than no feature.
//
// Answers 202 rather than 200: nothing is committed, and the till is told not
// to wait on it. Failures are swallowed for the same reason the MQTT path
// swallows them — a terminal that cannot say how it is must still sell, and a
// blank square on a dashboard beats a till that stopped because Redis was busy.
func (ctl *PosController) IngestHealth(c *fiber.Ctx) error {
var health models.PosHealth
if err := c.BodyParser(&health); err != nil {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest,
"message": "could not read the heartbeat: " + err.Error(),
"status": false,
})
}
// Over MQTT these come from the topic. There is no topic here, so the body
// is the only source and both are required — a heartbeat that cannot say
// which till it belongs to is unfilable.
if strings.TrimSpace(health.Terminalid) == "" {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest, "status": false,
"message": "terminal_id is required",
})
}
if strings.TrimSpace(health.Locationid) == "" {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest, "status": false,
"message": "location_id is required",
})
}
// Matches the consumer: a bare {"status":"offline"} is a Last Will and must
// survive as-is, but an unset status from a till that is plainly talking to
// us means online.
if strings.TrimSpace(health.Status) == "" {
health.Status = "online"
}
if err := ctl.posService.RecordHealth(c.Context(), health); err != nil {
// Logged, not returned. See above — the till must not slow down for it.
log.Printf("pos: could not record heartbeat from %s/%s over HTTP: %v",
health.Locationid, health.Terminalid, err)
}
return c.Status(http.StatusAccepted).JSON(fiber.Map{
"status": true, "code": http.StatusAccepted,
})
}
// Catalogue answers a terminal's product pull.
func (ctl *PosController) Catalogue(c *fiber.Ctx) error {
storeID := strings.TrimSpace(c.Query("store_id"))
if storeID == "" {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest,
"message": "store_id is required",
"status": false,
})
}
page, _ := strconv.Atoi(c.Query("page", "0"))
pageSize, _ := strconv.Atoi(c.Query("page_size", "500"))
result, err := ctl.posService.Catalogue(storeID, c.Query("since"), page, pageSize)
if err != nil {
return posIngestError(c, "Catalogue", err)
}
return c.Status(http.StatusOK).JSON(result)
}
// TerminalHealth returns one till's live state, for a support call that starts
// with a terminal code.
func (ctl *PosController) TerminalHealth(c *fiber.Ctx) error {
terminalID := strings.TrimSpace(c.Query("terminal_id"))
if terminalID == "" {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest, "message": "terminal_id is required", "status": false,
})
}
fields, err := ctl.posService.TerminalHealth(c.Context(), terminalID)
if err != nil {
return c.Status(http.StatusServiceUnavailable).JSON(fiber.Map{
"code": http.StatusServiceUnavailable, "message": err.Error(), "status": false,
})
}
if fields == nil {
// Not an error. The till has simply not reported inside its TTL, which
// is the answer the caller wanted — said plainly rather than as a 404
// that reads like the terminal does not exist.
return c.JSON(fiber.Map{
"code": http.StatusOK,
"status": true,
"details": fiber.Map{
"terminal_id": terminalID,
"status": "offline",
"reason": "no heartbeat received within the presence window",
},
})
}
return c.JSON(fiber.Map{"code": http.StatusOK, "status": true, "details": fields})
}
// LocationHealth returns every till at a shop — the "which counters are dark"
// board. Tills that have stopped reporting come back marked offline rather than
// being omitted, because a missing till is exactly what somebody is looking for.
func (ctl *PosController) LocationHealth(c *fiber.Ctx) error {
locationID := strings.TrimSpace(c.Query("location_id"))
if locationID == "" {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest, "message": "location_id is required", "status": false,
})
}
terminals, err := ctl.posService.LocationHealth(c.Context(), locationID)
if err != nil {
return c.Status(http.StatusServiceUnavailable).JSON(fiber.Map{
"code": http.StatusServiceUnavailable, "message": err.Error(), "status": false,
})
}
online := 0
for _, t := range terminals {
if t["status"] == "online" {
online++
}
}
return c.JSON(fiber.Map{
"code": http.StatusOK,
"status": true,
"details": fiber.Map{
"location_id": locationID,
"total": len(terminals),
"online": online,
"terminals": terminals,
},
})
}
// ---------------------------------------------------------------- Sales reads
//
// Unlike the ingest handlers above, these answer in the usual
// `{code, message, status, details}` envelope — they are read by the web app,
// not by a terminal, and nothing about them is bound to the till's contract.
// posSalesFilter reads the shared query parameters.
func posSalesFilter(c *fiber.Ctx) (models.PosSalesFilter, error) {
locationID, err := strconv.Atoi(strings.TrimSpace(c.Query("locationid")))
if err != nil || locationID <= 0 {
return models.PosSalesFilter{}, fmt.Errorf("locationid is required")
}
pageno, _ := strconv.Atoi(c.Query("pageno", "0"))
pagesize, _ := strconv.Atoi(c.Query("pagesize", "50"))
return models.PosSalesFilter{
Locationid: locationID,
Fromdate: strings.TrimSpace(c.Query("fromdate")),
Todate: strings.TrimSpace(c.Query("todate")),
Terminalid: strings.TrimSpace(c.Query("terminalid")),
Cashiername: strings.TrimSpace(c.Query("cashiername")),
Paymentmode: strings.TrimSpace(c.Query("paymentmode")),
Pageno: pageno,
Pagesize: pagesize,
}, nil
}
// GetSales lists counter bills for an outlet, newest first.
func (ctl *PosController) GetSales(c *fiber.Ctx) error {
filter, err := posSalesFilter(c)
if err != nil {
return posBadRequest(c, err)
}
page, err := ctl.posService.Sales(filter)
if err != nil {
return posServerError(c, "GetSales", err)
}
return c.JSON(fiber.Map{"code": http.StatusOK, "status": true, "details": page})
}
// GetSaleDetail returns one bill with its lines.
//
// Accepts the terminal's order UUID, the invoice number, or this backend's
// posorderid — a support call starts from whichever the caller is looking at.
func (ctl *PosController) GetSaleDetail(c *fiber.Ctx) error {
locationID, err := strconv.Atoi(strings.TrimSpace(c.Query("locationid")))
if err != nil || locationID <= 0 {
return posBadRequest(c, fmt.Errorf("locationid is required"))
}
reference := strings.TrimSpace(c.Query("reference"))
if reference == "" {
return posBadRequest(c, fmt.Errorf("reference is required — an order id, invoice number or posorderid"))
}
bill, err := ctl.posService.SaleDetail(locationID, reference)
if err != nil {
return posServerError(c, "GetSaleDetail", err)
}
if bill == nil {
return c.Status(http.StatusNotFound).JSON(fiber.Map{
"code": http.StatusNotFound,
"message": "no bill matches that reference at this outlet",
"status": false,
})
}
return c.JSON(fiber.Map{"code": http.StatusOK, "status": true, "details": bill})
}
// GetSalesSummary totals a range, split by tender, day and till.
func (ctl *PosController) GetSalesSummary(c *fiber.Ctx) error {
filter, err := posSalesFilter(c)
if err != nil {
return posBadRequest(c, err)
}
summary, err := ctl.posService.SalesSummary(filter)
if err != nil {
return posServerError(c, "GetSalesSummary", err)
}
return c.JSON(fiber.Map{"code": http.StatusOK, "status": true, "details": summary})
}
func posBadRequest(c *fiber.Ctx, err error) error {
return c.Status(http.StatusBadRequest).JSON(fiber.Map{
"code": http.StatusBadRequest, "message": err.Error(), "status": false,
})
}
func posServerError(c *fiber.Ctx, op string, err error) error {
log.Printf("pos %s: %v", op, err)
return c.Status(http.StatusInternalServerError).JSON(fiber.Map{
"code": http.StatusInternalServerError, "message": err.Error(), "status": false,
})
}
// posIngestError decides whether the terminal should retry.
//
// The distinction matters more than the message does. A misconfigured store id
// will be just as wrong on the next attempt, so it is reported as a 4xx and the
// till halts and shows a person the reason. Anything else might succeed later,
// so it is a 5xx and the bills stay queued.
func posIngestError(c *fiber.Ctx, op string, err error) error {
log.Printf("pos %s: %v", op, err)
message := err.Error()
lower := strings.ToLower(message)
permanent := strings.Contains(lower, "is not a location id") ||
strings.Contains(lower, "no outlet is registered") ||
strings.Contains(lower, "does not belong to tenant") ||
strings.Contains(lower, "has no products stocked") ||
strings.Contains(lower, "no applocationid configured")
status := http.StatusInternalServerError
if permanent {
status = http.StatusBadRequest
}
return c.Status(status).JSON(fiber.Map{
"code": status,
"message": message,
"status": false,
})
}

36
controllers/productController.go
View File

@@ -309,6 +309,42 @@ func (ctl *ProductController) GetLocationProducts(c *fiber.Ctx) error {
})
}
// GetSaleTemplate serves the data the web app turns into the offline-sales
// spreadsheet.
//
// locationid is optional and defaults to 0, meaning every branch the tenant
// runs — one workbook for the whole business, with each row carrying the branch
// its stock belongs to. A store user passes their own locationid to get just
// theirs. tenantid is required: without it there is no scope at all.
func (ctl *ProductController) GetSaleTemplate(c *fiber.Ctx) error {
tenantID, _ := strconv.Atoi(c.Query("tenantid"))
locationID, _ := strconv.Atoi(c.Query("locationid", "0"))
if tenantID <= 0 {
return c.JSON(fiber.Map{
"status": false,
"code": http.StatusBadRequest,
"message": "tenantid is required",
})
}
result, err := ctl.productService.GetSaleTemplate(tenantID, locationID)
if err != nil {
return c.JSON(fiber.Map{
"status": false,
"code": http.StatusInternalServerError,
"message": err.Error(),
})
}
return c.JSON(fiber.Map{
"status": true,
"code": http.StatusOK,
"message": "Success",
"details": result,
})
}
func (ctl *ProductController) GetLocationProductSummary(c *fiber.Ctx) error {
tenantID, _ := strconv.Atoi(c.Query("tenantid"))
locationID, _ := strconv.Atoi(c.Query("locationid"))

85
db/redis.go Normal file
View File

@@ -0,0 +1,85 @@
package db
import (
"context"
"log"
"os"
"strconv"
"strings"
"time"
"github.com/redis/go-redis/v9"
)
// Rdb is the shared Redis connection, or nil when Redis is not configured.
//
// Deliberately the *same* instance the express backend uses. POS presence is
// read by the rider app, which talks to that backend, and a second Redis would
// mean either cross-service HTTP calls on every board refresh or two copies of
// the truth about which tills are alive.
//
// Key namespaces do not collide: express owns `delivery:*`, `city:*`,
// `rider_*`; POS owns `pos:*`. Worth keeping that way — a shared datastore only
// stays safe while each writer's keys are obviously its own.
var Rdb *redis.Client
// RedisCtx is the background context for Redis calls made outside a request.
var RedisCtx = context.Background()
// InitRedis connects if REDIS_HOST is set, and does nothing if it is not.
//
// Redis is optional here: without it the POS health board goes dark, but bills
// still arrive and commit. That is the right failure — losing presence is an
// inconvenience, losing a sale is not — so this never aborts startup.
func InitRedis() {
host := strings.TrimSpace(os.Getenv("REDIS_HOST"))
if host == "" {
log.Println("redis: REDIS_HOST not set, POS presence disabled")
return
}
port := getEnv("REDIS_PORT", "6379")
dbIndex, err := strconv.Atoi(getEnv("REDIS_DB", "0"))
if err != nil {
dbIndex = 0
}
Rdb = redis.NewClient(&redis.Options{
Addr: host + ":" + port,
Username: getEnv("REDIS_USER", "default"),
Password: os.Getenv("REDIS_PASSWORD"),
DB: dbIndex,
// Short on purpose. A degraded Redis must fail fast rather than tie up
// a pooled connection for tens of seconds — the express backend learned
// this the hard way, where a 10s x 3-retry config let one stuck call
// hold a connection for ~35s and exhausted the pool under load.
DialTimeout: 5 * time.Second,
ReadTimeout: 3 * time.Second,
WriteTimeout: 3 * time.Second,
PoolTimeout: 4 * time.Second,
})
ctx, cancel := context.WithTimeout(RedisCtx, 5*time.Second)
defer cancel()
if err := Rdb.Ping(ctx).Err(); err != nil {
// Logged, not fatal. A broker that cannot be reached is fatal because
// bills would silently queue; Redis being down only costs the board.
log.Printf("redis: could not reach %s:%s — POS presence will be unavailable: %v", host, port, err)
Rdb = nil
return
}
log.Printf("✅ Redis connected at %s:%s (db %d)", host, port, dbIndex)
}
// CloseRedis releases the pool on shutdown.
func CloseRedis() {
if Rdb == nil {
return
}
if err := Rdb.Close(); err != nil {
log.Printf("redis: close failed: %v", err)
}
}

48
facade/container.go
View File

@@ -9,16 +9,21 @@ import (
)
type Facade struct {
UserController *controllers.UserController
ProductController *controllers.ProductController
OrderController *controllers.OrderController
DeliveriesController *controllers.DeliveriesController
UtilsController *controllers.UtilsController
TenantController *controllers.TenantController
PartnerController *controllers.PartnerController
UserController *controllers.UserController
ProductController *controllers.ProductController
OrderController *controllers.OrderController
DeliveriesController *controllers.DeliveriesController
UtilsController *controllers.UtilsController
TenantController *controllers.TenantController
PartnerController *controllers.PartnerController
CustomerController *controllers.CustomerController
StockRequestController *controllers.StockRequestController
CatalogueController *controllers.CatalogueController
PosController *controllers.PosController
// Held so the NATS consumer can reach the ingest without going through
// HTTP. Unexported: everything else should use the controller.
posService services.PosService
}
// NewFacade wires up modules against the main (nearledb) connection.
@@ -79,16 +84,33 @@ func NewFacade(db *gorm.DB, catalogueDB *gorm.DB) *Facade {
stockRequestService := services.NewStockRequestService(stockRequestRepo, productService)
stockRequestController := controllers.NewStockRequestController(stockRequestService)
// POS Module — ingest from the in-store terminals.
//
// Presence has no *gorm.DB: terminal health lives in Redis under a TTL, so
// a till that loses power ages out of the board by itself instead of
// leaving a Postgres row claiming it is online.
posRepo := repositories.NewPosRepository(db)
posPresence := repositories.NewPosPresenceRepository()
posService := services.NewPosService(posRepo, posPresence)
posController := controllers.NewPosController(posService)
return &Facade{
UserController: userController,
ProductController: productController,
OrderController: orderController,
DeliveriesController: deliveriesController,
UtilsController: utilsController,
TenantController: tenantController,
UserController: userController,
ProductController: productController,
OrderController: orderController,
DeliveriesController: deliveriesController,
UtilsController: utilsController,
TenantController: tenantController,
PartnerController: partnerController,
CustomerController: customerController,
StockRequestController: stockRequestController,
CatalogueController: catalogueController,
PosController: posController,
posService: posService,
}
}
// PosService exposes the ingest to callers outside the HTTP layer — the NATS
// consumer runs the same code path a POST does, so a bill arriving over MQTT
// and one arriving over HTTP cannot diverge.
func (f *Facade) PosService() services.PosService { return f.posService }

41
go.mod
View File

@@ -2,9 +2,21 @@ module nearle
go 1.24
toolchain go1.24.0
require gorm.io/gorm v1.25.10
require (
firebase.google.com/go v3.13.0+incompatible
github.com/aws/aws-sdk-go-v2 v1.42.1
github.com/aws/aws-sdk-go-v2/config v1.32.30
github.com/aws/aws-sdk-go-v2/credentials v1.19.29
github.com/aws/aws-sdk-go-v2/service/s3 v1.105.1
github.com/eclipse/paho.mqtt.golang v1.5.0
github.com/gofiber/fiber v1.14.6
github.com/joho/godotenv v1.5.1
github.com/redis/go-redis/v9 v9.18.0
golang.org/x/oauth2 v0.12.0
google.golang.org/api v0.143.0
gorm.io/driver/postgres v1.6.0
gorm.io/gorm v1.25.10
)
require (
cloud.google.com/go v0.110.7 // indirect
@@ -14,12 +26,8 @@ require (
cloud.google.com/go/iam v1.1.1 // indirect
cloud.google.com/go/longrunning v0.5.1 // indirect
cloud.google.com/go/storage v1.30.1 // indirect
firebase.google.com/go v3.13.0+incompatible // indirect
github.com/andybalholm/brotli v1.0.6 // indirect
github.com/aws/aws-sdk-go-v2 v1.42.1 // indirect
github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.14 // indirect
github.com/aws/aws-sdk-go-v2/config v1.32.30 // indirect
github.com/aws/aws-sdk-go-v2/credentials v1.19.29 // indirect
github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.30 // indirect
github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.30 // indirect
github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.30 // indirect
@@ -28,24 +36,24 @@ require (
github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.23 // indirect
github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.30 // indirect
github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.31 // indirect
github.com/aws/aws-sdk-go-v2/service/s3 v1.105.1 // indirect
github.com/aws/aws-sdk-go-v2/service/signin v1.4.1 // indirect
github.com/aws/aws-sdk-go-v2/service/sso v1.32.1 // indirect
github.com/aws/aws-sdk-go-v2/service/ssooidc v1.37.1 // indirect
github.com/aws/aws-sdk-go-v2/service/sts v1.44.1 // indirect
github.com/aws/smithy-go v1.27.3 // indirect
github.com/cespare/xxhash/v2 v2.3.0 // indirect
github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
github.com/fsnotify/fsnotify v1.7.0 // indirect
github.com/go-sql-driver/mysql v1.7.1 // indirect
github.com/gofiber/fiber v1.14.6 // indirect
github.com/gofiber/utils v0.0.10 // indirect
github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
github.com/golang/protobuf v1.5.3 // indirect
github.com/google/go-cmp v0.5.9 // indirect
github.com/google/go-cmp v0.6.0 // indirect
github.com/google/s2a-go v0.1.7 // indirect
github.com/google/uuid v1.4.0 // indirect
github.com/googleapis/enterprise-certificate-proxy v0.3.1 // indirect
github.com/googleapis/gax-go/v2 v2.12.0 // indirect
github.com/gorilla/schema v1.1.0 // indirect
github.com/gorilla/websocket v1.5.3 // indirect
github.com/hashicorp/hcl v1.0.0 // indirect
github.com/jackc/pgpassfile v1.0.0 // indirect
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
@@ -53,14 +61,14 @@ require (
github.com/jackc/puddle/v2 v2.2.2 // indirect
github.com/jinzhu/inflection v1.0.0 // indirect
github.com/jinzhu/now v1.1.5 // indirect
github.com/joho/godotenv v1.5.1 // indirect
github.com/klauspost/compress v1.17.2 // indirect
github.com/klauspost/compress v1.19.0 // indirect
github.com/magiconair/properties v1.8.7 // indirect
github.com/mattn/go-colorable v0.1.13 // indirect
github.com/mattn/go-isatty v0.0.20 // indirect
github.com/mattn/go-runewidth v0.0.15 // indirect
github.com/mitchellh/mapstructure v1.5.0 // indirect
github.com/rivo/uniseg v0.4.4 // indirect
github.com/rogpeppe/go-internal v1.11.0 // indirect
github.com/sagikazarmark/locafero v0.3.0 // indirect
github.com/sagikazarmark/slog-shim v0.1.0 // indirect
github.com/sourcegraph/conc v0.3.0 // indirect
@@ -72,15 +80,14 @@ require (
github.com/valyala/fasthttp v1.50.0 // indirect
github.com/valyala/tcplisten v1.0.0 // indirect
go.opencensus.io v0.24.0 // indirect
go.uber.org/atomic v1.11.0 // indirect
go.uber.org/multierr v1.11.0 // indirect
golang.org/x/crypto v0.31.0 // indirect
golang.org/x/exp v0.0.0-20231006140011-7918f672742d // indirect
golang.org/x/net v0.21.0 // indirect
golang.org/x/oauth2 v0.12.0 // indirect
golang.org/x/net v0.33.0 // indirect
golang.org/x/sync v0.10.0 // indirect
golang.org/x/time v0.3.0 // indirect
golang.org/x/xerrors v0.0.0-20220907171357-04be3eba64a2 // indirect
google.golang.org/api v0.143.0 // indirect
google.golang.org/appengine v1.6.7 // indirect
google.golang.org/genproto v0.0.0-20230913181813-007df8e322eb // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20230913181813-007df8e322eb // indirect
@@ -88,7 +95,6 @@ require (
google.golang.org/grpc v1.58.2 // indirect
google.golang.org/protobuf v1.31.0 // indirect
gopkg.in/ini.v1 v1.67.0 // indirect
gorm.io/driver/postgres v1.6.0 // indirect
)
require (
@@ -99,5 +105,4 @@ require (
golang.org/x/sys v0.28.0 // indirect
golang.org/x/text v0.21.0 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
gorm.io/driver/mysql v1.5.2
)

61
go.sum
View File

@@ -93,7 +93,13 @@ github.com/aws/aws-sdk-go-v2/service/sts v1.44.1 h1:RvfHDg+xvAeZ+5741vUEjpOVtYSI
github.com/aws/aws-sdk-go-v2/service/sts v1.44.1/go.mod h1:9gdl4RrflIdpDb2TlXshWgR1F9TeCkvqDx77Vpr4Z/Q=
github.com/aws/smithy-go v1.27.3 h1:F3Zb497UhhskkfpJmfkXswyo+t0sh9OTBnIHjogWbVY=
github.com/aws/smithy-go v1.27.3/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWRnGsAI=
github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI=
github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
@@ -105,6 +111,10 @@ github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
github.com/eclipse/paho.mqtt.golang v1.5.0 h1:EH+bUVJNgttidWFkLLVKaQPGmkTUfQQqjOsyvMGvD6o=
github.com/eclipse/paho.mqtt.golang v1.5.0/go.mod h1:du/2qNQVqJf/Sqs4MEL77kR8QTqANF7XU7Fk0aOTAgk=
github.com/envoyproxy/go-control-plane v0.9.0/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
github.com/envoyproxy/go-control-plane v0.9.1-0.20191026205805-5f8ba28d4473/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
github.com/envoyproxy/go-control-plane v0.9.4/go.mod h1:6rpuAdCZL397s3pYoYcLgu1mIlRU8Am5FuJP05cCM98=
@@ -118,9 +128,6 @@ github.com/fsnotify/fsnotify v1.7.0/go.mod h1:40Bi/Hjc2AVfZrqy+aj+yEI+/bRxZnMJyT
github.com/go-gl/glfw v0.0.0-20190409004039-e6da0acd62b1/go.mod h1:vR7hzQXu2zJy9AVAgeJqvqgH9Q5CA+iKCZ2gyEVpxRU=
github.com/go-gl/glfw/v3.3/glfw v0.0.0-20191125211704-12ad95a8df72/go.mod h1:tQ2UAYgL5IevRw8kRxooKSPJfGvJ9fJQFa0TUsXzTg8=
github.com/go-gl/glfw/v3.3/glfw v0.0.0-20200222043503-6f7a984d4dc4/go.mod h1:tQ2UAYgL5IevRw8kRxooKSPJfGvJ9fJQFa0TUsXzTg8=
github.com/go-sql-driver/mysql v1.7.0/go.mod h1:OXbVy3sEdcQ2Doequ6Z5BW6fXNQTmx+9S1MCJN5yJMI=
github.com/go-sql-driver/mysql v1.7.1 h1:lUIinVbN1DY0xBg0eMOzmmtGoHwWBbvnWubQUrtU8EI=
github.com/go-sql-driver/mysql v1.7.1/go.mod h1:OXbVy3sEdcQ2Doequ6Z5BW6fXNQTmx+9S1MCJN5yJMI=
github.com/gofiber/fiber v1.14.6 h1:QRUPvPmr8ijQuGo1MgupHBn8E+wW0IKqiOvIZPtV70o=
github.com/gofiber/fiber v1.14.6/go.mod h1:Yw2ekF1YDPreO9V6TMYjynu94xRxZBdaa8X5HhHsjCM=
github.com/gofiber/fiber/v2 v2.50.0 h1:ia0JaB+uw3GpNSCR5nvC5dsaxXjRU5OEu36aytx+zGw=
@@ -170,11 +177,14 @@ github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/
github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
github.com/google/martian v2.1.0+incompatible h1:/CP5g8u/VJHijgedC/Legn3BAbAaWPgecwXBIDzw5no=
github.com/google/martian v2.1.0+incompatible/go.mod h1:9I4somxYTbIHy5NJKHRl3wXiIaQGbYVAs8BPL6v8lEs=
github.com/google/martian/v3 v3.0.0/go.mod h1:y5Zk1BBys9G+gd6Jrk0W3cC1+ELVxBWuIGO+w/tUAp0=
github.com/google/martian/v3 v3.1.0/go.mod h1:y5Zk1BBys9G+gd6Jrk0W3cC1+ELVxBWuIGO+w/tUAp0=
github.com/google/martian/v3 v3.3.2 h1:IqNFLAmvJOgVlpdEBiQbDc2EwKW77amAycfTuWKdfvw=
github.com/google/martian/v3 v3.3.2/go.mod h1:oBOf6HBosgwRXnUGWUB05QECsc6uvmMiJ3+6W4l/CUk=
github.com/google/pprof v0.0.0-20181206194817-3ea8567a2e57/go.mod h1:zfwlbNMJ+OItoe0UupaVj+oy1omPYYDuagoSzA8v9mc=
github.com/google/pprof v0.0.0-20190515194954-54271f7e092f/go.mod h1:zfwlbNMJ+OItoe0UupaVj+oy1omPYYDuagoSzA8v9mc=
github.com/google/pprof v0.0.0-20191218002539-d4f498aebedc/go.mod h1:ZgVRPoUq/hfqzAqh7sHMqb3I9Rq5C59dIz2SbBwJ4eM=
@@ -200,6 +210,8 @@ github.com/googleapis/gax-go/v2 v2.12.0/go.mod h1:y+aIqrI5eb1YGMVJfuV3185Ts/D7qK
github.com/googleapis/google-cloud-go-testing v0.0.0-20200911160855-bcd43fbb19e8/go.mod h1:dvDLG8qkwmyD9a/MJJN3XJcT3xFxOKAvTZGvuZmac9g=
github.com/gorilla/schema v1.1.0 h1:CamqUDOFUBqzrvxuz2vEwo8+SUdwsluFh7IlzJh30LY=
github.com/gorilla/schema v1.1.0/go.mod h1:kgLaKoK1FELgZqMAVxx/5cbj0kT+57qxUrAlIO2eleU=
github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
github.com/hashicorp/golang-lru v0.5.0/go.mod h1:/m3WP610KZHVQ1SGc6re/UDhFvYD7pJ4Ao+sR/qLZy8=
github.com/hashicorp/golang-lru v0.5.1/go.mod h1:/m3WP610KZHVQ1SGc6re/UDhFvYD7pJ4Ao+sR/qLZy8=
github.com/hashicorp/hcl v1.0.0 h1:0Anlzjpi4vEasTeNFn2mLJgTSwt0+6sfsiTG8qcWGx4=
@@ -226,8 +238,10 @@ github.com/jstemmer/go-junit-report v0.0.0-20190106144839-af01ea7f8024/go.mod h1
github.com/jstemmer/go-junit-report v0.9.1/go.mod h1:Brl9GWCQeLvo8nXZwPNNblvFj/XSXhF0NWZEnDohbsk=
github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
github.com/klauspost/compress v1.10.7/go.mod h1:aoV0uJVorq1K+umq18yTdKaF57EivdYsUV+/s2qKfXs=
github.com/klauspost/compress v1.17.2 h1:RlWWUY/Dr4fL8qk9YG7DTZ7PDgME2V4csBXA8L/ixi4=
github.com/klauspost/compress v1.17.2/go.mod h1:ntbaceVETuRiXiv4DpjP66DpAtAGkEQskQzEyD//IeE=
github.com/klauspost/compress v1.19.0 h1:sXLILfc9jV2QYWkzFOPWStmcUVH2RHEB1JCdY2oVvCQ=
github.com/klauspost/compress v1.19.0/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
github.com/klauspost/cpuid/v2 v2.0.9 h1:lgaqFMSdTdQYdZ04uHyN2d/eKdOMyi2YLSvlQIBFYa4=
github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg=
github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
@@ -257,12 +271,14 @@ github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZN
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
github.com/redis/go-redis/v9 v9.18.0 h1:pMkxYPkEbMPwRdenAzUNyFNrDgHx9U+DrBabWNfSRQs=
github.com/redis/go-redis/v9 v9.18.0/go.mod h1:k3ufPphLU5YXwNTUcCRXGxUoF1fqxnhFQmscfkCoDA0=
github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
github.com/rivo/uniseg v0.4.4 h1:8TfxU8dW6PdqD27gjM8MVNuicgxIjxpm4K7x4jp8sis=
github.com/rivo/uniseg v0.4.4/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFRclV5y23lUDJ4=
github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
github.com/rogpeppe/go-internal v1.11.0 h1:cWPaGQEPrBb5/AsnsZesgZZ9yb1OQ+GOISoDNXVBh4M=
github.com/rogpeppe/go-internal v1.11.0/go.mod h1:ddIwULY96R17DhadqLgMfk9H9tvdUzkipdSkR5nkCZA=
github.com/sagikazarmark/locafero v0.3.0 h1:zT7VEGWC2DTflmccN/5T1etyKvxSxpHsjb9cJvm4SvQ=
github.com/sagikazarmark/locafero v0.3.0/go.mod h1:w+v7UsPNFwzF1cHuOajOOzoq4U7v/ig1mpRjqV+Bu1U=
github.com/sagikazarmark/slog-shim v0.1.0 h1:diDBnUNK9N/354PgrxMywXnAwEr1QZcOr6gto+ugjYE=
@@ -303,6 +319,8 @@ github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9de
github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.1.32/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/zeebo/xxh3 v1.0.2 h1:xZmwmqxHZA8AI603jOQ0tMqmBr9lPeFwGg6d+xy9DC0=
github.com/zeebo/xxh3 v1.0.2/go.mod h1:5NWz9Sef7zIDm2JHfFlcQvNekmcEl9ekUZQQKCYaDcA=
go.opencensus.io v0.21.0/go.mod h1:mSImk1erAIZhrmZN+AvHh14ztQfjbGwt4TtuofqLduU=
go.opencensus.io v0.22.0/go.mod h1:+kGneAE2xo2IficOXnaByMWTGM9T73dGwxeWcUqIpI8=
go.opencensus.io v0.22.2/go.mod h1:yxeiOL68Rb0Xd1ddK5vPZ/oVn4vY4Ynel7k9FzqtOIw=
@@ -311,6 +329,8 @@ go.opencensus.io v0.22.4/go.mod h1:yxeiOL68Rb0Xd1ddK5vPZ/oVn4vY4Ynel7k9FzqtOIw=
go.opencensus.io v0.22.5/go.mod h1:5pWMHQbX5EPX2/62yrJeAkowc+lfs/XD7Uxpq3pI6kk=
go.opencensus.io v0.24.0 h1:y73uSU6J157QMP2kn2r30vwW1A2W2WFwSCGnAVxeaD0=
go.opencensus.io v0.24.0/go.mod h1:vNK8G9p7aAivkbmorf4v+7Hgx+Zs0yY+0fOtgBfjQKo=
go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
@@ -320,8 +340,6 @@ golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8U
golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
golang.org/x/crypto v0.0.0-20210421170649-83a5a9bb288b/go.mod h1:T9bdIzuCu7OtxOm1hfPfRQxPLYneinmdGuTeoZ9dtd4=
golang.org/x/crypto v0.0.0-20220722155217-630584e8d5aa/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
golang.org/x/crypto v0.13.0 h1:mvySKfSWJ+UKUii46M40LOvyWfN0s2U+46/jDd0e6Ck=
golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliYc=
golang.org/x/crypto v0.31.0 h1:ihbySMvVjLAeSH1IbfcRTkD/iNscyz8rGzjF/E5hV6U=
golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
@@ -393,10 +411,8 @@ golang.org/x/net v0.0.0-20201209123823-ac852fbbde11/go.mod h1:m0MpNAwzfU5UDzcl9v
golang.org/x/net v0.0.0-20201224014010-6772e930b67b/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
golang.org/x/net v0.0.0-20211112202133-69e39bad7dc2/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
golang.org/x/net v0.15.0 h1:ugBLEUaxABaB5AJqW9enI0ACdci2RUd4eP51NTBvuJ8=
golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk=
golang.org/x/net v0.21.0 h1:AQyQV4dYCvJ7vGmJyKki9+PBdyvhkSd8EIx/qb0AYv4=
golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
golang.org/x/net v0.33.0 h1:74SYHlV8BIgHIFC/LrYkOGIwL19eTYXQ5wc6TBuO36I=
golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4=
golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
golang.org/x/oauth2 v0.0.0-20190226205417-e64efc72b421/go.mod h1:gOpvHmFTYa4IltrdGE7lF6nIHvwfUNPOp7c8zoXwtLw=
golang.org/x/oauth2 v0.0.0-20190604053449-0f29369cfe45/go.mod h1:gOpvHmFTYa4IltrdGE7lF6nIHvwfUNPOp7c8zoXwtLw=
@@ -418,8 +434,6 @@ golang.org/x/sync v0.0.0-20200317015054-43a5402ce75a/go.mod h1:RxMgew5VJxzue5/jJ
golang.org/x/sync v0.0.0-20200625203802-6e8e738ad208/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20201207232520-09787c993a3a/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.3.0 h1:ftCYgMx6zT/asHUrPw8BLLscYtGznsLAnjq5RH9P66E=
golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y=
golang.org/x/sync v0.10.0 h1:3NQrjDixjgGwUOCaF8w2+VYHv0Ve/vGYSbdkTa98gmQ=
golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
@@ -461,8 +475,6 @@ golang.org/x/sys v0.0.0-20210423185535-09eb48e85fd7/go.mod h1:h1NjWce9XRLGQEsW7w
golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.14.0 h1:Vz7Qs629MkJkGyHxUlRHizWJRG2j8fbQKjELVSNhy7Q=
golang.org/x/sys v0.14.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA=
golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
@@ -474,8 +486,6 @@ golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
golang.org/x/text v0.3.4/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
golang.org/x/text v0.21.0 h1:zyQAAkrwaneQ066sspRyJaG9VNi/YJ1NfzcGB3hZ/qo=
golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
golang.org/x/time v0.0.0-20181108054448-85acf8d2951c/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
@@ -641,8 +651,8 @@ google.golang.org/protobuf v1.31.0 h1:g0LDEJHgrBl9N9r17Ru3sqWhkIx2NB67okBHPwC7hs
google.golang.org/protobuf v1.31.0/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=
gopkg.in/ini.v1 v1.67.0 h1:Dgnx+6+nfE+IfzjUEISNeydPJh9AXNNsWbGP9KzCsOA=
gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
@@ -650,13 +660,8 @@ gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gorm.io/driver/mysql v1.5.2 h1:QC2HRskSE75wBuOxe0+iCkyJZ+RqpudsQtqkp+IMuXs=
gorm.io/driver/mysql v1.5.2/go.mod h1:pQLhh1Ut/WUAySdTHwBpBv6+JKcj+ua4ZFx1QQTBzb8=
gorm.io/driver/postgres v1.6.0 h1:2dxzU8xJ+ivvqTRph34QX+WrRaJlmfyPqXmoGVjMBa4=
gorm.io/driver/postgres v1.6.0/go.mod h1:vUw0mrGgrTK+uPHEhAdV4sfFELrByKVGnaVRkXDhtWo=
gorm.io/gorm v1.25.2-0.20230530020048-26663ab9bf55/go.mod h1:L4uxeKpfBml98NYqVqwAdmV1a2nBtAec/cf3fpucW/k=
gorm.io/gorm v1.25.5 h1:zR9lOiiYf09VNh5Q1gphfyia1JpiClIWG9hQaxB/mls=
gorm.io/gorm v1.25.5/go.mod h1:hbnx/Oo0ChWMn1BIhpy1oYozzpM15i4YPuHDmfYtwg8=
gorm.io/gorm v1.25.10 h1:dQpO+33KalOA+aFYGlK+EfxcI5MbO7EP2yYygwh9h+s=
gorm.io/gorm v1.25.10/go.mod h1:hbnx/Oo0ChWMn1BIhpy1oYozzpM15i4YPuHDmfYtwg8=
honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

33
main.go
View File

@@ -5,6 +5,7 @@ import (
"log"
"nearle/db"
"nearle/facade"
"nearle/messaging"
"nearle/models"
"nearle/routes"
"os"
@@ -39,13 +40,36 @@ func main() {
db.Connect()
fmt.Println("✅ Database connections established!")
// Shared with the express backend. POS terminal presence lives here under a
// TTL; optional, because losing the health board is an inconvenience and
// losing a sale is not.
db.InitRedis()
// Ensure schema is updated
db.DB.AutoMigrate(&models.StockRequest{})
// Counter sales from the in-store terminals. Separate tables from `orders`
// because a bill carries a cashier, a terminal, rounding, promos, loyalty
// and a payment split that `orders` has nowhere to put.
if err := db.DB.AutoMigrate(&models.PosOrders{}, &models.PosOrderItems{}); err != nil {
log.Fatal("POS schema migration failed:", err)
}
f := facade.NewFacade(db.DB, db.CatalogueDB)
routes.RegisterRoutes(app, f)
// POS terminals reach the ingest over MQTT when MQTT_URL is set, and over
// HTTP otherwise. Both land on the same service, so a bill cannot behave
// differently depending on how it arrived.
//
// A broker that is configured but unreachable is fatal on purpose: coming
// up healthy while every till quietly queues is the worse failure.
posMqtt, err := messaging.StartPosMqttConsumer(f.PosService())
if err != nil {
log.Fatal("POS MQTT consumer failed to start:", err)
}
// Start server
go func() {
if err := app.Listen(":1122"); err != nil {
@@ -53,7 +77,7 @@ func main() {
}
}()
gracefulShutdown()
gracefulShutdown(posMqtt)
}
func selectDBMiddleware(c *fiber.Ctx) error {
@@ -78,13 +102,18 @@ func selectDBMiddleware(c *fiber.Ctx) error {
return c.Next()
}
func gracefulShutdown() {
func gracefulShutdown(posMqtt *messaging.PosMqttConsumer) {
c := make(chan os.Signal, 1)
signal.Notify(c, os.Interrupt, syscall.SIGTERM)
<-c
fmt.Println("\nShutting down gracefully...")
// Drained before anything else: a bill mid-commit still gets its ack, and
// without one the terminal would hold it and send it again on restart.
posMqtt.Close()
db.CloseRedis()
// Normally: close db.DB_DEV and db.DB_LIVE
// Example:
// closeDB(db.DB_DEV)

340
messaging/posmqtt.go Normal file
View File

@@ -0,0 +1,340 @@
package messaging
import (
"context"
"encoding/json"
"fmt"
"log"
"os"
"strconv"
"strings"
"time"
"nearle/models"
"nearle/services"
mqtt "github.com/eclipse/paho.mqtt.golang"
)
// MQTT ingest for the Nearle POS terminals.
//
// The broker is Eclipse Mosquitto, shared with the rider fleet. An audit of the
// estate found no reachable NATS and no MQTT gateway on the NATS boxes that do
// exist, so a NATS consumer that briefly lived here was deleted rather than
// left to rot — a client for a protocol nothing speaks is worse than none.
//
// Enabled with MQTT_URL. Unset, the terminals reach the same service over HTTP
// instead, and this file does nothing.
//
// Only one replica consumes: see posConsumerElected.
const (
// Namespaced under `nearle/` alongside the rider app's
// `nearle/riders/{riderId}/...`, so one broker ACL rule covers each system
// and it is obvious from a topic which one it belongs to.
//
// Wildcards for MQTT are `+` per level, where NATS uses `*`.
topicOrders = "nearle/pos/+/+/order"
topicCustomers = "nearle/pos/+/+/customer"
topicHealth = "nearle/pos/+/+/health"
)
type PosMqttConsumer struct {
client mqtt.Client
svc services.PosService
// Bills and registrations share a pool; heartbeats get their own, so a
// backlog of sales cannot make every till look dark at the moment the
// system is busiest.
ingest *posPool
health *posPool
}
// StartPosMqttConsumer connects and subscribes.
//
// Returns (nil, nil) when MQTT_URL is unset — a deployment without a broker is
// supported, and the caller carries on with the HTTP endpoints.
func StartPosMqttConsumer(svc services.PosService) (*PosMqttConsumer, error) {
url := strings.TrimSpace(os.Getenv("MQTT_URL"))
if url == "" {
log.Println("pos: MQTT_URL not set, plain-MQTT ingest disabled")
return nil, nil
}
// Only one replica consumes.
//
// MQTT has no queue groups — every subscriber receives every message, so
// three replicas would each commit the same bill and publish three acks.
// The ingest is idempotent, so nothing double-counts, but it is three times
// the database work and three times the traffic for one sale.
//
// A StatefulSet gives pods stable ordinal names, so ordinal 0 is a
// deterministic election with no coordination and no extra dependency. If
// that pod dies the set recreates it; tills hold their bills and re-send in
// the meantime, which is exactly what they are built to do.
if !posConsumerElected() {
log.Printf("pos: replica %q is not the elected consumer, MQTT ingest idle here",
os.Getenv("HOSTNAME"))
return nil, nil
}
// Each ingest worker holds a database transaction while it runs, so the
// real ceiling is the Postgres connection pool rather than the CPU. The
// queue is deep enough to absorb a burst and shallow enough that a genuine
// overload is felt as backpressure rather than hidden as latency.
c := &PosMqttConsumer{
svc: svc,
ingest: newPosPool("ingest", posPoolSize("POS_INGEST_WORKERS", 8), 256),
health: newPosPool("health", posPoolSize("POS_HEALTH_WORKERS", 2), 512),
}
opts := mqtt.NewClientOptions().
AddBroker(url).
// Stable, so the broker resumes this session and redelivers anything
// in flight rather than treating every restart as a new subscriber.
// Defaults to the pod name so replicas can never collide: a second
// connection with the same client id evicts the first, and the two then
// fight in a reconnect loop that looks like a flapping network.
SetClientID(getEnvDefault("MQTT_CLIENT_ID",
getEnvDefault("HOSTNAME", "nearle-pos-ingest"))).
SetCleanSession(false).
// Ordered delivery keeps paho on one goroutine, which is what lets a
// full queue push back on the broker. With concurrent delivery paho
// would keep reading no matter how far behind the workers were.
SetOrderMatters(posOrderedDelivery).
SetAutoReconnect(true).
SetMaxReconnectInterval(30 * time.Second).
SetKeepAlive(30 * time.Second).
SetConnectionLostHandler(func(_ mqtt.Client, err error) {
log.Printf("pos: MQTT connection lost: %v", err)
})
if user := os.Getenv("MQTT_USER"); user != "" {
opts.SetUsername(user).SetPassword(os.Getenv("MQTT_PASSWORD"))
}
// Re-subscribed on every (re)connect rather than once at startup: with a
// broker that did not persist the session, a reconnect would otherwise come
// back silently subscribed to nothing.
opts.SetOnConnectHandler(func(client mqtt.Client) {
log.Printf("pos: connected to MQTT broker %s", url)
for topic, handler := range map[string]mqtt.MessageHandler{
topicOrders: wrapHandler(c.ingest, c.handleOrders),
topicCustomers: wrapHandler(c.ingest, c.handleCustomers),
topicHealth: wrapHandler(c.health, c.handleHealth),
} {
if token := client.Subscribe(topic, 1, handler); token.Wait() && token.Error() != nil {
log.Printf("pos: could not subscribe to %s: %v", topic, token.Error())
continue
}
log.Printf("pos: subscribed to %s", topic)
}
})
client := mqtt.NewClient(opts)
if token := client.Connect(); token.Wait() && token.Error() != nil {
return nil, fmt.Errorf("could not connect to the MQTT broker at %s: %w", url, token.Error())
}
c.client = client
return c, nil
}
func (c *PosMqttConsumer) handleOrders(_ mqtt.Client, msg mqtt.Message) {
var batch models.PosOrderBatch
if err := json.Unmarshal(msg.Payload(), &batch); err != nil {
// Dropped rather than retried: there is no batch id to answer with, and
// the till will time out and re-send anyway.
log.Printf("pos: discarding unreadable order batch on %s: %v", msg.Topic(), err)
return
}
store, terminal := topicIdentity(msg.Topic())
if batch.Storeid == "" {
batch.Storeid = store
}
if batch.Terminalid == "" {
batch.Terminalid = terminal
}
ack, err := c.svc.IngestOrders(batch)
if err != nil {
// Nothing committed, so nothing is acknowledged. The terminal keeps
// every bill and retries — which is the entire point of the design.
log.Printf("pos: order batch %s from %s/%s failed, not acking: %v",
batch.Batchid, store, terminal, err)
return
}
c.publishAck(store, terminal, ack)
log.Printf("pos: order batch %s from %s/%s — %d accepted, %d rejected",
batch.Batchid, store, terminal, len(ack.Accepted), len(ack.Rejected))
}
func (c *PosMqttConsumer) handleCustomers(_ mqtt.Client, msg mqtt.Message) {
var batch models.PosCustomerBatch
if err := json.Unmarshal(msg.Payload(), &batch); err != nil {
log.Printf("pos: discarding unreadable customer batch on %s: %v", msg.Topic(), err)
return
}
store, terminal := topicIdentity(msg.Topic())
if batch.Storeid == "" {
batch.Storeid = store
}
if batch.Terminalid == "" {
batch.Terminalid = terminal
}
ack, err := c.svc.IngestCustomers(batch)
if err != nil {
log.Printf("pos: customer batch %s from %s/%s failed, not acking: %v",
batch.Batchid, store, terminal, err)
return
}
c.publishAck(store, terminal, ack)
}
// handleHealth records one heartbeat.
//
// Never acknowledged. Presence is fire-and-forget: a till whose heartbeat
// failed must carry on selling, and a blank square on a dashboard is a far
// better outcome than a terminal that stopped because Redis was busy.
func (c *PosMqttConsumer) handleHealth(_ mqtt.Client, msg mqtt.Message) {
var health models.PosHealth
if err := json.Unmarshal(msg.Payload(), &health); err != nil {
log.Printf("pos: discarding unreadable heartbeat on %s: %v", msg.Topic(), err)
return
}
// From the topic, not the body — the same rule bills follow.
store, terminal := topicIdentity(msg.Topic())
if health.Locationid == "" {
health.Locationid = store
}
if health.Terminalid == "" {
health.Terminalid = terminal
}
// The broker's Last Will arrives here too, as a bare {"status":"offline"}
// with no other fields, which is exactly what should be recorded when a
// till loses power mid-shift.
if health.Status == "" {
health.Status = "online"
}
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := c.svc.RecordHealth(ctx, health); err != nil {
log.Printf("pos: could not record heartbeat from %s/%s: %v", store, terminal, err)
}
}
// publishAck answers the till that sent the batch, and only that till.
func (c *PosMqttConsumer) publishAck(store, terminal string, ack *models.PosAck) {
if store == "" || terminal == "" {
log.Printf("pos: cannot ack batch %s — the topic named no terminal", ack.Batchid)
return
}
payload, err := json.Marshal(ack)
if err != nil {
log.Printf("pos: could not encode ack for batch %s: %v", ack.Batchid, err)
return
}
topic := fmt.Sprintf("nearle/pos/%s/%s/ack", store, terminal)
// QoS 1: losing an ack means the till re-sends bills that are already
// banked. Harmless, because the ingest deduplicates — but wasted traffic on
// a shop line that may not have much to spare.
token := c.client.Publish(topic, 1, false, payload)
if !token.WaitTimeout(10*time.Second) || token.Error() != nil {
log.Printf("pos: could not publish ack to %s: %v", topic, token.Error())
}
}
// topicIdentity reads the store and terminal out of
// `nearle/pos/<store>/<terminal>/<kind>`.
//
// Taken from the topic rather than the body on purpose: a till that could name
// a store in its payload could post sales into another shop's books.
func topicIdentity(topic string) (store, terminal string) {
parts := strings.Split(topic, "/")
if len(parts) < 5 {
return "", ""
}
return parts[2], parts[3]
}
// PublishCatalogueChanged tells every till in a store to pull now.
//
// Retained, so a terminal that was switched off during the change still hears
// about it when it comes back.
func (c *PosMqttConsumer) PublishCatalogueChanged(storeID, revision string) error {
payload, err := json.Marshal(map[string]string{"revision": revision})
if err != nil {
return err
}
token := c.client.Publish(fmt.Sprintf("nearle/pos/%s/catalogue", storeID), 1, true, payload)
token.Wait()
return token.Error()
}
// Close disconnects, allowing a moment for in-flight acks to leave.
func (c *PosMqttConsumer) Close() {
if c == nil || c.client == nil {
return
}
// Workers drain before the connection closes, so a bill mid-commit still
// gets its ack out. Disconnecting first would strand it: committed here,
// unacknowledged there, and sent again on the till's next attempt.
c.ingest.stop()
c.health.stop()
quiesce, err := strconv.Atoi(getEnvDefault("MQTT_QUIESCE_MS", "2000"))
if err != nil || quiesce < 0 {
quiesce = 2000
}
c.client.Disconnect(uint(quiesce))
}
// posConsumerElected decides whether this replica runs the MQTT ingest.
//
// Rules, in order:
//
// - POS_MQTT_CONSUMER=always or =never settles it outright, for deployments
// that are not a StatefulSet or that want the consumer somewhere specific.
// - A StatefulSet pod name ending in `-0` is elected. Ordinals are stable and
// unique, so this needs no lock, no lease and no coordination.
// - Anything else — a bare container, a Deployment, local development —
// is elected, because a single instance that refused to consume would be a
// far more confusing failure than one that did.
func posConsumerElected() bool {
switch strings.ToLower(strings.TrimSpace(os.Getenv("POS_MQTT_CONSUMER"))) {
case "always", "true", "yes":
return true
case "never", "false", "no":
return false
}
host := strings.TrimSpace(os.Getenv("HOSTNAME"))
if i := strings.LastIndex(host, "-"); i >= 0 {
if ordinal := host[i+1:]; ordinal != "" && strings.Trim(ordinal, "0123456789") == "" {
// A StatefulSet ordinal. Only the first replica consumes.
return ordinal == "0"
}
}
// Not an ordinal-named pod, so there is nothing to elect against.
return true
}
func getEnvDefault(key, fallback string) string {
if v := strings.TrimSpace(os.Getenv(key)); v != "" {
return v
}
return fallback
}

423
messaging/posmqtt_test.go Normal file
View File

@@ -0,0 +1,423 @@
package messaging
import (
"context"
"encoding/json"
"errors"
"strings"
"sync"
"testing"
"time"
"nearle/models"
mqtt "github.com/eclipse/paho.mqtt.golang"
)
// These drive the real handlers through paho's own interfaces, so what is under
// test is the code that runs in production rather than a parallel
// reimplementation of it.
//
// No embedded broker: the infrastructure audit established that the broker is
// Mosquitto 2.1.2 and that it works. What was never established is whether
// *this* code acks the right terminal, and refuses to ack when the ingest
// failed — which is where a bug would cost a shop its takings.
// fakePosService lets a test decide what the ingest did.
type fakePosService struct {
ack *models.PosAck
err error
batches []models.PosOrderBatch
custBatch []models.PosCustomerBatch
heartbeats []models.PosHealth
healthErr error
}
func (f *fakePosService) IngestOrders(batch models.PosOrderBatch) (*models.PosAck, error) {
f.batches = append(f.batches, batch)
return f.ack, f.err
}
func (f *fakePosService) IngestCustomers(batch models.PosCustomerBatch) (*models.PosAck, error) {
f.custBatch = append(f.custBatch, batch)
return f.ack, f.err
}
func (f *fakePosService) Catalogue(string, string, int, int) (*models.PosCatalogueResponse, error) {
return nil, nil
}
func (f *fakePosService) RecordHealth(_ context.Context, health models.PosHealth) error {
f.heartbeats = append(f.heartbeats, health)
return f.healthErr
}
func (f *fakePosService) TerminalHealth(context.Context, string) (map[string]string, error) {
return nil, nil
}
func (f *fakePosService) Sales(models.PosSalesFilter) (*models.PosSalesPage, error) {
return nil, nil
}
func (f *fakePosService) SaleDetail(int, string) (*models.PosOrders, error) {
return nil, nil
}
func (f *fakePosService) SalesSummary(models.PosSalesFilter) (*models.PosSalesSummary, error) {
return nil, nil
}
func (f *fakePosService) LocationHealth(context.Context, string) ([]map[string]string, error) {
return nil, nil
}
// ---------------------------------------------------------------- paho fakes
type published struct {
topic string
qos byte
retained bool
payload []byte
}
// fakeClient records what was published and nothing else.
type fakeClient struct {
mu sync.Mutex
sent []published
}
func (c *fakeClient) Publish(topic string, qos byte, retained bool, payload any) mqtt.Token {
c.mu.Lock()
defer c.mu.Unlock()
body, _ := payload.([]byte)
c.sent = append(c.sent, published{topic: topic, qos: qos, retained: retained, payload: body})
return doneToken{}
}
func (c *fakeClient) publishes() []published {
c.mu.Lock()
defer c.mu.Unlock()
return append([]published(nil), c.sent...)
}
func (c *fakeClient) IsConnected() bool { return true }
func (c *fakeClient) IsConnectionOpen() bool { return true }
func (c *fakeClient) Connect() mqtt.Token { return doneToken{} }
func (c *fakeClient) Disconnect(uint) {}
func (c *fakeClient) Subscribe(string, byte, mqtt.MessageHandler) mqtt.Token {
return doneToken{}
}
func (c *fakeClient) SubscribeMultiple(map[string]byte, mqtt.MessageHandler) mqtt.Token {
return doneToken{}
}
func (c *fakeClient) Unsubscribe(...string) mqtt.Token { return doneToken{} }
func (c *fakeClient) AddRoute(string, mqtt.MessageHandler) {}
func (c *fakeClient) OptionsReader() mqtt.ClientOptionsReader { return mqtt.ClientOptionsReader{} }
type doneToken struct{}
func (doneToken) Wait() bool { return true }
func (doneToken) WaitTimeout(time.Duration) bool { return true }
func (doneToken) Done() <-chan struct{} {
ch := make(chan struct{})
close(ch)
return ch
}
func (doneToken) Error() error { return nil }
type fakeMessage struct {
topic string
payload []byte
}
func (m fakeMessage) Duplicate() bool { return false }
func (m fakeMessage) Qos() byte { return 1 }
func (m fakeMessage) Retained() bool { return false }
func (m fakeMessage) Topic() string { return m.topic }
func (m fakeMessage) MessageID() uint16 { return 1 }
func (m fakeMessage) Payload() []byte { return m.payload }
func (m fakeMessage) Ack() {}
func consumerFor(svc *fakePosService) (*PosMqttConsumer, *fakeClient) {
client := &fakeClient{}
return &PosMqttConsumer{client: client, svc: svc}, client
}
func orderBatch(batchID string, ids ...string) []byte {
orders := make([]models.PosOrder, 0, len(ids))
for _, id := range ids {
orders = append(orders, models.PosOrder{Id: id, Invoicenumber: "INV-" + id})
}
body, _ := json.Marshal(models.PosOrderBatch{Schema: 1, Batchid: batchID, Orders: orders})
return body
}
// ---------------------------------------------------------------------- tests
func TestAckGoesBackToTheTerminalThatSent(t *testing.T) {
ack := models.NewPosAck("batch-1")
ack.Accept("order-a")
c, client := consumerFor(&fakePosService{ack: ack})
c.handleOrders(nil, fakeMessage{
topic: "nearle/pos/12/T4A9/order",
payload: orderBatch("batch-1", "order-a"),
})
sent := client.publishes()
if len(sent) != 1 {
t.Fatalf("published %d messages, want exactly 1", len(sent))
}
// Addressed to the till that sent it. A store-wide ack would tell every
// other counter that bills they never sent had landed.
if sent[0].topic != "nearle/pos/12/T4A9/ack" {
t.Errorf("ack topic = %q, want nearle/pos/12/T4A9/ack", sent[0].topic)
}
if sent[0].qos != 1 {
t.Errorf("ack qos = %d, want 1", sent[0].qos)
}
if sent[0].retained {
t.Error("the ack was retained; a stale ack replayed to a new session would retire bills that were never sent")
}
var got models.PosAck
if err := json.Unmarshal(sent[0].payload, &got); err != nil {
t.Fatalf("decode ack: %v", err)
}
if got.Batchid != "batch-1" {
t.Errorf("batch_id = %q, want batch-1", got.Batchid)
}
if len(got.Accepted) != 1 || got.Accepted[0] != "order-a" {
t.Errorf("accepted = %v, want [order-a]", got.Accepted)
}
}
func TestAFailedIngestIsNotAcked(t *testing.T) {
// The single most important behaviour here. An ack the ingest did not earn
// tells a terminal to delete a bill that was never banked.
c, client := consumerFor(&fakePosService{err: errors.New("database is having a bad minute")})
c.handleOrders(nil, fakeMessage{
topic: "nearle/pos/12/T4A9/order",
payload: orderBatch("batch-2", "order-a"),
})
if sent := client.publishes(); len(sent) != 0 {
t.Fatalf("a batch that failed to commit was acknowledged: %s", sent[0].payload)
}
}
func TestStoreAndTerminalComeFromTheTopic(t *testing.T) {
// The body is authoritative for nothing about identity. A till that could
// name a store in its payload could post sales into another shop's books.
svc := &fakePosService{ack: models.NewPosAck("batch-3")}
c, _ := consumerFor(svc)
c.handleOrders(nil, fakeMessage{
topic: "nearle/pos/44/T0001/order",
payload: orderBatch("batch-3", "order-x"),
})
if len(svc.batches) != 1 {
t.Fatalf("the batch never reached the ingest")
}
if got := svc.batches[0].Storeid; got != "44" {
t.Errorf("store_id = %q, want 44 (from the topic)", got)
}
if got := svc.batches[0].Terminalid; got != "T0001" {
t.Errorf("terminal_id = %q, want T0001", got)
}
}
func TestABodyCannotOverrideTheTopicIdentity(t *testing.T) {
// A till claiming to be somewhere else must not be believed.
svc := &fakePosService{ack: models.NewPosAck("batch-4")}
c, client := consumerFor(svc)
body, _ := json.Marshal(models.PosOrderBatch{
Schema: 1,
Batchid: "batch-4",
Storeid: "99", // a shop this till has no claim on
Orders: []models.PosOrder{{Id: "order-a"}},
})
c.handleOrders(nil, fakeMessage{topic: "nearle/pos/12/T4A9/order", payload: body})
// The ingest still resolves the store it was *told*, which is a known gap —
// but the ack must go back to the real terminal, so a forged store id
// cannot redirect another till's acknowledgements.
sent := client.publishes()
if len(sent) != 1 || sent[0].topic != "nearle/pos/12/T4A9/ack" {
t.Fatalf("ack went to %v, want nearle/pos/12/T4A9/ack", sent)
}
}
func TestAMalformedBatchIsDroppedWithoutAcking(t *testing.T) {
// Nothing to key an ack on, and nothing committed. Silence is correct: the
// till times out and re-sends.
svc := &fakePosService{ack: models.NewPosAck("x")}
c, client := consumerFor(svc)
c.handleOrders(nil, fakeMessage{
topic: "nearle/pos/12/T4A9/order",
payload: []byte("not json at all"),
})
if len(svc.batches) != 0 {
t.Error("an unreadable batch reached the ingest")
}
if sent := client.publishes(); len(sent) != 0 {
t.Errorf("an unreadable batch was acknowledged: %s", sent[0].payload)
}
}
func TestRegistrationsAckOnTheSameTopic(t *testing.T) {
ack := models.NewPosAck("cust-1")
ack.Accept("customer-a")
c, client := consumerFor(&fakePosService{ack: ack})
body, _ := json.Marshal(models.PosCustomerBatch{
Schema: 1,
Batchid: "cust-1",
Customers: []models.PosCustomer{{Id: "customer-a", Mobile: "9840012345", Name: "Meena"}},
})
c.handleCustomers(nil, fakeMessage{topic: "nearle/pos/12/T4A9/customer", payload: body})
sent := client.publishes()
if len(sent) != 1 || sent[0].topic != "nearle/pos/12/T4A9/ack" {
t.Fatalf("registration ack went to %v", sent)
}
}
func TestAHeartbeatIsRecordedAndNeverAcked(t *testing.T) {
// Presence is fire-and-forget. A till waiting on an ack for its heartbeat
// would be a till that a busy dashboard can block.
svc := &fakePosService{}
c, client := consumerFor(svc)
body, _ := json.Marshal(models.PosHealth{Status: "online", Pendingbills: 4, Todaybills: 37})
c.handleHealth(nil, fakeMessage{topic: "nearle/pos/12/T4A9/health", payload: body})
if len(svc.heartbeats) != 1 {
t.Fatalf("the heartbeat never reached the presence store")
}
got := svc.heartbeats[0]
if got.Terminalid != "T4A9" || got.Locationid != "12" {
t.Errorf("identity = %s/%s, want 12/T4A9 (from the topic)", got.Locationid, got.Terminalid)
}
if got.Pendingbills != 4 {
t.Errorf("pending_bills = %d, want 4", got.Pendingbills)
}
if sent := client.publishes(); len(sent) != 0 {
t.Error("a heartbeat was acknowledged; presence must be fire-and-forget")
}
}
func TestALastWillIsRecordedAsOffline(t *testing.T) {
// The broker publishes this on the till's behalf when it loses power. It
// carries nothing but a status, and that is the point — it is the only way
// to tell "closed for the night" from "unplugged".
svc := &fakePosService{}
c, _ := consumerFor(svc)
c.handleHealth(nil, fakeMessage{
topic: "nearle/pos/12/T4A9/health",
payload: []byte(`{"status":"offline"}`),
})
if len(svc.heartbeats) != 1 {
t.Fatal("the will never reached the presence store")
}
if got := svc.heartbeats[0].Status; got != "offline" {
t.Errorf("status = %q, want offline — a will must not be defaulted to online", got)
}
}
func TestAFailedPresenceWriteDoesNotStopTheTill(t *testing.T) {
// Redis being unreachable must cost the board, never a sale.
svc := &fakePosService{healthErr: errors.New("redis is down")}
c, client := consumerFor(svc)
c.handleHealth(nil, fakeMessage{
topic: "nearle/pos/12/T4A9/health",
payload: []byte(`{"status":"online"}`),
})
if sent := client.publishes(); len(sent) != 0 {
t.Error("a failed heartbeat produced a message back to the till")
}
}
func TestAnEmptyAckSerialisesAsAListNotNull(t *testing.T) {
// A terminal reading `null` for accepted treats the whole batch as
// unconfirmed and sends it again for ever.
body, err := json.Marshal(models.NewPosAck("batch-5"))
if err != nil {
t.Fatalf("marshal: %v", err)
}
if want := `"accepted":[]`; !strings.Contains(string(body), want) {
t.Errorf("ack serialised as %s, want it to contain %s", body, want)
}
}
func TestTopicIdentityRejectsShortTopics(t *testing.T) {
// A topic that names no terminal must yield nothing rather than a
// plausible-looking wrong answer that sends an ack to the wrong place.
for _, topic := range []string{"nearle/pos/order", "pos/12/T4A9/order", "", "nearle"} {
store, terminal := topicIdentity(topic)
if store != "" || terminal != "" {
t.Errorf("topicIdentity(%q) = %q/%q, want empty", topic, store, terminal)
}
}
store, terminal := topicIdentity("nearle/pos/12/T4A9/order")
if store != "12" || terminal != "T4A9" {
t.Errorf("topicIdentity = %q/%q, want 12/T4A9", store, terminal)
}
}
// MQTT has no queue groups: every subscriber gets every message. Three replicas
// all consuming would commit the same bill three times and publish three acks —
// harmless, because the ingest is idempotent, but three times the work.
func TestOnlyTheFirstStatefulSetReplicaConsumes(t *testing.T) {
cases := []struct {
name string
hostname string
override string
want bool
}{
{"statefulset ordinal 0", "fiesta-0", "", true},
{"statefulset ordinal 1", "fiesta-1", "", false},
{"statefulset ordinal 2", "fiesta-2", "", false},
{"double-digit ordinal", "fiesta-10", "", false},
// A Deployment pod has a random suffix, not an ordinal. Refusing to
// consume there would be a far more confusing failure than consuming.
{"deployment pod", "fiesta-7d4f9c8b6d-x2k9p", "", true},
{"bare container", "a1b2c3d4e5f6", "", true},
{"no hostname", "", "", true},
// The override settles it outright either way.
{"forced on", "fiesta-2", "always", true},
{"forced off", "fiesta-0", "never", false},
{"forced on via true", "fiesta-5", "true", true},
{"forced off via false", "fiesta-0", "false", false},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
t.Setenv("HOSTNAME", c.hostname)
t.Setenv("POS_MQTT_CONSUMER", c.override)
if got := posConsumerElected(); got != c.want {
t.Errorf("posConsumerElected() = %v, want %v (hostname %q, override %q)",
got, c.want, c.hostname, c.override)
}
})
}
}

174
messaging/posworkers.go Normal file
View File

@@ -0,0 +1,174 @@
package messaging
import (
"log"
"os"
"strconv"
"sync"
mqtt "github.com/eclipse/paho.mqtt.golang"
)
// Concurrency for the MQTT ingest.
//
// paho delivers messages on a single goroutine, so without this every bill is
// committed one after another. A bill is a full Postgres transaction — advisory
// lock, dedup check, stock row locks, availability check, four inserts, commit —
// which realistically costs 10–30ms. Serially that is 30–100 bills a second,
// and a shop-wide backlog draining after an outage would take minutes to land.
//
// ### Why a bounded pool rather than a goroutine per message
//
// paho can be told to call handlers concurrently, but it spawns without limit.
// A storm would then open a database transaction per message, exhaust the
// connection pool, and stall every one of them at once — turning a slow minute
// into a dead one.
//
// A fixed pool behind a bounded queue does the opposite. When the queue fills,
// submitting **blocks**, which is the point: paho stops acknowledging, the
// broker's in-flight window fills, and it stops sending. Backpressure travels
// all the way back to the till, which holds its bills and retries. Slow, but
// nothing is dropped and nothing is lost.
//
// ### Why bills and heartbeats have separate pools
//
// A heartbeat is one Redis write and a bill is a transaction. Sharing a queue
// would let a backlog of bills delay presence, and every till would appear to
// go dark at exactly the moment the system was busiest — the worst possible
// time to be blind to which counters are alive.
// posPool is a fixed set of workers reading a bounded queue.
type posPool struct {
name string
jobs chan func()
wg sync.WaitGroup
once sync.Once
// Guards the transition to closed. A plain `select` over a done-channel and
// the job channel is not enough: once both are ready Go picks between them
// at random, and picking the send panics on a closed channel. Held for
// reading across the whole of submit, so stop cannot close the queue out
// from under a send already in progress.
mu sync.RWMutex
closed bool
}
func newPosPool(name string, workers, queue int) *posPool {
p := &posPool{
name: name,
jobs: make(chan func(), queue),
}
p.wg.Add(workers)
for i := 0; i < workers; i++ {
go func() {
defer p.wg.Done()
for job := range p.jobs {
job()
}
}()
}
log.Printf("pos: %s pool started with %d workers, queue %d", name, workers, queue)
return p
}
// submit queues work, blocking when the queue is full.
//
// Blocking is deliberate. Dropping would lose a bill outright; the terminal
// would eventually re-send it, but only after its ack timeout, and meanwhile we
// would have thrown away work we had already accepted. Blocking instead pushes
// back through paho to the broker to the till, which is exactly where the
// decision to slow down belongs.
func (p *posPool) submit(job func()) {
p.mu.RLock()
if p.closed {
p.mu.RUnlock()
// Shutting down. Running it inline still gets the work done and its ack
// published, rather than discarding a bill that already reached us.
job()
return
}
// The read lock is held across the send. Blocking here while the queue is
// full cannot deadlock against stop: the workers only exit once the channel
// is closed, and that happens under the write lock this send is holding
// off — so they stay alive and keep draining until this send completes.
p.jobs <- job
p.mu.RUnlock()
}
// stop drains the queue and waits for in-flight work.
//
// Every job already accepted runs to completion, so a bill mid-commit still
// gets its ack. Without one the terminal would hold it and send it again on
// restart — harmless, but avoidable.
func (p *posPool) stop() {
p.once.Do(func() {
// The write lock waits for every submit already in progress, so the
// channel is never closed while something is mid-send.
p.mu.Lock()
p.closed = true
close(p.jobs)
p.mu.Unlock()
p.wg.Wait()
log.Printf("pos: %s pool drained", p.name)
})
}
// posPoolSize reads a worker count from the environment.
//
// The default is deliberately modest. Each worker holds a database transaction
// while it runs, so the useful ceiling is the Postgres connection pool, not the
// CPU — set this above what the database can serve and the workers simply queue
// inside the driver instead, where there is no backpressure to feel.
func posPoolSize(key string, fallback int) int {
v, err := strconv.Atoi(os.Getenv(key))
if err != nil || v <= 0 {
return fallback
}
if v > 128 {
return 128
}
return v
}
// posOrderedDelivery reports whether paho should preserve message order.
//
// Left on: paho then delivers on one goroutine, which hands work to the pool
// and blocks when it is full. That single delivery goroutine is what makes
// backpressure reach the broker at all — with concurrent delivery paho would
// keep reading regardless of how far behind the workers were.
const posOrderedDelivery = true
// wrapHandler puts a paho message handler behind a pool.
//
// The payload is copied because paho reuses its buffer once the handler
// returns, and the work now happens after that.
func wrapHandler(pool *posPool, h mqtt.MessageHandler) mqtt.MessageHandler {
return func(client mqtt.Client, msg mqtt.Message) {
topic := msg.Topic()
payload := make([]byte, len(msg.Payload()))
copy(payload, msg.Payload())
pool.submit(func() {
h(client, copiedMessage{topic: topic, payload: payload})
})
}
}
// copiedMessage carries a payload that outlives paho's buffer.
type copiedMessage struct {
topic string
payload []byte
}
func (m copiedMessage) Duplicate() bool { return false }
func (m copiedMessage) Qos() byte { return 1 }
func (m copiedMessage) Retained() bool { return false }
func (m copiedMessage) Topic() string { return m.topic }
func (m copiedMessage) MessageID() uint16 { return 0 }
func (m copiedMessage) Payload() []byte { return m.payload }
func (m copiedMessage) Ack() {}

247
messaging/posworkers_test.go Normal file
View File

@@ -0,0 +1,247 @@
package messaging
import (
"sync"
"sync/atomic"
"testing"
"time"
mqtt "github.com/eclipse/paho.mqtt.golang"
)
func TestEveryJobRuns(t *testing.T) {
pool := newPosPool("test", 4, 16)
var done int64
var wg sync.WaitGroup
for i := 0; i < 100; i++ {
wg.Add(1)
pool.submit(func() {
defer wg.Done()
atomic.AddInt64(&done, 1)
})
}
wg.Wait()
pool.stop()
if got := atomic.LoadInt64(&done); got != 100 {
t.Errorf("ran %d jobs, want 100", got)
}
}
func TestConcurrencyIsBounded(t *testing.T) {
// The reason the pool exists. Unbounded concurrency would open a database
// transaction per message and exhaust the connection pool under a storm,
// stalling every one of them at once.
const workers = 4
pool := newPosPool("test", workers, 64)
var inFlight, peak int64
var wg sync.WaitGroup
for i := 0; i < 200; i++ {
wg.Add(1)
pool.submit(func() {
defer wg.Done()
now := atomic.AddInt64(&inFlight, 1)
for {
was := atomic.LoadInt64(&peak)
if now <= was || atomic.CompareAndSwapInt64(&peak, was, now) {
break
}
}
time.Sleep(time.Millisecond)
atomic.AddInt64(&inFlight, -1)
})
}
wg.Wait()
pool.stop()
if got := atomic.LoadInt64(&peak); got > workers {
t.Errorf("peak concurrency %d exceeded the %d workers", got, workers)
}
}
func TestSubmitBlocksRatherThanDroppingWork(t *testing.T) {
// A full queue must slow the caller down, not discard a bill. Dropping
// would throw away work already accepted from the broker, and the terminal
// would only find out at its ack timeout.
pool := newPosPool("test", 1, 1)
release := make(chan struct{})
var ran int64
// Occupy the single worker.
pool.submit(func() {
<-release
atomic.AddInt64(&ran, 1)
})
// Fill the queue, then a third submit must block until the worker frees up.
pool.submit(func() { atomic.AddInt64(&ran, 1) })
blocked := make(chan struct{})
go func() {
pool.submit(func() { atomic.AddInt64(&ran, 1) })
close(blocked)
}()
select {
case <-blocked:
t.Fatal("submit returned while the queue was full; work would be dropped under load")
case <-time.After(100 * time.Millisecond):
// Correctly blocked.
}
close(release)
select {
case <-blocked:
case <-time.After(3 * time.Second):
t.Fatal("submit never unblocked after the worker freed up")
}
pool.stop()
if got := atomic.LoadInt64(&ran); got != 3 {
t.Errorf("ran %d jobs, want 3 — none may be lost", got)
}
}
func TestStopDrainsAcceptedWork(t *testing.T) {
// A bill mid-commit must still get its ack. Without one the terminal holds
// it and sends it again on restart — harmless, but avoidable.
pool := newPosPool("test", 2, 64)
var done int64
for i := 0; i < 50; i++ {
pool.submit(func() {
time.Sleep(time.Millisecond)
atomic.AddInt64(&done, 1)
})
}
pool.stop()
if got := atomic.LoadInt64(&done); got != 50 {
t.Errorf("only %d of 50 jobs completed before shutdown finished", got)
}
}
func TestSubmitAfterStopStillRunsTheWork(t *testing.T) {
// A message that arrived during shutdown has already been taken from the
// broker. Discarding it would lose a bill we accepted responsibility for.
pool := newPosPool("test", 2, 8)
pool.stop()
var ran int64
pool.submit(func() { atomic.AddInt64(&ran, 1) })
if got := atomic.LoadInt64(&ran); got != 1 {
t.Error("work submitted during shutdown was discarded")
}
}
func TestStopIsIdempotent(t *testing.T) {
// Close() may be reached twice on a shutdown path; a second close of the
// jobs channel would panic and take the process down mid-drain.
pool := newPosPool("test", 2, 8)
pool.stop()
pool.stop()
pool.stop()
}
func TestPoolSizeFallsBackAndClamps(t *testing.T) {
t.Setenv("POS_TEST_WORKERS", "")
if got := posPoolSize("POS_TEST_WORKERS", 8); got != 8 {
t.Errorf("unset = %d, want the fallback 8", got)
}
t.Setenv("POS_TEST_WORKERS", "not a number")
if got := posPoolSize("POS_TEST_WORKERS", 8); got != 8 {
t.Errorf("garbage = %d, want the fallback 8", got)
}
t.Setenv("POS_TEST_WORKERS", "0")
if got := posPoolSize("POS_TEST_WORKERS", 8); got != 8 {
t.Errorf("zero = %d, want the fallback 8", got)
}
t.Setenv("POS_TEST_WORKERS", "-4")
if got := posPoolSize("POS_TEST_WORKERS", 8); got != 8 {
t.Errorf("negative = %d, want the fallback 8", got)
}
t.Setenv("POS_TEST_WORKERS", "24")
if got := posPoolSize("POS_TEST_WORKERS", 8); got != 24 {
t.Errorf("explicit = %d, want 24", got)
}
// Clamped: more workers than the database can serve just moves the queue
// inside the driver, where there is no backpressure to feel.
t.Setenv("POS_TEST_WORKERS", "100000")
if got := posPoolSize("POS_TEST_WORKERS", 8); got != 128 {
t.Errorf("absurd = %d, want the 128 clamp", got)
}
}
func TestAWrappedHandlerCopiesThePayload(t *testing.T) {
// paho reuses its buffer once a handler returns, and with a pool the work
// now happens *after* that. Without a copy a queued bill would be read as
// whatever message happened to arrive next — silently, and as valid JSON
// often enough to commit the wrong sale.
pool := newPosPool("test", 1, 4)
seen := make(chan string, 1)
wrapped := wrapHandler(pool, func(_ mqtt.Client, msg mqtt.Message) {
seen <- string(msg.Payload())
})
// A buffer paho would reuse.
buffer := []byte(`{"batch_id":"original"}`)
wrapped(nil, fakeMessage{topic: "nearle/pos/12/T4A9/order", payload: buffer})
// Overwrite it the instant the handler returns, exactly as paho would.
for i := range buffer {
buffer[i] = 'X'
}
select {
case got := <-seen:
if got != `{"batch_id":"original"}` {
t.Errorf("handler saw %q — the payload was not copied before queueing", got)
}
case <-time.After(3 * time.Second):
t.Fatal("the wrapped handler never ran")
}
pool.stop()
}
func TestAWrappedHandlerKeepsTheTopic(t *testing.T) {
// Store and terminal are read from the topic, never the body. Losing it in
// the hand-off would leave the ack with nowhere to go.
pool := newPosPool("test", 1, 4)
seen := make(chan string, 1)
wrapped := wrapHandler(pool, func(_ mqtt.Client, msg mqtt.Message) {
seen <- msg.Topic()
})
wrapped(nil, fakeMessage{topic: "nearle/pos/1135/T4A9/order", payload: []byte("{}")})
select {
case got := <-seen:
if got != "nearle/pos/1135/T4A9/order" {
t.Errorf("topic = %q, want nearle/pos/1135/T4A9/order", got)
}
case <-time.After(3 * time.Second):
t.Fatal("the wrapped handler never ran")
}
pool.stop()
}

91
models/order.go
View File

@@ -439,6 +439,97 @@ type Ordersequences struct {
Paymentprefix string `json:"paymentprefix" gorm:"default:PAY"`
}
// ── Offline (in-store) sales import ───────────────────────────────────────────
//
// A sale rung up at the counter never passes through the app, so nothing
// deducts its stock. These types carry a spreadsheet of such sales into the
// same order path online orders use, so one ledger remains the single source
// of truth for stock and one revenue figure covers both channels.
// OfflineSaleItem is one spreadsheet row. Only Productid and Qtysold are
// required; the rest fall back to the product's own pricing when left blank.
// Productname is carried for verification against Productid, not for matching
// (see SaleTemplateRow for why a name can't be a key).
type OfflineSaleItem struct {
Productid int `json:"productid"`
Productname string `json:"productname"`
Qtysold float64 `json:"qtysold"`
Unitprice float64 `json:"unitprice"`
Discountamount float64 `json:"discountamount"`
Taxpercent float64 `json:"taxpercent"`
}
// OfflineSaleBill is one counter bill — the rows of a spreadsheet grouped by
// their branch and bill number.
//
// Locationid is the branch the bill was rung up at, taken from the spreadsheet
// row rather than from a store the operator picked in the UI. One workbook can
// therefore carry sales for every branch a merchant runs, and each bill's stock
// comes out of its own outlet. Bills are grouped per branch, so the same bill
// number at two outlets is two separate sales, not a duplicate.
//
// Billno is what makes a re-upload of the same file safe: it is recorded on the
// order and refused if already present for that branch.
type OfflineSaleBill struct {
Locationid int `json:"locationid"`
Billno string `json:"billno"`
Saledate string `json:"saledate"`
Paymentmode string `json:"paymentmode"`
Customername string `json:"customername"`
Customermobile string `json:"customermobile"`
Remarks string `json:"remarks"`
Items []OfflineSaleItem `json:"items"`
}
// OfflineSalesUpload is the request body.
//
// Locationid here is a scope constraint, not the destination. Left at 0 the
// bills go to whichever branch each one names, which is what a multi-branch
// owner uploads. Set to a branch it pins the whole upload to that outlet and
// any bill naming a different one is refused — that is how a store user is
// held to their own store no matter what the spreadsheet says.
//
// Every branch referenced is checked against Tenantid regardless, so no upload
// can reach an outlet the merchant does not own.
type OfflineSalesUpload struct {
Tenantid int `json:"tenantid"`
Locationid int `json:"locationid"`
Userid int `json:"userid"`
Bills []OfflineSaleBill `json:"bills"`
}
// Outcomes a single bill can have. A bill is all-or-nothing: it either commits
// with its stock movement or it leaves nothing behind.
const (
OfflineSaleImported = "imported"
OfflineSaleDuplicate = "duplicate"
OfflineSaleFailed = "failed"
)
// OfflineSaleResult reports one bill's fate. Bills are independent, so a file
// with one bad bill still imports the rest and names exactly what it skipped.
// The branch is echoed back because a single upload spans several, and "bill 7
// failed" is not actionable without knowing which store it belonged to.
type OfflineSaleResult struct {
Locationid int `json:"locationid"`
Locationname string `json:"locationname"`
Billno string `json:"billno"`
Status string `json:"status"`
Orderid string `json:"orderid"`
Orderheaderid int `json:"orderheaderid"`
Itemcount int `json:"itemcount"`
Amount float64 `json:"amount"`
Message string `json:"message"`
}
type OfflineSalesUploadResponse struct {
Imported int `json:"imported"`
Duplicate int `json:"duplicate"`
Failed int `json:"failed"`
Totalamount float64 `json:"totalamount"`
Results []OfflineSaleResult `json:"results"`
}
type TenantRevenueSummary struct {
Tenantid int `json:"tenantid"`
Tenantname string `json:"tenantname"`

212
models/pos.go Normal file
View File

@@ -0,0 +1,212 @@
package models
// Wire format for the Nearle POS terminal.
//
// These types mirror what the till actually publishes, field for field. The
// terminal is the fixed side of this contract: it is installed on a hundred
// machines that cannot all be updated at once, so the names here follow its
// JSON rather than this codebase's usual Go casing.
//
// The authoritative description lives in the terminal repository at
// docs/sync-contract.md.
// PosOrderItem is one line of a counter bill.
//
// Productid arrives as a string because the till stores catalogue ids as text.
// It carries the numeric products.productid this backend issued during a
// catalogue pull, so it parses back to an int on arrival.
type PosOrderItem struct {
Productid string `json:"product_id"`
Barcode string `json:"barcode"`
Name string `json:"name"`
Quantity float64 `json:"quantity"`
Unitprice float64 `json:"unit_price"`
Discount float64 `json:"discount"`
Gstrate float64 `json:"gst_rate"`
Tax float64 `json:"tax"`
Linetotal float64 `json:"line_total"`
}
// PosOrderCustomer is the shopper snapshot carried on the bill itself.
//
// Deliberately thin. The full profile travels on its own uplink; this exists so
// a bill can be attached to somebody even when their registration has not
// arrived yet.
type PosOrderCustomer struct {
Id string `json:"id"`
Mobile string `json:"mobile"`
Name string `json:"name"`
}
// PosOrderPayment is one tender against a bill. A bill may be split across
// several.
type PosOrderPayment struct {
Method string `json:"method"`
Amount float64 `json:"amount"`
Reference string `json:"reference"`
}
// PosOrderPromo records a campaign that fired, as an amount rather than a rule.
// A bill read back years later must show what was actually given, not what
// today's rules would give.
type PosOrderPromo struct {
Id string `json:"id"`
Name string `json:"name"`
Type string `json:"type"`
Amount float64 `json:"amount"`
}
// PosOrder is one completed sale.
//
// Id is a UUID minted at the till and is the only thing that identifies this
// bill. It is what deduplication keys on, because at-least-once delivery means
// the same bill legitimately arrives more than once.
type PosOrder struct {
Id string `json:"id"`
Invoicenumber string `json:"invoice_number"`
Createdat string `json:"created_at"`
Terminalid string `json:"terminal_id"`
Cashier string `json:"cashier"`
Customer *PosOrderCustomer `json:"customer"`
Subtotal float64 `json:"subtotal"`
Discount float64 `json:"discount"`
Promos []PosOrderPromo `json:"promos"`
Tax float64 `json:"tax"`
Roundoff float64 `json:"round_off"`
Total float64 `json:"total"`
Pointsearned int `json:"points_earned"`
Pointsredeemed int `json:"points_redeemed"`
Payments []PosOrderPayment `json:"payments"`
Items []PosOrderItem `json:"items"`
// GST per slab, as printed on the tax invoice: {"0.05": 12.30, "0.18": 4.50}.
// Absent from terminals built before this field existed, which is why every
// consumer of it has to tolerate an empty map.
Taxbreakdown map[string]float64 `json:"tax_breakdown"`
}
// PosOrderBatch is the envelope a terminal publishes.
//
// Storeid carries the numeric tenantlocations.locationid as a string. The
// tenant is resolved from it server-side and never taken from the terminal — a
// till must not be able to name the tenant it posts into.
type PosOrderBatch struct {
Schema int `json:"schema"`
Batchid string `json:"batch_id"`
Storeid string `json:"store_id"`
Terminalid string `json:"terminal_id"`
Sentat string `json:"sent_at"`
Orders []PosOrder `json:"orders"`
}
// PosCustomer is a shopper registered at a till.
//
// No loyalty figures. Points, lifetime spend and visit counts are derived from
// the bill stream, which is idempotent and sees every counter; accepting a
// terminal's local balance would make the last till to sync win.
type PosCustomer struct {
Id string `json:"id"`
Mobile string `json:"mobile"`
Name string `json:"name"`
Email string `json:"email"`
Gender string `json:"gender"`
Dateofbirth string `json:"date_of_birth"`
Registeredat string `json:"registered_at"`
Registeredbyterminal string `json:"registered_by_terminal"`
}
type PosCustomerBatch struct {
Schema int `json:"schema"`
Batchid string `json:"batch_id"`
Storeid string `json:"store_id"`
Terminalid string `json:"terminal_id"`
Sentat string `json:"sent_at"`
Customers []PosCustomer `json:"customers"`
}
// PosAck is the only thing that retires a bill on the terminal.
//
// The rule the whole design rests on: a till marks a record synced if and only
// if its id appears in Accepted. Silence is not acceptance — an empty ack, a
// dropped connection or a 200 with no body all leave the record pending and it
// is sent again.
//
// Naming an id in Rejected is a decision, not a fault: the terminal stops
// retrying that record and waits for a person. Use it for "this bill is
// malformed", never for "the database is having a bad minute" — for the latter,
// do not ack at all and let the till back off and retry.
type PosAck struct {
Batchid string `json:"batch_id"`
Accepted []string `json:"accepted"`
Rejected map[string]string `json:"rejected,omitempty"`
}
// NewPosAck returns an ack with non-nil members, so it serialises as `[]` and
// `{}` rather than `null`. A terminal reading null for accepted would treat the
// whole batch as unconfirmed.
func NewPosAck(batchID string) *PosAck {
return &PosAck{
Batchid: batchID,
Accepted: make([]string, 0),
Rejected: make(map[string]string),
}
}
func (a *PosAck) Accept(id string) {
a.Accepted = append(a.Accepted, id)
}
func (a *PosAck) Reject(id, reason string) {
a.Rejected[id] = reason
}
// PosCatalogueProduct is one product as the till stores it.
type PosCatalogueProduct struct {
Id string `json:"id"`
Name string `json:"name"`
Barcode string `json:"barcode"`
Sku string `json:"sku"`
Category string `json:"category"`
Price float64 `json:"price"`
Mrp float64 `json:"mrp,omitempty"`
Stock float64 `json:"stock"`
Unit string `json:"unit"`
Gstrate float64 `json:"gst_rate"`
Hsncode string `json:"hsn_code,omitempty"`
Brand string `json:"brand,omitempty"`
Isactive bool `json:"is_active"`
}
// PosCatalogueCustomer is a shopper travelling *down* to a terminal.
//
// The mirror of PosCustomer, and the difference is the point: the uplink
// carries no loyalty figures because a till's local balance is only its own
// view, while the downlink carries them because the back office has seen every
// counter and is the only thing that can total them.
type PosCatalogueCustomer struct {
Id string `json:"id"`
Name string `json:"name"`
Mobile string `json:"mobile"`
Email string `json:"email,omitempty"`
Gender string `json:"gender,omitempty"`
Dateofbirth string `json:"date_of_birth,omitempty"`
Loyaltypoints int `json:"loyalty_points"`
Lifetimespend float64 `json:"lifetime_spend"`
Visitcount int `json:"visit_count"`
Createdat string `json:"created_at,omitempty"`
Lastvisitat string `json:"last_visit_at,omitempty"`
}
// PosCatalogueResponse answers a terminal's catalogue pull.
//
// Isdelta is load-bearing. A response marked false is treated as a full
// snapshot and the terminal withdraws every product it does not mention — so
// answering a change set with false empties the shelf.
type PosCatalogueResponse struct {
Revision string `json:"revision"`
Isdelta bool `json:"is_delta"`
Hasmore bool `json:"has_more"`
Products []PosCatalogueProduct `json:"products"`
Customers []PosCatalogueCustomer `json:"customers"`
Retiredids []string `json:"retired_product_ids"`
}

58
models/poshealth.go Normal file
View File

@@ -0,0 +1,58 @@
package models
// PosHealth is what a till reports about itself every 30 seconds.
//
// This is a liveness signal, not a record. It lives in Redis under a TTL and is
// never written to Postgres: a terminal that dies simply stops refreshing and
// disappears from the board on its own, with no reaper job and no row left
// claiming "online" three days after the shop closed.
//
// The fields exist to answer questions a person actually asks when a shop
// phones in: is the till on, is it reaching us, is it selling anything, and is
// the hardware in the way.
type PosHealth struct {
// Identity. Terminalid is the short code printed on invoices — the thing a
// support call starts with.
Terminalid string `json:"terminal_id"`
Locationid string `json:"location_id"`
Storename string `json:"store_name"`
Appversion string `json:"app_version"`
// "online" while the till is refreshing this. The broker's Last Will
// overwrites it with "offline" if the terminal loses power mid-shift, which
// is the only way to tell *closed for the night* from *unplugged*.
Status string `json:"status"`
// Queue depth — the number that matters most. A shop quietly accumulating
// unsynced takings looks completely normal from the shop floor, and this is
// the only thing that makes it visible before someone reconciles a till and
// finds a day missing.
Pendingbills int `json:"pending_bills"`
Pendingregistrations int `json:"pending_registrations"`
Oldestpendingat string `json:"oldest_pending_at"`
// Today's trading. A till that is connected but has rung nothing in three
// hours usually means a jammed printer or an absent cashier, and neither
// shows up in a plain online/offline board.
Todaybills int `json:"today_bills"`
Todayamount float64 `json:"today_amount"`
Lastbillat string `json:"last_bill_at"`
// Device state, for pre-emptive support.
//
// Pointers so that *not reported* is distinguishable from *reported as
// zero*. Not every build collects these — battery and free storage need
// platform packages a desktop till has no use for — and writing an
// uncollected reading as 0 would show a board full of terminals on a flat
// battery with an unreachable printer. A nil field is skipped entirely.
Batterylevel *int `json:"battery_level,omitempty"`
Batterycharging *bool `json:"battery_charging,omitempty"`
Storagefreemb *int `json:"storage_free_mb,omitempty"`
Printerreachable *bool `json:"printer_reachable,omitempty"`
Drawerstatus *string `json:"drawer_status,omitempty"`
// Stamped by the till. The consumer also stamps its own arrival time, and
// the two disagreeing is itself a signal — a till whose clock is wrong
// writes bills under the wrong business date.
Reportedat string `json:"reported_at"`
}

209
models/posorder.go Normal file
View File

@@ -0,0 +1,209 @@
package models
import "time"
// Counter sales, stored at the fidelity the till actually rang them.
//
// Separate from `orders` on purpose. An app order and a counter bill are
// different documents: a bill 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, and the loss is silent.
//
// The cost of the split is that existing revenue queries do not see these rows
// until they are extended to union them in — done in orderRepository's summary
// queries, and the thing to remember when adding a new report.
//
// Stock is *not* separate: a counter sale writes the same productstocks "out"
// rows an app order does, through the same helper. Two stock ledgers would mean
// the catalogue pull sends a till figures that ignore its own sales.
// PosOrders is one counter bill.
type PosOrders struct {
Posorderid int `json:"posorderid" gorm:"primaryKey;autoIncrement;column:posorderid"`
// The UUID minted at the till. Globally unique by construction and the only
// thing that identifies this bill, so it carries a unique index: delivery is
// at-least-once and the same bill legitimately arrives more than once.
Terminalorderid string `json:"terminalorderid" gorm:"column:terminalorderid;uniqueIndex;not null"`
// Human-facing, and unique only per terminal — a till that was replaced
// restarts its own series, so gaps are normal and duplicates across
// terminals are expected.
Invoicenumber string `json:"invoicenumber" gorm:"column:invoicenumber;index"`
Tenantid int `json:"tenantid" gorm:"column:tenantid;index"`
Locationid int `json:"locationid" gorm:"column:locationid;index"`
// Which physical till, e.g. "T4A9". Free text: nothing keys on it, but a
// support call starts with it.
Terminalid string `json:"terminalid" gorm:"column:terminalid;index"`
Cashiername string `json:"cashiername" gorm:"column:cashiername"`
// Resolved against the customers table. Zero for a walk-in.
Customerid int `json:"customerid" gorm:"column:customerid;index"`
Customermobile string `json:"customermobile" gorm:"column:customermobile"`
Customername string `json:"customername" gorm:"column:customername"`
// When the sale was rung, not when it reached us — a till that was offline
// for a day uploads bills whose Billedat is yesterday, and every daily
// figure must use this rather than Receivedat.
Billedat time.Time `json:"billedat" gorm:"column:billedat;index"`
// YYYY-MM-DD of Billedat, denormalised so a day's takings are one indexed
// equality match rather than a range scan with timezone arithmetic.
Businessdate string `json:"businessdate" gorm:"column:businessdate;index"`
Subtotal float64 `json:"subtotal" gorm:"column:subtotal"`
Discount float64 `json:"discount" gorm:"column:discount"`
Taxamount float64 `json:"taxamount" gorm:"column:taxamount"`
// The paise adjustment printed on the bill. Kept because total is not
// derivable from the other columns without it.
Roundoff float64 `json:"roundoff" gorm:"column:roundoff"`
// What the shopper actually paid. The figure every revenue report sums.
Total float64 `json:"total" gorm:"column:total"`
Pointsearned int `json:"pointsearned" gorm:"column:pointsearned"`
Pointsredeemed int `json:"pointsredeemed" gorm:"column:pointsredeemed"`
Itemcount int `json:"itemcount" gorm:"column:itemcount"`
// The largest tender, for the common "how did they pay" grouping.
Paymentmode string `json:"paymentmode" gorm:"column:paymentmode;index"`
// The full split, verbatim. A bill can be part cash, part card, part
// loyalty, and collapsing that to one mode would lose the reconciliation a
// cashier settles their drawer against.
Paymentsjson string `json:"paymentsjson" gorm:"column:paymentsjson;type:jsonb"`
// Campaigns that fired, stored as amounts rather than rules — a bill read
// back years later must show what was given, not what today's rules give.
Promosjson string `json:"promosjson" gorm:"column:promosjson;type:jsonb"`
// GST per slab, as printed on the tax invoice.
Taxbreakdownjson string `json:"taxbreakdownjson" gorm:"column:taxbreakdownjson;type:jsonb"`
// Which upload carried this bill, and when it landed. Kept for tracing a
// terminal's complaint back to a specific batch.
Batchid string `json:"batchid" gorm:"column:batchid;index"`
Receivedat time.Time `json:"receivedat" gorm:"column:receivedat"`
Created time.Time `json:"created" gorm:"column:created;autoCreateTime"`
Updated time.Time `json:"updated" gorm:"column:updated;autoUpdateTime"`
Items []PosOrderItems `json:"items" gorm:"-"`
}
func (PosOrders) TableName() string {
return "pos_orders"
}
// PosOrderItems is one line of a counter bill.
type PosOrderItems struct {
Posorderitemid int `json:"posorderitemid" gorm:"primaryKey;autoIncrement;column:posorderitemid"`
Posorderid int `json:"posorderid" gorm:"column:posorderid;index"`
Tenantid int `json:"tenantid" gorm:"column:tenantid;index"`
Locationid int `json:"locationid" gorm:"column:locationid;index"`
Productid int `json:"productid" gorm:"column:productid;index"`
// Snapshotted rather than joined. A product renamed or withdrawn next month
// must not change what a bill from today says it sold.
Productname string `json:"productname" gorm:"column:productname"`
Barcode string `json:"barcode" gorm:"column:barcode"`
Unitname string `json:"unitname" gorm:"column:unitname"`
// Fractional: a counter sells 1.5 kg of onions. Note that productstocks
// cannot represent that — see roundStockQty.
Quantity float64 `json:"quantity" gorm:"column:quantity"`
Unitprice float64 `json:"unitprice" gorm:"column:unitprice"`
Discountamount float64 `json:"discountamount" gorm:"column:discountamount"`
// Stored as a fraction (0.18), matching how the till holds it.
Gstrate float64 `json:"gstrate" gorm:"column:gstrate"`
Taxamount float64 `json:"taxamount" gorm:"column:taxamount"`
// What this line contributed to the bill total, after its share of every
// discount. The lines sum to the bill's Total less Roundoff.
Linetotal float64 `json:"linetotal" gorm:"column:linetotal"`
Created time.Time `json:"created" gorm:"column:created;autoCreateTime"`
}
func (PosOrderItems) TableName() string {
return "pos_order_items"
}
// PosSalesFilter scopes a query over counter sales.
//
// Locationid is required and is the authorisation boundary — every read is
// scoped to one outlet, so a caller cannot page through another shop's takings
// by omitting a parameter.
type PosSalesFilter struct {
Locationid int
Fromdate string // YYYY-MM-DD, matched against businessdate
Todate string
Terminalid string
Cashiername string
Paymentmode string
Pageno int
Pagesize int
}
// PosSalesPage is one page of bills, with the total so a caller can paginate
// without a second request.
type PosSalesPage struct {
Total int64 `json:"total"`
Pageno int `json:"pageno"`
Pagesize int `json:"pagesize"`
Bills []PosOrders `json:"bills"`
}
// PosSalesSummary totals a range of counter sales.
//
// Deliberately separate from the bill list: a shop settling a till wants the
// figures, not five hundred rows, and computing them client-side would mean
// fetching every page first.
type PosSalesSummary struct {
Locationid int `json:"locationid"`
Fromdate string `json:"fromdate"`
Todate string `json:"todate"`
Billcount int `json:"billcount"`
Itemcount int `json:"itemcount"`
Grosssales float64 `json:"grosssales"`
Taxcollected float64 `json:"taxcollected"`
Discount float64 `json:"discountgiven"`
Roundoff float64 `json:"roundoff"`
Averagebill float64 `json:"averagebill"`
// What a cashier reconciles the drawer against.
Bypaymentmode []PosPaymentTotal `json:"bypaymentmode"`
// One row per trading day, for a chart.
Byday []PosDayTotal `json:"byday"`
// Which tills contributed, so an outlet with several counters can see them
// apart without a second query.
Byterminal []PosTerminalTotal `json:"byterminal"`
}
type PosPaymentTotal struct {
Paymentmode string `json:"paymentmode"`
Billcount int `json:"billcount"`
Amount float64 `json:"amount"`
}
type PosDayTotal struct {
Businessdate string `json:"businessdate"`
Billcount int `json:"billcount"`
Amount float64 `json:"amount"`
}
type PosTerminalTotal struct {
Terminalid string `json:"terminalid"`
Billcount int `json:"billcount"`
Amount float64 `json:"amount"`
}

78
models/product.go
View File

@@ -77,8 +77,16 @@ type Products struct {
Productcombo int `json:"productcombo" gorm:"default:0"`
Variants int `json:"variants" gorm:"default:0"`
Quantity int `json:"quantity"`
Retailprice float64 `json:"retailprice,omitempty"`
Diffprice float64 `json:"diffprice,omitempty"`
// Price is the EFFECTIVE selling price at the location a query was scoped
// to: productlocations.price when the store has set one, otherwise the
// master Retailprice below. Read-only — it is computed by the query, never
// written through this struct. Location-scoped endpoints must expose it, or
// a price the admin sets per store can never reach the customer app: they
// returned only Retailprice, which the admin catalogue never writes.
// Same meaning as Locationproducts.Price, so both product feeds agree.
Price float64 `json:"price" gorm:"->"`
Retailprice float64 `json:"retailprice,omitempty"`
Diffprice float64 `json:"diffprice,omitempty"`
Diffpercent float64 `json:"diffpercent,omitempty"`
Othercost float64 `json:"othercost,omitempty"`
Approve int `json:"approve"`
@@ -124,11 +132,16 @@ type Locationproducts struct {
Productcombo int `json:"productcombo" gorm:"default:0"`
Variants int `json:"variants" gorm:"default:0"`
Quantity int `json:"quantity"`
Retailprice float64 `json:"retailprice,omitempty"`
Diffprice float64 `json:"diffprice,omitempty"`
Diffpercent float64 `json:"diffpercent,omitempty"`
Othercost float64 `json:"othercost,omitempty"`
Approve int `json:"approve" gorm:"default:0"`
// Price is the per-store selling price from productlocations.price — the one
// CreateProductLocation upserts. Read-only here: it comes from the joined
// productlocations row, not from products. Without it a store could set a
// price and never read it back, so the UI always showed the master price.
Price float64 `json:"price" gorm:"->"`
Retailprice float64 `json:"retailprice,omitempty"`
Diffprice float64 `json:"diffprice,omitempty"`
Diffpercent float64 `json:"diffpercent,omitempty"`
Othercost float64 `json:"othercost,omitempty"`
Approve int `json:"approve" gorm:"default:0"`
// Productstatus string `json:"productstatus" gorm:"default:available"`
Status string `json:"status" gorm:"default:outofstock"`
}
@@ -322,6 +335,57 @@ type ProductLocationRef struct {
Productid int
}
// SaleTemplateRow is one line of the downloadable offline-sales spreadsheet: a
// product stocked at one branch, with the numbers the person at the till needs
// to see before typing a sold quantity against it.
//
// Tenantid and Locationid ride on every row because one workbook covers every
// branch a merchant runs. The row's own Locationid decides which branch's stock
// its sale comes out of — a tenant-level import would be wrong, since the same
// product is held separately at each outlet.
//
// Productid is the only field that identifies the product. It cannot be
// productsku: across the live catalogue 6,245 products share just 93 distinct
// sku values (one tenant has 463 products all carrying sku "1"), and 154 are
// blank, so a sku is not a key. Productname is nearly unique per tenant but not
// reliably ("rice" appears 6 times for one tenant), so it travels as a
// human-readable confirmation only and is never matched on. That is why the
// spreadsheet has to be generated from this endpoint rather than typed from
// scratch — productid and locationid are filled in for the user.
type SaleTemplateRow struct {
Tenantid int `json:"tenantid"`
Locationid int `json:"locationid"`
Locationname string `json:"locationname"`
Productid int `json:"productid"`
Productname string `json:"productname"`
Productunit string `json:"productunit"`
Unitvalue string `json:"unitvalue"`
Categoryname string `json:"categoryname"`
Currentstock int `json:"currentstock"`
Price float64 `json:"price"`
Taxpercent float64 `json:"taxpercent"`
}
// SaleTemplateLocation is one branch covered by the workbook, so the sheet can
// list what it spans and the UI can summarise it without walking every row.
type SaleTemplateLocation struct {
Locationid int `json:"locationid"`
Locationname string `json:"locationname"`
Productcount int `json:"productcount"`
}
// SaleTemplate is the payload the web app turns into an .xlsx workbook.
//
// Locationid is 0 when the template spans every branch of the tenant, which is
// the normal case for an owner or admin. A store user gets a template for their
// own branch only, and it is then the single entry in Locations.
type SaleTemplate struct {
Tenantid int `json:"tenantid"`
Locationid int `json:"locationid"`
Locations []SaleTemplateLocation `json:"locations"`
Products []SaleTemplateRow `json:"products"`
}
type ProductSubcategory struct {
Subcatid int `json:"subcatid"`
Categoryid int `json:"categoryid"`

29
repositories/customerRepository.go
View File

@@ -188,10 +188,21 @@ func (r *customerRepository) GetTenantCustomers(tid, lid, pageno, pagesize int,
var args []interface{}
searchLike := "%" + keyword + "%"
// DISTINCT ON collapses to one row per customer BEFORE the LIMIT is applied.
// Without it the store-scoped branch below paginated the joined
// customerlocations rows — one per saved address — so `pagesize` bought a
// page of addresses, not of customers. Live example: locationid 1185 returned
// 12 rows that were only 2 people, 11 of them one customer's addresses. A
// store with a page size of 20 therefore listed roughly three customers and
// gave no hint that the rest existed.
//
// The ORDER BY must lead with the DISTINCT ON expression, so customerid sorts
// first; the trailing keys only decide WHICH address represents a customer,
// preferring the one flagged primary.
if lid != 0 {
q1 = `SELECT a.customerid,a.firstname,a.lastname,a.contactno,a.email,
q1 = `SELECT DISTINCT ON (a.customerid) a.customerid,a.firstname,a.lastname,a.contactno,a.email,
b.locationid as deliverylocationid,b.address,b.suburb,b.city,b.state,b.landmark,b.doorno,b.postcode,
b.latitude,b.longitude,a.applocationid,c.locationid as tenantlocationid,a.status
b.latitude,b.longitude,a.applocationid,c.locationid as tenantlocationid,a.status
FROM customers a
LEFT JOIN customerlocations b ON a.customerid=b.customerid
INNER JOIN tenantcustomers c ON a.customerid=c.customerid
@@ -204,13 +215,17 @@ func (r *customerRepository) GetTenantCustomers(tid, lid, pageno, pagesize int,
args = append(args, searchLike, searchLike, searchLike)
}
q1 += ` ORDER BY a.customerid DESC LIMIT ? OFFSET ?`
q1 += ` ORDER BY a.customerid DESC, b.primaryaddress DESC NULLS LAST, b.locationid ASC
LIMIT ? OFFSET ?`
args = append(args, pagesize, offset)
} else {
q1 = `SELECT a.customerid,a.firstname,a.lastname,a.contactno,a.email,
// A customer linked to several outlets of the same tenant has one
// tenantcustomers row per outlet, so this branch double-counted them
// against the LIMIT too.
q1 = `SELECT DISTINCT ON (a.customerid) a.customerid,a.firstname,a.lastname,a.contactno,a.email,
a.address,a.suburb,a.city,a.state,a.landmark,a.doorno,a.postcode,
a.latitude,a.longitude,a.applocationid,c.locationid as tenantlocationid,a.status
a.latitude,a.longitude,a.applocationid,c.locationid as tenantlocationid,a.status
FROM customers a
INNER JOIN tenantcustomers c ON a.customerid=c.customerid
WHERE c.tenantid = ?`
@@ -223,12 +238,10 @@ func (r *customerRepository) GetTenantCustomers(tid, lid, pageno, pagesize int,
args = append(args, searchLike, searchLike, searchLike)
}
q1 += ` ORDER BY a.customerid DESC LIMIT ? OFFSET ?`
q1 += ` ORDER BY a.customerid DESC, c.locationid ASC LIMIT ? OFFSET ?`
args = append(args, pagesize, offset)
}
print(q1)
r.db.Raw(q1, args...).Find(&data)
return data
}

71
repositories/deliveriesRepository.go
View File

@@ -1,11 +1,13 @@
package repositories
import (
"errors"
"fmt"
"log"
"nearle/models"
"strconv"
"strings"
"time"
"github.com/jinzhu/copier"
"gorm.io/gorm"
@@ -147,18 +149,75 @@ func (r *deliveriesRepository) UpdateDelivery(data models.UpdateDeliveryStatus)
var ord models.Updateorderstatus
var cloc models.Customerlocations
if data.Deliveryid == 0 {
return errors.New("deliveryid is required")
}
tx := r.db.Begin()
if tx.Error != nil {
return tx.Error
}
if err := tx.Table("deliveries").Where("deliveryid = ?", data.Deliveryid).Updates(&data).Error; err != nil {
tx.Rollback()
return err
}
// The parent order is resolved from the delivery row rather than taken from
// the request. Every status branch below writes the order with
// "WHERE orderheaderid = ?", and a client that omits orderheaderid made that
// "WHERE orderheaderid = 0", matching nothing. GORM reports no error for an
// update that affects no rows, so the handler still answered 201 Success
// while the order silently kept its old status — 635 deliveries are marked
// delivered against an order still reading pending because of this.
//
// deliveryid is the one field every caller must send (it is how the row
// above is found), so deriving the link from it makes the sync independent
// of how complete the client's payload is.
orderHeaderID := data.Orderheaderid
if orderHeaderID == 0 {
if err := tx.Table("deliveries").
Select("orderheaderid").
Where("deliveryid = ?", data.Deliveryid).
Scan(&orderHeaderID).Error; err != nil {
tx.Rollback()
return err
}
}
if orderHeaderID == 0 {
tx.Rollback()
return fmt.Errorf("delivery %d has no order attached", data.Deliveryid)
}
// syncOrder applies the status to the parent order and fails loudly if the
// row is not there, instead of reporting success for a write that landed
// nowhere.
syncOrder := func() error {
res := tx.Table("orders").Where("orderheaderid = ?", orderHeaderID).Updates(&ord)
if res.Error != nil {
return res.Error
}
if res.RowsAffected == 0 {
return fmt.Errorf("order %d not found for delivery %d", orderHeaderID, data.Deliveryid)
}
return nil
}
// The lifecycle timestamp mirrored onto the order. Clients frequently send
// the status without one, and because Updates() skips zero-valued struct
// fields the order's own column was left blank while its status moved on.
stamp := func(supplied string) string {
if strings.TrimSpace(supplied) != "" {
return supplied
}
return time.Now().Format("2006-01-02 15:04:05")
}
switch data.Orderstatus {
case "pending":
ord.Orderstatus = data.Orderstatus
ord.Pending = data.Assigntime
if err := tx.Table("orders").Where("orderheaderid = ?", data.Orderheaderid).Updates(&ord).Error; err != nil {
ord.Pending = stamp(data.Assigntime)
if err := syncOrder(); err != nil {
tx.Rollback()
return err
}
@@ -181,8 +240,8 @@ func (r *deliveriesRepository) UpdateDelivery(data models.UpdateDeliveryStatus)
case "delivered":
ord.Orderstatus = data.Orderstatus
ord.Delivered = data.Deliverytime
if err := tx.Table("orders").Where("orderheaderid = ?", data.Orderheaderid).Updates(&ord).Error; err != nil {
ord.Delivered = stamp(data.Deliverytime)
if err := syncOrder(); err != nil {
tx.Rollback()
return err
}
@@ -204,8 +263,8 @@ func (r *deliveriesRepository) UpdateDelivery(data models.UpdateDeliveryStatus)
case "cancelled":
ord.Orderstatus = data.Orderstatus
ord.Cancelled = data.Canceltime
if err := tx.Table("orders").Where("orderheaderid = ?", data.Orderheaderid).Updates(&ord).Error; err != nil {
ord.Cancelled = stamp(data.Canceltime)
if err := syncOrder(); err != nil {
tx.Rollback()
return err
}

1284
repositories/orderRepository.go
View File

File diff suppressed because it is too large Load Diff

195
repositories/posPresence.go Normal file
View File

@@ -0,0 +1,195 @@
package repositories
import (
"context"
"fmt"
"strconv"
"time"
"nearle/db"
"nearle/models"
"github.com/redis/go-redis/v9"
)
// POS terminal presence, in Redis.
//
// ### Why Redis and not a table
//
// A heartbeat is a fact with an expiry date. Written to Postgres it needs a
// row per till updated twice a minute — around 288,000 writes a day across a
// hundred terminals — and a reaper job to mark a till offline once it stops,
// because a row that says "online" has no way of ageing out on its own.
//
// A Redis key with a TTL does the ageing for free. A till that loses power
// stops refreshing, the key expires, and it disappears from the board without
// anything having to notice. That is the whole design.
//
// ### Keys
//
// pos:terminal:{terminalcode} HASH, TTL 90s — one till's state
// pos:location:{locationid}:terminals SET, no TTL — which tills a shop has
//
// The set has no TTL on purpose, mirroring how `city:{tenantid}:active_deliveries`
// is treated in the express backend: it is an index of what exists, not a claim
// that any of it is alive right now. Membership means "this till has been seen
// here"; liveness is whether the hash still exists.
const (
// Three missed heartbeats. 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.
posPresenceTTL = 90 * time.Second
posTerminalKeyFmt = "pos:terminal:%s"
posLocationKeyFmt = "pos:location:%s:terminals"
)
type PosPresenceRepository interface {
Record(ctx context.Context, health models.PosHealth) error
Terminal(ctx context.Context, terminalID string) (map[string]string, error)
Location(ctx context.Context, locationID string) ([]map[string]string, error)
}
type posPresenceRepository struct{}
func NewPosPresenceRepository() PosPresenceRepository { return &posPresenceRepository{} }
// Record writes one heartbeat and refreshes its TTL.
func (r *posPresenceRepository) Record(ctx context.Context, health models.PosHealth) error {
if db.Rdb == nil {
return fmt.Errorf("redis is not configured")
}
if health.Terminalid == "" {
return fmt.Errorf("heartbeat has no terminal id")
}
terminalKey := fmt.Sprintf(posTerminalKeyFmt, health.Terminalid)
fields := map[string]any{
"terminal_id": health.Terminalid,
"location_id": health.Locationid,
"store_name": health.Storename,
"app_version": health.Appversion,
"status": health.Status,
"pending_bills": health.Pendingbills,
"pending_registrations": health.Pendingregistrations,
"oldest_pending_at": health.Oldestpendingat,
"today_bills": health.Todaybills,
"today_amount": health.Todayamount,
"last_bill_at": health.Lastbillat,
"reported_at": health.Reportedat,
// Stamped here as well as at the till. The two disagreeing by more than
// a few seconds means the terminal's clock is wrong — which matters,
// because bills are filed under the business date the till decided.
"received_at": time.Now().UTC().Format(time.RFC3339),
}
// Device readings only when the till actually reported them. A build that
// does not collect battery level must not leave one behind saying 0%.
if health.Batterylevel != nil {
fields["battery_level"] = *health.Batterylevel
}
if health.Batterycharging != nil {
fields["battery_charging"] = *health.Batterycharging
}
if health.Storagefreemb != nil {
fields["storage_free_mb"] = *health.Storagefreemb
}
if health.Printerreachable != nil {
fields["printer_reachable"] = *health.Printerreachable
}
if health.Drawerstatus != nil {
fields["drawer_status"] = *health.Drawerstatus
}
// HSet leaves untouched fields in place, so a reading that stops being
// reported would otherwise linger for ever at its last value. Clearing the
// absent ones keeps the hash honest about what this till currently knows.
stale := make([]string, 0, 5)
for field, reported := range map[string]bool{
"battery_level": health.Batterylevel != nil,
"battery_charging": health.Batterycharging != nil,
"storage_free_mb": health.Storagefreemb != nil,
"printer_reachable": health.Printerreachable != nil,
"drawer_status": health.Drawerstatus != nil,
} {
if !reported {
stale = append(stale, field)
}
}
pipe := db.Rdb.TxPipeline()
pipe.HSet(ctx, terminalKey, fields)
if len(stale) > 0 {
pipe.HDel(ctx, terminalKey, stale...)
}
pipe.Expire(ctx, terminalKey, posPresenceTTL)
if health.Locationid != "" {
// No TTL: this is the list of tills a shop has, not a claim that any of
// them is alive. Liveness is whether the hash above still exists.
pipe.SAdd(ctx, fmt.Sprintf(posLocationKeyFmt, health.Locationid), health.Terminalid)
}
_, err := pipe.Exec(ctx)
return err
}
// Terminal returns one till's last known state, or nil if it has gone quiet.
func (r *posPresenceRepository) Terminal(ctx context.Context, terminalID string) (map[string]string, error) {
if db.Rdb == nil {
return nil, fmt.Errorf("redis is not configured")
}
fields, err := db.Rdb.HGetAll(ctx, fmt.Sprintf(posTerminalKeyFmt, terminalID)).Result()
if err != nil && err != redis.Nil {
return nil, err
}
if len(fields) == 0 {
// Expired or never seen. Both mean "not reporting", which is what the
// caller needs to know; distinguishing them would need a durable record
// this deliberately does not keep.
return nil, nil
}
return fields, nil
}
// Location returns every till registered at a shop, live or dark.
//
// A till whose key has expired comes back as a stub with status "offline"
// rather than being omitted. Omitting it would make a dead terminal
// indistinguishable from one that was never installed — and the dead one is
// precisely what somebody is looking for.
func (r *posPresenceRepository) Location(ctx context.Context, locationID string) ([]map[string]string, error) {
if db.Rdb == nil {
return nil, fmt.Errorf("redis is not configured")
}
members, err := db.Rdb.SMembers(ctx, fmt.Sprintf(posLocationKeyFmt, locationID)).Result()
if err != nil && err != redis.Nil {
return nil, err
}
out := make([]map[string]string, 0, len(members))
for _, terminalID := range members {
fields, err := r.Terminal(ctx, terminalID)
if err != nil {
return nil, err
}
if fields == nil {
fields = map[string]string{
"terminal_id": terminalID,
"location_id": locationID,
"status": "offline",
// Says why it is being reported offline, rather than leaving a
// reader to guess whether the till said so or simply vanished.
"reason": "no heartbeat within " + strconv.Itoa(int(posPresenceTTL.Seconds())) + "s",
}
}
out = append(out, fields)
}
return out, nil
}

843
repositories/posRepository.go Normal file
View File

@@ -0,0 +1,843 @@
package repositories
import (
"encoding/json"
"errors"
"fmt"
"strconv"
"strings"
"time"
"nearle/models"
"gorm.io/gorm"
)
// Ingestion for the Nearle POS terminal.
//
// Bills arrive here already rung up and paid for — the till is the system of
// record until we say otherwise, and it holds its own copy for a week on the
// strength of our acknowledgement. Two consequences shape everything below.
//
// **A duplicate is a success.** Delivery is at-least-once: a lost ack makes a
// terminal re-send bills that are already banked. Reporting those as failures
// would strand a day of takings on the till for ever. So a bill we already hold
// is accepted, silently, without touching stock again.
//
// **Acknowledge only after the commit.** A bill named in the ack is one the
// terminal is entitled to delete. Saying so before the transaction lands would
// trade a real sale for a queue position.
//
// The commit itself is deliberately not reimplemented here. Each bill runs
// through createOrderTx, the same path an app order and a spreadsheet import
// take, so stock deduction, the per-product row locks that prevent overselling,
// the ledger entries and sequence allocation stay shared rather than forked.
type PosRepository interface {
IngestOrders(batch models.PosOrderBatch) (*models.PosAck, error)
IngestCustomers(batch models.PosCustomerBatch) (*models.PosAck, error)
Catalogue(storeID, since string, page, pageSize int) (*models.PosCatalogueResponse, error)
// Reading counter sales back out. Without these a committed bill is
// unreachable from every screen in the product.
Sales(f models.PosSalesFilter) (*models.PosSalesPage, error)
SaleDetail(locationID int, reference string) (*models.PosOrders, error)
SalesSummary(f models.PosSalesFilter) (*models.PosSalesSummary, error)
}
type posRepository struct {
db *gorm.DB
// Held rather than embedded so the order machinery is reached explicitly.
orders *orderRepository
}
func NewPosRepository(db *gorm.DB) PosRepository {
return &posRepository{db: db, orders: &orderRepository{db: db}}
}
// resolvePosStore turns the terminal's store_id into an authorised outlet.
//
// The till sends a location and nothing else. The tenant is looked up from it
// here and never accepted from the wire: a terminal that could name its own
// tenant could post sales into somebody else's books.
func (r *posRepository) resolvePosStore(storeID string) (*offlineLocationContext, error) {
locationID, err := strconv.Atoi(strings.TrimSpace(storeID))
if err != nil || locationID <= 0 {
return nil, fmt.Errorf("store_id %q is not a location id; configure the terminal's Store ID with the numeric locationid", storeID)
}
var tenantID int
err = r.db.Raw(
`SELECT COALESCE(MIN(tenantid), 0) FROM tenantlocations WHERE locationid = ?`,
locationID,
).Scan(&tenantID).Error
if err != nil {
return nil, err
}
if tenantID <= 0 {
return nil, fmt.Errorf("no outlet is registered with locationid %d", locationID)
}
return r.orders.resolveOfflineLocationContext(tenantID, locationID)
}
// IngestOrders commits a batch of counter bills and reports what landed.
//
// A failure to resolve the outlet at all returns an error rather than an ack,
// so the terminal treats the outcome as unknown and retries. A failure on one
// bill is reported against that bill alone and the rest still commit.
func (r *posRepository) IngestOrders(batch models.PosOrderBatch) (*models.PosAck, error) {
ack := models.NewPosAck(batch.Batchid)
if len(batch.Orders) == 0 {
return ack, nil
}
ctx, err := r.resolvePosStore(batch.Storeid)
if err != nil {
return nil, err
}
products, err := r.orders.loadOfflineProducts(ctx.Tenantid, ctx.Locationid)
if err != nil {
return nil, err
}
if len(products) == 0 {
return nil, fmt.Errorf("outlet '%s' has no products stocked against it", ctx.Locationname)
}
for _, order := range batch.Orders {
if strings.TrimSpace(order.Id) == "" {
// Nothing to key on, so it can never be deduplicated. Refusing it
// is safer than admitting a bill that would double on every retry.
ack.Reject("", "order is missing its id")
continue
}
if reason := r.importPosOrder(ctx, products, batch.Batchid, batch.Terminalid, order); reason != "" {
ack.Reject(order.Id, reason)
continue
}
ack.Accept(order.Id)
}
return ack, nil
}
// importPosOrder commits one bill, or leaves nothing behind.
//
// Returns an empty string on success — including the case where the bill was
// already held, which is a success from the terminal's point of view.
//
// The bill lands in pos_orders at full fidelity, and the stock it consumed goes
// through the same productstocks ledger an app order uses. Those two facts pull
// in opposite directions and both matter: the bill is its own kind of document
// and deserves its own table, but stock is one number per shelf and must not be
// tracked twice.
// batchTerminal is the terminal the whole batch came from, used when a bill
// does not name one itself. Over MQTT the consumer fills it in from the topic;
// over HTTP the terminal sends it once at the top of the batch rather than
// repeating it on every bill.
func (r *posRepository) importPosOrder(
ctx *offlineLocationContext,
products map[int]offlineProduct,
batchID string,
batchTerminal string,
order models.PosOrder,
) string {
if len(order.Items) == 0 {
return "bill has no items"
}
saleDate, err := parsePosSaleDate(order.Createdat)
if err != nil {
return err.Error()
}
// The till has already apportioned bill-level discounts across its lines to
// get the tax right, but it sends each line at its own pre-apportionment
// value. Left alone, the item rows would sum to the subtotal while the
// header carried the total, and every report that adds up lines would
// disagree with the one that reads the header.
//
// So the lines are scaled onto what was actually collected. The till's own
// figures stay authoritative for the bill as a whole; this only decides how
// that whole is attributed across the lines inside it.
netAmount := order.Total - order.Roundoff
lineSum := 0.0
taxSum := 0.0
for _, item := range order.Items {
lineSum += item.Linetotal
taxSum += item.Tax
}
amountFactor := 1.0
if lineSum > 0 && netAmount > 0 {
amountFactor = netAmount / lineSum
}
taxFactor := 1.0
if taxSum > 0 && order.Tax > 0 {
taxFactor = order.Tax / taxSum
}
items := make([]models.PosOrderItems, 0, len(order.Items))
lines := make([]stockLine, 0, len(order.Items))
var taxTotal float64
for _, raw := range order.Items {
productID, err := strconv.Atoi(strings.TrimSpace(raw.Productid))
if err != nil || productID <= 0 {
return fmt.Sprintf("line '%s' has product_id %q, which is not a catalogue id", raw.Name, raw.Productid)
}
// Membership of this map is the ownership check. A product absent from
// it is either another tenant's or not stocked here, and either way the
// bill is refused rather than posted against a catalogue it has no
// claim on.
product, ok := products[productID]
if !ok {
return fmt.Sprintf("product %d is not stocked at %s", productID, ctx.Locationname)
}
if raw.Quantity <= 0 {
return fmt.Sprintf("product '%s' has a quantity of %g; it must be greater than zero", product.Productname, raw.Quantity)
}
landing := raw.Linetotal * amountFactor
taxAmount := raw.Tax * taxFactor
gross := raw.Unitprice * raw.Quantity
discount := gross - landing
if discount < 0 {
discount = 0
}
taxTotal += taxAmount
items = append(items, models.PosOrderItems{
Tenantid: ctx.Tenantid,
Locationid: ctx.Locationid,
Productid: productID,
Productname: product.Productname,
Barcode: raw.Barcode,
Unitname: product.Productunit,
Quantity: raw.Quantity,
Unitprice: raw.Unitprice,
Discountamount: discount,
Gstrate: raw.Gstrate,
Taxamount: taxAmount,
Linetotal: landing,
})
lines = append(lines, stockLine{
Productid: productID,
Locationid: ctx.Locationid,
Productname: product.Productname,
Quantity: raw.Quantity,
})
}
paymentMode := "cash"
if len(order.Payments) > 0 {
// The largest tender names the bill. A split paid mostly by card with
// ten rupees of change in cash is a card sale in every report anyone
// actually reads — the full split is kept in Paymentsjson regardless.
largest := order.Payments[0]
for _, p := range order.Payments[1:] {
if p.Amount > largest.Amount {
largest = p
}
}
if m := strings.ToLower(strings.TrimSpace(largest.Method)); m != "" {
paymentMode = m
}
}
tx := r.db.Begin()
if tx.Error != nil {
return fmt.Sprintf("could not start a transaction: %v", tx.Error)
}
// Held for the life of the transaction, so a redelivery arriving at the
// same moment waits here and then sees the committed row rather than racing
// past the check below and banking the sale twice. The unique index on
// terminalorderid would catch it either way; this turns a constraint
// violation into an orderly "already held".
lockKey := "possale:" + strings.ToUpper(strings.TrimSpace(order.Id))
if err := tx.Exec(`SELECT pg_advisory_xact_lock(hashtext(?))`, lockKey).Error; err != nil {
tx.Rollback()
return fmt.Sprintf("could not lock bill %s: %v", order.Invoicenumber, err)
}
var already int
err = tx.Raw(
`SELECT COALESCE(COUNT(*), 0) FROM pos_orders WHERE terminalorderid = ?`,
strings.TrimSpace(order.Id),
).Scan(&already).Error
if err != nil {
tx.Rollback()
return fmt.Sprintf("could not check whether bill %s was already held: %v", order.Invoicenumber, err)
}
if already > 0 {
// Already banked. Accepted, not rejected — this is the ordinary result
// of a lost ack, and calling it a failure would leave the till holding
// a bill we have had all along. Stock is deliberately untouched.
tx.Rollback()
return ""
}
// Locks first, then availability, then the writes — the same order an app
// order takes, and the reason two tills selling the last unit cannot both
// succeed.
if err := lockStockRows(tx, ctx.Tenantid, lines); err != nil {
tx.Rollback()
return err.Error()
}
if err := assertStockAvailable(tx, ctx.Tenantid, lines, func(l stockLine) int {
return roundStockQty(l.Quantity)
}); err != nil {
tx.Rollback()
return err.Error()
}
customerID, err := r.orders.resolveOfflineCustomer(tx, ctx, posCustomerName(order), posCustomerMobile(order))
if err != nil {
tx.Rollback()
return fmt.Sprintf("could not resolve the customer: %v", err)
}
bill := models.PosOrders{
Terminalorderid: strings.TrimSpace(order.Id),
Invoicenumber: order.Invoicenumber,
Tenantid: ctx.Tenantid,
Locationid: ctx.Locationid,
// The bill's own terminal wins; the batch's is the fallback. Without
// this the column was empty on every bill that arrived over HTTP —
// the invoice number carried the code and the column did not, so
// per-terminal reconciliation had nothing to group on.
Terminalid: posTerminalFor(order.Terminalid, batchTerminal),
Cashiername: order.Cashier,
Customerid: customerID,
Customermobile: posCustomerMobile(order),
Customername: posCustomerName(order),
Billedat: saleDate,
// The day the sale was rung, not the day it arrived. A till that was
// offline overnight uploads yesterday's bills this morning, and every
// daily figure has to follow the sale rather than the upload.
Businessdate: saleDate.Format("2006-01-02"),
Subtotal: order.Subtotal,
Discount: order.Discount,
Taxamount: taxTotal,
Roundoff: order.Roundoff,
Total: order.Total,
Pointsearned: order.Pointsearned,
Pointsredeemed: order.Pointsredeemed,
Itemcount: len(items),
Paymentmode: paymentMode,
Paymentsjson: posJSON(order.Payments),
Promosjson: posJSON(order.Promos),
// Every jsonb column must carry valid JSON. Left at Go's zero value an
// empty string reaches Postgres and the whole insert fails with
// "invalid input syntax for type json" — taking the bill down with it.
Taxbreakdownjson: posJSON(order.Taxbreakdown),
Batchid: batchID,
Receivedat: time.Now(),
}
if err := tx.Create(&bill).Error; err != nil {
tx.Rollback()
return fmt.Sprintf("could not write bill %s: %v", order.Invoicenumber, err)
}
for i := range items {
items[i].Posorderid = bill.Posorderid
if err := tx.Create(&items[i]).Error; err != nil {
tx.Rollback()
return fmt.Sprintf("could not write a line of bill %s: %v", order.Invoicenumber, err)
}
// The same ledger an app order writes to. A second stock ledger for
// counter sales would mean the catalogue pull sends a till figures that
// ignore the till's own trading.
if err := recordStockOut(tx, ctx.Tenantid, lines[i], roundStockQty(lines[i].Quantity)); err != nil {
tx.Rollback()
return fmt.Sprintf("could not deduct stock for bill %s: %v", order.Invoicenumber, err)
}
}
if err := tx.Commit().Error; err != nil {
return fmt.Sprintf("could not commit bill %s: %v", order.Invoicenumber, err)
}
return ""
}
// posJSON encodes a payload column.
//
// Falls back to a JSON null rather than failing the bill: these columns exist
// to be read back later, and losing one is not a reason to refuse a sale the
// shopper has already paid for.
func posJSON(v any) string {
body, err := json.Marshal(v)
if err != nil || len(body) == 0 {
return "null"
}
return string(body)
}
// posTerminalFor picks which terminal code to file a bill under.
//
// Trimmed before the emptiness test: a terminal sending `" "` is saying nothing,
// and treating that as a real code would file bills under a blank that looks
// identical to the missing value this exists to fix.
func posTerminalFor(orderTerminal, batchTerminal string) string {
if t := strings.TrimSpace(orderTerminal); t != "" {
return t
}
return strings.TrimSpace(batchTerminal)
}
func posCustomerName(order models.PosOrder) string {
if order.Customer == nil {
return ""
}
return order.Customer.Name
}
func posCustomerMobile(order models.PosOrder) string {
if order.Customer == nil {
return ""
}
return order.Customer.Mobile
}
// parsePosSaleDate reads the till's timestamp.
//
// The terminal sends ISO-8601. A blank one falls back to now; an unparseable
// one is refused, because importing a sale under the wrong date corrupts every
// daily revenue figure that reads it.
// parsePosSaleDate reads the moment a bill was rung.
//
// The order of these layouts is load-bearing, and the two zoned ones must stay
// first. A terminal that sends its offset — `2026-08-05T00:30:00+05:30` — gets
// both readings right: the instant is correct, and Format("2006-01-02") still
// yields the till's own trading day rather than UTC's.
//
// The two bare layouts exist for terminals built before the offset was added,
// which are still in the field. `time.Parse` fills an absent zone with UTC, so
// those bills record an instant wrong by the offset — a Coimbatore wall clock
// read as though it were London. That is not recoverable here: nothing in the
// payload says which zone it came from. Their business date is still right,
// which is why the daily figures held up while billedat did not, and why these
// are tolerated rather than refused.
func parsePosSaleDate(raw string) (time.Time, error) {
raw = strings.TrimSpace(raw)
if raw == "" {
return time.Now(), nil
}
for _, layout := range []string{
time.RFC3339Nano,
time.RFC3339,
"2006-01-02T15:04:05.999999",
"2006-01-02 15:04:05",
} {
if t, err := time.Parse(layout, raw); err == nil {
return t, nil
}
}
return time.Time{}, fmt.Errorf("unrecognised created_at %q", raw)
}
// IngestCustomers records shoppers registered at a till.
//
// Insert-if-absent, never an update. A registration is replayed freely, and a
// profile corrected at head office must not be reverted by a terminal replaying
// what it captured months ago.
func (r *posRepository) IngestCustomers(batch models.PosCustomerBatch) (*models.PosAck, error) {
ack := models.NewPosAck(batch.Batchid)
if len(batch.Customers) == 0 {
return ack, nil
}
ctx, err := r.resolvePosStore(batch.Storeid)
if err != nil {
return nil, err
}
for _, customer := range batch.Customers {
mobile := strings.TrimSpace(customer.Mobile)
if strings.TrimSpace(customer.Id) == "" || mobile == "" {
ack.Reject(customer.Id, "registration is missing its id or mobile number")
continue
}
if err := r.upsertPosCustomer(ctx, customer, mobile); err != nil {
ack.Reject(customer.Id, err.Error())
continue
}
ack.Accept(customer.Id)
}
return ack, nil
}
// upsertPosCustomer attaches the shopper to this outlet's app location.
//
// Matched on contactno, which is what the rest of the system already keys a
// shopper on, so a shopper registered at a till and one who installed the app
// end up as one row rather than two.
func (r *posRepository) upsertPosCustomer(
ctx *offlineLocationContext,
customer models.PosCustomer,
mobile string,
) error {
name := strings.TrimSpace(customer.Name)
if name == "" {
name = "Counter Customer"
}
var existing int
err := r.db.Raw(
`SELECT COALESCE(MIN(customerid), 0) FROM customers WHERE contactno = ? AND applocationid = ?`,
mobile, ctx.Applocationid,
).Scan(&existing).Error
if err != nil {
return err
}
if existing > 0 {
// Already known. Accepted without a write — the terminal's copy is not
// newer than ours in any way we can establish.
return nil
}
// status 0 mirrors every other customer row in production, including ones
// actively placing orders. A different value here would make a shopper
// registered at the counter behave unlike all the others.
var created int
err = r.db.Raw(`
INSERT INTO customers (configid, firstname, lastname, contactno, email, gender, dob, applocationid, locationid, status, created, updated)
VALUES (?, ?, '', ?, ?, ?, ?, ?, ?, 0, NOW(), NOW())
RETURNING customerid`,
ctx.Configid, name, mobile,
strings.TrimSpace(customer.Email),
strings.TrimSpace(customer.Gender),
strings.TrimSpace(customer.Dateofbirth),
ctx.Applocationid, ctx.Locationid,
).Scan(&created).Error
if err != nil {
return err
}
if created <= 0 {
return errors.New("failed to create the customer row")
}
return nil
}
// posRevisionLayout is the timestamp inside a catalogue revision.
//
// The revision is the terminal's memory of when it last pulled: it stores what
// we send and hands it back on the next request, and the time encoded in it is
// the cutoff for what has changed since. Colons are avoided so the whole string
// stays safe in a URL query without escaping.
const posRevisionLayout = "20060102T150405Z"
// posRevisionFor mints the revision a terminal will send back to us.
func posRevisionFor(locationID int, at time.Time) string {
return fmt.Sprintf("loc%d-%s", locationID, at.UTC().Format(posRevisionLayout))
}
// posRevisionCutoff reads the timestamp back out of a revision.
//
// Returns the zero time when the revision is missing, malformed, or belongs to
// a different outlet — and a zero cutoff means "send everything". Falling back
// to a full snapshot is the only safe direction: answering an unreadable
// revision with a *delta* would leave the terminal quietly missing every change
// it had not already seen, with nothing to indicate it.
func posRevisionCutoff(locationID int, revision string) time.Time {
revision = strings.TrimSpace(revision)
prefix := fmt.Sprintf("loc%d-", locationID)
if !strings.HasPrefix(revision, prefix) {
return time.Time{}
}
at, err := time.Parse(posRevisionLayout, strings.TrimPrefix(revision, prefix))
if err != nil {
return time.Time{}
}
return at
}
// Catalogue answers a terminal's pull, as a snapshot or as a change set.
//
// ### The rule this function exists to keep
//
// A response with `is_delta: false` is treated as a full snapshot, and the
// terminal **withdraws every product the response does not mention**. So a
// filtered result labelled `false` empties the shop's shelf.
//
// The two are therefore decided together, from one value: a zero cutoff means
// no filter and `is_delta: false`; a non-zero cutoff means filtered and
// `is_delta: true`. There is no path through this function that filters without
// also setting the flag.
//
// ### What counts as a change
//
// A product is included when any of three things moved since the cutoff: the
// product row itself (name, tax, brand), its row at this location (price,
// availability), or its stock ledger. Stock is included because a shop's count
// drifts from the till's on every sale rung elsewhere, and a delta that omitted
// it would let that drift persist until someone forced a full pull.
//
// ### What a delta cannot do
//
// A product *deleted* from productlocations leaves no tombstone, so a change set
// cannot know to withdraw it. Only a full snapshot collects those. A terminal
// should pull without a revision periodically — the morning import is the
// natural moment — and this is why.
func (r *posRepository) Catalogue(storeID, since string, page, pageSize int) (*models.PosCatalogueResponse, error) {
ctx, err := r.resolvePosStore(storeID)
if err != nil {
return nil, err
}
if pageSize <= 0 || pageSize > 1000 {
pageSize = 500
}
if page < 0 {
page = 0
}
// The single decision. Everything downstream reads this rather than
// re-deriving it, so the filter and the flag cannot disagree.
cutoff := posRevisionCutoff(ctx.Locationid, since)
isDelta := !cutoff.IsZero()
type row struct {
Productid int
Productname string
Productsku string
Categoryname string
Productunit string
Productbrand string
Price float64
Retailprice float64
Taxpercent float64
Stock float64
Status string
}
// A product counts as changed if the product row, its row at this location,
// or its stock ledger moved. Written as one predicate so a delta cannot
// miss a price change simply because the product row was untouched.
changed := ""
params := []interface{}{ctx.Tenantid, ctx.Locationid}
if isDelta {
changed = `AND (
a.updated >= ?
OR b.updated >= ?
OR EXISTS (SELECT 1 FROM productstocks s2
WHERE s2.productid = a.productid AND s2.tenantid = a.tenantid
AND s2.locationid = b.locationid
AND (s2.stockdate >= ? OR s2.updated >= ?))
)`
params = append(params, cutoff, cutoff, cutoff, cutoff)
}
rows := make([]row, 0)
query := fmt.Sprintf(`
SELECT a.productid,
COALESCE(a.productname, '') AS productname,
COALESCE(a.productsku, '') AS productsku,
COALESCE(c.categoryname, '') AS categoryname,
COALESCE(a.productunit, '') AS productunit,
COALESCE(a.productbrand, '') AS productbrand,
CASE WHEN COALESCE(b.price, 0) > 0 THEN b.price ELSE COALESCE(a.retailprice, 0) END AS price,
COALESCE(a.retailprice, 0) AS retailprice,
COALESCE(a.taxpercent, 0) AS taxpercent,
COALESCE((
SELECT SUM(CASE WHEN LOWER(s.stocktype) = 'in' THEN s.quantity ELSE 0 END) -
SUM(CASE WHEN LOWER(s.stocktype) = 'out' THEN s.quantity ELSE 0 END)
FROM productstocks s
WHERE s.productid = a.productid AND s.tenantid = a.tenantid AND s.locationid = b.locationid
), 0) AS stock,
COALESCE(b.status, '') AS status
FROM products a
INNER JOIN productlocations b ON a.productid = b.productid AND a.tenantid = b.tenantid
LEFT JOIN productcategories c ON a.categoryid = c.categoryid
WHERE a.tenantid = ? AND b.locationid = ? AND a.productid > 0 %s
ORDER BY a.productid
LIMIT ? OFFSET ?`, changed)
// One row past the page, purely so has_more can be answered without a
// second count query.
params = append(params, pageSize+1, page*pageSize)
if err := r.db.Raw(query, params...).Scan(&rows).Error; err != nil {
return nil, err
}
// One row beyond the page was requested purely to answer has_more without a
// second count query.
hasMore := len(rows) > pageSize
if hasMore {
rows = rows[:pageSize]
}
products := make([]models.PosCatalogueProduct, 0, len(rows))
for _, p := range rows {
// Rows with productid <= 0 are excluded in SQL rather than here. Live
// data has at least one — almost certainly an insert that never got a
// sequence value — and it can never be billed, because the ingest
// refuses any line whose id is not positive. Filtering it in the query
// also keeps pagination exact: skipped after the LIMIT, it would eat a
// slot and hand back a short page.
mrp := p.Retailprice
if mrp <= p.Price {
mrp = 0
}
// Indian GST is 0/5/12/18/28, but the column holds 3, 4, 6, 7, 9, 10,
// 15 and even -1 across live data. A negative rate would put negative
// tax on a bill and a negative figure in a slab on a filed return, so
// it is floored here rather than trusted.
gstRate := p.Taxpercent / 100
if gstRate < 0 {
gstRate = 0
}
// Withdrawn from sale when there is no selling price. Neither
// productlocations.price nor retailprice is set on much of the estate —
// only productcost is — and a till that can ring an item up at ₹0 is
// worse than one that cannot ring it up at all. Pricing the product
// makes it sellable; nothing here needs changing.
sellable := p.Price > 0 &&
!strings.EqualFold(strings.TrimSpace(p.Status), "outofstock")
products = append(products, models.PosCatalogueProduct{
Id: strconv.Itoa(p.Productid),
Name: p.Productname,
Barcode: posBarcode(p.Productid, p.Productsku),
Sku: p.Productsku,
Category: posCategory(p.Categoryname),
Price: p.Price,
Mrp: mrp,
Stock: p.Stock,
Unit: posUnit(p.Productunit),
Gstrate: gstRate,
Brand: p.Productbrand,
Isactive: sellable,
})
}
// The revision only advances on the final page.
//
// A terminal that gives up half way through a paginated pull — a dropped
// connection, a till switched off — must not be left holding a revision
// that claims it has seen pages it never received. Every one of those
// products would then be excluded from the next delta and stay stale
// indefinitely, with nothing anywhere to indicate it.
//
// So mid-pull we echo back whatever the terminal already had: unchanged if
// it sent one, empty if it did not, and empty means the next pull is a full
// snapshot. Both are recoverable; a prematurely advanced revision is not.
//
// The stamp is taken a second in the past. A product written during the
// same second this query ran could otherwise land on the wrong side of the
// next cutoff and be skipped for good — overlapping by a second costs one
// redundant row and cannot lose one.
revision := strings.TrimSpace(since)
if !hasMore {
revision = posRevisionFor(ctx.Locationid, time.Now().Add(-time.Second))
}
return &models.PosCatalogueResponse{
Revision: revision,
// Decided with the filter, never separately. False here would tell the
// terminal to withdraw every product this response omits.
Isdelta: isDelta,
Hasmore: hasMore,
Products: products,
Customers: make([]models.PosCatalogueCustomer, 0),
// A product deleted from productlocations leaves no tombstone, so a
// change set cannot know to withdraw it. Only a full snapshot collects
// those, which is why a terminal should pull without a revision
// periodically.
Retiredids: make([]string, 0),
}, nil
}
// posBarcode decides what the till scans this product by.
//
// The terminal holds a **unique** index on barcode, so whatever this returns has
// to be distinct across the whole catalogue or the import fails outright.
//
// `products.productsku` cannot be trusted for that. Measured against live data:
// 6,245 products carry only 93 distinct SKUs, and the single value "1" is used
// by 5,794 of them. Mapping SKU straight to barcode would collapse most of the
// catalogue onto one row.
//
// So a SKU is used only when it looks like a real scannable code — 8 to 14
// digits, the shape of an EAN-8, UPC-A or EAN-13 — and otherwise the product id
// stands in. The id is unique by construction, which keeps the import working
// today; the day real barcodes are populated, scanning starts working on its own
// with no change here.
//
// Until then, scanning a physical barcode at the till will not find anything.
// That is a data problem, not a code one.
func posBarcode(productID int, sku string) string {
sku = strings.TrimSpace(sku)
if len(sku) >= 8 && len(sku) <= 14 {
digitsOnly := true
for _, r := range sku {
if r < '0' || r > '9' {
digitsOnly = false
break
}
}
if digitsOnly {
return sku
}
}
return strconv.Itoa(productID)
}
// posCategory maps a category name onto one of the terminal's fixed buckets.
//
// The till ships a closed enum, so anything unrecognised has to land somewhere;
// grocery is the catch-all it already uses for uncategorised stock.
func posCategory(name string) string {
switch strings.ToLower(strings.TrimSpace(name)) {
case "dairy":
return "dairy"
case "fruits", "fruit":
return "fruits"
case "vegetables", "vegetable":
return "vegetables"
case "beverages", "beverage", "drinks":
return "beverages"
case "snacks", "snack":
return "snacks"
case "personal care", "personalcare":
return "personalCare"
case "household", "home care", "homecare":
return "household"
default:
return "grocery"
}
}
// posUnit maps a unit of measure onto the terminal's enum, defaulting to pieces.
func posUnit(unit string) string {
switch strings.ToLower(strings.TrimSpace(unit)) {
case "kg", "kilogram", "kilo":
return "kilogram"
case "g", "gram", "grams":
return "gram"
case "l", "litre", "liter":
return "litre"
case "ml", "millilitre", "milliliter":
return "millilitre"
case "pack", "packet":
return "pack"
default:
return "piece"
}
}

253
repositories/posRepository_test.go Normal file
View File

@@ -0,0 +1,253 @@
package repositories
import (
"testing"
"time"
)
// The terminal holds a unique index on barcode, so this rule decides whether a
// catalogue import succeeds at all. Measured against live data when it was
// written: 6,245 products, 93 distinct SKUs, and "1" used by 5,794 of them.
func TestPosBarcodeFallsBackToProductIdWhenTheSkuIsNotScannable(t *testing.T) {
cases := []struct {
name string
productID int
sku string
want string
}{
{"the SKU almost every product shares", 844, "1", "844"},
{"blank SKU", 845, "", "845"},
{"whitespace only", 846, " ", "846"},
{"too short to be a barcode", 847, "1234567", "847"},
{"too long to be a barcode", 848, "123456789012345", "848"},
{"not digits", 849, "SKU-ABC-123", "849"},
{"digits with a space", 850, "1234 5678", "850"},
// Real scannable codes are used as-is, so the day the catalogue carries
// them scanning starts working with no code change.
{"EAN-8", 851, "12345678", "12345678"},
{"UPC-A", 852, "012345678905", "012345678905"},
{"EAN-13", 853, "8901030865278", "8901030865278"},
{"padded EAN-13", 854, " 8901030865278 ", "8901030865278"},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
if got := posBarcode(c.productID, c.sku); got != c.want {
t.Errorf("posBarcode(%d, %q) = %q, want %q", c.productID, c.sku, got, c.want)
}
})
}
}
func TestPosBarcodesAreUniqueAcrossACatalogueOfSharedSkus(t *testing.T) {
// The failure this exists to prevent: a whole catalogue collapsing onto one
// barcode and the import being rejected by the terminal's unique index.
seen := make(map[string]int)
for id := 844; id < 844+500; id++ {
barcode := posBarcode(id, "1")
if first, clash := seen[barcode]; clash {
t.Fatalf("products %d and %d both produced barcode %q", first, id, barcode)
}
seen[barcode] = id
}
}
func TestRoundStockQtyNeverUnderDeducts(t *testing.T) {
// productstocks.quantity is an integer column and a counter sells 1.5 kg of
// onions. Rounding up keeps recorded stock at or below what is on the shelf;
// truncating would let the shop oversell a little more with every sale.
cases := []struct {
quantity float64
want int
}{
{1, 1},
{1.5, 2},
{0.25, 1},
{2.0, 2},
{2.01, 3},
{0, 1},
{-1, 1},
}
for _, c := range cases {
if got := roundStockQty(c.quantity); got != c.want {
t.Errorf("roundStockQty(%g) = %d, want %d", c.quantity, got, c.want)
}
}
}
func TestLegacyOrderQtyIsUnchanged(t *testing.T) {
// App orders have always truncated, and that behaviour is deliberately
// preserved rather than corrected — changing it would silently alter stock
// deduction for every order already flowing through createOrderTx.
cases := []struct {
quantity float64
want int
}{
{1, 1},
{1.5, 1},
{0.5, 1},
{3.9, 3},
{0, 1},
}
for _, c := range cases {
if got := legacyOrderQty(c.quantity); got != c.want {
t.Errorf("legacyOrderQty(%g) = %d, want %d", c.quantity, got, c.want)
}
}
}
// A catalogue revision is the terminal's memory of when it last pulled. If it
// does not survive a round trip, every pull silently becomes a full snapshot —
// or worse, a filtered result gets labelled as one and the shop's shelf empties.
func TestPosRevisionRoundTrips(t *testing.T) {
at := time.Date(2026, 8, 3, 12, 30, 45, 0, time.UTC)
revision := posRevisionFor(1135, at)
if revision != "loc1135-20260803T123045Z" {
t.Fatalf("revision = %q, want loc1135-20260803T123045Z", revision)
}
got := posRevisionCutoff(1135, revision)
if !got.Equal(at) {
t.Errorf("cutoff = %v, want %v", got, at)
}
}
func TestAnUnusableRevisionFallsBackToAFullSnapshot(t *testing.T) {
// A zero cutoff means "send everything", and the caller turns that into
// is_delta:false. Falling back the other way — answering an unreadable
// revision with a change set — would leave a terminal permanently missing
// every change it had not already seen, with nothing to show for it.
cases := []struct {
name string
location int
revision string
}{
{"empty", 1135, ""},
{"whitespace", 1135, " "},
{"no prefix", 1135, "20260803T123045Z"},
{"malformed timestamp", 1135, "loc1135-not-a-time"},
{"truncated timestamp", 1135, "loc1135-20260803"},
{"another outlet's revision", 1135, "loc1097-20260803T123045Z"},
{"prefix collision", 113, "loc1135-20260803T123045Z"},
{"garbage", 1135, "../../etc/passwd"},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
if got := posRevisionCutoff(c.location, c.revision); !got.IsZero() {
t.Errorf("cutoff = %v, want zero (full snapshot) for %q", got, c.revision)
}
})
}
}
func TestAnOutletCannotReplayAnotherOutletsRevision(t *testing.T) {
// loc1135 and loc113 share a textual prefix. Matching loosely would let one
// shop's cutoff silently scope another shop's delta.
at := time.Date(2026, 8, 3, 12, 30, 45, 0, time.UTC)
revision := posRevisionFor(1135, at)
if got := posRevisionCutoff(1135, revision); got.IsZero() {
t.Error("the issuing outlet could not read back its own revision")
}
for _, other := range []int{113, 11350, 1097, 1} {
if got := posRevisionCutoff(other, revision); !got.IsZero() {
t.Errorf("outlet %d accepted outlet 1135's revision (cutoff %v)", other, got)
}
}
}
// The bug this covers reached production and stayed invisible for a day.
//
// The MQTT consumer backfills a missing terminal code from the topic, but it
// wrote it onto the *batch* while the row was built from the *order*, so the
// two never met. Bills arriving over HTTP had no topic to fall back on at all.
// The result: 16 of 17 live bills carried an empty terminalid while their own
// invoice numbers read INV-2608-T5EDD-000NN, and `byterminal` on the sales
// summary grouped almost everything under "".
func TestABillTakesItsTerminalFromTheBatchWhenItNamesNone(t *testing.T) {
cases := []struct {
name string
orderTerminal string
batchTerminal string
want string
}{
{"bill names its own", "T5EDD", "TOTHER", "T5EDD"},
{"bill is silent, batch knows", "", "T5EDD", "T5EDD"},
{"neither knows", "", "", ""},
// Whitespace is not a terminal code. Treating it as one would file
// bills under a blank that reads identically to the missing value
// this fallback exists to prevent.
{"bill sends whitespace", " ", "T5EDD", "T5EDD"},
{"batch sends whitespace", "", " ", ""},
{"codes are trimmed", " T5EDD ", "", "T5EDD"},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
if got := posTerminalFor(c.orderTerminal, c.batchTerminal); got != c.want {
t.Errorf("posTerminalFor(%q, %q) = %q, want %q",
c.orderTerminal, c.batchTerminal, got, c.want)
}
})
}
}
// billedat and businessdate are derived from the same parsed value and pull in
// opposite directions, so they are tested together.
//
// Live bill INV-2608-T5EDD-00116 carried billedat 2026-08-05T12:49:28Z beside
// receivedat 2026-08-05T07:19:28Z — the sale appearing to happen five and a
// half hours after it was received. The till was sending a naive local
// timestamp and time.Parse fills that silence with UTC, so a Coimbatore wall
// clock was recorded as though read in London.
//
// The daily figures survived it by luck: businessdate comes off the wall clock
// either way, and the wall clock was always the till's own. Anything comparing
// billedat against real time did not.
func TestASaleDateKeepsBothTheInstantAndTheTradingDay(t *testing.T) {
// Coimbatore, late enough that UTC has not yet rolled into the same day.
const ist = "2026-08-05T00:30:00+05:30"
at, err := parsePosSaleDate(ist)
if err != nil {
t.Fatalf("parsePosSaleDate(%q) errored: %v", ist, err)
}
// The instant. 00:30 IST is 19:00 UTC the previous evening.
wantInstant := time.Date(2026, 8, 4, 19, 0, 0, 0, time.UTC)
if !at.UTC().Equal(wantInstant) {
t.Errorf("instant = %v, want %v", at.UTC(), wantInstant)
}
// The trading day. This is the one that must NOT follow UTC — the shop rang
// this sale on the 5th and its takings belong to the 5th. Deriving the
// business date from UTC would file it under the 4th and leave two days
// wrong: one short, one over.
if got := at.Format("2006-01-02"); got != "2026-08-05" {
t.Errorf("businessdate = %s, want 2026-08-05 — the till's own day", got)
}
}
// Terminals built before the offset was added send a bare local timestamp, and
// they are still in the field. Parsing must not start refusing them.
//
// The instant such a bill records is wrong by the offset and cannot be
// recovered — there is nothing in the payload that says which zone it was read
// in. Its business date is still right, which is why the daily figures held up,
// and why this stays a tolerated legacy rather than a rejection.
func TestANaiveSaleDateIsStillAccepted(t *testing.T) {
at, err := parsePosSaleDate("2026-08-05T12:49:28.245")
if err != nil {
t.Fatalf("a pre-offset terminal must not be refused: %v", err)
}
if got := at.Format("2006-01-02"); got != "2026-08-05" {
t.Errorf("businessdate = %s, want 2026-08-05", got)
}
}

223
repositories/posSalesRepository.go Normal file
View File

@@ -0,0 +1,223 @@
package repositories
import (
"fmt"
"strings"
"nearle/models"
)
// Reading counter sales back out.
//
// The ingest side of this package only ever writes. Without these, a bill that
// reached pos_orders was invisible to every screen in the product — the data
// was safe and unreachable, which is its own kind of lost.
//
// Every query is scoped to one locationid. That is the authorisation boundary:
// a caller who omits it gets an error rather than a page through somebody
// else's takings.
// posSalesWhere builds the shared filter, so the list, the detail and the
// summary can never disagree about what "this outlet in this range" means.
func posSalesWhere(f models.PosSalesFilter) (string, []interface{}) {
where := "locationid = ?"
params := []interface{}{f.Locationid}
// Matched on 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.
if f.Fromdate != "" && f.Todate != "" {
where += " AND businessdate BETWEEN ? AND ?"
params = append(params, f.Fromdate, f.Todate)
} else if f.Fromdate != "" {
where += " AND businessdate >= ?"
params = append(params, f.Fromdate)
} else if f.Todate != "" {
where += " AND businessdate <= ?"
params = append(params, f.Todate)
}
if t := strings.TrimSpace(f.Terminalid); t != "" {
where += " AND terminalid = ?"
params = append(params, t)
}
if c := strings.TrimSpace(f.Cashiername); c != "" {
where += " AND cashiername = ?"
params = append(params, c)
}
if p := strings.TrimSpace(f.Paymentmode); p != "" {
where += " AND LOWER(paymentmode) = ?"
params = append(params, strings.ToLower(p))
}
return where, params
}
// Sales returns a page of bills, newest first, with the total count.
//
// Line items are deliberately not included: a page of fifty bills would drag
// several hundred rows behind it, and a list screen shows none of them. Use
// SaleDetail for one bill.
func (r *posRepository) Sales(f models.PosSalesFilter) (*models.PosSalesPage, error) {
if f.Locationid <= 0 {
return nil, fmt.Errorf("locationid is required")
}
if f.Pagesize <= 0 || f.Pagesize > 500 {
f.Pagesize = 50
}
if f.Pageno < 0 {
f.Pageno = 0
}
where, params := posSalesWhere(f)
var total int64
if err := r.db.Raw(
fmt.Sprintf(`SELECT COUNT(*) FROM pos_orders WHERE %s`, where),
params...,
).Scan(&total).Error; err != nil {
return nil, err
}
bills := make([]models.PosOrders, 0)
// Ordered by billedat rather than by id: a batch uploaded after an outage
// arrives out of order, and a list sorted by arrival would interleave
// yesterday's bills through today's.
query := fmt.Sprintf(
`SELECT * FROM pos_orders WHERE %s
ORDER BY billedat DESC, posorderid DESC
LIMIT ? OFFSET ?`, where)
if err := r.db.Raw(query,
append(params, f.Pagesize, f.Pageno*f.Pagesize)...,
).Scan(&bills).Error; err != nil {
return nil, err
}
return &models.PosSalesPage{
Total: total,
Pageno: f.Pageno,
Pagesize: f.Pagesize,
Bills: bills,
}, nil
}
// SaleDetail returns one bill with its lines.
//
// Accepts either the terminal's own order UUID or this backend's posorderid,
// because a support call starts from whichever the caller happens to be looking
// at — a receipt carries the invoice number, a log carries the UUID.
func (r *posRepository) SaleDetail(locationID int, reference string) (*models.PosOrders, error) {
if locationID <= 0 {
return nil, fmt.Errorf("locationid is required")
}
reference = strings.TrimSpace(reference)
if reference == "" {
return nil, fmt.Errorf("an order id, invoice number or posorderid is required")
}
var bill models.PosOrders
err := r.db.Raw(`
SELECT * FROM pos_orders
WHERE locationid = ?
AND (terminalorderid = ? OR invoicenumber = ?
OR CAST(posorderid AS TEXT) = ?)
LIMIT 1`,
locationID, reference, reference, reference,
).Scan(&bill).Error
if err != nil {
return nil, err
}
if bill.Posorderid == 0 {
return nil, nil
}
items := make([]models.PosOrderItems, 0)
if err := r.db.Raw(
`SELECT * FROM pos_order_items WHERE posorderid = ? ORDER BY posorderitemid`,
bill.Posorderid,
).Scan(&items).Error; err != nil {
return nil, err
}
bill.Items = items
return &bill, nil
}
// SalesSummary totals a range, broken out the three ways somebody actually
// asks for: by tender, by day, and by till.
func (r *posRepository) SalesSummary(f models.PosSalesFilter) (*models.PosSalesSummary, error) {
if f.Locationid <= 0 {
return nil, fmt.Errorf("locationid is required")
}
where, params := posSalesWhere(f)
summary := &models.PosSalesSummary{
Locationid: f.Locationid,
Fromdate: f.Fromdate,
Todate: f.Todate,
Bypaymentmode: make([]models.PosPaymentTotal, 0),
Byday: make([]models.PosDayTotal, 0),
Byterminal: make([]models.PosTerminalTotal, 0),
}
var head struct {
Billcount int
Itemcount int
Grosssales float64
Taxcollected float64
Discount float64
Roundoff float64
}
if err := r.db.Raw(fmt.Sprintf(`
SELECT COUNT(*) AS billcount,
COALESCE(SUM(itemcount), 0) AS itemcount,
COALESCE(SUM(total), 0) AS grosssales,
COALESCE(SUM(taxamount), 0) AS taxcollected,
COALESCE(SUM(discount), 0) AS discount,
COALESCE(SUM(roundoff), 0) AS roundoff
FROM pos_orders WHERE %s`, where), params...).Scan(&head).Error; err != nil {
return nil, err
}
summary.Billcount = head.Billcount
summary.Itemcount = head.Itemcount
summary.Grosssales = head.Grosssales
summary.Taxcollected = head.Taxcollected
summary.Discount = head.Discount
summary.Roundoff = head.Roundoff
if head.Billcount > 0 {
summary.Averagebill = head.Grosssales / float64(head.Billcount)
}
if err := r.db.Raw(fmt.Sprintf(`
SELECT COALESCE(paymentmode,'') AS paymentmode,
COUNT(*) AS billcount, COALESCE(SUM(total),0) AS amount
FROM pos_orders WHERE %s
GROUP BY paymentmode ORDER BY amount DESC`, where),
params...).Scan(&summary.Bypaymentmode).Error; err != nil {
return nil, err
}
if err := r.db.Raw(fmt.Sprintf(`
SELECT businessdate, COUNT(*) AS billcount,
COALESCE(SUM(total),0) AS amount
FROM pos_orders WHERE %s
GROUP BY businessdate ORDER BY businessdate`, where),
params...).Scan(&summary.Byday).Error; err != nil {
return nil, err
}
if err := r.db.Raw(fmt.Sprintf(`
SELECT COALESCE(terminalid,'') AS terminalid, COUNT(*) AS billcount,
COALESCE(SUM(total),0) AS amount
FROM pos_orders WHERE %s
GROUP BY terminalid ORDER BY amount DESC`, where),
params...).Scan(&summary.Byterminal).Error; err != nil {
return nil, err
}
return summary, nil
}

340
repositories/productRepository.go
View File

@@ -22,13 +22,14 @@ type ProductRepository interface {
GetProductStocks(tenantID, locationID string) ([]models.Productstocks, error)
CreateProductStock(stocks []models.Productstock) error
UpdateProductStatus(productIDs []int, status string) error
ReactivateProductLocations(refs []models.ProductLocationRef) error
SyncProductLocationStatus(refs []models.ProductLocationRef) error
CreateProduct(product models.Products) error
UpdateProduct(product models.Products) error
DeleteProduct(productID int) error
GetStockStatement(tenantID, locationID, subcategoryID, pageno, pagesize int, keyword string) ([]models.Productstockstatement, error)
GetLocationProducts(tenantID, locationID, subcategoryID, pageno, pagesize int, keyword string) ([]models.Locationproducts, error)
GetLocationProductSummary(tenantID, locationID int) ([]models.ProductSummary, error)
GetSaleTemplate(tenantID, locationID int) (*models.SaleTemplate, error)
FetchFilteredProducts(categoryID, subcategoryID, productID, applocationID, tenantID, locationID int, keyword, productStatus, approve string, pageno, pagesize int) ([]models.Tenantproducts, error)
GetProductByVariant(tenantid, variantid, locationid int) ([]models.Products, error)
GetSubcategories(categoryID int) ([]models.Subcategory, error)
@@ -88,12 +89,29 @@ func (r *productRepository) GetProductSubCategory(categoryID, tenantID int) ([]m
func (r *productRepository) GetProductCount(tenantid, categoryid, subcategory int, approve string) ([]models.Productcount, error) {
var data []models.Productcount
// available/outofstock are counted from the ledger, not from
// products.productstatus. That column is a lifecycle field ("Active" /
// "Inactive") that a bug in the stock-receipt path used to overwrite with
// availability values, so counting it returned near-nonsense: of 6245
// products it matched 'available' on 136 and 'outofstock' on 12, with the
// rest — the real answer — invisible under "Active".
//
// A product counts as available when it holds positive stock at any one of
// the tenant's outlets, which is the only sensible tenant-wide reading of a
// quantity that is really per-outlet. total = available + outofstock.
baseQuery := `
SELECT
SELECT
COUNT(*) AS total,
SUM(CASE WHEN a.productstatus = 'available' THEN 1 ELSE 0 END) AS available,
SUM(CASE WHEN a.productstatus = 'outofstock' THEN 1 ELSE 0 END) AS outofstock
SUM(CASE WHEN COALESCE(s.balance, 0) > 0 THEN 1 ELSE 0 END) AS available,
SUM(CASE WHEN COALESCE(s.balance, 0) <= 0 THEN 1 ELSE 0 END) AS outofstock
FROM products a
LEFT JOIN (
SELECT productid, tenantid,
SUM(CASE WHEN LOWER(stocktype) = 'in' THEN quantity ELSE 0 END) -
SUM(CASE WHEN LOWER(stocktype) = 'out' THEN quantity ELSE 0 END) AS balance
FROM productstocks
GROUP BY productid, tenantid
) s ON s.productid = a.productid AND s.tenantid = a.tenantid
WHERE 1 = 1
`
@@ -222,16 +240,27 @@ func (r *productRepository) GetProductStocks(tenantID, locationID string) ([]mod
var params []interface{}
var conditions []string
// One row per product+location holding the live balance, so every
// per-ledger-row column has to be aggregated: this rolls up many
// productstocks rows and Postgres rejects a bare a.tenantid/a.stocktype
// under GROUP BY a.productid (that alone made this endpoint return a
// 42803 error instead of any stock at all).
//
// stocktype is matched case-insensitively because the ledger holds a mix
// of 'in' and 'IN' in production — a bare = 'in' silently dropped every
// uppercase receipt, which understated stock rather than erroring.
query := `
SELECT
a.productid, a.tenantid, MAX(a.stockdate) AS stockdate, a.locationid, a.stocktype, a.maxquantity, a.minquantity, a.status,
a.productid, a.tenantid, a.locationid, MAX(a.stockdate) AS stockdate,
MAX(a.stocktype) AS stocktype, MAX(a.maxquantity) AS maxquantity,
MAX(a.minquantity) AS minquantity, MAX(a.status) AS status,
b.applocationid, b.categoryid, b.subcategoryid, b.catalogueid, b.addonid, b.discountid, b.pricingid,
b.productname, b.productimage, b.productdesc, b.productsku, b.brandid, b.productbrand, b.productunit,
b.unitvalue, b.toppicks, b.productcost, b.taxamount, b.taxpercent, b.producttax, b.productstock,
b.productcombo, b.variants, b.retailprice, b.diffprice, b.diffpercent, b.othercost, b.approve,
b.productstatus, b.created, b.updated, c.subcatname AS subcategoryname,
SUM(CASE WHEN a.stocktype = 'in' THEN a.quantity ELSE 0 END) -
SUM(CASE WHEN a.stocktype = 'out' THEN a.quantity ELSE 0 END) AS quantity
SUM(CASE WHEN LOWER(a.stocktype) = 'in' THEN a.quantity ELSE 0 END) -
SUM(CASE WHEN LOWER(a.stocktype) = 'out' THEN a.quantity ELSE 0 END) AS quantity
FROM productstocks a
JOIN products b ON a.productid = b.productid
INNER JOIN productsubcategories c ON c.subcatid = b.subcategoryid
@@ -251,7 +280,8 @@ func (r *productRepository) GetProductStocks(tenantID, locationID string) ([]mod
query += " WHERE " + strings.Join(conditions, " AND ")
}
query += " GROUP BY a.productid"
// b.* / c.* ride along on the primary keys' functional dependency.
query += " GROUP BY a.productid, a.tenantid, a.locationid, b.productid, c.subcatid"
if err := r.db.Raw(query, params...).Scan(&stocks).Error; err != nil {
return nil, err
@@ -264,17 +294,32 @@ func (r *productRepository) CreateProductStock(stocks []models.Productstock) err
return r.db.Table("productstocks").Create(&stocks).Error
}
// ReactivateProductLocations flips productlocations.status back to
// "available" for each ref — the counterpart to CreateOrder flagging a
// location "outofstock" when its stock hits zero. Without this, a store
// that runs out and then restocks via an approved stock request stays
// flagged outofstock forever, since receiving stock only ever added to the
// productstocks ledger and never touched this per-location flag.
func (r *productRepository) ReactivateProductLocations(refs []models.ProductLocationRef) error {
// SyncProductLocationStatus recomputes productlocations.status for each ref
// from the productstocks ledger: "available" when the live SUM(in)-SUM(out)
// balance is positive, "outofstock" when it is not.
//
// It replaces an earlier version that flipped the flag to "available"
// unconditionally on any receipt. That left the flag drifting from reality in
// both directions — a receipt that only partly covered a negative balance
// marked the product sellable when it wasn't, and stock that arrived by any
// route the API didn't own (a direct insert, an import) never cleared an
// "outofstock" set by a much earlier order. Deriving the flag instead of
// assuming it means every write path converges on the same answer, and a row
// that has already drifted repairs itself on the next ledger entry.
func (r *productRepository) SyncProductLocationStatus(refs []models.ProductLocationRef) error {
for _, ref := range refs {
if err := r.db.Table("productlocations").
Where("tenantid = ? AND locationid = ? AND productid = ?", ref.Tenantid, ref.Locationid, ref.Productid).
Update("status", "available").Error; err != nil {
if err := r.db.Exec(`
UPDATE productlocations
SET status = CASE WHEN (
SELECT COALESCE(
SUM(CASE WHEN LOWER(stocktype) = 'in' THEN quantity ELSE 0 END) -
SUM(CASE WHEN LOWER(stocktype) = 'out' THEN quantity ELSE 0 END), 0)
FROM productstocks
WHERE productid = ? AND tenantid = ? AND locationid = ?
) > 0 THEN 'available' ELSE 'outofstock' END
WHERE tenantid = ? AND locationid = ? AND productid = ?`,
ref.Productid, ref.Tenantid, ref.Locationid,
ref.Tenantid, ref.Locationid, ref.Productid).Error; err != nil {
return err
}
}
@@ -345,9 +390,14 @@ func (r *productRepository) GetStockStatement(tenantID, locationID, subcategoryI
params := []interface{}{tenantID, locationID}
// opening is the balance carried in from *before* today, so it stops at
// stockdate < CURRENT_DATE. It used to include today (<=), which made it
// arithmetically identical to closing — the Inventory ledger then showed
// the same number in both columns and looked like stock never moved, even
// on days with sales.
query := `SELECT a.productid,a.productname,a.productimage,a.categoryid,a.subcategoryid,a.productunit,a.unitvalue,a.productcost,a.taxpercent,a.taxamount,a.retailprice,b.tenantid,b.locationid,
COALESCE( SUM(CASE WHEN UPPER(c.stocktype) = 'IN' AND c.stockdate::date <= CURRENT_DATE THEN c.quantity ELSE 0 END) -
SUM(CASE WHEN UPPER(c.stocktype) = 'OUT' AND c.stockdate::date <= CURRENT_DATE THEN c.quantity ELSE 0 END),0 )
COALESCE( SUM(CASE WHEN UPPER(c.stocktype) = 'IN' AND c.stockdate::date < CURRENT_DATE THEN c.quantity ELSE 0 END) -
SUM(CASE WHEN UPPER(c.stocktype) = 'OUT' AND c.stockdate::date < CURRENT_DATE THEN c.quantity ELSE 0 END),0 )
AS opening,
COALESCE(SUM(CASE WHEN UPPER(c.stocktype) = 'IN' AND c.stockdate::date = CURRENT_DATE THEN c.quantity ELSE 0 END), 0) AS credit,
COALESCE(SUM(CASE WHEN UPPER(c.stocktype) = 'OUT' AND c.stockdate::date = CURRENT_DATE THEN c.quantity ELSE 0 END), 0) AS debit,
@@ -405,12 +455,30 @@ func (r *productRepository) GetLocationProducts(tenantID, locationID, subcategor
params := []interface{}{tenantID, locationID}
// b.price is the per-store selling price. It has to be selected explicitly:
// a.* only covers products (whose price column is retailprice, the master
// price), so without this the catalogue could never read back a price set
// for this outlet via CreateProductLocation.
// quantity/productstock both alias the same live SUM(in)-SUM(out) balance
// from productstocks — placed after a.* so they overwrite the static,
// never-decremented products.quantity column GORM would otherwise scan
// into Locationproducts.Quantity, which is what made the console's stock
// column look frozen after an order despite CreateOrder recording the
// "out" ledger entry correctly.
// COALESCE so `price` means the same thing here as in GetProducts: the
// effective selling price at this outlet, falling back to the master
// retailprice when the store hasn't set its own. Returning a bare b.price
// reported 0 for any product priced only at tenant level, which the store
// catalogue then rendered as "—".
query := `SELECT a.*, b.productlocationid, b.status,
COALESCE(NULLIF(b.price, 0), a.retailprice, 0) AS price,
COALESCE(SUM(CASE WHEN UPPER(c.stocktype) = 'IN' THEN c.quantity ELSE 0 END), 0) AS total_in,
COALESCE(SUM(CASE WHEN UPPER(c.stocktype) = 'OUT' THEN c.quantity ELSE 0 END), 0) AS total_out,
COALESCE(SUM(CASE WHEN UPPER(c.stocktype) = 'IN' THEN c.quantity ELSE 0 END) -
SUM(CASE WHEN UPPER(c.stocktype) = 'OUT' THEN c.quantity ELSE 0 END), 0) AS productstock
FROM products a
COALESCE(SUM(CASE WHEN UPPER(c.stocktype) = 'IN' THEN c.quantity ELSE 0 END) -
SUM(CASE WHEN UPPER(c.stocktype) = 'OUT' THEN c.quantity ELSE 0 END), 0) AS productstock,
COALESCE(SUM(CASE WHEN UPPER(c.stocktype) = 'IN' THEN c.quantity ELSE 0 END) -
SUM(CASE WHEN UPPER(c.stocktype) = 'OUT' THEN c.quantity ELSE 0 END), 0) AS quantity
FROM products a
INNER JOIN productlocations b ON a.productid = b.productid AND a.tenantid = b.tenantid
LEFT JOIN productstocks c ON a.productid = c.productid AND b.locationid = c.locationid AND a.tenantid = c.tenantid
WHERE a.approve=1 AND a.tenantid = ? AND b.locationid = ?`
@@ -427,7 +495,7 @@ func (r *productRepository) GetLocationProducts(tenantID, locationID, subcategor
query += ` GROUP BY a.productid, a.productname, a.productimage, a.categoryid, a.subcategoryid,
a.productunit, a.productcost, a.taxpercent, a.taxamount, a.retailprice,
b.tenantid, b.locationid, b.productlocationid, b.status
b.tenantid, b.locationid, b.productlocationid, b.status, b.price
ORDER BY a.productid DESC LIMIT ? OFFSET ?`
params = append(params, pagesize, offset)
@@ -441,6 +509,108 @@ func (r *productRepository) GetLocationProducts(tenantID, locationID, subcategor
return data, nil
}
// GetSaleTemplate lists products stocked at a tenant's branches, with each
// one's live ledger balance, so the web app can generate a pre-filled
// offline-sales spreadsheet.
//
// locationID = 0 means "every branch this tenant runs", which is the normal
// case: a merchant with several outlets gets ONE workbook covering all of them,
// with tenantid and locationid stamped on every row. The row's own locationid
// is what later decides which branch a sale is deducted from, so the operator
// never has to pick a store or juggle a file per outlet. Passing a specific
// locationID narrows it to that branch, which is what a store user gets.
//
// It deliberately returns the whole catalogue unpaged — a spreadsheet meant to
// be filled in and handed back is only useful if it contains every product that
// could have been sold.
//
// The balance is the same SUM(in) - SUM(out) expression CreateOrder validates
// against, so the "currentstock" read in the sheet is exactly the number the
// import will check the typed quantity against. LOWER() covers the mixed-case
// stocktype values in production ('out', 'IN', 'in').
//
// The INNER JOIN on tenantlocations is load-bearing: it confines the result to
// branches the tenant actually owns, so a template can never disclose another
// merchant's catalogue even if a stray productlocations row pointed at one.
func (r *productRepository) GetSaleTemplate(tenantID, locationID int) (*models.SaleTemplate, error) {
if tenantID <= 0 {
return nil, errors.New("tenantid is required")
}
if locationID < 0 {
locationID = 0
}
// Only checked when the caller narrowed to one branch. Without it a
// mistyped locationid would silently yield an empty template rather than
// saying the outlet is not theirs.
if locationID > 0 {
var locationName string
err := r.db.Raw(
`SELECT COALESCE(locationname, '') FROM tenantlocations WHERE tenantid = ? AND locationid = ?`,
tenantID, locationID,
).Scan(&locationName).Error
if err != nil {
return nil, err
}
if strings.TrimSpace(locationName) == "" {
return nil, fmt.Errorf("location %d does not belong to tenant %d", locationID, tenantID)
}
}
rows := make([]models.SaleTemplateRow, 0)
query := `
SELECT a.tenantid,
b.locationid,
COALESCE(tl.locationname, '') AS locationname,
a.productid,
a.productname,
COALESCE(a.productunit, '') AS productunit,
COALESCE(a.unitvalue, '') AS unitvalue,
COALESCE(d.categoryname, '') AS categoryname,
COALESCE(SUM(CASE WHEN LOWER(c.stocktype) = 'in' THEN c.quantity ELSE 0 END) -
SUM(CASE WHEN LOWER(c.stocktype) = 'out' THEN c.quantity ELSE 0 END), 0) AS currentstock,
CASE WHEN COALESCE(b.price, 0) > 0 THEN b.price ELSE COALESCE(a.retailprice, 0) END AS price,
COALESCE(a.taxpercent, 0) AS taxpercent
FROM products a
INNER JOIN productlocations b ON a.productid = b.productid AND a.tenantid = b.tenantid
INNER JOIN tenantlocations tl ON tl.locationid = b.locationid AND tl.tenantid = a.tenantid
LEFT JOIN productstocks c
ON a.productid = c.productid AND b.locationid = c.locationid AND a.tenantid = c.tenantid
LEFT JOIN productcategories d ON a.categoryid = d.categoryid
WHERE a.approve = 1 AND a.tenantid = ? AND (? = 0 OR b.locationid = ?)
GROUP BY a.tenantid, b.locationid, tl.locationname, a.productid, a.productname,
a.productunit, a.unitvalue, d.categoryname, b.price, a.retailprice, a.taxpercent
ORDER BY tl.locationname ASC, a.productname ASC`
if err := r.db.Raw(query, tenantID, locationID, locationID).Scan(&rows).Error; err != nil {
return nil, err
}
// Summarised from the rows themselves rather than queried separately, so
// the branch list can never disagree with what the sheet actually contains.
locations := make([]models.SaleTemplateLocation, 0)
seen := make(map[int]int)
for _, row := range rows {
if idx, ok := seen[row.Locationid]; ok {
locations[idx].Productcount++
continue
}
seen[row.Locationid] = len(locations)
locations = append(locations, models.SaleTemplateLocation{
Locationid: row.Locationid,
Locationname: strings.TrimSpace(row.Locationname),
Productcount: 1,
})
}
return &models.SaleTemplate{
Tenantid: tenantID,
Locationid: locationID,
Locations: locations,
Products: rows,
}, nil
}
func (r *productRepository) GetLocationProductSummary(tenantID, locationID int) ([]models.ProductSummary, error) {
data := make([]models.ProductSummary, 0)
@@ -508,30 +678,55 @@ func (r *productRepository) FetchFilteredProducts(
// Build product query
var products []models.Products
// Both derived tables collapse to one row per product before joining, and
// both are scoped by tenant + (optionally) location. Three things were
// wrong here and each one showed up as bad stock in the console:
// • productlocations was joined on productid alone, so a product stocked
// in three outlets came back three times, each row carrying another
// outlet's status.
// • the stock subquery grouped by (productid, locationid) but joined on
// productid only, so a product's quantity was whichever outlet's row
// the planner happened to pair it with — not this outlet's.
// • stocktype was compared case-sensitively against 'in'/'out' while the
// ledger stores a mix of 'in' and 'IN', so uppercase receipts were
// dropped from the balance.
// locationID 0 means "not scoped to an outlet": stock is then the tenant's
// total across outlets, which is what an unscoped listing should show.
query := r.db.
Table("products a").
Select(`
a.*,
a.*,
b.status,
c.categoryname,
b.locationid,
c.categoryname,
d.subcatname AS subcategoryname,
ps.locationid,
COALESCE(ps.quantity, 0) AS productstock,
COALESCE(ps.quantity, 0) AS quantity
`).
Joins("LEFT JOIN productlocations b ON a.productid = b.productid").
Joins(`
LEFT JOIN (
SELECT productid, tenantid,
MAX(locationid) AS locationid,
MAX(status) AS status
FROM productlocations
WHERE (? = 0 OR locationid = ?)
GROUP BY productid, tenantid
) b ON b.productid = a.productid AND b.tenantid = a.tenantid
`, locationID, locationID).
Joins("LEFT JOIN productcategories c ON a.categoryid = c.categoryid").
Joins("LEFT JOIN productsubcategories d ON a.subcategoryid = d.subcatid").
Joins(`
LEFT JOIN (
SELECT
SELECT
productid,
locationid,
SUM(CASE WHEN stocktype = 'in' THEN quantity ELSE 0 END) -
SUM(CASE WHEN stocktype = 'out' THEN quantity ELSE 0 END) AS quantity
tenantid,
SUM(CASE WHEN LOWER(stocktype) = 'in' THEN quantity ELSE 0 END) -
SUM(CASE WHEN LOWER(stocktype) = 'out' THEN quantity ELSE 0 END) AS quantity
FROM productstocks
GROUP BY productid, locationid
) ps ON ps.productid = a.productid
`).
WHERE (? = 0 OR locationid = ?)
GROUP BY productid, tenantid
) ps ON ps.productid = a.productid AND ps.tenantid = a.tenantid
`, locationID, locationID).
Where("a.tenantid = ?", tenantID).
Order("a.productid DESC")
@@ -548,7 +743,13 @@ func (r *productRepository) FetchFilteredProducts(
query = query.Where("a.productstatus = ?", productStatus)
}
if locationID != 0 {
query = query.Where("e.locationid = ?", locationID)
// The outlet scope is already applied inside the productlocations and
// productstocks subqueries above; this only narrows the result to
// products actually carried by that outlet. It used to reference an
// alias `e` that no query in this file defines, so every call that
// passed a locationid failed outright with "missing FROM-clause entry
// for table e" instead of returning products.
query = query.Where("b.locationid = ?", locationID)
}
if approve != "" {
query = query.Where("a.approve = ?", approve)
@@ -589,12 +790,15 @@ func (r *productRepository) GetProductByVariant(tenantid, variantid, locationid
var data []models.Products
// productstock is a correlated subquery (not a JOIN+GROUP BY) so it can
// coexist with `p.*` without having to enumerate every products column.
// When locationid is 0 (caller didn't scope to a store), both the
// subquery and the productlocations join simply match nothing, so
// Productstock/Locationstatus come back zero-valued — same response
// shape as before this field existed, not an error.
// productstock/quantity are correlated subqueries (not a JOIN+GROUP BY) so
// they can coexist with `p.*` without having to enumerate every products
// column. quantity is duplicated on purpose: it's placed after `p.*` so it
// overwrites the static, never-decremented products.quantity column that
// would otherwise scan into Products.Quantity. When locationid is 0
// (caller didn't scope to a store), both subqueries and the
// productlocations join simply match nothing, so
// Productstock/Quantity/Locationstatus come back zero-valued — same
// response shape as before this field existed, not an error.
err := r.db.
Table("products p").
Select(`
@@ -609,8 +813,14 @@ func (r *productRepository) GetProductByVariant(tenantid, variantid, locationid
SUM(CASE WHEN LOWER(ps.stocktype) = 'out' THEN ps.quantity ELSE 0 END)
FROM productstocks ps
WHERE ps.productid = p.productid AND ps.tenantid = p.tenantid AND ps.locationid = ?
), 0) AS productstock
`, locationid).
), 0) AS productstock,
COALESCE((
SELECT SUM(CASE WHEN LOWER(ps.stocktype) = 'in' THEN ps.quantity ELSE 0 END) -
SUM(CASE WHEN LOWER(ps.stocktype) = 'out' THEN ps.quantity ELSE 0 END)
FROM productstocks ps
WHERE ps.productid = p.productid AND ps.tenantid = p.tenantid AND ps.locationid = ?
), 0) AS quantity
`, locationid, locationid).
Joins("LEFT JOIN productcategories c ON p.categoryid = c.categoryid").
Joins("LEFT JOIN productsubcategories d ON p.subcategoryid = d.subcatid").
Joins("LEFT JOIN productdiscounts pd ON pd.productid = p.productid").
@@ -638,7 +848,7 @@ func (r *productRepository) GetProducts(params models.ProductFilter) ([]models.P
var products []models.Products
q := r.db.Table("products a").
Joins("LEFT JOIN productlocations pl ON pl.productid = a.productid").
Joins("LEFT JOIN productlocations pl ON pl.productid = a.productid AND pl.tenantid = a.tenantid").
Joins("LEFT JOIN productdiscounts pd ON pd.productid = a.productid").
Joins("LEFT JOIN productcategories c ON a.categoryid = c.categoryid").
Where("a.categoryid = ?", params.CategoryID)
@@ -664,10 +874,46 @@ func (r *productRepository) GetProducts(params models.ProductFilter) ([]models.P
)
}
// productstock/quantity are correlated subqueries computing the live
// SUM(in)-SUM(out) balance from productstocks, scoped to params.LocationID
// (0 if the caller didn't scope to a store, matching nothing so both come
// back zero). quantity is placed after `a.*` so it overwrites the static,
// never-decremented products.quantity column — same fix as
// GetLocationProducts/GetProductByVariant, otherwise this endpoint would
// keep showing stock that never reduces after an order.
// price is the effective selling price at params.LocationID: the store's own
// productlocations.price, falling back to the master products.retailprice
// when that outlet hasn't set one. It has to be here — this endpoint feeds
// the customer app's browse-by-subcategory view, and `a.*` only carries
// retailprice, which the admin catalogue never writes. So a price the admin
// set per store could never reach the app; every product priced as 0.
//
// Deliberately a correlated subquery rather than a read off the joined `pl`:
// that join isn't outlet-scoped unless params.LocationID is set, so reading
// pl.price directly would pick an arbitrary branch's price (and multiply the
// rows) whenever the caller didn't scope to one. Same shape as the
// productstock subqueries below, for the same reason.
err := q.Select(`
a.*,
COALESCE(pd.discountvalue, 0) AS discountvalue
`).Find(&products).Error
COALESCE(pd.discountvalue, 0) AS discountvalue,
COALESCE(NULLIF((
SELECT pl2.price FROM productlocations pl2
WHERE pl2.productid = a.productid AND pl2.tenantid = a.tenantid AND pl2.locationid = ?
LIMIT 1
), 0), a.retailprice, 0) AS price,
COALESCE((
SELECT SUM(CASE WHEN LOWER(ps.stocktype) = 'in' THEN ps.quantity ELSE 0 END) -
SUM(CASE WHEN LOWER(ps.stocktype) = 'out' THEN ps.quantity ELSE 0 END)
FROM productstocks ps
WHERE ps.productid = a.productid AND ps.tenantid = a.tenantid AND ps.locationid = ?
), 0) AS productstock,
COALESCE((
SELECT SUM(CASE WHEN LOWER(ps.stocktype) = 'in' THEN ps.quantity ELSE 0 END) -
SUM(CASE WHEN LOWER(ps.stocktype) = 'out' THEN ps.quantity ELSE 0 END)
FROM productstocks ps
WHERE ps.productid = a.productid AND ps.tenantid = a.tenantid AND ps.locationid = ?
), 0) AS quantity
`, params.LocationID, params.LocationID, params.LocationID).Find(&products).Error
return products, err
}

182
repositories/stockLedger.go Normal file
View File

@@ -0,0 +1,182 @@
package repositories
import (
"fmt"
"math"
"sort"
"time"
"nearle/models"
"gorm.io/gorm"
)
// Shared stock machinery.
//
// Extracted from createOrderTx so that an order placed in the app and a bill
// rung up at a counter deduct stock through exactly the same code. Two
// implementations of the rule that stops overselling would drift, and the first
// anyone would know about it is a shelf that is empty in the database and full
// in the shop, or the reverse.
//
// None of these commit or roll back — the caller owns the transaction boundary,
// because what should happen to the rest of the work on failure is the caller's
// business, not the ledger's.
// stockLine is the minimum the ledger needs to know about one sold line.
//
// Deliberately not models.OrderDetail: the POS ingest writes its own tables and
// has no OrderDetail to hand, and coupling the ledger to one caller's row type
// is what forced the duplication this file removes.
type stockLine struct {
Productid int
Locationid int
Productname string
// Units sold. Fractional because a counter sells 1.5 kg of onions; the
// ledger itself is integer-only, and roundStockQty explains the gap.
Quantity float64
}
// roundStockQty turns a sold quantity into a ledger quantity.
//
// productstocks.quantity is an integer column, so fractional sales cannot be
// represented exactly. Rounding *up* is the conservative direction: 1.5 kg
// deducts 2, so the recorded stock is never higher than what is physically on
// the shelf. Truncating instead would under-deduct on every fractional sale and
// let the shop oversell a little more each time.
//
// This is a workaround, not a fix. A shop that sells much by weight needs the
// column to be numeric.
func roundStockQty(quantity float64) int {
if quantity <= 0 {
return 1
}
return int(math.Ceil(quantity - 1e-9))
}
// lockStockRows takes a row lock on every (tenant, location, product) the sale
// touches, before anything reads availability.
//
// Without it two concurrent sales of the same product can both read "in stock"
// before either commits its deduction, oversell the item and drive the balance
// negative. Locking productlocations — the row the stock computation is already
// keyed against — serialises conflicting sales instead.
//
// Locks are taken in a fixed (productid, locationid) order so two sales sharing
// products always contend in the same sequence. Without that ordering they
// deadlock against each other rather than merely blocking.
func lockStockRows(tx *gorm.DB, tenantID int, lines []stockLine) error {
type lockTarget struct {
productid int
locationid int
}
seen := make(map[lockTarget]bool, len(lines))
locks := make([]lockTarget, 0, len(lines))
for _, line := range lines {
lt := lockTarget{productid: line.Productid, locationid: line.Locationid}
if !seen[lt] {
seen[lt] = true
locks = append(locks, lt)
}
}
sort.Slice(locks, func(a, b int) bool {
if locks[a].productid != locks[b].productid {
return locks[a].productid < locks[b].productid
}
return locks[a].locationid < locks[b].locationid
})
for _, lt := range locks {
var locked int
const q = `SELECT productlocationid FROM productlocations
WHERE tenantid = ? AND locationid = ? AND productid = ? FOR UPDATE`
if err := tx.Raw(q, tenantID, lt.locationid, lt.productid).Scan(&locked).Error; err != nil {
return fmt.Errorf("failed to lock stock for product %d: %w", lt.productid, err)
}
}
return nil
}
// availableStock is the ledger balance for one product at one location.
func availableStock(tx *gorm.DB, tenantID, locationID, productID int) (int, error) {
var available int
const q = `
SELECT COALESCE(
SUM(CASE WHEN LOWER(stocktype) = 'in' THEN quantity ELSE 0 END) -
SUM(CASE WHEN LOWER(stocktype) = 'out' THEN quantity ELSE 0 END),
0
)
FROM productstocks
WHERE productid = ? AND tenantid = ? AND locationid = ?`
if err := tx.Raw(q, productID, tenantID, locationID).Scan(&available).Error; err != nil {
return 0, fmt.Errorf("failed to verify stock for product %d: %w", productID, err)
}
return available, nil
}
// assertStockAvailable refuses the whole sale if any line cannot be met.
//
// Checked for every line before any is written, so a sale never lands
// half-deducted. Call it only with the locks from lockStockRows already held —
// otherwise the balance it reads can change before the deduction is written.
func assertStockAvailable(tx *gorm.DB, tenantID int, lines []stockLine, qtyOf func(stockLine) int) error {
for _, line := range lines {
available, err := availableStock(tx, tenantID, line.Locationid, line.Productid)
if err != nil {
return err
}
requested := qtyOf(line)
if available < requested {
name := line.Productname
if name == "" {
name = fmt.Sprintf("ID %d", line.Productid)
}
return fmt.Errorf(
"insufficient stock for product '%s': requested %d, available %d",
name, requested, available,
)
}
}
return nil
}
// recordStockOut writes the ledger entry for one sold line and re-derives the
// location's availability flag from the balance it just produced.
func recordStockOut(tx *gorm.DB, tenantID int, line stockLine, quantity int) error {
stock := models.Productstock{
Tenantid: tenantID,
Stockdate: time.Now(),
Locationid: line.Locationid,
Productid: line.Productid,
Quantity: quantity,
Stocktype: "out",
Status: "Active",
}
if err := tx.Table("productstocks").Create(&stock).Error; err != nil {
return err
}
syncProductLocationStatus(tx, tenantID, line.Locationid, line.Productid)
return nil
}
// legacyOrderQty is how createOrderTx has always turned an order quantity into
// a ledger quantity: truncate, then floor at 1.
//
// Preserved exactly rather than corrected, because changing it would silently
// alter stock deduction for every app order in production. It under-deducts a
// fractional line — 1.5 becomes 1 — which is why the POS path uses
// roundStockQty instead. Worth reconciling once someone owns the decision.
func legacyOrderQty(quantity float64) int {
q := int(quantity)
if q <= 0 {
q = 1
}
return q
}

1
routes/orderroutes.go
View File

@@ -24,6 +24,7 @@ func RegisterOrderRoutes(api fiber.Router, f *facade.Facade) {
orders.Get("/getorderdetails", f.OrderController.GetOrderDetails)
orders.Put("/updateorder", f.OrderController.UpdateOrder)
orders.Post("/createorder", f.OrderController.CreateOrderv3)
orders.Post("/uploadofflinesales", f.OrderController.UploadOfflineSales)
reports := api.Group("/v1/web/reports")
reports.Get("/sales-summary", f.OrderController.GetSalesSummary)

42
routes/posroutes.go Normal file
View File

@@ -0,0 +1,42 @@
package routes
import (
"nearle/facade"
"github.com/gofiber/fiber/v2"
)
// Routes for the Nearle POS terminal.
//
// The paths are fixed by the till, which appends `/orders`, `/customers` and
// `/catalogue` to whatever base URL a shop enters in Settings. Set that base to
// this group — `https://your-host/live/api/v1/pos` — and the three line up.
//
// Kept in their own group rather than folded into the order routes because a
// terminal authenticates as a device, not as a signed-in user, and because
// these answer with a bare ack rather than the web app's response envelope.
func RegisterPosRoutes(api fiber.Router, f *facade.Facade) {
pos := api.Group("/v1/pos")
pos.Post("/orders", f.PosController.IngestOrders)
pos.Post("/customers", f.PosController.IngestCustomers)
pos.Get("/catalogue", f.PosController.Catalogue)
// The 30-second heartbeat, for tills on the HTTP route. The broker carries
// the same payload for tills on MQTT; both land in the same Redis record,
// so the fleet board cannot tell them apart and does not need to.
pos.Post("/health", f.PosController.IngestHealth)
// Counter sales, read back out. The ingest above only ever writes; without
// these a committed bill is unreachable from every screen in the product.
pos.Get("/sales", f.PosController.GetSales)
pos.Get("/sales/detail", f.PosController.GetSaleDetail)
pos.Get("/sales/summary", f.PosController.GetSalesSummary)
// Terminal presence, read from Redis. What the rider app's POS board and a
// support call both hit — the tills themselves publish health over the
// broker rather than posting it here.
pos.Get("/health/terminal", f.PosController.TerminalHealth)
pos.Get("/health/location", f.PosController.LocationHealth)
}

1
routes/productroutes.go
View File

@@ -23,6 +23,7 @@ func RegisterProductRoutes(api fiber.Router, f *facade.Facade) {
products.Get("/getstockstatement", f.ProductController.GetStockStatement)
products.Get("/getlocationproducts", f.ProductController.GetLocationProducts)
products.Get("/getlocationproductsummary", f.ProductController.GetLocationProductSummary)
products.Get("/getsaletemplate", f.ProductController.GetSaleTemplate)
products.Get("/getallproducts", f.ProductController.GetAllProducts)
products.Put("/updateproductlocation", f.ProductController.UpdateProductLocation)
products.Post("/createproductlocation", f.ProductController.CreateProductLocation)

1
routes/routes.go
View File

@@ -19,4 +19,5 @@ func RegisterRoutes(app *fiber.App, f *facade.Facade) {
RegisterPartnerRoutes(api, f)
RegisterCustomerRoutes(api, f)
RegisterCatalogueRoutes(api, f)
RegisterPosRoutes(api, f)
}

7
routes/utilsroutes.go
View File

@@ -11,7 +11,12 @@ func RegisterUtilsRoutes(api fiber.Router, f *facade.Facade) {
utils := api.Group("/v1/web/utils")
utils.Get("/getapptypes", f.UtilsController.GetAppTypes)
// utils.Post("/notifyuser", f.UtilsController.NotifyUser)
// Commented out since the initial commit, which meant every rider push the
// admin console has ever sent returned 404 — riders were assigned deliveries
// and never told. The handler, the FcmNotification model, the Firebase
// service account and the Dockerfile COPY that puts it in the image were all
// already in place; only the route was missing.
utils.Post("/notifyuser", f.UtilsController.NotifyUser)
utils.Get("/getsubcategories", f.UtilsController.GetSubcategories)
utils.Get("/getapplocations", f.UtilsController.GetApplocations)
utils.Get("/getappcategories", f.UtilsController.GetAppCategory)

122
scratch/dbinspect/cleanup.go Normal file
View File

@@ -0,0 +1,122 @@
package main
import (
"fmt"
"gorm.io/gorm"
)
// cleanup removes everything the end-to-end proof wrote to the live database.
//
// Three things, in an order that leaves nothing half-undone: the stock the test
// bills consumed is returned, the bills themselves are deleted, and the price
// that was set to make a product sellable goes back to what it was.
//
// The two test bills are named explicitly rather than deleted by date or by
// "everything in pos_orders" — a table that will hold real takings tomorrow is
// not one to run an unbounded DELETE against.
// Every mobile the probes registered, so a cleanup run leaves nothing behind.
var probeMobiles = []string{"9840012345", "9840099999", "9840077777"}
var testOrderIDs = []string{
"11111111-2222-4333-8444-555555555555", // the HTTP probe
"99999999-8888-4777-8666-555555555555", // the MQTT probe
}
func cleanup(db *gorm.DB) {
var billIDs []int
db.Raw(`SELECT posorderid FROM pos_orders WHERE terminalorderid IN ?`,
testOrderIDs).Scan(&billIDs)
if len(billIDs) == 0 {
fmt.Println("no test bills found — nothing to undo")
}
// Stock first. Deleting the bills before returning what they consumed would
// leave the ledger short with nothing left to explain why.
var consumed []struct {
Productid int
Quantity float64
}
db.Raw(`SELECT productid, SUM(quantity) AS quantity
FROM pos_order_items WHERE posorderid IN ?
GROUP BY productid`, billIDs).Scan(&consumed)
for _, c := range consumed {
qty := int(c.Quantity)
if float64(qty) < c.Quantity {
qty++ // the ingest rounded up, so the reversal must too
}
if err := db.Exec(`
INSERT INTO productstocks (tenantid, stockdate, locationid, productid,
quantity, stocktype, status)
VALUES (?, NOW(), ?, ?, ?, 'in', 'Active')`,
tenantID, locationID, c.Productid, qty).Error; err != nil {
fmt.Println(" return stock:", err)
continue
}
fmt.Printf(" returned %d units of product %d\n", qty, c.Productid)
}
if len(billIDs) > 0 {
db.Exec(`DELETE FROM pos_order_items WHERE posorderid IN ?`, billIDs)
db.Exec(`DELETE FROM pos_orders WHERE posorderid IN ?`, billIDs)
fmt.Printf(" deleted %d test bill(s)\n", len(billIDs))
}
db.Exec(`UPDATE productlocations SET price = 0
WHERE tenantid=? AND locationid=? AND productid=?`,
tenantID, locationID, productID)
fmt.Printf(" product %d price restored to 0\n", productID)
// The shopper the probes created. Removed only when nothing references it —
// a customer row attached to a real order is not test data any more.
for _, mobile := range probeMobiles {
// A customer row attached to a real order is not test data any more.
var referenced int
db.Raw(`SELECT COUNT(*) FROM orders WHERE customerid IN
(SELECT customerid FROM customers WHERE contactno = ?)`,
mobile).Scan(&referenced)
if referenced > 0 {
fmt.Printf(" customer %s left in place — %d order(s) reference it\n",
mobile, referenced)
continue
}
res := db.Exec(`DELETE FROM customers WHERE contactno = ?`, mobile)
if res.RowsAffected > 0 {
fmt.Printf(" removed probe customer %s\n", mobile)
}
}
var balance float64
db.Raw(`SELECT COALESCE(
SUM(CASE WHEN LOWER(stocktype)='in' THEN quantity ELSE 0 END) -
SUM(CASE WHEN LOWER(stocktype)='out' THEN quantity ELSE 0 END), 0)
FROM productstocks WHERE tenantid=? AND locationid=? AND productid=?`,
tenantID, locationID, productID).Scan(&balance)
fmt.Printf(" product %d balance back to %.0f\n", productID, balance)
}
// showCustomer reports whether the registration probe reached the customers
// table, and under which id — the question an ack alone cannot answer.
func showCustomer(db *gorm.DB, mobile string) {
var rows []struct {
Customerid int
Firstname string
Contactno string
Applocationid int
}
db.Raw(`SELECT customerid, COALESCE(firstname,'') AS firstname,
COALESCE(contactno,'') AS contactno,
COALESCE(applocationid,0) AS applocationid
FROM customers WHERE contactno = ?`, mobile).Scan(&rows)
if len(rows) == 0 {
fmt.Printf(" no customer with contactno %s\n", mobile)
return
}
for _, r := range rows {
fmt.Printf(" customerid=%d %q contactno=%s applocid=%d\n",
r.Customerid, r.Firstname, r.Contactno, r.Applocationid)
}
}

183
scratch/dbinspect/main.go Normal file
View File

@@ -0,0 +1,183 @@
// End-to-end proof for the POS ingest, against the live database.
//
// Sets a temporary price on ONE product so a bill can be rung, and prints the
// exact SQL to undo it. Everything else is read-only.
//
// go run ./scratch/dbinspect price # set a test price, print the undo
// go run ./scratch/dbinspect verify # show the bill and the stock it moved
// go run ./scratch/dbinspect restore # put the price back
package main
import (
"fmt"
"log"
"os"
"github.com/joho/godotenv"
"gorm.io/driver/postgres"
"gorm.io/gorm"
"gorm.io/gorm/logger"
)
const (
tenantID = 1087
locationID = 1135
productID = 6988 // Mysore Banana — 750 units in stock, 8% tax
testPrice = 60.00
)
func main() {
_ = godotenv.Load()
dsn := fmt.Sprintf(
"host=%s user=%s password=%s dbname=%s port=%s sslmode=disable TimeZone=Asia/Kolkata",
os.Getenv("DB_HOST"), os.Getenv("DB_USER"), os.Getenv("DB_PASSWORD"),
os.Getenv("DB_NAME"), os.Getenv("DB_PORT"),
)
db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
Logger: logger.Default.LogMode(logger.Silent),
})
if err != nil {
log.Fatal("connect:", err)
}
mode := "verify"
if len(os.Args) > 1 {
mode = os.Args[1]
}
switch mode {
case "price":
var before float64
db.Raw(`SELECT COALESCE(price,0) FROM productlocations
WHERE tenantid=? AND locationid=? AND productid=?`,
tenantID, locationID, productID).Scan(&before)
if err := db.Exec(`UPDATE productlocations SET price = ?
WHERE tenantid=? AND locationid=? AND productid=?`,
testPrice, tenantID, locationID, productID).Error; err != nil {
log.Fatal("price:", err)
}
fmt.Printf("product %d priced at %.2f (was %.2f)\n", productID, testPrice, before)
fmt.Printf("\nUNDO:\n UPDATE productlocations SET price = %.2f\n"+
" WHERE tenantid=%d AND locationid=%d AND productid=%d;\n",
before, tenantID, locationID, productID)
case "restore":
if err := db.Exec(`UPDATE productlocations SET price = 0
WHERE tenantid=? AND locationid=? AND productid=?`,
tenantID, locationID, productID).Error; err != nil {
log.Fatal("restore:", err)
}
fmt.Printf("product %d price restored to 0\n", productID)
case "verify":
fmt.Println("=== pos_orders ===")
var bills []struct {
Posorderid int
Terminalorderid string
Invoicenumber string
Terminalid string
Cashiername string
Businessdate string
Subtotal float64
Taxamount float64
Roundoff float64
Total float64
Itemcount int
Paymentmode string
}
db.Raw(`SELECT posorderid, terminalorderid, invoicenumber, terminalid,
cashiername, businessdate, subtotal, taxamount, roundoff,
total, itemcount, paymentmode
FROM pos_orders ORDER BY posorderid DESC LIMIT 5`).Scan(&bills)
if len(bills) == 0 {
fmt.Println(" (none yet)")
}
for _, b := range bills {
fmt.Printf(" #%d %s till=%s cashier=%s date=%s\n",
b.Posorderid, b.Invoicenumber, b.Terminalid, b.Cashiername, b.Businessdate)
fmt.Printf(" uuid=%s\n", b.Terminalorderid)
fmt.Printf(" subtotal=%.2f tax=%.2f roundoff=%.2f total=%.2f items=%d paid=%s\n",
b.Subtotal, b.Taxamount, b.Roundoff, b.Total, b.Itemcount, b.Paymentmode)
}
fmt.Println("\n=== pos_order_items ===")
var items []struct {
Posorderid int
Productid int
Productname string
Quantity float64
Unitprice float64
Gstrate float64
Taxamount float64
Linetotal float64
}
db.Raw(`SELECT posorderid, productid, productname, quantity, unitprice,
gstrate, taxamount, linetotal
FROM pos_order_items ORDER BY posorderitemid DESC LIMIT 10`).Scan(&items)
for _, i := range items {
fmt.Printf(" bill#%d %-18.18s qty=%-6.2f @%-8.2f gst=%-6.2f tax=%-7.2f line=%.2f\n",
i.Posorderid, i.Productname, i.Quantity, i.Unitprice,
i.Gstrate, i.Taxamount, i.Linetotal)
}
fmt.Println("\n=== stock ledger for the test product ===")
var moves []struct {
Productstockid int
Quantity int
Stocktype string
Stockdate string
}
db.Raw(`SELECT productstockid, quantity, stocktype,
TO_CHAR(stockdate,'YYYY-MM-DD HH24:MI:SS') AS stockdate
FROM productstocks
WHERE tenantid=? AND locationid=? AND productid=?
ORDER BY productstockid DESC LIMIT 5`,
tenantID, locationID, productID).Scan(&moves)
for _, m := range moves {
fmt.Printf(" #%d %-4s qty=%-6d %s\n",
m.Productstockid, m.Stocktype, m.Quantity, m.Stockdate)
}
var balance float64
db.Raw(`SELECT COALESCE(
SUM(CASE WHEN LOWER(stocktype)='in' THEN quantity ELSE 0 END) -
SUM(CASE WHEN LOWER(stocktype)='out' THEN quantity ELSE 0 END), 0)
FROM productstocks WHERE tenantid=? AND locationid=? AND productid=?`,
tenantID, locationID, productID).Scan(&balance)
fmt.Printf(" balance now: %.0f\n", balance)
case "cleanup":
cleanup(db)
case "columns":
for _, t := range []string{"products", "productlocations", "productstocks"} {
fmt.Printf("=== %s ===\n", t)
var cols []struct {
ColumnName string
DataType string
}
db.Raw(`SELECT column_name, data_type FROM information_schema.columns
WHERE table_name = ? ORDER BY ordinal_position`, t).Scan(&cols)
for _, c := range cols {
marker := ""
n := c.ColumnName
if n == "created" || n == "updated" || n == "updated_at" ||
n == "stockdate" || n == "modified" {
marker = " <-- timestamp"
}
fmt.Printf(" %-24s %s%s\n", c.ColumnName, c.DataType, marker)
}
}
case "customer":
fmt.Println("=== customers matching the uplink probe ===")
showCustomer(db, "9840012345")
default:
log.Fatalf("unknown mode %q — use price, verify, restore or cleanup", mode)
}
}

180
scratch/gstrates/main.go Normal file
View File

@@ -0,0 +1,180 @@
// Set GST rates on the POS catalogue products.
//
// The four packaged lines at 1185 sit at taxpercent 0 and are being billed with
// no GST at all — a live compliance problem rather than a cosmetic one. Those
// are written.
//
// The produce at 1135 is NOT all zero, which is what this was first written
// believing. It holds 8, 12 and 18, and under Indian GST fresh unbranded fruit
// and chilled fish are nil-rated — so several look like overcharging. Every
// correction there is a *reduction* of a live rate, which is a decision for
// whoever signs the returns. Reported as REVIEW and left untouched.
//
// go run ./scratch/gstrates plan
// go run ./scratch/gstrates apply
package main
import (
"fmt"
"log"
"os"
"github.com/joho/godotenv"
"gorm.io/driver/postgres"
"gorm.io/gorm"
"gorm.io/gorm/logger"
)
// Indian GST on food, as it applies to these lines.
//
// Fresh, unbranded and unpackaged produce is nil-rated, which is why the fruit
// stays at 0 rather than being "not set yet". Packaged branded snacks are 12%.
// Breakfast cereal is 18%.
//
// Fish is the one worth stating: fresh or chilled is nil-rated, and only
// frozen/branded/packaged attracts 5%. Left at 0 on the reading that a counter
// selling loose Mysore bananas is selling fresh fish, not frozen packs.
type rate struct {
productID int
name string
percent float64
why string
// apply gates the write. Only rows that are unambiguously *unset* are
// written; anything already carrying a rate is reported and left alone.
//
// The fresh produce at 1135 is the reason for this flag. Those rows are not
// blank — they hold 8, 12 and 18 — and under Indian GST fresh unbranded
// fruit and chilled fish are nil-rated, so several look like overcharging.
// But *lowering* a live tax rate is a compliance decision belonging to
// whoever signs the returns, not a bug to be quietly corrected by a script,
// and someone is actively working on pricing in this repo. Reported, not
// touched.
apply bool
}
var rates = []rate{
// 1135 — fresh produce, nil-rated under Indian GST.
//
// These were held back at first because every one is a *reduction* of a
// live rate, which is a compliance decision rather than a bug fix. Released
// on the owner's explicit instruction after that was put to them.
//
// Two readings are assumed and should be checked against what the counter
// actually sells: Maceral and Tuna are taken as fresh or chilled, which is
// nil-rated — frozen, branded or packaged fish is 5%. Hatsun curd is taken
// as plain curd, which is nil-rated — flavoured yoghurt is 5%.
{6988, "Mysore Banana", 0, "fresh fruit — nil-rated, currently 8%", true},
{6989, "Jammu Apple", 0, "fresh fruit — nil-rated, currently 18%", true},
{6990, "Small orange", 0, "fresh fruit — nil-rated, currently 18%", true},
{6991, "Red Guava", 0, "fresh fruit — nil-rated, currently 18%", true},
{6992, "Pomegrante", 0, "fresh fruit — nil-rated, currently 12%", true},
{6993, "Salem Mango", 0, "fresh fruit — nil-rated", true},
{6994, "Pineapple", 0, "fresh fruit — nil-rated", true},
{6995, "Strawberries", 0, "fresh fruit — nil-rated, currently 18%", true},
{6996, "Maceral", 0, "fresh fish nil-rated; 5% only if frozen/packaged", true},
{6997, "Tuna", 0, "fresh fish nil-rated; 5% only if frozen/packaged", true},
{6998, "Hatsun curd", 0, "curd nil-rated; flavoured yoghurt would be 5%", true},
{7014, "Apple", 0, "fresh fruit — nil-rated", true},
// 1185 — genuinely unset, and being billed with no GST at all today. This
// is the half that is unambiguous: every one is an increase from zero, so
// nothing is being under-collected on the strength of a script's opinion.
{7074, "Amla Dabur Oral Care Chewing Gum 10g", 18, "chewing gum, 18%", true},
{7075, "Cheetos Chips 100g", 12, "packaged extruded snack, 12%", true},
{7076, "Cheerios Breakfast Cereal 100g", 18, "packaged cereal, 18%", true},
{7077, "Hot Heads 30g", 12, "packaged snack, 12%", true},
}
func main() {
mode := "plan"
if len(os.Args) > 1 {
mode = os.Args[1]
}
_ = godotenv.Load()
dsn := fmt.Sprintf("host=%s port=%s user=%s password=%s dbname=%s sslmode=disable",
os.Getenv("DB_HOST"), os.Getenv("DB_PORT"), os.Getenv("DB_USER"),
os.Getenv("DB_PASSWORD"), os.Getenv("DB_NAME"))
db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
Logger: logger.Default.LogMode(logger.Silent),
})
if err != nil {
log.Fatal(err)
}
write := mode == "apply"
fmt.Printf("%-6s %-38s %6s -> %6s %s\n", "id", "product", "now", "new", "why")
fmt.Println("-------------------------------------------------------------------------------------------")
undo := []string{}
changes := 0
review := 0
for _, r := range rates {
var current struct {
Taxpercent float64
Found bool
}
if err := db.Raw(`SELECT COALESCE(taxpercent, 0) AS taxpercent, true AS found
FROM products WHERE productid = ? LIMIT 1`,
r.productID).Scan(&current).Error; err != nil {
log.Fatalf("reading %d: %v", r.productID, err)
}
if !current.Found {
fmt.Printf("%-6d %-38s NO products ROW - skipped\n", r.productID, r.name)
continue
}
if current.Taxpercent == r.percent {
fmt.Printf("%-6d %-38s %6.0f unchanged %s\n",
r.productID, r.name, current.Taxpercent, r.why)
continue
}
if !r.apply {
fmt.Printf("%-6d %-38s %6.0f REVIEW %-3.0f %s\n",
r.productID, r.name, current.Taxpercent, r.percent, r.why)
review++
continue
}
fmt.Printf("%-6d %-38s %6.0f -> %6.0f %s\n",
r.productID, r.name, current.Taxpercent, r.percent, r.why)
undo = append(undo, fmt.Sprintf(
"UPDATE products SET taxpercent = %.0f WHERE productid = %d;",
current.Taxpercent, r.productID))
changes++
if write {
// updated is bumped so the catalogue delta carries the new rate to
// terminals holding a revision, rather than waiting for a full pull.
if err := db.Exec(`UPDATE products SET taxpercent = ?, updated = NOW()
WHERE productid = ?`, r.percent, r.productID).Error; err != nil {
log.Fatalf("writing %d: %v", r.productID, err)
}
}
}
fmt.Println("-------------------------------------------------------------------------------------------")
if write {
fmt.Printf("APPLIED %d rate(s).\n", changes)
} else {
fmt.Printf("%d rate(s) would change. Nothing written — run `apply` to commit.\n", changes)
}
if review > 0 {
fmt.Printf("%d row(s) flagged REVIEW and deliberately not written — each is a\n"+
"reduction of a live tax rate and needs a decision, not a script.\n", review)
}
fmt.Println()
if len(undo) > 0 {
fmt.Println("-- undo:")
for _, u := range undo {
fmt.Println(u)
}
}
}

141
scratch/healthproof/main.go Normal file
View File

@@ -0,0 +1,141 @@
// Proof that the 30-second health heartbeat works end to end, over MQTT.
//
// Publishes a heartbeat to the live broker as a throwaway terminal, then polls
// the public API until it shows online — and keeps polling past the TTL so the
// automatic expiry is visible too. Nothing is written to Postgres; presence
// lives in Redis under a TTL and cleans itself up.
//
// REQUIRES pos_terminal CREDENTIALS. The MQTT_USER in .env is pos_ingest, which
// the broker ACL deliberately denies publish on the health topic — it may only
// write acks and the catalogue. Running this with the ingest account connects
// fine and then silently drops every publish, because Mosquitto answers an
// ACL-denied QoS 1 publish with a PUBACK and discards it. That looks exactly
// like a broken consumer and cost an hour of misdiagnosis; set MQTT_USER and
// MQTT_PASSWORD to the terminal account before believing a negative result.
//
// The HTTP path needs none of this — see POST /pos/health, which is what the
// fix on v1.3.96 added and how the endpoint was actually verified.
//
// go run ./scratch/healthproof
package main
import (
"encoding/json"
"fmt"
"io"
"log"
"net/http"
"os"
"time"
mqtt "github.com/eclipse/paho.mqtt.golang"
"github.com/joho/godotenv"
)
const (
locationID = "1135"
terminalID = "TPROOF" // throwaway; disappears on its own when the TTL lapses
apiBase = "https://fiesta.nearle.app/live/api/v1/pos"
)
func main() {
_ = godotenv.Load()
brokerURL := os.Getenv("MQTT_URL")
if brokerURL == "" {
log.Fatal("MQTT_URL not set")
}
opts := mqtt.NewClientOptions().
AddBroker(brokerURL).
SetClientID("healthproof-" + terminalID).
SetUsername(os.Getenv("MQTT_USER")).
SetPassword(os.Getenv("MQTT_PASSWORD")).
SetConnectTimeout(10 * time.Second)
client := mqtt.NewClient(opts)
if t := client.Connect(); t.Wait() && t.Error() != nil {
log.Fatal("connect: ", t.Error())
}
defer client.Disconnect(250)
fmt.Printf("connected to %s as %s\n\n", brokerURL, terminalID)
fmt.Println("BEFORE — has this terminal ever been seen?")
show()
// Exactly what the till sends every 30 seconds.
health, _ := json.Marshal(map[string]any{
"schema": 1, "status": "online",
"terminal_id": terminalID, "location_id": locationID,
"store_name": "Ragul stores Selvapuram", "app_version": "1.1.0",
"pending_bills": 0, "pending_registrations": 0,
"today_bills": 17, "today_amount": 2510.0,
"printer_reachable": true,
"reported_at": time.Now().UTC().Format(time.RFC3339),
})
topic := fmt.Sprintf("nearle/pos/%s/%s/health", locationID, terminalID)
if t := client.Publish(topic, 1, false, health); t.Wait() && t.Error() != nil {
log.Fatal("publish: ", t.Error())
}
fmt.Printf("\npublished one heartbeat to %s\n", topic)
time.Sleep(2 * time.Second)
fmt.Println("\nAFTER one heartbeat:")
show()
// The TTL is 90s and a real till refreshes every 30s, so it never lapses
// while the till is alive. Stopping here is what a till being switched off
// looks like.
fmt.Println("\nnow going quiet, as a till that was switched off would.")
fmt.Println("presence TTL is 90s, so it should drop off on its own:")
for _, wait := range []int{30, 30, 35} {
time.Sleep(time.Duration(wait) * time.Second)
fmt.Printf("\n+%ds since the last heartbeat:\n", wait)
show()
}
}
func show() {
resp, err := http.Get(fmt.Sprintf("%s/health/location?location_id=%s", apiBase, locationID))
if err != nil {
fmt.Println(" API unreachable:", err)
return
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var out struct {
Details struct {
Online int `json:"online"`
Total int `json:"total"`
Terminals []struct {
Terminalid string `json:"terminal_id"`
Status string `json:"status"`
Reason string `json:"reason"`
Todaybills int `json:"today_bills"`
Todayamount float64 `json:"today_amount"`
Reportedat string `json:"reported_at"`
} `json:"terminals"`
} `json:"details"`
}
if err := json.Unmarshal(body, &out); err != nil {
fmt.Println(" unparseable:", string(body)[:200])
return
}
fmt.Printf(" online %d of %d\n", out.Details.Online, out.Details.Total)
for _, t := range out.Details.Terminals {
mark := " "
if t.Terminalid == terminalID {
mark = ">"
}
extra := t.Reason
if t.Status == "online" {
extra = fmt.Sprintf("today %d bills / Rs %.0f, reported %s",
t.Todaybills, t.Todayamount, t.Reportedat)
}
fmt.Printf(" %s %-8s %-8s %s\n", mark, t.Terminalid, t.Status, extra)
}
}

148
scratch/mqttpub/main.go Normal file
View File

@@ -0,0 +1,148 @@
// Publishes a bill over the real broker and waits for the ack, standing in for
// a till until one is available to test with.
//
// go run ./scratch/mqttpub
package main
import (
"encoding/json"
"fmt"
"log"
"os"
"time"
mqtt "github.com/eclipse/paho.mqtt.golang"
"github.com/joho/godotenv"
)
const (
locationID = "1135"
terminalID = "T4A9"
orderID = "99999999-8888-4777-8666-555555555555" // distinct from the HTTP test
)
func main() {
_ = godotenv.Load()
broker := os.Getenv("MQTT_URL")
if broker == "" {
broker = "tcp://66.116.225.226:1883"
}
opts := mqtt.NewClientOptions().
AddBroker(broker).
SetClientID("pos-e2e-probe").
SetUsername(os.Getenv("MQTT_USER")).
SetPassword(os.Getenv("MQTT_PASSWORD")).
SetCleanSession(true)
client := mqtt.NewClient(opts)
if t := client.Connect(); t.Wait() && t.Error() != nil {
log.Fatal("connect:", t.Error())
}
defer client.Disconnect(500)
fmt.Println("connected to", broker)
acks := make(chan []byte, 1)
ackTopic := fmt.Sprintf("nearle/pos/%s/%s/ack", locationID, terminalID)
if t := client.Subscribe(ackTopic, 1, func(_ mqtt.Client, m mqtt.Message) {
acks <- m.Payload()
}); t.Wait() && t.Error() != nil {
log.Fatal("subscribe:", t.Error())
}
fmt.Println("listening on", ackTopic)
batch := map[string]any{
"schema": 1,
"batch_id": "batch-mqtt-0001",
"store_id": locationID,
"terminal_id": terminalID,
"sent_at": time.Now().UTC().Format(time.RFC3339),
"orders": []map[string]any{{
"id": orderID,
"invoice_number": "INV-2608-T4A9-00002",
"created_at": time.Now().UTC().Format(time.RFC3339),
"terminal_id": terminalID,
"cashier": "Divya",
"customer": map[string]any{"id": "c-2", "mobile": "9840099999", "name": "Ravi"},
"subtotal": 60.0,
"discount": 0.0,
"promos": []any{},
"tax": 4.44,
"tax_breakdown": map[string]float64{"0.08": 4.44},
"round_off": 0.0,
"total": 60.0,
"points_earned": 0,
"points_redeemed": 0,
"payments": []map[string]any{{"method": "upi", "amount": 60.0, "reference": "TESTUPI"}},
"items": []map[string]any{{
"product_id": "6988", "barcode": "6988", "name": "Mysore Banana",
"quantity": 1, "unit_price": 60.0, "discount": 0.0,
"gst_rate": 0.08, "tax": 4.44, "line_total": 60.0,
}},
}},
}
body, _ := json.Marshal(batch)
orderTopic := fmt.Sprintf("nearle/pos/%s/%s/order", locationID, terminalID)
if t := client.Publish(orderTopic, 1, false, body); t.Wait() && t.Error() != nil {
log.Fatal("publish:", t.Error())
}
fmt.Println("published a bill to", orderTopic)
// The same 20 seconds a real till waits before giving up and re-sending.
select {
case payload := <-acks:
fmt.Println("\nACK RECEIVED:")
var pretty map[string]any
_ = json.Unmarshal(payload, &pretty)
out, _ := json.MarshalIndent(pretty, " ", " ")
fmt.Println(" " + string(out))
case <-time.After(20 * time.Second):
fmt.Println("\nNO ACK within 20s — a real till would keep the bill and send it again")
os.Exit(1)
}
// A heartbeat too, so the Redis presence path is exercised.
health, _ := json.Marshal(map[string]any{
"schema": 1, "status": "online",
"terminal_id": terminalID, "location_id": locationID,
"store_name": "Ragul stores Selvapuram", "app_version": "1.1.0",
"pending_bills": 0, "pending_registrations": 0,
"today_bills": 2, "today_amount": 170.0,
"printer_reachable": false,
"reported_at": time.Now().UTC().Format(time.RFC3339),
})
healthTopic := fmt.Sprintf("nearle/pos/%s/%s/health", locationID, terminalID)
if t := client.Publish(healthTopic, 1, false, health); t.Wait() && t.Error() != nil {
log.Fatal("publish health:", t.Error())
}
fmt.Println("\npublished a heartbeat to", healthTopic)
// The registration uplink. Tested over HTTP early on; this is the same
// service reached over the broker, which is the path a real till uses.
custBatch, _ := json.Marshal(map[string]any{
"schema": 1, "batch_id": "batch-cust-mqtt-0001",
"store_id": locationID, "terminal_id": terminalID,
"customers": []map[string]any{{
"id": "3d7a0000-0000-4000-8000-000000000001",
"mobile": "9840077777",
"name": "MQTT Probe Shopper",
"registered_at": time.Now().UTC().Format(time.RFC3339),
"registered_by_terminal": terminalID,
}},
})
custTopic := fmt.Sprintf("nearle/pos/%s/%s/customer", locationID, terminalID)
if t := client.Publish(custTopic, 1, false, custBatch); t.Wait() && t.Error() != nil {
log.Fatal("publish customer:", t.Error())
}
fmt.Println("published a registration to", custTopic)
select {
case payload := <-acks:
fmt.Println(" registration ACK:", string(payload))
case <-time.After(20 * time.Second):
fmt.Println(" NO ACK for the registration")
os.Exit(1)
}
}

194
scratch/seedprices/main.go Normal file
View File

@@ -0,0 +1,194 @@
// Seed retail prices so the POS has something sellable.
//
// These are plausible Coimbatore figures, not authoritative ones. They exist so
// the terminal can ring a real bill; the owner corrects them afterwards.
//
// go run ./scratch/seedprices plan # show every change and the undo SQL
// go run ./scratch/seedprices apply # write them
// go run ./scratch/seedprices verify # read back what the catalogue now serves
package main
import (
"fmt"
"log"
"os"
"github.com/joho/godotenv"
"gorm.io/driver/postgres"
"gorm.io/gorm"
"gorm.io/gorm/logger"
)
type priced struct {
locationID int
productID int
name string
unit string
price float64
note string
}
// Prices are per the product's own unit — per kilogram where the unit is
// kilogram, per pack where it is piece. Getting that backwards is the easiest
// way to make a till look broken, so the unit is carried through and printed.
var seed = []priced{
// 1135 — fresh produce
{1135, 6988, "Mysore Banana", "kilogram", 60, ""},
{1135, 6989, "Jammu Apple", "piece", 30, "per fruit, not per kg"},
{1135, 6990, "Small orange", "kilogram", 90, ""},
{1135, 6991, "Red Guava", "kilogram", 80, ""},
{1135, 6992, "Pomegrante", "kilogram", 180, ""},
{1135, 6993, "Salem Mango", "kilogram", 90, "seasonal, swings 80-120"},
{1135, 6994, "Pineapple", "kilogram", 60, ""},
{1135, 6995, "Strawberries", "piece", 150, "priced as a punnet"},
{1135, 6996, "Maceral", "kilogram", 220, "READ AS MACKEREL - correct if wrong"},
{1135, 6997, "Tuna", "kilogram", 280, ""},
{1135, 6998, "Hatsun curd", "piece", 30, "500g pouch"},
{1135, 7014, "Apple", "kilogram", 200, ""},
// 1185 — packaged
{1185, 7074, "Amla Dabur Oral Care Chewing Gum 10g", "piece", 10, ""},
{1185, 7075, "Cheetos Chips 100g", "piece", 40, ""},
{1185, 7076, "Cheerios Breakfast Cereal 100g", "piece", 120, ""},
// 7077 Hot Heads is already at 50 — someone set it deliberately, leave it.
}
func main() {
mode := "plan"
if len(os.Args) > 1 {
mode = os.Args[1]
}
_ = godotenv.Load()
dsn := fmt.Sprintf("host=%s port=%s user=%s password=%s dbname=%s sslmode=disable",
os.Getenv("DB_HOST"), os.Getenv("DB_PORT"), os.Getenv("DB_USER"),
os.Getenv("DB_PASSWORD"), os.Getenv("DB_NAME"))
db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
Logger: logger.Default.LogMode(logger.Silent),
})
if err != nil {
log.Fatal(err)
}
switch mode {
case "plan":
plan(db, false)
case "apply":
plan(db, true)
case "verify":
verify(db)
default:
log.Fatalf("unknown mode %q — use plan, apply or verify", mode)
}
}
func plan(db *gorm.DB, write bool) {
fmt.Printf("%-6s %-38s %-9s %8s -> %8s\n", "id", "product", "unit", "now", "new")
fmt.Println("--------------------------------------------------------------------------------")
undo := []string{}
changes := 0
for _, p := range seed {
var current struct {
Price float64
Tenantid int
Found bool
}
row := db.Raw(`SELECT COALESCE(price, 0) AS price, tenantid, true AS found
FROM productlocations
WHERE productid = ? AND locationid = ?
LIMIT 1`, p.productID, p.locationID).Scan(&current)
if row.Error != nil {
log.Fatalf("reading %d: %v", p.productID, row.Error)
}
if !current.Found {
fmt.Printf("%-6d %-38s NO productlocations ROW - skipped\n", p.productID, p.name)
continue
}
// Never overwrite a price a human already set. A seed value is a
// placeholder; a real one is a decision, and losing it silently would
// be worse than leaving a gap.
if current.Price > 0 {
fmt.Printf("%-6d %-38s %-9s %8.2f already priced, left alone\n",
p.productID, p.name, p.unit, current.Price)
continue
}
note := ""
if p.note != "" {
note = " <- " + p.note
}
fmt.Printf("%-6d %-38s %-9s %8.2f -> %8.2f%s\n",
p.productID, p.name, p.unit, current.Price, p.price, note)
undo = append(undo, fmt.Sprintf(
"UPDATE productlocations SET price = %.2f WHERE productid = %d AND locationid = %d;",
current.Price, p.productID, p.locationID))
changes++
if write {
// updated is bumped so the catalogue delta carries the new price to
// terminals that already hold a revision, rather than waiting for
// someone to force a full pull.
err := db.Exec(`UPDATE productlocations
SET price = ?, updated = NOW()
WHERE productid = ? AND locationid = ?`,
p.price, p.productID, p.locationID).Error
if err != nil {
log.Fatalf("writing %d: %v", p.productID, err)
}
}
}
fmt.Println("--------------------------------------------------------------------------------")
if write {
fmt.Printf("APPLIED %d price(s).\n\n", changes)
} else {
fmt.Printf("%d price(s) would change. Nothing written — run `apply` to commit.\n\n", changes)
}
fmt.Println("-- undo, if you want the zeros back:")
for _, u := range undo {
fmt.Println(u)
}
}
func verify(db *gorm.DB) {
type row struct {
Locationid int
Productid int
Productname string
Price float64
Taxpercent float64
}
var rows []row
db.Raw(`SELECT b.locationid, a.productid, a.productname,
COALESCE(b.price, 0) AS price, COALESCE(a.taxpercent, 0) AS taxpercent
FROM products a
INNER JOIN productlocations b ON a.productid = b.productid AND a.tenantid = b.tenantid
WHERE b.locationid IN (1135, 1185) AND a.productid > 0
ORDER BY b.locationid, a.productid`).Scan(&rows)
sellable := 0
for _, r := range rows {
flag := ""
if r.Price > 0 {
sellable++
} else {
flag = " <- still zero, not sellable"
}
fmt.Printf("loc %d %-6d %-38s %8.2f tax=%.0f%s\n",
r.Locationid, r.Productid, r.Productname[:min(38, len(r.Productname))], r.Price, r.Taxpercent, flag)
}
fmt.Printf("\n%d of %d rows are sellable.\n", sellable, len(rows))
}
func min(a, b int) int {
if a < b {
return a
}
return b
}

90
scratch/termfixcleanup/main.go Normal file
View File

@@ -0,0 +1,90 @@
// Removes the single bill posted to prove the terminalid fix on v1.3.96.
//
// Named by its own terminalorderid rather than by date or by "the newest row" —
// pos_orders holds real takings, and is not a table to run an unbounded DELETE
// against. Stock is returned before the bill is deleted, so the ledger is never
// left short with nothing remaining to explain why.
//
// go run ./scratch/termfixcleanup
package main
import (
"fmt"
"log"
"os"
"github.com/joho/godotenv"
"gorm.io/driver/postgres"
"gorm.io/gorm"
"gorm.io/gorm/logger"
)
const (
tenantID = 1087
locationID = 1135
testOrder = "a1b2c3d4-0000-4000-8000-termfix00001"
)
func main() {
_ = godotenv.Load()
dsn := fmt.Sprintf("host=%s port=%s user=%s password=%s dbname=%s sslmode=disable",
os.Getenv("DB_HOST"), os.Getenv("DB_PORT"), os.Getenv("DB_USER"),
os.Getenv("DB_PASSWORD"), os.Getenv("DB_NAME"))
db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
Logger: logger.Default.LogMode(logger.Silent),
})
if err != nil {
log.Fatal(err)
}
var billIDs []int
db.Raw(`SELECT posorderid FROM pos_orders WHERE terminalorderid = ?`,
testOrder).Scan(&billIDs)
if len(billIDs) == 0 {
fmt.Println("no test bill found — nothing to undo")
return
}
fmt.Printf("found test bill(s): %v\n", billIDs)
var consumed []struct {
Productid int
Quantity float64
}
db.Raw(`SELECT productid, SUM(quantity) AS quantity
FROM pos_order_items WHERE posorderid IN ?
GROUP BY productid`, billIDs).Scan(&consumed)
for _, c := range consumed {
qty := int(c.Quantity)
if float64(qty) < c.Quantity {
qty++ // the ingest rounds up, so the reversal must too
}
if err := db.Exec(`
INSERT INTO productstocks (tenantid, stockdate, locationid, productid,
quantity, stocktype, status)
VALUES (?, NOW(), ?, ?, ?, 'in', 'Active')`,
tenantID, locationID, c.Productid, qty).Error; err != nil {
fmt.Println(" return stock:", err)
continue
}
fmt.Printf(" returned %d unit(s) of product %d\n", qty, c.Productid)
}
db.Exec(`DELETE FROM pos_order_items WHERE posorderid IN ?`, billIDs)
db.Exec(`DELETE FROM pos_orders WHERE posorderid IN ?`, billIDs)
fmt.Printf(" deleted %d bill(s) and their items\n", len(billIDs))
var left int64
db.Raw(`SELECT COUNT(*) FROM pos_orders WHERE terminalorderid = ?`, testOrder).Scan(&left)
fmt.Printf("\nremaining test rows: %d\n", left)
var stock float64
db.Raw(`SELECT COALESCE(SUM(CASE WHEN LOWER(stocktype)='in' THEN quantity ELSE 0 END) -
SUM(CASE WHEN LOWER(stocktype)='out' THEN quantity ELSE 0 END), 0)
FROM productstocks WHERE productid = 6988 AND locationid = ? AND tenantid = ?`,
locationID, tenantID).Scan(&stock)
fmt.Printf("Mysore Banana stock now: %.0f (was 750 before any probe)\n", stock)
}

5
services/orderService.go
View File

@@ -18,6 +18,7 @@ type OrderService interface {
GetOrderDetails(orderHeaderID int) ([]models.OrderDetails, error)
UpdateOrder(order *models.Orders) error
CreateOrder(order models.Orders) (models.Orders, error)
UploadOfflineSales(input models.OfflineSalesUpload) (*models.OfflineSalesUploadResponse, error)
GetCustomerOrdersv3(customerID, tenantID, moduleID, fromDate, toDate, orderStatus, keyword string, pageSize, offset int) ([]models.CustomerOrder, error)
GetTenantLocationOrders(input models.DeliveryQuery) ([]models.OrderInfo, error)
GetRevenueSummary(tid, lid int, fdate, tdate string) (*models.TenantRevenueSummary, error)
@@ -81,6 +82,10 @@ func (s *orderService) CreateOrder(order models.Orders) (models.Orders, error) {
return s.repo.CreateOrder(order)
}
func (s *orderService) UploadOfflineSales(input models.OfflineSalesUpload) (*models.OfflineSalesUploadResponse, error) {
return s.repo.UploadOfflineSales(input)
}
func (s *orderService) GetCustomerOrdersv3(customerID, tenantID, moduleID, fromDate, toDate, orderStatus, keyword string, pageSize, offset int) ([]models.CustomerOrder, error) {
return s.repo.GetCustomerOrdersv3(customerID, tenantID, moduleID, fromDate, toDate, orderStatus, keyword, pageSize, offset)
}

71
services/posService.go Normal file
View File

@@ -0,0 +1,71 @@
package services
import (
"context"
"nearle/models"
"nearle/repositories"
)
type PosService interface {
IngestOrders(batch models.PosOrderBatch) (*models.PosAck, error)
IngestCustomers(batch models.PosCustomerBatch) (*models.PosAck, error)
Catalogue(storeID, since string, page, pageSize int) (*models.PosCatalogueResponse, error)
// RecordHealth stores one heartbeat. Never acknowledged back to the till:
// presence is a fire-and-forget signal, and a terminal that stopped selling
// because its heartbeat failed would be a worse outcome than a blank board.
RecordHealth(ctx context.Context, health models.PosHealth) error
TerminalHealth(ctx context.Context, terminalID string) (map[string]string, error)
LocationHealth(ctx context.Context, locationID string) ([]map[string]string, error)
Sales(f models.PosSalesFilter) (*models.PosSalesPage, error)
SaleDetail(locationID int, reference string) (*models.PosOrders, error)
SalesSummary(f models.PosSalesFilter) (*models.PosSalesSummary, error)
}
type posService struct {
repo repositories.PosRepository
presence repositories.PosPresenceRepository
}
func NewPosService(repo repositories.PosRepository, presence repositories.PosPresenceRepository) PosService {
return &posService{repo: repo, presence: presence}
}
func (s *posService) RecordHealth(ctx context.Context, health models.PosHealth) error {
return s.presence.Record(ctx, health)
}
func (s *posService) TerminalHealth(ctx context.Context, terminalID string) (map[string]string, error) {
return s.presence.Terminal(ctx, terminalID)
}
func (s *posService) LocationHealth(ctx context.Context, locationID string) ([]map[string]string, error) {
return s.presence.Location(ctx, locationID)
}
func (s *posService) IngestOrders(batch models.PosOrderBatch) (*models.PosAck, error) {
return s.repo.IngestOrders(batch)
}
func (s *posService) IngestCustomers(batch models.PosCustomerBatch) (*models.PosAck, error) {
return s.repo.IngestCustomers(batch)
}
func (s *posService) Catalogue(storeID, since string, page, pageSize int) (*models.PosCatalogueResponse, error) {
return s.repo.Catalogue(storeID, since, page, pageSize)
}
func (s *posService) Sales(f models.PosSalesFilter) (*models.PosSalesPage, error) {
return s.repo.Sales(f)
}
func (s *posService) SaleDetail(locationID int, reference string) (*models.PosOrders, error) {
return s.repo.SaleDetail(locationID, reference)
}
func (s *posService) SalesSummary(f models.PosSalesFilter) (*models.PosSalesSummary, error) {
return s.repo.SalesSummary(f)
}

47
services/productService.go
View File

@@ -4,7 +4,6 @@ import (
"fmt"
"nearle/models"
"nearle/repositories"
"strings"
"time"
)
@@ -23,6 +22,7 @@ type ProductService interface {
GetStockStatement(tenantID, locationID, subcategoryID, pageno, pagesize int, keyword string) ([]models.Productstockstatement, error)
GetLocationProducts(tenantID, locationID, subcategoryID, pageno, pagesize int, keyword string) ([]models.Locationproducts, error)
GetLocationProductSummary(tenantID, locationID int) ([]models.ProductSummary, error)
GetSaleTemplate(tenantID, locationID int) (*models.SaleTemplate, error)
FetchFilteredProducts(categoryID, subcategoryID, productID, applocationID, tenantID, locationID int, keyword, productStatus, approve string, pageno, pagesize int) ([]models.Tenantproducts, error)
GetProductByVariant(tenantid, variantid, locationid int) ([]models.Products, error)
GetProductsBySubcategory(params models.ProductFilter) (map[string]interface{}, error)
@@ -77,20 +77,15 @@ func (s *productService) CreateProductStock(stocks []models.Productstock) error
return err
}
idMap := make(map[int]struct{})
var productIDs []int
locMap := make(map[models.ProductLocationRef]struct{})
var locRefs []models.ProductLocationRef
for _, stk := range stocks {
if stk.Productid > 0 {
if _, exists := idMap[stk.Productid]; !exists {
idMap[stk.Productid] = struct{}{}
productIDs = append(productIDs, stk.Productid)
}
}
// Only "in" entries mean stock actually arrived — an "out" entry
// (a sale) should never flip a location back to available.
if stk.Productid > 0 && stk.Locationid > 0 && stk.Tenantid > 0 && strings.EqualFold(stk.Stocktype, "in") {
// Every entry gets synced, "in" and "out" alike: the status is now
// derived from the resulting balance rather than assumed from the
// direction of the movement, so an "out" that empties a location
// flags it outofstock and a partial "in" that leaves the balance at
// or below zero correctly does not mark it sellable.
if stk.Productid > 0 && stk.Locationid > 0 && stk.Tenantid > 0 {
ref := models.ProductLocationRef{Tenantid: stk.Tenantid, Locationid: stk.Locationid, Productid: stk.Productid}
if _, exists := locMap[ref]; !exists {
locMap[ref] = struct{}{}
@@ -99,14 +94,18 @@ func (s *productService) CreateProductStock(stocks []models.Productstock) error
}
}
if len(productIDs) > 0 {
if err := s.repo.UpdateProductStatus(productIDs, "available"); err != nil {
return err
}
}
// products.productstatus is deliberately NOT touched here. It is a
// per-product lifecycle field holding "Active"/"Inactive", and receiving
// stock used to overwrite it with "available" — an availability value in a
// lifecycle column, which is how 136 products ended up reading "available"
// and 12 "outofstock" with their real lifecycle state destroyed.
//
// Availability is a per-outlet fact and belongs to productlocations.status,
// which SyncProductLocationStatus derives from the ledger below. A single
// column on products cannot express it anyway: the same product can be
// stocked at one outlet and empty at another.
if len(locRefs) > 0 {
if err := s.repo.ReactivateProductLocations(locRefs); err != nil {
if err := s.repo.SyncProductLocationStatus(locRefs); err != nil {
return err
}
}
@@ -142,6 +141,10 @@ func (s *productService) GetLocationProductSummary(tenantID, locationID int) ([]
return s.repo.GetLocationProductSummary(tenantID, locationID)
}
func (s *productService) GetSaleTemplate(tenantID, locationID int) (*models.SaleTemplate, error) {
return s.repo.GetSaleTemplate(tenantID, locationID)
}
func (s *productService) FetchFilteredProducts(categoryID, subcategoryID, productID, applocationID, tenantID, locationID int, keyword, productStatus,
approve string, pageno, pagesize int) ([]models.Tenantproducts, error) {
return s.repo.FetchFilteredProducts(categoryID, subcategoryID, productID, applocationID, tenantID, locationID, keyword, productStatus, approve, pageno, pagesize)
@@ -290,6 +293,11 @@ func (s *productService) ImportCatalogueProduct(reqs []models.ImportCataloguePro
}
}
// Price carries the selling price onto the per-store row. Omitting it
// left productlocations.price at 0 for every imported product, and that
// column — not products.retailprice — is what the store catalogue, the
// customer app and each order line read. The result was a catalogue
// where nothing had a price and every order booked an amount of 0.
locations = append(locations, models.Productlocations{
Tenantid: req.Tenantid,
Locationid: req.Locationid,
@@ -297,6 +305,7 @@ func (s *productService) ImportCatalogueProduct(reqs []models.ImportCataloguePro
Quantity: req.Quantity,
Stocktype: req.Stocktype,
Status: req.Status,
Price: float32(req.Retailprice),
})
}