Correct what /posroles tells a console about each role

The supervisor blurb still said "Also signs into the app", which was true when it
was written and is now the opposite of true: a till account has no Nearle Daily
login at all. A console showing that text would be telling a store admin the one
thing about these roles they most need not to believe.

The cashier blurb said "Billing only", which understated it in the other
direction — a cashier now has their own username and password, so a shop can
open without a supervisor standing there.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.env

@@ -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

.gitignore

@@ -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

controllers/orderController.go

@@ -1,6 +1,7 @@
 package controllers
 
 import (
+	"fmt"
 	"log"
 	"nearle/models"
 	"net/http"
@@ -303,6 +304,24 @@ func (ctl *OrderController) CreateOrderv3(c *fiber.Ctx) error {
 		}
 	}
 
+	// 🛠️ Strategy 3: some clients send the header under "orders" but the line
+	// items as a SIBLING top-level "items" array rather than nested inside
+	// it. Strategy 2's OrderWrapper only has an "orders" field, so
+	// encoding/json silently drops that sibling key — the order header
+	// parses fine but data.Items ends up empty, which used to let the order
+	// go through with zero items and skip the stock check entirely (the
+	// pre-validation loop below iterates over data.Items). Pick it up here
+	// if strategies 1/2 left Items empty.
+	if len(data.Items) == 0 {
+		type ItemsWrapper struct {
+			Items []models.OrderDetail `json:"items"`
+		}
+		var itemsWrapper ItemsWrapper
+		if err := c.BodyParser(&itemsWrapper); err == nil && len(itemsWrapper.Items) > 0 {
+			data.Items = itemsWrapper.Items
+		}
+	}
+
 	// Double check we have the required ID
 	if data.Tenantid == 0 {
 		return c.Status(http.StatusConflict).JSON(fiber.Map{
@@ -312,6 +331,18 @@ func (ctl *OrderController) CreateOrderv3(c *fiber.Ctx) error {
 		})
 	}
 
+	// An order with no line items has nothing to check stock against — the
+	// pre-validation loop in CreateOrder simply wouldn't run, silently
+	// creating a phantom header-only order that never deducted stock.
+	// Reject it outright instead.
+	if len(data.Items) == 0 {
+		return c.Status(http.StatusBadRequest).JSON(fiber.Map{
+			"code":    http.StatusBadRequest,
+			"message": "Order must contain at least one item",
+			"status":  false,
+		})
+	}
+
 	if strings.TrimSpace(data.Orderdate) == "" {
 		data.Orderdate = time.Now().Format("2006-01-02 15:04:05")
 	}
@@ -341,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")

controllers/posController.go

@@ -0,0 +1,832 @@
+package controllers
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"nearle/middleware"
+	"nearle/models"
+	"nearle/repositories"
+	"nearle/services"
+	"nearle/utils"
+
+	"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,
+	})
+}
+
+// Login signs a terminal in and returns its session.
+//
+// The one POS route that is deliberately left unauthenticated — it is where a
+// token comes from. Everything else on the group sits behind the session this
+// issues.
+func (ctl *PosController) Login(c *fiber.Ctx) error {
+	var req models.PosLoginRequest
+	if err := c.BodyParser(&req); err != nil {
+		return c.Status(http.StatusBadRequest).JSON(fiber.Map{
+			"code": http.StatusBadRequest, "status": false,
+			"message": "invalid request body",
+		})
+	}
+
+	if strings.TrimSpace(req.Authname) == "" && strings.TrimSpace(req.Contactno) == "" {
+		return c.Status(http.StatusBadRequest).JSON(fiber.Map{
+			"code": http.StatusBadRequest, "status": false,
+			"message": "an email or mobile number is required",
+		})
+	}
+
+	session, err := ctl.posService.Login(req)
+	if err != nil {
+		// A rejected credential is 401 and says nothing about which half was
+		// wrong. Anything else is the deployment's problem, not the caller's,
+		// and is logged rather than described down the wire.
+		if repositories.PosLoginRejected(err) {
+			return c.Status(http.StatusUnauthorized).JSON(fiber.Map{
+				"code": http.StatusUnauthorized, "status": false,
+				"message": err.Error(),
+			})
+		}
+
+		log.Printf("pos login (%s): %v", req.Authname, err)
+		return c.Status(http.StatusForbidden).JSON(fiber.Map{
+			"code": http.StatusForbidden, "status": false, "message": err.Error(),
+		})
+	}
+
+	return c.JSON(fiber.Map{
+		"code": http.StatusOK, "status": true,
+		"message": "Login successful",
+		"details": session,
+	})
+}
+
+// Session echoes back who the caller is, per their token.
+//
+// What a till calls on start-up to find out whether the session it saved
+// yesterday is still good, without having to make a real request and interpret
+// the failure. Answers 401 through the middleware when it is not.
+func (ctl *PosController) Session(c *fiber.Ctx) error {
+	claims, ok := middleware.PosClaimsFrom(c)
+	if !ok {
+		return c.Status(http.StatusUnauthorized).JSON(fiber.Map{
+			"code": http.StatusUnauthorized, "status": false,
+			"message": "no session token was presented",
+		})
+	}
+
+	return c.JSON(fiber.Map{
+		"code": http.StatusOK, "status": true,
+		"details": fiber.Map{
+			"user_id":     claims.Userid,
+			"tenant_id":   claims.Tenantid,
+			"location_id": claims.Locationid,
+			"store_id":    strconv.Itoa(claims.Locationid),
+			"role_id":     claims.Roleid,
+			"terminal_id": claims.Terminalid,
+			"expires_at":  time.Unix(claims.Expiresat, 0).UTC().Format(time.RFC3339),
+		},
+	})
+}
+
+// Staff lists who may ring a bill at this terminal's outlet.
+//
+// Scoped by the caller's own session rather than by a query parameter. A till
+// asking "who works here" must not be able to ask on behalf of another shop,
+// and the answer carries PINs — so the outlet comes from the token, and a
+// request without one is refused whatever POS_AUTH_REQUIRED says.
+func (ctl *PosController) Staff(c *fiber.Ctx) error {
+	claims, ok := middleware.PosClaimsFrom(c)
+	if !ok {
+		return c.Status(http.StatusUnauthorized).JSON(fiber.Map{
+			"code": http.StatusUnauthorized, "status": false,
+			"message": "a session token is required to read staff",
+		})
+	}
+
+	staff, err := ctl.posService.Staff(claims.Tenantid, claims.Locationid)
+	if err != nil {
+		return posServerError(c, "Staff", err)
+	}
+
+	return c.JSON(fiber.Map{
+		"code": http.StatusOK, "status": true,
+		"details": models.PosStaffResponse{
+			Locationid: claims.Locationid,
+			Staff:      staff,
+		},
+	})
+}
+
+// ------------------------------------------------------------- Till staff
+//
+// A shop runs its own counter. A supervisor creates their cashiers from the
+// terminal, and every one of these reads the tenant and outlet from the
+// caller's session token rather than from the request — so a supervisor at one
+// shop cannot create, edit or list staff at another. That is the same inversion
+// that stopped a till naming its own store id, applied to people.
+
+// posManager returns the caller's session, provided they may manage staff.
+func posManager(c *fiber.Ctx) (utils.PosClaims, error) {
+	claims, ok := middleware.PosClaimsFrom(c)
+	if !ok {
+		return claims, fiber.NewError(http.StatusUnauthorized,
+			"a session token is required")
+	}
+	if !models.PosRoleCanManageStaff(claims.Roleid) {
+		// A cashier signing in on the same terminal must not be able to mint
+		// themselves a supervisor.
+		return claims, fiber.NewError(http.StatusForbidden,
+			"only a supervisor can manage till users")
+	}
+	return claims, nil
+}
+
+// CreatePosUser adds a cashier or supervisor at the caller's outlet.
+func (ctl *PosController) CreatePosUser(c *fiber.Ctx) error {
+	claims, err := posManager(c)
+	if err != nil {
+		return posClaimError(c, err)
+	}
+
+	var req models.PosUserRequest
+	if err := c.BodyParser(&req); err != nil {
+		return posBadRequest(c, fmt.Errorf("invalid request body"))
+	}
+
+	user, err := ctl.posService.CreateUser(claims.Tenantid, claims.Locationid, claims.Configid, req)
+	if err != nil {
+		// Every failure here is something the caller can act on — a bad role, a
+		// PIN already in use, a name left blank — so it is reported as a 400
+		// with the reason rather than logged and hidden behind a 500.
+		return posBadRequest(c, err)
+	}
+
+	return c.Status(http.StatusCreated).JSON(fiber.Map{
+		"code": http.StatusCreated, "status": true,
+		"message": "User created", "details": user,
+	})
+}
+
+// UpdatePosUser edits one of the caller's own till users.
+func (ctl *PosController) UpdatePosUser(c *fiber.Ctx) error {
+	claims, err := posManager(c)
+	if err != nil {
+		return posClaimError(c, err)
+	}
+
+	var req models.PosUserRequest
+	if err := c.BodyParser(&req); err != nil {
+		return posBadRequest(c, fmt.Errorf("invalid request body"))
+	}
+
+	user, err := ctl.posService.UpdateUser(claims.Tenantid, claims.Locationid, req)
+	if err != nil {
+		return posBadRequest(c, err)
+	}
+
+	return c.JSON(fiber.Map{
+		"code": http.StatusOK, "status": true,
+		"message": "User updated", "details": user,
+	})
+}
+
+// ListPosUsers returns the till users at the caller's outlet.
+//
+// Readable by anyone signed in, not only a supervisor: the terminal needs the
+// list to show who is on shift, and a cashier can already see their colleagues
+// standing next to them. PINs are the part that matters, and those only go to
+// somebody who could set them anyway.
+func (ctl *PosController) ListPosUsers(c *fiber.Ctx) error {
+	claims, ok := middleware.PosClaimsFrom(c)
+	if !ok {
+		return c.Status(http.StatusUnauthorized).JSON(fiber.Map{
+			"code": http.StatusUnauthorized, "status": false,
+			"message": "a session token is required",
+		})
+	}
+
+	users, err := ctl.posService.ListUsers(
+		claims.Tenantid, claims.Locationid,
+		strings.EqualFold(c.Query("include_inactive"), "true"),
+	)
+	if err != nil {
+		return posServerError(c, "ListPosUsers", err)
+	}
+
+	// A cashier sees who is on shift, not how to sign in as them.
+	if !models.PosRoleCanManageStaff(claims.Roleid) {
+		for i := range users {
+			users[i].Pin = ""
+		}
+	}
+
+	return c.JSON(fiber.Map{
+		"code": http.StatusOK, "status": true,
+		"details": fiber.Map{"location_id": claims.Locationid, "users": users},
+	})
+}
+
+// DeletePosUser retires a till user. Deactivates rather than deletes — bills
+// carry the cashier's name and shifts settle against it.
+func (ctl *PosController) DeletePosUser(c *fiber.Ctx) error {
+	claims, err := posManager(c)
+	if err != nil {
+		return posClaimError(c, err)
+	}
+
+	userID, convErr := strconv.Atoi(strings.TrimSpace(c.Query("user_id")))
+	if convErr != nil || userID <= 0 {
+		return posBadRequest(c, fmt.Errorf("user_id is required"))
+	}
+	if userID == claims.Userid {
+		// Otherwise the last supervisor at a shop can lock everybody out with
+		// one tap, and only we can undo it.
+		return posBadRequest(c, fmt.Errorf("you cannot deactivate the account you are signed in as"))
+	}
+
+	if err := ctl.posService.DeactivateUser(claims.Tenantid, claims.Locationid, userID); err != nil {
+		return posBadRequest(c, err)
+	}
+
+	return c.JSON(fiber.Map{
+		"code": http.StatusOK, "status": true, "message": "User deactivated",
+	})
+}
+
+// PinLogin signs somebody in by PIN at a terminal that is already open.
+//
+// Requires an existing valid session, and that is the whole security model
+// here: four digits is ten thousand guesses, which is no barrier at all to an
+// anonymous caller. Tying it to a token means a supervisor has already opened
+// the terminal with a real password, and the guesses are confined to one
+// outlet's own staff.
+//
+// The new session is minted fresh rather than derived from the presented one,
+// so a cashier taking over from a supervisor drops the supervisor's
+// permissions instead of inheriting them.
+func (ctl *PosController) PinLogin(c *fiber.Ctx) error {
+	claims, ok := middleware.PosClaimsFrom(c)
+	if !ok {
+		return c.Status(http.StatusUnauthorized).JSON(fiber.Map{
+			"code": http.StatusUnauthorized, "status": false,
+			"message": "sign the terminal in with an email and password before using PIN sign-in",
+		})
+	}
+
+	var req models.PosLoginRequest
+	if err := c.BodyParser(&req); err != nil {
+		return posBadRequest(c, fmt.Errorf("invalid request body"))
+	}
+	if strings.TrimSpace(req.Pin) == "" {
+		return posBadRequest(c, fmt.Errorf("a PIN is required"))
+	}
+
+	session, err := ctl.posService.LoginWithPin(claims.Tenantid, claims.Locationid, req.Pin)
+	if err != nil {
+		if repositories.PosLoginRejected(err) {
+			return c.Status(http.StatusUnauthorized).JSON(fiber.Map{
+				"code": http.StatusUnauthorized, "status": false,
+				"message": "that PIN was not recognised",
+			})
+		}
+		return posBadRequest(c, err)
+	}
+
+	return c.JSON(fiber.Map{
+		"code": http.StatusOK, "status": true,
+		"message": "Signed in", "details": session,
+	})
+}
+
+// posClaimError renders the fiber.Error that posManager returns.
+func posClaimError(c *fiber.Ctx, err error) error {
+	var fe *fiber.Error
+	if errors.As(err, &fe) {
+		return c.Status(fe.Code).JSON(fiber.Map{
+			"code": fe.Code, "status": false, "message": fe.Message,
+		})
+	}
+	return posServerError(c, "posClaims", err)
+}
+
+// ------------------------------------------------------- Till staff, from the web
+//
+// The same staff management as `/pos/users`, for the console an admin actually
+// uses. Deliberately the same service calls underneath rather than a parallel
+// implementation: a supervisor created from a browser must be the same thing as
+// one created at a counter, and two code paths writing one table is exactly how
+// that stops being true.
+//
+// The difference is where the outlet comes from. A terminal proves it with a
+// signed token; the console asserts it, because it has no session of its own.
+// So it is verified against the tenant before anything is written — which is
+// weaker than a signature, and is why these should move behind the same guard
+// once the console can hold a session.
+
+// posWebScope reads and checks the tenant and outlet a console request names.
+func (ctl *PosController) posWebScope(tenantID, locationID int) error {
+	if tenantID <= 0 {
+		return fmt.Errorf("tenantid is required")
+	}
+	if locationID <= 0 {
+		return fmt.Errorf("locationid is required")
+	}
+
+	allowed, err := ctl.posService.LocationAllowed(tenantID, locationID)
+	if err != nil {
+		return fmt.Errorf("could not verify the outlet")
+	}
+	if !allowed {
+		// Not "no such outlet" — that would confirm which ids exist. It did not
+		// belong to the tenant asking, and that is all the caller needs.
+		return fmt.Errorf("outlet %d does not belong to tenant %d", locationID, tenantID)
+	}
+	return nil
+}
+
+// WebCreatePosUser adds a supervisor or cashier from the console.
+func (ctl *PosController) WebCreatePosUser(c *fiber.Ctx) error {
+	var req models.PosUserWebRequest
+	if err := c.BodyParser(&req); err != nil {
+		return posBadRequest(c, fmt.Errorf("invalid request body"))
+	}
+
+	if err := ctl.posWebScope(req.Tenantid, req.Locationid); err != nil {
+		return posBadRequest(c, err)
+	}
+
+	// The configid the outlet's other people already use, so a new cashier is
+	// visible to the same portal as their colleagues. Asked for rather than
+	// derived would mean a console sending a number nobody can look up.
+	configID := ctl.posService.ConfigidFor(req.Tenantid)
+
+	user, err := ctl.posService.CreateUser(req.Tenantid, req.Locationid, configID, req.PosUserRequest)
+	if err != nil {
+		return posBadRequest(c, err)
+	}
+
+	return c.Status(http.StatusCreated).JSON(fiber.Map{
+		"code": http.StatusCreated, "status": true,
+		"message": "User created", "details": user,
+	})
+}
+
+// WebUpdatePosUser edits one of an outlet's till users from the console.
+func (ctl *PosController) WebUpdatePosUser(c *fiber.Ctx) error {
+	var req models.PosUserWebRequest
+	if err := c.BodyParser(&req); err != nil {
+		return posBadRequest(c, fmt.Errorf("invalid request body"))
+	}
+
+	if err := ctl.posWebScope(req.Tenantid, req.Locationid); err != nil {
+		return posBadRequest(c, err)
+	}
+
+	user, err := ctl.posService.UpdateUser(req.Tenantid, req.Locationid, req.PosUserRequest)
+	if err != nil {
+		return posBadRequest(c, err)
+	}
+
+	return c.JSON(fiber.Map{
+		"code": http.StatusOK, "status": true,
+		"message": "User updated", "details": user,
+	})
+}
+
+// WebListPosUsers lists an outlet's till users for the console.
+func (ctl *PosController) WebListPosUsers(c *fiber.Ctx) error {
+	tenantID, _ := strconv.Atoi(strings.TrimSpace(c.Query("tenantid")))
+	locationID, _ := strconv.Atoi(strings.TrimSpace(c.Query("locationid")))
+
+	if err := ctl.posWebScope(tenantID, locationID); err != nil {
+		return posBadRequest(c, err)
+	}
+
+	users, err := ctl.posService.ListUsers(tenantID, locationID,
+		strings.EqualFold(c.Query("include_inactive"), "true"))
+	if err != nil {
+		return posServerError(c, "WebListPosUsers", err)
+	}
+
+	return c.JSON(fiber.Map{
+		"code": http.StatusOK, "status": true,
+		"details": fiber.Map{"location_id": locationID, "users": users},
+	})
+}
+
+// WebDeletePosUser retires a till user from the console.
+func (ctl *PosController) WebDeletePosUser(c *fiber.Ctx) error {
+	tenantID, _ := strconv.Atoi(strings.TrimSpace(c.Query("tenantid")))
+	locationID, _ := strconv.Atoi(strings.TrimSpace(c.Query("locationid")))
+
+	if err := ctl.posWebScope(tenantID, locationID); err != nil {
+		return posBadRequest(c, err)
+	}
+
+	userID, err := strconv.Atoi(strings.TrimSpace(c.Query("userid")))
+	if err != nil || userID <= 0 {
+		return posBadRequest(c, fmt.Errorf("userid is required"))
+	}
+
+	if err := ctl.posService.DeactivateUser(tenantID, locationID, userID); err != nil {
+		return posBadRequest(c, err)
+	}
+
+	return c.JSON(fiber.Map{
+		"code": http.StatusOK, "status": true, "message": "User deactivated",
+	})
+}
+
+// WebPosRoles lists the roles a console may offer.
+//
+// Served rather than hardcoded in the console, because the numbers are this
+// backend's business. A console that hardcoded 7 and 8 would be wrong the day
+// they change, and would have no way to know.
+func (ctl *PosController) WebPosRoles(c *fiber.Ctx) error {
+	return c.JSON(fiber.Map{
+		"code": http.StatusOK, "status": true,
+		"details": []fiber.Map{
+			{
+				"role_id": models.PosRoleSupervisor, "role": "supervisor",
+				"label": models.PosRoleName(models.PosRoleSupervisor),
+				"description": "Runs the terminal: imports, settings, voids, and " +
+					"creating counter staff. Signs in at a till only — a till " +
+					"account has no Nearle Daily login.",
+			},
+			{
+				"role_id": models.PosRoleCashier, "role": "cashier",
+				"label": models.PosRoleName(models.PosRoleCashier),
+				"description": "Billing only. Signs in at a till with their own username " +
+					"and password, so a shop can open without a supervisor present.",
+			},
+		},
+	})
+}

controllers/productController.go

@@ -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"))
@@ -367,8 +403,9 @@ func (ctl *ProductController) GetProductByVariant(c *fiber.Ctx) error {
 
 	tenantID, _ := strconv.Atoi(c.Query("tenantid"))
 	variantid, _ := strconv.Atoi(c.Query("variantid"))
+	locationID, _ := strconv.Atoi(c.Query("locationid"))
 
-	result, err := ctl.productService.GetProductByVariant(tenantID, variantid)
+	result, err := ctl.productService.GetProductByVariant(tenantID, variantid, locationID)
 
 	if err != nil {
 

controllers/tenantController.go

@@ -328,8 +328,12 @@ func (ctl *TenantController) CreateStaff(c *fiber.Ctx) error {
 	}
 
 	if err := ctl.tenantService.CreateStaff(data); err != nil {
-		return c.Status(http.StatusInternalServerError).JSON(fiber.Map{
+		// A rejected PIN, a missing name, a role nobody set — these are things
-			"code":    http.StatusConflict,
+		// the person filling in the form can fix, so they come back as 400 with
+		// the reason. This answered 500 with a body claiming 409, which told a
+		// console nothing it could act on and told the operator less.
+		return c.Status(http.StatusBadRequest).JSON(fiber.Map{
+			"code":    http.StatusBadRequest,
 			"message": err.Error(),
 			"status":  false,
 		})

db/redis.go

@@ -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)
+	}
+}

docs/MOBILE_ORDER_VERIFICATION.md

@@ -0,0 +1,124 @@
+# Order Creation — Mobile Developer Verification Guide
+
+## Why this exists
+
+We found that orders placed through the app were being saved with **zero line
+items** — the order header (tenant, location, customer) saved fine, but the
+`items` array was silently getting dropped somewhere between the app and the
+database. Because the stock check only runs over whatever's in `items`, an
+order with no items also skipped stock validation entirely.
+
+The backend now tolerates a few different request shapes and has a stock
+check in place, but the app's actual request needs to be verified against
+what's below to confirm it lines up.
+
+## Endpoint
+
+```
+POST https://fiesta.nearle.app/live/api/v1/mob/orders/createorder
+Content-Type: application/json
+```
+
+## Request shape — items MUST be inside `orders`, not a sibling of it
+
+**Correct:**
+```json
+{
+  "orders": {
+    "tenantid": 1135,
+    "locationid": 1166,
+    "customerid": 42,
+    "items": [
+      { "productid": 7060, "orderqty": 2, "price": 45.0 }
+    ]
+  }
+}
+```
+
+**Also accepted (flat, no wrapper):**
+```json
+{
+  "tenantid": 1135,
+  "locationid": 1166,
+  "customerid": 42,
+  "items": [
+    { "productid": 7060, "orderqty": 2, "price": 45.0 }
+  ]
+}
+```
+
+**This shape used to silently lose the items — avoid it:**
+```json
+{
+  "orders": { "tenantid": 1135, "locationid": 1166 },
+  "items": [ { "productid": 7060, "orderqty": 2 } ]
+}
+```
+`items` as a sibling of `orders` (not nested inside it) is now handled as a
+fallback server-side too, but don't rely on the fallback — put `items` inside
+`orders` to match the primary/documented shape.
+
+## Required fields per item
+
+| field       | type   | required | notes                                    |
+|-------------|--------|----------|-------------------------------------------|
+| `productid` | int    | yes      | must be a real product for the tenant     |
+| `orderqty`  | number | yes      | quantity being ordered                    |
+| `price`     | number | recommended | unit price at time of order          |
+| `locationid`| int    | no       | defaults to the order's own `locationid` if omitted |
+
+## Expected responses — verify your app handles all of these
+
+| Scenario | HTTP code | Body (key fields) |
+|---|---|---|
+| Order succeeds | `200` | `"status": true`, `"details": { "orderheaderid": ..., "items": [...] }` |
+| No `tenantid` at all | `409` | `"status": false`, `"message": "Tenant ID is required"` |
+| `items` missing/empty | `400` | `"status": false`, `"message": "Order must contain at least one item"` |
+| Requested qty > available stock | `409` | `"status": false`, `"message": "insufficient stock for product '<name>': requested X, available Y"` |
+
+**Important:** a `409` with "insufficient stock" is not a network/server
+error — it's the correct, expected response when a customer tries to order
+more than what's in stock at that store. The app should catch this
+specifically (check the message text, or treat any `409` from this endpoint
+as a stock problem) and show the customer a clear "not enough stock" message
+rather than a generic error screen.
+
+## How to verify end-to-end yourselves
+
+1. Pick a real `tenantid` + `locationid` + `productid` combo you know has
+   stock (ask backend/ops for current numbers, or check via the merchant
+   web app's inventory view).
+2. Place a normal order for 1 unit through the app. Confirm it returns `200`
+   and the response's `details.items` array is non-empty.
+3. Place an order for a quantity larger than what's currently in stock for
+   that product/location. Confirm you get a `409` with an "insufficient
+   stock" message, and that the app surfaces this to the user instead of
+   silently failing or showing a generic error.
+4. Cancel a successful order and confirm a follow-up stock check reflects
+   the restored quantity (ask backend to check, or place the same
+   over-quantity order again afterward — it should now succeed if
+   cancellation restored enough stock).
+
+## Checking stock before the customer even taps "order"
+
+`GET /live/api/v1/mob/products/getproductbyvariant` now accepts an optional
+`locationid` query param:
+
+```
+GET /live/api/v1/mob/products/getproductbyvariant?tenantid=1135&variantid=44&locationid=1166
+```
+
+When `locationid` is passed, each returned product now carries two extra
+live fields:
+
+| field | meaning |
+|---|---|
+| `productstock` | live available quantity at that store — same SUM(in)-SUM(out) formula the order stock check uses |
+| `locationstatus` | that store's status for this product, e.g. `"outofstock"` or `"available"`/`"Active"` |
+
+**If `locationid` is omitted, both fields come back empty/zero** — this is
+the old behavior preserved for backward compatibility, not new stock data.
+Start passing `locationid` (the store the customer is browsing) to get real
+numbers, and use it to show "out of stock" / gray out the add-to-cart button
+*before* the customer tries to order, instead of only finding out from the
+`409` response above.

docs/POS_API.md

@@ -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.

docs/POS_LOGIN.md

@@ -0,0 +1,625 @@
+# Nearle POS — Terminal Sign-In
+
+How a till authenticates, and how it finds out which shop it belongs to.
+
+**Base URL** `https://fiesta.nearle.app/live/api/v1/pos`
+**Live since** 6 Aug 2026, `v1.3.98`
+
+---
+
+## What changed, and why it matters
+
+A terminal used to hold a store id typed into Settings and a password compiled
+into the app. That made the store id a **claim** rather than a fact: any till
+could name any outlet and be believed, so changing one number on one screen
+moved a terminal into another tenant's books. The password was identical on
+every install of a build.
+
+Now a person signs in with their own back-office account, and the outlet
+arrives **as a consequence** — sealed inside a signed token the terminal cannot
+edit, and re-checked by the server on every request.
+
+The rule to hold onto: **the till no longer decides which shop it is. It is
+told.**
+
+---
+
+## Quickstart
+
+```bash
+BASE=https://fiesta.nearle.app/live/api/v1/pos
+
+# 1. Sign in
+curl -s -X POST $BASE/login \
+  -H 'Content-Type: application/json' \
+  -d '{"authname":"rsselvapuram@gmail.com","password":"…","terminal_id":"T5EDD"}'
+
+# 2. Use the token on everything else
+curl -s $BASE/session -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## The flow
+
+These steps are in order, and the order matters.
+
+**1. Sign in.** `POST /login` with the operator's own credentials — the same
+`app_users` account they use for the web console. There is no separate POS
+password.
+
+**2. Read `store_id` out of the response.** Do not ask anyone to type it. It is
+whatever the back office says that account's outlet is.
+
+**3. If `locations` has more than one entry, ask which one.** Only then. A
+single-outlet account gets a list of one and must never see a picker.
+
+**4. Save the token.** Platform keystore, not a plain file or SQLite — it is a
+bearer credential for a whole trading day. Restore it on launch **before** any
+upload or catalogue pull runs.
+
+**5. Send it on every request** as `Authorization: Bearer <token>`.
+
+**6. Import `staff`.** Replace the till's local staff with what came down, and
+deactivate anything that wasn't in the list. That is what retires the built-in
+PINs.
+
+---
+
+## `POST /login`
+
+The only unauthenticated route. It is where a token comes from.
+
+### Request
+
+```json
+{
+  "authname": "rsselvapuram@gmail.com",
+  "password": "…",
+  "terminal_id": "T5EDD",
+  "device_id": "a5f3…",
+  "location_id": 1135,
+  "configid": 1
+}
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `authname` | yes* | Email. **Or** send `contactno` instead. |
+| `contactno` | yes* | Mobile number, as an alternative to `authname`. |
+| `password` | yes | |
+| `terminal_id` | no | This till's short code, e.g. `T5EDD`. Recorded on the session. |
+| `device_id` | no | The device's stable UUID. |
+| `location_id` | no | **Only** meaningful for a multi-outlet account. A request, not an assertion — it is checked against what the account may reach. |
+| `configid` | no | Inferred when absent. Send it only if you get the ambiguity error below. |
+
+\* one of `authname` or `contactno`.
+
+### Response — `200`
+
+```json
+{
+  "code": 200,
+  "status": true,
+  "message": "Login successful",
+  "details": {
+    "token": "eyJ1aWQiOjEy….K3p9",
+    "expires_at": "2026-09-05T10:51:17Z",
+
+    "user_id": 1229,
+    "full_name": "Selvapuram",
+    "email": "rsselvapuram@gmail.com",
+    "role_id": 0,
+
+    "tenant_id": 1087,
+    "tenant_name": "Ragul Stores",
+
+    "store_id": "1135",
+    "location_id": 1135,
+    "location_name": "Ragul stores Selvapuram",
+    "gstin": "123456",
+    "address": "…",
+    "phone": "…",
+
+    "locations": [
+      { "location_id": 1135, "location_name": "Ragul stores Selvapuram",
+        "address": "", "city": "", "status": "Active" }
+    ],
+
+    "staff": [
+      { "user_id": 1148, "full_name": "Ragul Kannan",
+        "role": "Super admin", "pin": "1111", "status": "Active" }
+    ]
+  }
+}
+```
+
+### The fields that matter
+
+**`store_id`** — a string, because that is the shape every uplink already
+sends. Use it verbatim as the `store_id` on `/orders`, `/customers` and
+`/catalogue`. It is the same value as `location_id`, handed back in the form it
+will be replayed in.
+
+**`token`** — **opaque**. Do not parse it, do not read anything out of it, do
+not trust anything it appears to say. Its only correct use is to hand it back.
+
+**`expires_at`** — 30 days out. Long on purpose: a shop signs a terminal in once
+and expects it to keep working. Forcing a re-login mid-shift means a queue of
+customers waiting while somebody finds the manager.
+
+**`gstin` / `address` / `phone`** — print these on the receipt. They are a legal
+requirement on a GST invoice and they used to be compile-time constants, so a
+shop correcting its GSTIN had to wait for a rebuild. Write them locally on
+sign-in.
+
+**`locations`** — every outlet this account may open a till at. Length 1 is the
+normal case.
+
+**`staff`** — see [Staff and PINs](#staff-and-pins). **Often empty.**
+
+---
+
+## `GET /session`
+
+Answers who the caller is, per their token. What a till calls on launch to
+check whether yesterday's session is still good, without making a real request
+and interpreting the failure.
+
+Requires the token. Returns `401` when there isn't one.
+
+```json
+{
+  "code": 200,
+  "status": true,
+  "details": {
+    "user_id": 1229,
+    "tenant_id": 1087,
+    "location_id": 1135,
+    "store_id": "1135",
+    "role_id": 0,
+    "terminal_id": "PROBE",
+    "expires_at": "2026-09-05T10:51:17Z"
+  }
+}
+```
+
+---
+
+## `GET /staff`
+
+Who may ring a bill at this terminal's outlet. For pulling down somebody hired
+mid-shift without signing the terminal out.
+
+**Takes no parameters.** The answer carries PINs, so the outlet comes from the
+caller's own token — a till must not be able to ask who works at the shop next
+door. A request without a token is refused whatever the enforcement setting is.
+
+```json
+{
+  "code": 200,
+  "status": true,
+  "details": {
+    "location_id": 1135,
+    "staff": []
+  }
+}
+```
+
+---
+
+## Roles
+
+Two POS roles, added to `app_roles`:
+
+| roleid | Role | Can |
+|---|---|---|
+| `7` | **Supervisor** | everything a till does, **plus** creating and editing counter staff |
+| `8` | **Cashier** | billing only |
+
+The session carries both, so the terminal never has to map role ids itself:
+
+```json
+{ "role_id": 7, "role": "Supervisor", "can_manage_staff": true }
+```
+
+Branch on `can_manage_staff`, not on the number. `app_roles` holds six rows for
+four back-office roles (Admin is both 3 and 5, Manager both 4 and 6) and most
+accounts carry an id that is not in the table at all — any mapping written on
+the terminal would be wrong.
+
+### The till and Nearle Daily do not share accounts
+
+`app_users` is the only thing the two products have in common. An account
+belongs to one or the other, never to both:
+
+| | Nearle Daily app + console | POS terminal |
+|---|---|---|
+| roles | `1`–`6` — Super admin, Operations, Admin, Manager | `7` Supervisor, `8` Cashier |
+| `/applogin`, `/tenant/weblogin`, `/tenant/login` | yes | **not found** |
+| `POST /v1/pos/login` | **403** | yes |
+| listed by `/getallusers`, `/getstaffs` | yes | **hidden** |
+
+A Nearle Daily **Super admin is not the administrator of anybody's POS.** The
+back office reaches a till by *provisioning* a Supervisor from the console; it
+never becomes one by signing in.
+
+This was the other way round until it was measured. Roles 1–6 counted as
+supervisors, on the reasoning that somebody who already administers a shop from
+a browser is not made less privileged by standing at the counter. That handed
+till-supervisor powers to **68 live accounts, 59 of them platform Super
+admins**, while the actual shop accounts carry `roleid 0` and were refused.
+
+Both directions are now closed in the queries themselves rather than in a check
+each call site has to remember — a till account is not *rejected* by the app
+login, it is simply not found.
+
+**`role_id` 0 is not a role.** It is what an account carries when nobody set
+one, 22 live accounts have it including a delivery rider, and it grants nothing
+on either side.
+
+### Every till account gets its own username and password
+
+Both roles. A PIN cannot open a *closed* terminal — `/pos/login/pin` requires a
+session that already exists — so a PIN-only account works only while somebody
+else is standing there to unlock the till first. For a Supervisor that was an
+outright deadlock; for a Cashier it meant a shop that could not open until two
+people had arrived, and whoever gets in at seven is as often the cashier as the
+supervisor.
+
+So a Cashier signs in exactly like a Supervisor does, and the *role* decides
+what they get — not which credential they used:
+
+```
+POST /v1/pos/login   supervisor.1185@pos.nearle.in   -> full shell
+POST /v1/pos/login   cashier.1185@pos.nearle.in      -> billing only
+```
+
+`POST /pos/users` generates both when the request omits them, and returns the
+password **once**, in the creation response only:
+
+```json
+{ "user_id": 1452, "role": "Cashier",
+  "authname": "cashier.1185@pos.nearle.in",
+  "password": "9tWx2KUJksM5Rm", "pin": "4513", "has_password": true }
+```
+
+`GET /pos/users` never returns a password, only `has_password`. An admin who
+loses it reissues rather than looks it up.
+
+Send `authname` and `password` explicitly if the shop wants its people signing
+in as themselves. A generated name that collides — a second cashier at one
+outlet — becomes `cashier2.1185@pos.nearle.in`; a name **you** supplied is never
+adjusted, it is refused, because silently signing somebody in as another
+person's address is worse than an error.
+
+The PIN stays optional. It switches operator at an open counter, which not every
+shop does, and it is the one credential the till holds in plaintext to hand
+around — so it is set deliberately, never by default.
+
+---
+
+## `POST /pos/login/pin` — signing on at an open terminal
+
+For a cashier taking over a counter a supervisor has already opened.
+
+**Requires an existing valid token.** That is the security model, not an
+oversight: four digits is ten thousand guesses, which is no barrier at all to an
+anonymous caller. Tying it to a session means a supervisor has opened the
+terminal with a real password first, and the guesses are confined to that one
+outlet's staff.
+
+```bash
+curl -s -X POST $BASE/login/pin \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"pin":"1602"}'
+```
+
+Returns a **new** session, with the same shape as `/login`. New rather than
+reused, because the token carries the role — a cashier taking over from a
+supervisor must drop their permissions, not inherit them.
+
+`401` if the PIN is not recognised. `400` if two people at the outlet share it,
+which creation refuses but older data may contain.
+
+---
+
+## `/pos/users` — the shop's own counter staff
+
+A supervisor creates their own cashiers, from the terminal.
+
+**The outlet is never in the request.** Tenant and location come from the
+caller's token, so a supervisor at Selvapuram cannot create staff at R mart by
+sending a different number — the same inversion that stopped a till naming its
+own store id.
+
+### `POST /pos/users`
+
+```json
+{
+  "full_name": "Asha Kumar",
+  "role": "cashier",
+  "pin": "4821",
+  "authname": "asha@shop.test",
+  "password": "…"
+}
+```
+
+| Field | Notes |
+|---|---|
+| `full_name` | required; split across `firstname`/`lastname` |
+| `role` | `"supervisor"` or `"cashier"`. Anything else is refused — never defaulted |
+| `pin` | optional, 4 digits. See the rules below |
+| `authname` | optional. **Generated if omitted** — `cashier.1185@pos.nearle.in`, or `cashier2.…` if that is taken |
+| `password` | optional. **Generated if omitted**, and returned once in this response |
+
+**Everyone gets a username and a password, cashiers included**, because a PIN
+cannot open a closed terminal. Omit both fields and they are generated for you,
+so provisioning a shop is one call per person.
+
+The response is the only time the password is returned; `GET /pos/users` reports
+`has_password` and nothing more.
+
+:warning: **PIN rules, and why**
+
+- **Exactly 4 digits, and cannot start with `0`.** `app_users.pin` is a
+  `bigint`, so `"0451"` would be stored as `451` and read back as three digits —
+  a cashier would type four and be refused for ever. One such account already
+  exists in live data.
+- **`1234`, `1111`, `2345`, `4321`, `9999`, `2222`, `3456`, `0000` are refused.**
+  Live data has `1234` on eleven accounts and `1111` on nine.
+- **Unique within the outlet**, not globally. A PIN only distinguishes people at
+  one counter; making it platform-unique would exhaust the space fast.
+
+Answers `201` with the created user. Every failure is a `400` carrying the
+reason, because all of them are things the caller can fix.
+
+### `GET /pos/users`
+
+Readable by anyone signed in — the terminal needs it to show who is on shift.
+**A cashier gets the list with `pin` blanked**; only somebody who could set a
+PIN gets to see one. `?include_inactive=true` to see leavers.
+
+### `PUT /pos/users`
+
+Same fields plus `user_id`. Send only what changes. Supervisor only.
+
+### `DELETE /pos/users?user_id=9189`
+
+Deactivates — never deletes, because bills carry the cashier's name and shifts
+settle against it. Supervisor only, and you cannot deactivate the account you
+are signed in as: otherwise the last supervisor at a shop can lock everyone out
+with one tap.
+
+---
+
+## Creating staff from the web console
+
+The same staff management, for the screen an admin actually uses. Registered
+under both `/v1/web/tenants` and `/v1/mob/tenants`.
+
+```
+GET    /v1/web/tenants/posroles
+GET    /v1/web/tenants/getposusers?tenantid=1087&locationid=1135
+POST   /v1/web/tenants/createposuser
+PUT    /v1/web/tenants/updateposuser
+DELETE /v1/web/tenants/deleteposuser?tenantid=1087&locationid=1135&userid=9189
+```
+
+`createposuser` takes the same body as `/pos/users`, plus the outlet — the
+console has no session token, so it has to name one:
+
+```json
+{
+  "tenantid": 1087,
+  "locationid": 1135,
+  "full_name": "Asha Kumar",
+  "role": "cashier",
+  "pin": "4821"
+}
+```
+
+**These run the same service calls as `/pos/users`.** A supervisor created from
+a browser is the same row, with the same rules applied, as one created at a
+counter — same PIN validation, same duplicate check, same identity-column
+allocation. That is the point of them: two paths writing one table is how the
+two stop matching.
+
+`configid` is never asked for. It is inferred from whichever value the tenant's
+existing accounts carry — a number nobody looks up, that varies per tenant (1087
+is spread across 1, 6 and 15), and that silently creates an account nobody can
+find if it is wrong.
+
+`GET /posroles` returns the two roles with their ids and labels, so a console
+offering the choice never has to know that supervisor is `7`.
+
+### :red_circle: These are unauthenticated
+
+Like every other route in the `/v1/web` and `/v1/mob` groups — there is no auth
+middleware anywhere on the web API. The outlet is checked against the tenant
+before anything is written, so a caller cannot create staff at a shop that is
+not theirs *given a tenant id* — but nothing proves the caller is that tenant.
+
+So this mints till credentials on an unauthenticated request. It is consistent
+with the rest of the platform, and it is still the weakest point in this design.
+They should move behind a session guard as soon as the console can hold one.
+
+The terminal routes are not affected: `/pos/users` proves its outlet with a
+signed token.
+
+---
+
+## Using the token
+
+```
+Authorization: Bearer eyJ1aWQiOjEy….K3p9
+```
+
+`X-Pos-Token: <token>` is accepted as a fallback, because some shop routers
+strip `Authorization` headers over plain HTTP. A bare token with no `Bearer `
+prefix is tolerated too.
+
+Send it on **every** POS call: `/orders`, `/customers`, `/catalogue`, `/health`,
+`/sales*`, `/session`, `/staff`.
+
+### What the server checks
+
+1. The token verifies against our signing key and has not expired.
+2. The outlet named in the request belongs to the token's tenant.
+
+The second is the one that matters. A valid token is a licence to name **your**
+outlets, not any outlet. The outlet is read from the query string *and* from the
+JSON body, because `/orders` and `/customers` carry `store_id` in the batch and
+never in the URL.
+
+```
+GET /catalogue?store_id=1135  →  200   your outlet
+GET /catalogue?store_id=1185  →  403   {"message":"this session cannot reach outlet 1185"}
+```
+
+---
+
+## Errors
+
+### Sign-in
+
+| Code | Meaning | What the till should do |
+|---|---|---|
+| `400` | Body unreadable, or neither `authname` nor `contactno` sent | Fix the request |
+| `401` | `those sign-in details were not recognised` | Ask them to re-type. **Wrong email and wrong password give the same message** — deliberately, so the endpoint isn't a directory of who banks here |
+| `403` | Real account, but it can't open this till | Show the message; re-typing won't help |
+
+The `403` messages, verbatim:
+
+- `this account is not set up for the till; ask your store admin to add you as a Supervisor or Cashier in the web console`
+- `this account is inactive; contact your administrator`
+- `this account has no password set; set one in the web console first`
+- `this account is not attached to a tenant and cannot open a till`
+- `no active outlet is registered for this account`
+- `this account cannot open a till at outlet 1185`
+- `more than one account uses these sign-in details; ask your administrator for the configid and send it with the login`
+
+That last one is real, not theoretical: `authname` is not unique in this schema.
+Live data has the same address twice. We refuse rather than pick one, because
+picking wrong means billing into another tenant's books.
+
+The **first** one is the common case now, and it is deliberately specific where a
+bad password is deliberately vague. By the time it fires the caller has already
+proved the credential, so naming the reason leaks nothing they did not just
+demonstrate — and the vague answer would send a shop owner hunting for a
+password that was never wrong.
+
+### Authenticated routes
+
+| Code | Meaning |
+|---|---|
+| `401` | No token, malformed token, bad signature, or expired — sign in again |
+| `403` | Valid token naming an outlet the tenant doesn't own |
+
+---
+
+## Multi-outlet accounts
+
+An account pinned to one location gets that location. An account with no
+location — a proprietor with several shops — gets all of the tenant's active
+outlets.
+
+```
+rsselvapuram@gmail.com  →  1 outlet   (1135, Selvapuram)
+raguladmin@gmail.com    →  6 outlets  (1097, 1135, 1137, 1138, 1139, 885536644)
+```
+
+When `locations.length > 1`:
+
+1. Show a picker. **Don't make it dismissable** — a terminal has to be standing
+   somewhere, and silently defaulting to the first outlet is how a day's takings
+   get filed against the wrong shop.
+2. Sign in **again** with `location_id` set to their choice.
+
+Re-signing-in is not laziness. The outlet is inside the signed token, so only
+the server can issue one for a different shop — and re-checking entitlement at
+that moment is the point.
+
+---
+
+## Staff and PINs
+
+Two different credentials, easily confused:
+
+| | Says | Checked by |
+|---|---|---|
+| **Sign-in** (email + password) | which **shop** this terminal is | the server |
+| **PIN** | which **person** rang this bill | the terminal, offline |
+
+The PIN stamps `cashiername` and is what shifts settle against. It is **shift
+attribution, not a security boundary** — the boundary is the token.
+
+### The PIN comes down in the clear
+
+Over TLS, and that's considered rather than sloppy. Four digits are
+brute-forceable in microseconds whatever they're wrapped in, so hashing
+server-side would buy the appearance of strength and not the substance — while
+costing something real, because the terminal salts every PIN with its own random
+salt before storing it and could never verify a hash computed on the server.
+
+**Store it hashed on the device.** It arrives in the clear; it must not sit that
+way.
+
+### Importing
+
+Write everyone in `staff`, keyed on `user_id` so a re-sync updates rather than
+duplicates. Then **deactivate everything you didn't just import** — that is what
+kills the built-in PINs. Deactivate, never delete: bills carry the cashier's
+name.
+
+### :warning: `staff` is usually empty today
+
+Only 116 of 596 accounts on the platform have a PIN set. Outlet 1135 — the one
+the terminal ships pointed at — has **zero**.
+
+So:
+
+- **An empty list is not a failure.** Do nothing and leave the till exactly as
+  it was.
+- **A list where every PIN is unusable** (`0`, blank) must behave the same way.
+  Deactivating the local accounts because the back office isn't filled in yet
+  would leave a counter nobody can sign in to.
+
+The terminal still ships with three seeded logins for exactly this reason. They
+retire automatically the moment real staff exist. Filling in real PINs in the
+back office is what makes that happen.
+
+---
+
+## Current state
+
+| | |
+|---|---|
+| Endpoints | live on `v1.3.98`, all three pods |
+| Signing key | set in `app-secrets` |
+| **Enforcement** | **OFF** — `POS_AUTH_REQUIRED` is unset |
+
+Enforcement being off means a request carrying **no** token is still allowed
+through, so terminals already trading don't stop the day this ships. It does
+**not** mean tokens are ignored:
+
+- a token that's present and invalid is **always** refused;
+- a valid token naming another tenant's outlet is **always** refused.
+
+Once the fleet is on a build that signs in, `POS_AUTH_REQUIRED=true` closes the
+door on untokened requests.
+
+---
+
+## Known limitations
+
+- **Passwords are stored in plaintext** across the whole platform, not just
+  here. Fixing it is a migration touching every login path.
+- **No role check.** Any active account with a tenant, a password and an active
+  outlet can open a till — including `roleid 0`, which isn't in `app_roles` at
+  all and currently includes a delivery rider. The damage is bounded by the
+  token: they can only reach their own tenant's books.
+- **`1135` means two different things.** It's a *location* (Ragul stores
+  Selvapuram, under tenant 1087) and separately a *tenant* (Suriya Store). Same
+  number, different tables. Watch for it in logs.

docs/POS_TERMINAL_INGEST.md

@@ -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.

docs/SECURITY_HANDOFF.md

@@ -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.

facade/container.go

@@ -19,6 +19,11 @@ type Facade struct {
 	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,6 +84,16 @@ 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,
@@ -90,5 +105,12 @@ func NewFacade(db *gorm.DB, catalogueDB *gorm.DB) *Facade {
 		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 }

go.mod

@@ -2,9 +2,21 @@ module nearle
 
 go 1.24
 
-toolchain go1.24.0
+require (
-
+	firebase.google.com/go v3.13.0+incompatible
-require gorm.io/gorm v1.25.10
+	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.19.0 // indirect
-	github.com/klauspost/compress v1.17.2 // 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/net v0.33.0 // indirect
-	golang.org/x/oauth2 v0.12.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
 )

go.sum

@@ -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.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
-github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+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.19.0 h1:sXLILfc9jV2QYWkzFOPWStmcUVH2RHEB1JCdY2oVvCQ=
-github.com/klauspost/compress v1.17.2/go.mod h1:ntbaceVETuRiXiv4DpjP66DpAtAGkEQskQzEyD//IeE=
+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.11.0 h1:cWPaGQEPrBb5/AsnsZesgZZ9yb1OQ+GOISoDNXVBh4M=
-github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+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.33.0 h1:74SYHlV8BIgHIFC/LrYkOGIwL19eTYXQ5wc6TBuO36I=
-golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk=
+golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4=
-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/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-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
-gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+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=

main.go

@@ -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)

messaging/posmqtt.go

@@ -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
+}

messaging/posmqtt_test.go

@@ -0,0 +1,462 @@
+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
+}
+
+// Sign-in plays no part over the broker: a terminal on MQTT authenticates to
+// the broker itself, and the topic it publishes on already names its store.
+// These exist to satisfy the interface, and returning "denied" is the safer
+// stub — a fake that waved authorisation through could hide a real regression.
+func (f *fakePosService) Login(models.PosLoginRequest) (*models.PosSession, error) {
+	return nil, nil
+}
+
+func (f *fakePosService) LocationAllowed(int, int) (bool, error) {
+	return false, nil
+}
+
+func (f *fakePosService) Staff(int, int) ([]models.PosStaffMember, error) {
+	return nil, nil
+}
+
+// Staff management plays no part over the broker — a terminal on MQTT publishes
+// bills and nothing else. Denied rather than permitted, so a fake cannot hide a
+// regression by waving authorisation through.
+func (f *fakePosService) CreateUser(int, int, int, models.PosUserRequest) (*models.PosUser, error) {
+	return nil, nil
+}
+
+func (f *fakePosService) UpdateUser(int, int, models.PosUserRequest) (*models.PosUser, error) {
+	return nil, nil
+}
+
+func (f *fakePosService) ListUsers(int, int, bool) ([]models.PosUser, error) {
+	return nil, nil
+}
+
+func (f *fakePosService) DeactivateUser(int, int, int) error { return nil }
+
+func (f *fakePosService) LoginWithPin(int, int, string) (*models.PosSession, error) {
+	return nil, nil
+}
+
+func (f *fakePosService) ConfigidFor(int) int { return 0 }
+
+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)
+			}
+		})
+	}
+}

messaging/posworkers.go

@@ -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()              {}

messaging/posworkers_test.go

@@ -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()
+}

middleware/posauth.go

@@ -0,0 +1,219 @@
+package middleware
+
+import (
+	"encoding/json"
+	"net/http"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+
+	"nearle/services"
+	"nearle/utils"
+
+	"github.com/gofiber/fiber/v2"
+)
+
+// Authorisation for the POS terminal.
+//
+// Before this, the whole POS surface was open. A till named its own outlet on
+// the wire and was believed, so `store_id=1185` in a URL was enough to read
+// another tenant's catalogue or post bills into their books. There was no
+// middleware in the codebase at all and the `JWT_SECRET_KEY` in the config was
+// read and never used.
+//
+// The fix is two checks, in this order:
+//
+//  1. the caller holds a token this server signed, and
+//  2. the outlet they are naming belongs to the tenant inside that token.
+//
+// The second is the one that matters. A valid token is not a licence to name
+// any location — it is a licence to name *your* locations, and without the
+// cross-check a real terminal at one shop could still read the shop next door.
+
+// PosLocalsKey names where the verified claims are parked for handlers.
+const PosLocalsKey = "posclaims"
+
+// posAuthRequired reports whether a request without a valid token is refused.
+//
+// Defaults to OFF, and that is a deliberate, temporary choice rather than an
+// oversight. Terminals are already in shops billing real customers against the
+// unauthenticated endpoints; switching enforcement on at deploy would stop
+// every one of them mid-trade. So the endpoint ships first, tills adopt it, and
+// `POS_AUTH_REQUIRED=true` closes the door once the fleet is carrying tokens.
+//
+// While it is off a token is still *verified* when one is sent, and a request
+// carrying a token for the wrong tenant is still refused — the flag only
+// decides what happens to a request carrying none.
+func posAuthRequired() bool {
+	return strings.EqualFold(strings.TrimSpace(os.Getenv("POS_AUTH_REQUIRED")), "true")
+}
+
+// PosAuth verifies the session token and pins the request to its outlet.
+func PosAuth(pos services.PosService) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		token := bearerToken(c)
+
+		if token == "" {
+			if posAuthRequired() {
+				return posUnauthorized(c, "a session token is required; sign in at /pos/login")
+			}
+			// Legacy till. Allowed through un-pinned, which is exactly the state
+			// this middleware exists to end — see posAuthRequired.
+			return c.Next()
+		}
+
+		claims, err := utils.ParsePosToken(token, time.Now())
+		if err != nil {
+			// Always refused, flag or no flag. A token that does not verify is
+			// a stronger signal than no token at all: nothing sends a broken
+			// one by accident.
+			return posUnauthorized(c, err.Error())
+		}
+
+		// The outlet named in the request, if it named one. Every POS route
+		// spells this differently — `store_id` on catalogue, `locationid` on
+		// sales, `location_id` on health — so all three are read rather than
+		// the caller being asked to change.
+		requested := requestedLocation(c)
+
+		if requested > 0 && requested != claims.Locationid {
+			// A different outlet than the token was issued for. Permitted only
+			// if the tenant genuinely owns it — a proprietor with six shops
+			// should be able to look at all six from one signed-in session.
+			allowed, err := pos.LocationAllowed(claims.Tenantid, requested)
+			if err != nil {
+				return c.Status(http.StatusServiceUnavailable).JSON(fiber.Map{
+					"code": http.StatusServiceUnavailable, "status": false,
+					"message": "could not verify outlet access",
+				})
+			}
+			if !allowed {
+				return c.Status(http.StatusForbidden).JSON(fiber.Map{
+					"code": http.StatusForbidden, "status": false,
+					"message": "this session cannot reach outlet " + strconv.Itoa(requested),
+				})
+			}
+		}
+
+		c.Locals(PosLocalsKey, claims)
+		return c.Next()
+	}
+}
+
+// bearerToken reads the session out of the request.
+//
+// `Authorization: Bearer …` is the form to use. `X-Pos-Token` is accepted as
+// well because some of the shop routers between a till and this server strip
+// Authorization headers on plain HTTP, and a terminal that cannot authenticate
+// is a shop that cannot trade.
+func bearerToken(c *fiber.Ctx) string {
+	header := strings.TrimSpace(c.Get("Authorization"))
+	if header != "" {
+		if after, found := strings.CutPrefix(header, "Bearer "); found {
+			return strings.TrimSpace(after)
+		}
+		if !strings.Contains(header, " ") {
+			// Tolerates a bare token. Terminals in the field get this wrong and
+			// the alternative is a shop that cannot sell.
+			return header
+		}
+	}
+	return strings.TrimSpace(c.Get("X-Pos-Token"))
+}
+
+// requestedLocation reads whichever outlet parameter this route happens to use.
+//
+// The three spellings are a wart — `store_id`, `locationid` and `location_id`
+// all mean the same thing across the POS routes. Normalising them is a breaking
+// change for terminals already in the field, so this reads all three instead
+// and leaves the naming alone.
+//
+// The body is searched as well as the query, and that is not an optional extra:
+// the two routes that *write* — order and customer ingest — carry `store_id` in
+// a JSON batch and never in the URL. Checking only the query string would leave
+// the exact call that posts bills into another tenant's books unguarded, which
+// is the hole this middleware exists to close.
+func requestedLocation(c *fiber.Ctx) int {
+	for _, key := range []string{"store_id", "locationid", "location_id"} {
+		if raw := strings.TrimSpace(c.Query(key)); raw != "" {
+			if id, err := strconv.Atoi(raw); err == nil && id > 0 {
+				return id
+			}
+		}
+	}
+	return bodyLocation(c)
+}
+
+// bodyLocation pulls the outlet out of a JSON request body.
+//
+// Decoded into a loose map rather than the batch type on purpose. This runs
+// before the handler and must not reject anything the handler would have
+// accepted — a body that fails to parse here is left to the handler to refuse
+// with its own message, and a batch shape that changes later must not silently
+// stop being authorised.
+//
+// `c.Body()` returns the buffered bytes, so reading it here does not consume
+// the stream the handler goes on to parse.
+func bodyLocation(c *fiber.Ctx) int {
+	body := c.Body()
+	if len(body) == 0 || len(body) > 8<<20 {
+		return 0
+	}
+
+	var probe struct {
+		Storeid    json.RawMessage `json:"store_id"`
+		Locationid json.RawMessage `json:"location_id"`
+	}
+	if err := json.Unmarshal(body, &probe); err != nil {
+		return 0
+	}
+
+	for _, raw := range []json.RawMessage{probe.Storeid, probe.Locationid} {
+		if id := asLocationID(raw); id > 0 {
+			return id
+		}
+	}
+	return 0
+}
+
+// asLocationID reads an id that may have been sent as a number or as a string.
+//
+// The till sends `"store_id": "1135"` and the health payload sends
+// `"location_id": "1135"`, both quoted, while other callers send it bare.
+// Accepting only one shape would silently skip the check for the other — and a
+// skipped check here reads exactly like a passed one.
+func asLocationID(raw json.RawMessage) int {
+	if len(raw) == 0 {
+		return 0
+	}
+
+	var asString string
+	if err := json.Unmarshal(raw, &asString); err == nil {
+		if id, err := strconv.Atoi(strings.TrimSpace(asString)); err == nil && id > 0 {
+			return id
+		}
+		return 0
+	}
+
+	var asNumber int
+	if err := json.Unmarshal(raw, &asNumber); err == nil && asNumber > 0 {
+		return asNumber
+	}
+	return 0
+}
+
+func posUnauthorized(c *fiber.Ctx, message string) error {
+	return c.Status(http.StatusUnauthorized).JSON(fiber.Map{
+		"code": http.StatusUnauthorized, "status": false, "message": message,
+	})
+}
+
+// PosClaimsFrom returns the verified session on a request, if it carried one.
+//
+// The second return distinguishes "no token" from "a token claiming tenant 0",
+// which a caller acting on the tenant id must not confuse.
+func PosClaimsFrom(c *fiber.Ctx) (utils.PosClaims, bool) {
+	claims, ok := c.Locals(PosLocalsKey).(utils.PosClaims)
+	return claims, ok
+}

middleware/posauth_test.go

@@ -0,0 +1,151 @@
+package middleware
+
+import (
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gofiber/fiber/v2"
+)
+
+// The outlet a request names has to be found wherever the route happens to put
+// it. These cover the extraction alone — it is the part that decides whether
+// the authorisation check runs at all, and a miss here reads exactly like a
+// pass.
+
+func locationFor(t *testing.T, method, target, body string) int {
+	t.Helper()
+
+	app := fiber.New()
+	found := -1
+	app.All("/probe", func(c *fiber.Ctx) error {
+		found = requestedLocation(c)
+		return c.SendStatus(fiber.StatusOK)
+	})
+
+	var reader *strings.Reader
+	if body == "" {
+		reader = strings.NewReader("")
+	} else {
+		reader = strings.NewReader(body)
+	}
+
+	req := httptest.NewRequest(method, target, reader)
+	if body != "" {
+		req.Header.Set("Content-Type", "application/json")
+	}
+
+	if _, err := app.Test(req); err != nil {
+		t.Fatalf("probing: %v", err)
+	}
+	return found
+}
+
+func TestTheOutletIsFoundUnderEveryNameTheRoutesUse(t *testing.T) {
+	// Three spellings for one thing across the POS routes. Missing any of them
+	// leaves that route unguarded.
+	cases := []struct {
+		name   string
+		target string
+	}{
+		{"catalogue says store_id", "/probe?store_id=1135"},
+		{"sales say locationid", "/probe?locationid=1135"},
+		{"health says location_id", "/probe?location_id=1135"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := locationFor(t, "GET", tc.target, ""); got != 1135 {
+				t.Fatalf("wanted outlet 1135, got %d", got)
+			}
+		})
+	}
+}
+
+// The two routes that *write* carry the outlet in a JSON batch and never in the
+// URL. Checking only the query string would leave the exact call that posts
+// bills into another tenant's books unguarded.
+func TestTheOutletIsFoundInAnIngestBody(t *testing.T) {
+	body := `{"batch_id":"b1","terminal_id":"T5EDD","store_id":"1135","orders":[]}`
+
+	if got := locationFor(t, "POST", "/probe", body); got != 1135 {
+		t.Fatalf("wanted outlet 1135 from the batch body, got %d", got)
+	}
+}
+
+// The till quotes its ids; other callers send them bare. Accepting only one
+// shape silently skips the check for the other.
+func TestAnOutletIsReadWhetherQuotedOrNot(t *testing.T) {
+	quoted := `{"store_id":"1135"}`
+	bare := `{"store_id":1135}`
+
+	if got := locationFor(t, "POST", "/probe", quoted); got != 1135 {
+		t.Fatalf("quoted store_id: wanted 1135, got %d", got)
+	}
+	if got := locationFor(t, "POST", "/probe", bare); got != 1135 {
+		t.Fatalf("bare store_id: wanted 1135, got %d", got)
+	}
+}
+
+func TestAHealthBodyNamesItsOutlet(t *testing.T) {
+	body := `{"terminal_id":"T5EDD","location_id":"1135","status":"online"}`
+
+	if got := locationFor(t, "POST", "/probe", body); got != 1135 {
+		t.Fatalf("wanted outlet 1135 from the health body, got %d", got)
+	}
+}
+
+// A request naming no outlet is not an error — /session names none — so it must
+// come back as "nothing to check" rather than as outlet zero.
+func TestARequestNamingNoOutletReportsNone(t *testing.T) {
+	if got := locationFor(t, "GET", "/probe", ""); got != 0 {
+		t.Fatalf("wanted 0 for a request naming no outlet, got %d", got)
+	}
+	if got := locationFor(t, "POST", "/probe", `{"batch_id":"b1"}`); got != 0 {
+		t.Fatalf("wanted 0 for a body naming no outlet, got %d", got)
+	}
+}
+
+// A body this middleware cannot parse must not be treated as naming an outlet.
+// The handler will refuse it on its own terms; guessing here would either
+// reject a good request or wave a bad one through.
+func TestAnUnparseableBodyNamesNoOutlet(t *testing.T) {
+	if got := locationFor(t, "POST", "/probe", `{not json at all`); got != 0 {
+		t.Fatalf("wanted 0 for an unparseable body, got %d", got)
+	}
+}
+
+func TestABearerTokenIsReadInEveryFormTheFieldSends(t *testing.T) {
+	app := fiber.New()
+	var got string
+	app.Get("/probe", func(c *fiber.Ctx) error {
+		got = bearerToken(c)
+		return c.SendStatus(fiber.StatusOK)
+	})
+
+	cases := []struct {
+		name   string
+		header string
+		value  string
+		want   string
+	}{
+		{"the standard form", "Authorization", "Bearer abc.def", "abc.def"},
+		{"a bare token, which terminals send", "Authorization", "abc.def", "abc.def"},
+		{"the fallback header", "X-Pos-Token", "abc.def", "abc.def"},
+		{"a scheme we do not issue", "Authorization", "Basic dXNlcjpwdw==", ""},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got = ""
+			req := httptest.NewRequest("GET", "/probe", nil)
+			req.Header.Set(tc.header, tc.value)
+			if _, err := app.Test(req); err != nil {
+				t.Fatalf("probing: %v", err)
+			}
+			if got != tc.want {
+				t.Fatalf("wanted %q, got %q", tc.want, got)
+			}
+		})
+	}
+}

models/order.go

@@ -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"`

models/pos.go

@@ -0,0 +1,480 @@
+package models
+
+import "strings"
+
+// 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"`
+}
+
+// ---------------------------------------------------------------- Sign-in
+//
+// A terminal used to hold a store id typed into Settings and a password
+// compiled into the app. That made the store id a *claim* rather than a fact:
+// any till could name any outlet and be believed, and one leaked build opened
+// every tenant on the platform.
+//
+// These types replace it with the account model the web console already uses.
+// A person signs in with their own `app_users` credentials, and the outlet
+// comes out of their record instead of going in from the wire.
+
+// PosLoginRequest is what a till sends to sign in.
+//
+// Authname or Contactno, matching the web console's own login — a shop should
+// not need a second set of credentials just because the screen is a till.
+//
+// Locationid is optional and only means anything for a user entitled to more
+// than one outlet: it says which of theirs this terminal is standing in. It is
+// checked against what they may reach, never trusted on its own.
+type PosLoginRequest struct {
+	Authname   string `json:"authname"`
+	Contactno  string `json:"contactno"`
+	Password   string `json:"password"`
+	Configid   int    `json:"configid"`
+	Locationid int    `json:"location_id"`
+
+	// A PIN, for signing on at a terminal a supervisor has already opened. Only
+	// honoured by the PIN route, which requires an existing session — four
+	// digits is no barrier to an anonymous caller.
+	Pin string `json:"pin"`
+
+	// Which physical till is asking. Recorded on the session so a stolen token
+	// can be told apart from the terminal it was issued to.
+	Terminalid string `json:"terminal_id"`
+	Deviceid   string `json:"device_id"`
+}
+
+// PosLoginLocation is one outlet a signed-in user may bill for.
+type PosLoginLocation struct {
+	Locationid   int    `json:"location_id"`
+	Locationname string `json:"location_name"`
+	Address      string `json:"address,omitempty"`
+	City         string `json:"city,omitempty"`
+	Status       string `json:"status,omitempty"`
+}
+
+// PosSession is what a till holds for the rest of the trading day.
+//
+// Storeid is returned as a string because that is the shape the terminal's
+// configuration already stores and sends — handing it back in the form it will
+// be replayed in removes a conversion, and a conversion is where a store id
+// gets mangled.
+type PosSession struct {
+	Token     string `json:"token"`
+	Expiresat string `json:"expires_at"`
+
+	Userid   int    `json:"user_id"`
+	Fullname string `json:"full_name"`
+	Email    string `json:"email,omitempty"`
+	Roleid   int    `json:"role_id"`
+
+	// What the role is called, and the one thing the terminal actually branches
+	// on. Sent as a flag rather than leaving the till to map role ids itself:
+	// `app_roles` has six rows for four roles and most accounts carry an id
+	// absent from it, so any mapping written on the terminal would be wrong.
+	Role           string `json:"role"`
+	Canmanagestaff bool   `json:"can_manage_staff"`
+
+	// Which portal this account belongs to. Carried so a supervisor creating a
+	// cashier gives them the same configid — an account created under the wrong
+	// one cannot sign into the web console and is invisible to half the
+	// platform's queries. Not sent to the terminal: it has no use for it and it
+	// is one more number to get wrong.
+	Configid int `json:"-"`
+
+	Tenantid   int    `json:"tenant_id"`
+	Tenantname string `json:"tenant_name"`
+
+	Storeid      string `json:"store_id"`
+	Locationid   int    `json:"location_id"`
+	Locationname string `json:"location_name"`
+	Gstin        string `json:"gstin,omitempty"`
+	Address      string `json:"address,omitempty"`
+	Phone        string `json:"phone,omitempty"`
+
+	// Every outlet this account may sign a terminal into. A single-outlet user
+	// gets a list of one, so the till has no special case: it shows a picker
+	// when there is a choice and skips it when there is not.
+	Locations []PosLoginLocation `json:"locations"`
+
+	// The people who may ring a bill at the chosen outlet.
+	//
+	// Sent with the session so a terminal is ready to trade the moment it signs
+	// in, rather than needing a second call before the first customer. May be
+	// empty — most tenants have no staff recorded yet — and the terminal has to
+	// cope with that rather than treat it as a failure.
+	Staff []PosStaffMember `json:"staff"`
+}
+
+// PosStaffMember is one person who may ring a bill at an outlet.
+//
+// Distinct from the account that signs the *terminal* in. The sign-in says
+// which shop this till belongs to; this says who is standing at it, and it is
+// what gets stamped on a bill as `cashiername` and settled against at the end
+// of a shift.
+//
+// The PIN travels in the clear, over TLS, and that is a considered choice
+// rather than an oversight. A four-digit PIN is brute-forceable in microseconds
+// whatever it is wrapped in, so hashing it here would buy the appearance of
+// strength and not the substance. What it would cost is real: the terminal
+// salts every PIN with its own random salt before storing it, so a hash
+// computed here could never be verified there without inventing a shared
+// scheme and keeping two codebases agreeing about it for ever.
+//
+// The honest framing is that a PIN is *shift attribution*, not a security
+// boundary. The boundary is the session token — which is what stops a till
+// reaching another tenant's books at all. The PIN decides which of the people
+// already inside a shop gets credited with a sale, and the terminal still
+// stores it hashed at rest.
+type PosStaffMember struct {
+	Userid   int    `json:"user_id"`
+	Fullname string `json:"full_name"`
+	Role     string `json:"role"`
+	Pin      string `json:"pin,omitempty"`
+	Status   string `json:"status,omitempty"`
+}
+
+// PosStaffResponse answers a request for an outlet's people.
+type PosStaffResponse struct {
+	Locationid int              `json:"location_id"`
+	Staff      []PosStaffMember `json:"staff"`
+}
+
+// ------------------------------------------------------------ POS staff roles
+//
+// `app_roles` is keyed by roleid and carries a configid, so the same name
+// appears more than once — Admin is both 3 and 5, Manager both 4 and 6, one per
+// portal. These two are deliberately not per-portal: a till is a till whichever
+// tenant owns it, and a role that had to be duplicated per config would be one
+// more thing to remember when a tenant is onboarded.
+//
+// The ids are fixed rather than allocated, because they are referenced from the
+// terminal and from this source. `app_roles.roleid` has no sequence and no
+// default — every id in that table was assigned by hand — so nothing is being
+// worked around here.
+const (
+	// PosRoleSupervisor runs the terminal: settings, imports, price overrides,
+	// voids, and creating the people below.
+	PosRoleSupervisor = 7
+
+	// PosRoleCashier bills, and nothing else.
+	PosRoleCashier = 8
+)
+
+// PosRoleName maps a role id to what a person calls it.
+func PosRoleName(roleID int) string {
+	switch roleID {
+	case PosRoleSupervisor:
+		return "Supervisor"
+	case PosRoleCashier:
+		return "Cashier"
+	}
+	return ""
+}
+
+// PosRoleFromName reads the role off a request.
+//
+// Accepts the name rather than the number, so a caller never has to hardcode 7
+// or 8 — and returns 0 for anything unrecognised, which every caller treats as
+// a refusal rather than as a default.
+func PosRoleFromName(name string) int {
+	switch strings.ToLower(strings.TrimSpace(name)) {
+	case "supervisor":
+		return PosRoleSupervisor
+	case "cashier":
+		return PosRoleCashier
+	}
+	return 0
+}
+
+// PosRoleEligible reports whether a role may open a till at all.
+//
+// The terminal and the Nearle Daily application share one `app_users` table,
+// and that is the only thing they share. An account belongs to one product or
+// the other and never to both: a person who administers a shop from a browser
+// does not thereby get a cash drawer, and a cashier does not thereby get the
+// back office.
+//
+// Eligibility is therefore granted explicitly — by provisioning a Supervisor or
+// a Cashier from the console — and is never inherited from a back-office role.
+// Anything else is refused at sign-in, including roleid 0, which is not a role
+// but the absence of one.
+func PosRoleEligible(roleID int) bool {
+	return roleID == PosRoleSupervisor || roleID == PosRoleCashier
+}
+
+// PosRoleCanManageStaff reports whether a role may create and edit till users.
+//
+// Supervisors, and nobody else.
+//
+// This used to include the back office's own roles 1 to 6, on the reasoning
+// that somebody who can already administer a shop from a browser is not made
+// less privileged by standing at the counter. That was wrong, and live data
+// showed how wrong: it handed till-supervisor powers to 68 accounts, 59 of them
+// Nearle Daily Super admins, not one of whom is the administrator of anybody's
+// POS. The actual shop accounts carry roleid 0 and were refused.
+//
+// The back office reaches the till by *provisioning* a supervisor from the
+// console, not by becoming one at the counter.
+func PosRoleCanManageStaff(roleID int) bool {
+	return roleID == PosRoleSupervisor
+}
+
+// PosUser is a person who signs in at a till.
+type PosUser struct {
+	Userid     int    `json:"user_id"`
+	Fullname   string `json:"full_name"`
+	Firstname  string `json:"first_name,omitempty"`
+	Lastname   string `json:"last_name,omitempty"`
+	Authname   string `json:"authname,omitempty"`
+	Contactno  string `json:"contactno,omitempty"`
+	Roleid     int    `json:"role_id"`
+	Role       string `json:"role"`
+	Pin        string `json:"pin,omitempty"`
+	Haspassword bool  `json:"has_password"`
+
+	// The password, returned only in the answer to a creation or a reset and
+	// never by a listing. An admin who loses it reissues rather than looks it
+	// up — the right shape even while the column behind it is plaintext.
+	Password string `json:"password,omitempty"`
+	Locationid int    `json:"location_id"`
+	Status     string `json:"status"`
+}
+
+// PosUserRequest creates or edits a till user.
+//
+// Note what is absent: tenant and location. Both come from the caller's own
+// session token. A supervisor creating staff can only ever create them at their
+// own outlet, and no field in this struct can say otherwise — which is the same
+// inversion that stopped a till naming its own shop.
+type PosUserRequest struct {
+	Userid    int    `json:"user_id"`
+	Fullname  string `json:"full_name"`
+	Role      string `json:"role"`
+	Pin       string `json:"pin"`
+	Password  string `json:"password"`
+	Authname  string `json:"authname"`
+	Contactno string `json:"contactno"`
+	Status    string `json:"status"`
+}
+
+// PosUserWebRequest is a staff change made from the web console.
+//
+// Identical to [PosUserRequest] but for the two fields a terminal never needs
+// to send: the console has no session token, so it has to name the outlet it is
+// working on. That is the one real difference between the two doors into this,
+// and it is also the weaker one — the till's outlet is proved by a signature,
+// while this is asserted. The handler checks the outlet belongs to the tenant
+// before writing anything, which is as far as it can go without the console
+// holding a session of its own.
+type PosUserWebRequest struct {
+	PosUserRequest
+	Tenantid   int `json:"tenantid"`
+	Locationid int `json:"locationid"`
+}

models/poshealth.go

@@ -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"`
+}

models/posorder.go

@@ -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"`
+}

models/product.go

@@ -77,12 +77,27 @@ type Products struct {
 	Productcombo      int     `json:"productcombo" gorm:"default:0"`
 	Variants          int     `json:"variants" gorm:"default:0"`
 	Quantity          int     `json:"quantity"`
+	// 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"`
 	Productstatus     string  `json:"productstatus" `
+	// Populated only by queries scoped to a specific location (e.g.
+	// GetProductByVariant when locationid is passed): Productstock becomes
+	// the live SUM(in)-SUM(out) balance from productstocks — the same
+	// formula CreateOrder's stock check uses — and Locationstatus mirrors
+	// productlocations.status ("outofstock"/"available") for that store.
+	// Left at zero values for callers that don't scope to a location.
+	Locationstatus string `json:"locationstatus,omitempty" gorm:"->"`
 	// Status string `json:"status" gorm:"default:InActive"`
 	// Status string `json:"status" gorm:"-"`
 }
@@ -117,6 +132,11 @@ type Locationproducts struct {
 	Productcombo      int     `json:"productcombo" gorm:"default:0"`
 	Variants          int     `json:"variants" gorm:"default:0"`
 	Quantity          int     `json:"quantity"`
+	// 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"`
@@ -306,6 +326,66 @@ type Productlocations struct {
 	Status            string  `json:"status"`
 }
 
+// ProductLocationRef identifies a single (tenant, location, product) row in
+// productlocations — used to reactivate it after new stock arrives, the
+// per-location counterpart to CreateOrder's outofstock flag.
+type ProductLocationRef struct {
+	Tenantid   int
+	Locationid int
+	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"`

models/tenant.go

@@ -121,6 +121,10 @@ type Tenantpricing struct {
 
 type StaffInfo struct {
 	Userid        int    `json:"userid"`
+	// What the role is called, so a console does not have to map ids itself.
+	// `app_roles` holds six rows for four back-office roles and most accounts
+	// carry an id absent from it, so any mapping written client-side is wrong.
+	Rolename      string `json:"rolename"`
 	Authname      string `json:"authname"`
 	Configid      int    `json:"configid"`
 	Authmode      int    `json:"authmode"`

repositories/customerRepository.go

@@ -188,8 +188,19 @@ 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
 			FROM customers a
@@ -204,11 +215,15 @@ 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
 			FROM customers a
@@ -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
 }

repositories/deliveriesRepository.go

@@ -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
+		ord.Pending = stamp(data.Assigntime)
-		if err := tx.Table("orders").Where("orderheaderid = ?", data.Orderheaderid).Updates(&ord).Error; err != nil {
+		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
+		ord.Delivered = stamp(data.Deliverytime)
-		if err := tx.Table("orders").Where("orderheaderid = ?", data.Orderheaderid).Updates(&ord).Error; err != nil {
+		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
+		ord.Cancelled = stamp(data.Canceltime)
-		if err := tx.Table("orders").Where("orderheaderid = ?", data.Orderheaderid).Updates(&ord).Error; err != nil {
+		if err := syncOrder(); err != nil {
 			tx.Rollback()
 			return err
 		}

repositories/posAuthRepository.go

@@ -0,0 +1,428 @@
+package repositories
+
+import (
+	"fmt"
+	"strings"
+
+	"nearle/models"
+)
+
+// Sign-in for the POS terminal.
+//
+// Deliberately reads the same `app_users` rows the web console authenticates
+// against rather than introducing a terminal-specific credential table. A shop
+// manager who can sign into the back office should be able to open the till
+// with the same details, and one account store means deactivating a leaver
+// closes both doors at once instead of one and a half.
+//
+// Kept in its own file because the rest of posRepository is about moving bills
+// and stock, and mixing authorisation into that made the one thing nobody
+// should have to hunt for the hardest thing to find.
+
+// posLoginRow is the credential check's raw answer.
+type posLoginRow struct {
+	Userid     int
+	Password   string
+	Status     string
+	Roleid     int
+	Configid   int
+	Tenantid   int
+	Locationid int
+	Firstname  string
+	Lastname   string
+	Email      string
+}
+
+// PosLogin authenticates a user and returns the session they are entitled to.
+//
+// The outlet is resolved here, from the user's own row and the tenant's list of
+// locations — never from anything the caller sent. That inversion is the whole
+// point of the endpoint.
+func (r *posRepository) PosLogin(req models.PosLoginRequest) (*models.PosSession, error) {
+	field, value := "authname", strings.TrimSpace(req.Authname)
+	if value == "" {
+		field, value = "contactno", strings.TrimSpace(req.Contactno)
+	}
+	if value == "" {
+		return nil, fmt.Errorf("an email or mobile number is required")
+	}
+
+	rows, err := r.posLoginCandidates(field, value, req.Configid)
+	if err != nil {
+		return nil, err
+	}
+
+	// One message for "no such account" and for "wrong password", on purpose.
+	// Distinguishing them turns the login into a directory of who banks here.
+	if len(rows) == 0 {
+		return nil, errPosLoginRejected
+	}
+
+	// `authname` is not unique in this schema — live data has the same address
+	// twice under one configid — so more than one row can come back. Resolving
+	// that by taking the first would let the account a person *meant* be
+	// shadowed by a stranger's, and on a POS that means billing into the wrong
+	// tenant's books. Refused instead, with the fix the caller can act on.
+	if len(rows) > 1 {
+		return nil, fmt.Errorf(
+			"more than one account uses these sign-in details; ask your administrator for the configid and send it with the login")
+	}
+
+	// Inactive accounts never reach here — posLoginCandidates excludes them, so
+	// that a deactivated duplicate cannot make a live login ambiguous.
+	row := rows[0]
+
+	// Matches the web console's plaintext comparison, which is what the stored
+	// column holds today. Constant-time so this endpoint at least does not add
+	// a timing oracle on top.
+	//
+	// TODO: the password column is plaintext across the whole platform. Hashing
+	// it is a migration touching every login path, not something this endpoint
+	// can fix alone — but a POS token minted off a plaintext password is only
+	// ever as good as that column.
+	if strings.TrimSpace(row.Password) == "" {
+		return nil, fmt.Errorf("this account has no password set; set one in the web console first")
+	}
+	if !constantTimeEqual(row.Password, req.Password) {
+		return nil, errPosLoginRejected
+	}
+
+	return r.sessionFor(row, req.Locationid)
+}
+
+// sessionFor turns an authenticated account into the session it is entitled to.
+//
+// Shared by both ways in — an email and password, or a PIN at an already-open
+// terminal. Extracted rather than duplicated because everything after the
+// credential check is authorisation, and two copies of an authorisation rule
+// is one copy too many.
+//
+// [requestedLocation] is optional and only means anything for an account that
+// reaches more than one outlet. It is checked against that set, never trusted
+// on its own.
+func (r *posRepository) sessionFor(row posLoginRow, requestedLocation int) (*models.PosSession, error) {
+	// The till is not the back office, and one account is never both. An
+	// account reaches a terminal only by having been provisioned for one —
+	// Supervisor or Cashier, created from the console — and never by carrying a
+	// Nearle Daily role that happens to sound senior.
+	//
+	// Checked here rather than in PosLogin so that the PIN route is covered by
+	// the same line. Both ways in build their session through this function, and
+	// a gate on only one of them would be a gate on neither.
+	if !models.PosRoleEligible(row.Roleid) {
+		return nil, errPosRoleIneligible
+	}
+
+	if row.Tenantid <= 0 {
+		return nil, fmt.Errorf("this account is not attached to a tenant and cannot open a till")
+	}
+
+	locations, err := r.posLoginLocations(row.Tenantid, row.Locationid)
+	if err != nil {
+		return nil, err
+	}
+	if len(locations) == 0 {
+		return nil, fmt.Errorf("no active outlet is registered for this account")
+	}
+
+	// Which outlet this terminal is standing in. A request may ask for one, but
+	// only from the set the account already reaches.
+	chosen := locations[0]
+	if requestedLocation > 0 {
+		match := false
+		for _, loc := range locations {
+			if loc.Locationid == requestedLocation {
+				chosen, match = loc, true
+				break
+			}
+		}
+		if !match {
+			return nil, fmt.Errorf("this account cannot open a till at outlet %d", requestedLocation)
+		}
+	}
+
+	session := &models.PosSession{
+		Userid:         row.Userid,
+		Fullname:       strings.TrimSpace(row.Firstname + " " + row.Lastname),
+		Email:          row.Email,
+		Roleid:         row.Roleid,
+		Role:           posRoleLabel(row.Roleid),
+		Configid:       row.Configid,
+		Canmanagestaff: models.PosRoleCanManageStaff(row.Roleid),
+		Tenantid:       row.Tenantid,
+		Storeid:        fmt.Sprintf("%d", chosen.Locationid),
+		Locationid:     chosen.Locationid,
+		Locationname:   chosen.Locationname,
+		Address:        chosen.Address,
+		Locations:      locations,
+	}
+
+	r.decoratePosSession(session)
+
+	// Staff come down with the session so a till is ready to trade the moment
+	// it signs in. A failure here is not a failed sign-in: a shop with no staff
+	// recorded — which is almost all of them today — must still be able to open
+	// its terminal.
+	if staff, err := r.PosStaff(session.Tenantid, session.Locationid); err == nil {
+		session.Staff = staff
+	}
+
+	return session, nil
+}
+
+// posRoleLabel names a role for the terminal.
+//
+// Prefers the two POS roles this codebase defines, then falls back to whatever
+// `app_roles` calls it — which is blank for a great many accounts, because most
+// carry a roleid that is not in that table at all.
+func posRoleLabel(roleID int) string {
+	if name := models.PosRoleName(roleID); name != "" {
+		return name
+	}
+	switch roleID {
+	case 1:
+		return "Super admin"
+	case 2:
+		return "Operations"
+	case 3, 5:
+		return "Admin"
+	case 4, 6:
+		return "Manager"
+	}
+	return ""
+}
+
+// posLoginCandidates finds the accounts matching a set of sign-in details.
+//
+// Returns a list rather than a row because `app_users` does not constrain
+// `authname` to be unique — not globally and not per configid. The caller
+// decides what an ambiguous match means; silently picking one here would bury
+// the decision in a LIMIT 1.
+//
+// The configid handling is the part worth explaining. The web console asks for
+// it because the browser knows which tenant portal it is on. A till does not:
+// somebody is standing at a counter typing an email and a password, and
+// demanding a number they have never seen would make the login unusable. So it
+// is honoured when sent and inferred when not — and inference that finds more
+// than one candidate is reported, never guessed.
+func (r *posRepository) posLoginCandidates(field, value string, configID int) ([]posLoginRow, error) {
+	rows := make([]posLoginRow, 0, 2)
+
+	query := fmt.Sprintf(`
+		SELECT userid, COALESCE(password, '') AS password, COALESCE(status, '') AS status,
+		       COALESCE(roleid, 0) AS roleid, COALESCE(configid, 0) AS configid,
+		       COALESCE(tenantid, 0) AS tenantid, COALESCE(locationid, 0) AS locationid,
+		       COALESCE(firstname, '') AS firstname, COALESCE(lastname, '') AS lastname,
+		       COALESCE(email, '') AS email
+		FROM app_users
+		WHERE LOWER(TRIM(%s)) = LOWER(TRIM(?))`, field)
+	params := []interface{}{value}
+
+	if configID > 0 {
+		query += ` AND configid = ?`
+		params = append(params, configID)
+	}
+
+	// Inactive accounts are excluded from the match rather than matched and
+	// then refused. A deactivated duplicate would otherwise make a working
+	// login ambiguous, which turns "this person left" into "nobody can open
+	// the till".
+	query += ` AND LOWER(COALESCE(status, 'active')) <> 'inactive' ORDER BY userid`
+
+	if err := r.db.Raw(query, params...).Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+// posLoginLocations lists the outlets an account may open a till at.
+//
+// A user pinned to one location gets that one alone; a tenant-level account
+// with locationid 0 — a proprietor with several shops — gets all of the
+// tenant's active outlets and picks at sign-in.
+//
+// Inactive outlets are excluded rather than listed and disabled: a till cannot
+// usefully trade at a closed shop, and offering it is an invitation to a
+// support call.
+func (r *posRepository) posLoginLocations(tenantID, pinned int) ([]models.PosLoginLocation, error) {
+	rows := make([]models.PosLoginLocation, 0)
+
+	query := `
+		SELECT locationid,
+		       COALESCE(locationname, '') AS locationname,
+		       COALESCE(address, '')      AS address,
+		       COALESCE(city, '')         AS city,
+		       COALESCE(status, '')       AS status
+		FROM tenantlocations
+		WHERE tenantid = ? AND LOWER(COALESCE(status, 'active')) <> 'inactive'`
+	params := []interface{}{tenantID}
+
+	if pinned > 0 {
+		query += ` AND locationid = ?`
+		params = append(params, pinned)
+	}
+	query += ` ORDER BY locationid`
+
+	if err := r.db.Raw(query, params...).Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+// decoratePosSession fills in what a receipt needs.
+//
+// The store name, GSTIN and address printed on a bill are a legal requirement
+// on a GST invoice, and the till had them as compile-time constants. Sending
+// them down with the session means a shop that corrects its GSTIN in the back
+// office sees the correction on its next receipt rather than at the next
+// rebuild.
+//
+// Failures here are swallowed: a missing tenant name is a cosmetic problem, and
+// refusing a sign-in over it would close a shop.
+func (r *posRepository) decoratePosSession(session *models.PosSession) {
+	var tenant struct {
+		Tenantname string
+		Gstin      string
+		Contactno  string
+		Address    string
+	}
+
+	// `registrationno` is where this schema keeps the GST number — there is no
+	// `gstin` column. Aliased rather than renamed through the stack so the till
+	// receives it under the name it prints on a receipt.
+	err := r.db.Raw(`
+		SELECT COALESCE(tenantname, '')       AS tenantname,
+		       COALESCE(registrationno, '')   AS gstin,
+		       COALESCE(primarycontact, '')   AS contactno,
+		       COALESCE(address, '')          AS address
+		FROM tenants WHERE tenantid = ? LIMIT 1`, session.Tenantid).Scan(&tenant).Error
+	if err != nil {
+		return
+	}
+
+	session.Tenantname = tenant.Tenantname
+	session.Gstin = tenant.Gstin
+	session.Phone = tenant.Contactno
+
+	// The outlet's own address wins — a chain's receipts must name the shop the
+	// customer is standing in, not head office. The tenant address is only a
+	// fallback for an outlet that has none recorded.
+	if strings.TrimSpace(session.Address) == "" {
+		session.Address = tenant.Address
+	}
+}
+
+// PosLocationAllowed reports whether a tenant owns an outlet.
+//
+// The check the whole session model rests on. Everything a terminal asks for
+// names a location, and this is what stops a valid token for one shop being
+// replayed against another.
+func (r *posRepository) PosLocationAllowed(tenantID, locationID int) (bool, error) {
+	if tenantID <= 0 || locationID <= 0 {
+		return false, nil
+	}
+
+	var count int64
+	err := r.db.Raw(
+		`SELECT COUNT(1) FROM tenantlocations WHERE tenantid = ? AND locationid = ?`,
+		tenantID, locationID,
+	).Scan(&count).Error
+	if err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+// errPosLoginRejected is the single answer to a bad email and a bad password.
+var errPosLoginRejected = fmt.Errorf("those sign-in details were not recognised")
+
+// errPosRoleIneligible is the answer to a correct credential on an account that
+// is not a till account.
+//
+// Deliberately specific, where a bad password is deliberately vague. By the
+// time this fires the caller has already proved the credential, so naming the
+// reason leaks nothing they did not just demonstrate — and the vague answer
+// would send a shop owner hunting for a password that was never wrong. It
+// names the fix, because the fix is somebody else's screen.
+var errPosRoleIneligible = fmt.Errorf(
+	"this account is not set up for the till; ask your store admin to add you as a Supervisor or Cashier in the web console")
+
+// PosLoginRejected reports whether an error is a failed credential check, so
+// the controller can answer 401 for those and 500 for a database fault without
+// matching on message text.
+func PosLoginRejected(err error) bool { return err == errPosLoginRejected }
+
+// constantTimeEqual compares two secrets without leaking their contents through
+// how long it took.
+//
+// Length is compared first and is deliberately allowed to leak — a password's
+// length is not the secret, and hashing to a fixed width just to hide it would
+// be more machinery than the exposure justifies.
+func constantTimeEqual(a, b string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	var diff byte
+	for i := 0; i < len(a); i++ {
+		diff |= a[i] ^ b[i]
+	}
+	return diff == 0
+}
+
+// PosStaff lists the people who may ring a bill at an outlet.
+//
+// Two sources, unioned, because the schema has two and neither is complete.
+// `tenantstaffs` is the table built for this and holds 12 rows on the entire
+// platform; `app_users.locationid` is where staff actually ended up. Reading
+// only the purpose-built table would return nothing for almost every shop, and
+// reading only `app_users` would miss anyone assigned through the back office's
+// staff screen. So both.
+//
+// Only people with a PIN come back. A row with `pin = 0` cannot ring anything —
+// offering it to the till would put a name on screen that no one can sign in
+// as, which reads as a broken terminal rather than as an unfinished setup.
+func (r *posRepository) PosStaff(tenantID, locationID int) ([]models.PosStaffMember, error) {
+	rows := make([]models.PosStaffMember, 0)
+
+	query := `
+		SELECT DISTINCT
+		       a.userid,
+		       TRIM(CONCAT(COALESCE(a.firstname,''), ' ', COALESCE(a.lastname,''))) AS fullname,
+		       COALESCE(r.rolename, '')  AS role,
+		       CAST(a.pin AS TEXT)       AS pin,
+		       COALESCE(a.status, '')    AS status
+		FROM app_users a
+		LEFT JOIN app_roles r ON r.roleid = a.roleid
+		WHERE a.tenantid = ?
+		  AND COALESCE(a.pin, 0) > 0
+		  AND LOWER(COALESCE(a.status, 'active')) <> 'inactive'
+		  AND (
+		        a.locationid = ?
+		     OR EXISTS (SELECT 1 FROM tenantstaffs s
+		                WHERE s.userid = a.userid
+		                  AND s.tenantid = a.tenantid
+		                  AND s.locationid = ?
+		                  AND LOWER(COALESCE(s.status, 'active')) <> 'inactive')
+		  )
+		ORDER BY fullname`
+
+	if err := r.db.Raw(query, tenantID, locationID, locationID).Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+
+	// A PIN shared by two people at one outlet would make the till attribute a
+	// bill to whichever row it happened to check first — so the second one is
+	// dropped rather than sent. Live data has 1234 on eleven accounts and 1111
+	// on nine, so this is not hypothetical.
+	seen := make(map[string]bool, len(rows))
+	unique := rows[:0]
+	for _, row := range rows {
+		if seen[row.Pin] {
+			continue
+		}
+		seen[row.Pin] = true
+		unique = append(unique, row)
+	}
+
+	return unique, nil
+}

repositories/posPresence.go

@@ -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
+}

repositories/posRepository.go

@@ -0,0 +1,859 @@
+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)
+
+	// Sign-in. The outlet a terminal bills for is decided here, from the user's
+	// own record, rather than being named by the till and believed.
+	PosLogin(req models.PosLoginRequest) (*models.PosSession, error)
+	PosLocationAllowed(tenantID, locationID int) (bool, error)
+	PosStaff(tenantID, locationID int) ([]models.PosStaffMember, error)
+
+	// Till staff, managed by the shop. Tenant and location are always the
+	// caller's own, taken from their session token — no argument here can name
+	// somebody else's outlet.
+	CreatePosUser(tenantID, locationID, configID int, req models.PosUserRequest) (*models.PosUser, error)
+	UpdatePosUser(tenantID, locationID int, req models.PosUserRequest) (*models.PosUser, error)
+	ListPosUsers(tenantID, locationID int, includeInactive bool) ([]models.PosUser, error)
+	DeactivatePosUser(tenantID, locationID, userID int) error
+	PosLoginByPin(tenantID, locationID int, pin string) (*models.PosSession, error)
+	PosConfigidFor(tenantID int) int
+
+	// 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"
+	}
+}

repositories/posRepository_test.go

@@ -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)
+	}
+}

repositories/posSalesRepository.go

@@ -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
+}

repositories/posUserRepository.go

@@ -0,0 +1,627 @@
+package repositories
+
+import (
+	"crypto/rand"
+	"fmt"
+	"math/big"
+	"strconv"
+	"strings"
+
+	"nearle/models"
+
+	"gorm.io/gorm"
+)
+
+// Till staff, managed by the shop rather than by us.
+//
+// A supervisor creates their own cashiers, at their own outlet, from the
+// terminal. Everything here follows one rule: **the tenant and the outlet come
+// from the caller's session token and never from the request body.** A
+// supervisor at Selvapuram cannot create a cashier at R mart by sending a
+// different number, for the same reason a till cannot bill into another shop.
+
+// PosPinMin and PosPinMax bound an acceptable PIN.
+//
+// Four digits, and never starting with a zero — because `app_users.pin` is a
+// `bigint`. A PIN of "0451" would be stored as 451 and read back as three
+// digits, so a cashier would type four and be refused for ever. Live data
+// already holds one such account.
+//
+// Refusing the leading zero costs a shop 1000 of 10000 combinations and buys a
+// PIN that means the same thing on the way in and on the way out.
+const (
+	PosPinMin = 1000
+	PosPinMax = 9999
+)
+
+// posDefaultAuthname is the username a till account gets when nobody names one.
+//
+// Keyed on the outlet and the role rather than on the person, so it survives
+// staff turnover: a shop replacing its cashier reissues one password instead of
+// re-teaching a new address. `nth` disambiguates a second account of the same
+// role at the same counter and is omitted for the first, so the common case
+// stays the readable one.
+//
+// The domain is deliberately not a real one. These are till credentials, never
+// a mailbox, and an address that looks deliverable invites somebody to try
+// sending a reset to it.
+func posDefaultAuthname(roleID, locationID, nth int) string {
+	role := strings.ToLower(models.PosRoleName(roleID))
+	if role == "" {
+		role = "staff"
+	}
+	if nth > 1 {
+		return fmt.Sprintf("%s%d.%d@pos.nearle.in", role, nth, locationID)
+	}
+	return fmt.Sprintf("%s.%d@pos.nearle.in", role, locationID)
+}
+
+// newPosPassword generates a till password.
+//
+// From crypto/rand, and returned to the caller exactly once — at creation —
+// because the column it lands in is plaintext and reading it back later should
+// take a deliberate query rather than an ordinary list call.
+//
+// The alphabet drops l, I, O, 0 and 1. These get read off one screen and typed
+// on another by somebody with a queue in front of them.
+func newPosPassword() string {
+	const alphabet = "abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+	out := make([]byte, 14)
+	for i := range out {
+		n, err := rand.Int(rand.Reader, big.NewInt(int64(len(alphabet))))
+		if err != nil {
+			// crypto/rand failing is not a condition to paper over with a
+			// weaker source; a guessable till password is worse than no till.
+			panic(fmt.Sprintf("generating a till password: %v", err))
+		}
+		out[i] = alphabet[n.Int64()]
+	}
+	return string(out)
+}
+
+// CreatePosUser adds a cashier or supervisor at the caller's outlet.
+func (r *posRepository) CreatePosUser(tenantID, locationID, configID int, req models.PosUserRequest) (*models.PosUser, error) {
+	roleID := models.PosRoleFromName(req.Role)
+	if roleID == 0 {
+		return nil, fmt.Errorf("role must be 'supervisor' or 'cashier'")
+	}
+
+	name := strings.TrimSpace(req.Fullname)
+	if name == "" {
+		return nil, fmt.Errorf("a name is required")
+	}
+	first, last := splitName(name)
+
+	pin, err := validatePosPin(req.Pin)
+	if err != nil {
+		return nil, err
+	}
+
+	password := strings.TrimSpace(req.Password)
+	authname := strings.ToLower(strings.TrimSpace(req.Authname))
+
+	// Every till account gets a username and a password, cashiers included.
+	//
+	// A PIN cannot open a *closed* terminal — the PIN route needs a session that
+	// already exists — so a PIN-only cashier can work only while a supervisor is
+	// standing there to unlock the till first. That is not how a shop opens: the
+	// person who arrives at seven is as often the cashier as the supervisor.
+	//
+	// Generated when the console does not supply them, so provisioning is one
+	// call and nobody has to invent a scheme. An explicit value always wins: a
+	// shop that wants its people signing in as themselves just sends one.
+	//
+	// Whether the name was generated is remembered, because the two cases want
+	// opposite handling on a collision — see the uniqueness check below.
+	nameWasGenerated := authname == ""
+	if nameWasGenerated {
+		authname = posDefaultAuthname(roleID, locationID, 0)
+	}
+	if password == "" {
+		password = newPosPassword()
+	}
+
+	// A PIN stays optional. It switches operator at an open counter, which not
+	// every shop does, and it is the one credential the till keeps in plaintext
+	// to hand around — so it is set deliberately, never by default.
+
+	var created *models.PosUser
+
+	err = r.db.Transaction(func(tx *gorm.DB) error {
+		// The advisory lock is for the PIN check below, not for the id.
+		//
+		// `userid` is an identity column — `information_schema.column_default`
+		// is empty for those, which is easy to misread as "no default at all"
+		// and was misread here once. Postgres allocates it, and this must not
+		// compute its own: an explicit id does not advance the sequence, so a
+		// hand-rolled MAX+1 leaves two allocators running in parallel that
+		// eventually land on the same number.
+		//
+		// The lock still earns its place. Two supervisors adding staff at the
+		// same instant could otherwise both find a PIN free and both take it,
+		// and a duplicate PIN attributes a bill to whichever row is read first.
+		if err := tx.Exec(`SELECT pg_advisory_xact_lock(hashtext('app_users'))`).Error; err != nil {
+			return err
+		}
+
+		if pin > 0 {
+			taken, err := posPinTaken(tx, tenantID, locationID, pin, 0)
+			if err != nil {
+				return err
+			}
+			if taken {
+				return fmt.Errorf("another person at this outlet already uses that PIN")
+			}
+		}
+
+		// Uniqueness is checked against `authname` and `email` together because
+		// the insert below writes the same value to both, and
+		// `app_users_email_unique` is a real constraint — a clash there fails the
+		// transaction rather than returning a message anyone can act on.
+		taken := func(candidate string) (bool, error) {
+			var n int64
+			err := tx.Raw(`SELECT COUNT(1) FROM app_users
+			               WHERE LOWER(TRIM(authname)) = ? OR LOWER(TRIM(email)) = ?`,
+				candidate, candidate).Scan(&n).Error
+			return n > 0, err
+		}
+
+		if nameWasGenerated {
+			// Walk to the first free one. Bounded so a bug here cannot spin:
+			// twenty till accounts of one role at a single outlet is already far
+			// past what a counter has, and the error names the fix.
+			found := false
+			for i := 0; i < 20; i++ {
+				clash, err := taken(authname)
+				if err != nil {
+					return err
+				}
+				if !clash {
+					found = true
+					break
+				}
+				authname = posDefaultAuthname(roleID, locationID, i+2)
+			}
+			if !found {
+				return fmt.Errorf("this outlet already has too many %s accounts; supply an email explicitly",
+					strings.ToLower(models.PosRoleName(roleID)))
+			}
+		} else {
+			clash, err := taken(authname)
+			if err != nil {
+				return err
+			}
+			if clash {
+				return fmt.Errorf("an account already uses %s", authname)
+			}
+		}
+
+		// `userid` is omitted so the identity column allocates it, and read back
+		// with RETURNING rather than guessed.
+		//
+		// The email columns go through NULLIF because `app_users_email_unique`
+		// is a real constraint: a second person created without an email would
+		// collide on the empty string, while NULLs do not collide in Postgres.
+		// A cashier who signs in by PIN alone has no email, and that is the
+		// common case.
+		var nextID int
+		if err := tx.Raw(`
+			INSERT INTO app_users
+			  (firstname, lastname, authname, email, contactno, password,
+			   pin, roleid, configid, tenantid, locationid, status)
+			VALUES (?, ?, NULLIF(?, ''), NULLIF(?, ''), NULLIF(?, ''), NULLIF(?, ''),
+			        NULLIF(?, 0), ?, ?, ?, ?, 'Active')
+			RETURNING userid`,
+			first, last, authname, authname, strings.TrimSpace(req.Contactno),
+			password, pin, roleID, configID, tenantID, locationID,
+		).Scan(&nextID).Error; err != nil {
+			return err
+		}
+		if nextID <= 0 {
+			return fmt.Errorf("the account was not created")
+		}
+
+		created = &models.PosUser{
+			Userid:      nextID,
+			Fullname:    name,
+			Firstname:   first,
+			Lastname:    last,
+			Authname:    authname,
+			Contactno:   strings.TrimSpace(req.Contactno),
+			Roleid:      roleID,
+			Role:        models.PosRoleName(roleID),
+			Pin:         posPinString(pin),
+			Haspassword: password != "",
+			Locationid:  locationID,
+			Status:      "Active",
+
+			// The one moment this is ever returned. Listing a till user reports
+			// only whether a password exists, so an admin who loses this has to
+			// reissue rather than look it up — which is the right shape even
+			// while the column itself is plaintext.
+			Password: password,
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	return created, nil
+}
+
+// UpdatePosUser edits a till user at the caller's outlet.
+//
+// Scoped by tenant *and* location in the WHERE clause rather than checked
+// first: a supervisor sending somebody else's user id updates no rows and is
+// told so, instead of quietly editing another shop's staff.
+func (r *posRepository) UpdatePosUser(tenantID, locationID int, req models.PosUserRequest) (*models.PosUser, error) {
+	if req.Userid <= 0 {
+		return nil, fmt.Errorf("user_id is required")
+	}
+
+	sets := []string{}
+	args := []interface{}{}
+
+	if name := strings.TrimSpace(req.Fullname); name != "" {
+		first, last := splitName(name)
+		sets = append(sets, "firstname = ?", "lastname = ?")
+		args = append(args, first, last)
+	}
+
+	if role := strings.TrimSpace(req.Role); role != "" {
+		roleID := models.PosRoleFromName(role)
+		if roleID == 0 {
+			return nil, fmt.Errorf("role must be 'supervisor' or 'cashier'")
+		}
+		sets = append(sets, "roleid = ?")
+		args = append(args, roleID)
+	}
+
+	pin := int64(0)
+	if strings.TrimSpace(req.Pin) != "" {
+		p, err := validatePosPin(req.Pin)
+		if err != nil {
+			return nil, err
+		}
+		pin = p
+		sets = append(sets, "pin = ?")
+		args = append(args, pin)
+	}
+
+	// The username a supervisor opens a closed terminal with.
+	//
+	// Editable because a password on its own is unusable: sign-in matches on
+	// `authname` or `contactno`, so an account given a password and no username
+	// cannot be reached by either. This was missing, and the failure was silent
+	// — the update reported success, wrote the password, dropped the username,
+	// and the supervisor was refused at the counter with "not recognised".
+	if authname := strings.TrimSpace(req.Authname); authname != "" {
+		sets = append(sets, "authname = ?")
+		args = append(args, authname)
+	}
+
+	if contactno := strings.TrimSpace(req.Contactno); contactno != "" {
+		sets = append(sets, "contactno = ?")
+		args = append(args, contactno)
+	}
+
+	if password := strings.TrimSpace(req.Password); password != "" {
+		sets = append(sets, "password = ?")
+		args = append(args, password)
+	}
+
+	if status := strings.TrimSpace(req.Status); status != "" {
+		sets = append(sets, "status = ?")
+		args = append(args, status)
+	}
+
+	if len(sets) == 0 {
+		return nil, fmt.Errorf("nothing to change")
+	}
+
+	err := r.db.Transaction(func(tx *gorm.DB) error {
+		if err := tx.Exec(`SELECT pg_advisory_xact_lock(hashtext('app_users'))`).Error; err != nil {
+			return err
+		}
+
+		if pin > 0 {
+			taken, err := posPinTaken(tx, tenantID, locationID, pin, req.Userid)
+			if err != nil {
+				return err
+			}
+			if taken {
+				return fmt.Errorf("another person at this outlet already uses that PIN")
+			}
+		}
+
+		query := fmt.Sprintf(
+			`UPDATE app_users SET %s WHERE userid = ? AND tenantid = ? AND locationid = ?`,
+			strings.Join(sets, ", "))
+		args = append(args, req.Userid, tenantID, locationID)
+
+		result := tx.Exec(query, args...)
+		if result.Error != nil {
+			return result.Error
+		}
+		if result.RowsAffected == 0 {
+			return fmt.Errorf("no user %d at this outlet", req.Userid)
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	users, err := r.ListPosUsers(tenantID, locationID, true)
+	if err != nil {
+		return nil, err
+	}
+	for i := range users {
+		if users[i].Userid == req.Userid {
+			return &users[i], nil
+		}
+	}
+	return nil, nil
+}
+
+// ListPosUsers returns the till users at an outlet.
+func (r *posRepository) ListPosUsers(tenantID, locationID int, includeInactive bool) ([]models.PosUser, error) {
+	rows := make([]struct {
+		Userid      int
+		Firstname   string
+		Lastname    string
+		Authname    string
+		Contactno   string
+		Roleid      int
+		Pin         int64
+		Haspassword bool
+		Status      string
+	}, 0)
+
+	query := `
+		SELECT userid,
+		       COALESCE(firstname,'') AS firstname, COALESCE(lastname,'') AS lastname,
+		       COALESCE(authname,'')  AS authname,  COALESCE(contactno,'') AS contactno,
+		       COALESCE(roleid,0)     AS roleid,    COALESCE(pin,0)        AS pin,
+		       (COALESCE(password,'') <> '') AS haspassword,
+		       COALESCE(status,'')    AS status
+		FROM app_users
+		WHERE tenantid = ? AND locationid = ?
+		  AND COALESCE(roleid,0) IN (?, ?)`
+	params := []interface{}{tenantID, locationID, models.PosRoleSupervisor, models.PosRoleCashier}
+
+	if !includeInactive {
+		query += ` AND LOWER(COALESCE(status,'active')) <> 'inactive'`
+	}
+	query += ` ORDER BY userid`
+
+	if err := r.db.Raw(query, params...).Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+
+	users := make([]models.PosUser, 0, len(rows))
+	for _, row := range rows {
+		users = append(users, models.PosUser{
+			Userid:      row.Userid,
+			Fullname:    strings.TrimSpace(row.Firstname + " " + row.Lastname),
+			Firstname:   row.Firstname,
+			Lastname:    row.Lastname,
+			Authname:    row.Authname,
+			Contactno:   row.Contactno,
+			Roleid:      row.Roleid,
+			Role:        models.PosRoleName(row.Roleid),
+			Pin:         posPinString(row.Pin),
+			Haspassword: row.Haspassword,
+			Locationid:  locationID,
+			Status:      row.Status,
+		})
+	}
+	return users, nil
+}
+
+// DeactivatePosUser retires somebody without deleting them.
+//
+// Bills carry the cashier's name and shifts settle against it, so a hard delete
+// would orphan a day's takings.
+func (r *posRepository) DeactivatePosUser(tenantID, locationID, userID int) error {
+	result := r.db.Exec(`
+		UPDATE app_users SET status = 'InActive'
+		WHERE userid = ? AND tenantid = ? AND locationid = ?
+		  AND COALESCE(roleid,0) IN (?, ?)`,
+		userID, tenantID, locationID, models.PosRoleSupervisor, models.PosRoleCashier)
+
+	if result.Error != nil {
+		return result.Error
+	}
+	if result.RowsAffected == 0 {
+		// Either no such person, or they belong to another shop, or they are a
+		// back-office account rather than till staff. One message for all three
+		// — distinguishing them tells a caller about rows they cannot see.
+		return fmt.Errorf("no till user %d at this outlet", userID)
+	}
+	return nil
+}
+
+// PosLoginByPin signs somebody in with a PIN alone, inside an outlet.
+//
+// A PIN is four digits, so this must never be reachable by an anonymous caller
+// — ten thousand guesses is not a barrier. It is only called with a tenant and
+// location taken from an *already valid* session token, which means a
+// supervisor has opened the terminal with a real password first and the guesses
+// are confined to one outlet's own staff.
+func (r *posRepository) PosLoginByPin(tenantID, locationID int, pin string) (*models.PosSession, error) {
+	value, err := validatePosPin(pin)
+	if err != nil {
+		return nil, errPosLoginRejected
+	}
+
+	var rows []posLoginRow
+	err = r.db.Raw(`
+		SELECT userid, COALESCE(password,'') AS password, COALESCE(status,'') AS status,
+		       COALESCE(roleid,0) AS roleid, COALESCE(configid,0) AS configid,
+		       COALESCE(tenantid,0) AS tenantid, COALESCE(locationid,0) AS locationid,
+		       COALESCE(firstname,'') AS firstname, COALESCE(lastname,'') AS lastname,
+		       COALESCE(email,'') AS email
+		FROM app_users
+		WHERE tenantid = ? AND locationid = ? AND pin = ?
+		  AND LOWER(COALESCE(status,'active')) <> 'inactive'
+		ORDER BY userid`, tenantID, locationID, value).Scan(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+
+	if len(rows) == 0 {
+		return nil, errPosLoginRejected
+	}
+	// Two people on one PIN would attribute a bill to whichever row was read
+	// first. Creation refuses a duplicate, but data predating this endpoint
+	// need not have, so it is refused here too rather than guessed.
+	if len(rows) > 1 {
+		return nil, fmt.Errorf("more than one person at this outlet uses that PIN; ask a supervisor to change one of them")
+	}
+
+	return r.sessionFor(rows[0], locationID)
+}
+
+// posPinTaken reports whether a PIN is already in use at an outlet.
+//
+// Scoped to the outlet rather than globally, because a PIN only ever
+// distinguishes people standing at the same counter — making them unique across
+// the platform would exhaust nine thousand combinations very quickly.
+func posPinTaken(tx *gorm.DB, tenantID, locationID int, pin int64, exceptUser int) (bool, error) {
+	var count int64
+	err := tx.Raw(`
+		SELECT COUNT(1) FROM app_users
+		WHERE tenantid = ? AND locationid = ? AND pin = ? AND userid <> ?
+		  AND LOWER(COALESCE(status,'active')) <> 'inactive'`,
+		tenantID, locationID, pin, exceptUser).Scan(&count).Error
+	return count > 0, err
+}
+
+// validatePosPin checks a PIN is one this schema can store faithfully.
+func validatePosPin(raw string) (int64, error) {
+	pin := strings.TrimSpace(raw)
+	if pin == "" {
+		return 0, nil
+	}
+
+	if len(pin) != 4 {
+		return 0, fmt.Errorf("a PIN is exactly 4 digits")
+	}
+	value, err := strconv.ParseInt(pin, 10, 64)
+	if err != nil {
+		return 0, fmt.Errorf("a PIN is digits only")
+	}
+	if value < PosPinMin || value > PosPinMax {
+		// Which is to say: it started with a zero. Said plainly, because "a PIN
+		// is 4 digits" would be baffling to somebody who just typed four.
+		return 0, fmt.Errorf("a PIN cannot start with 0")
+	}
+
+	// The first thing anyone tries, and live data already has 1234 on eleven
+	// accounts and 1111 on nine.
+	switch pin {
+	case "1234", "1111", "0000", "2345", "3456", "4321", "9999", "2222":
+		return 0, fmt.Errorf("that PIN is too easy to guess; choose another")
+	}
+
+	return value, nil
+}
+
+// posPinString renders a stored PIN.
+//
+// Anything the schema cannot represent as four digits comes back empty rather
+// than short: a three-digit PIN on screen is one a cashier cannot type, and
+// showing it would send them to a supervisor for a fault they cannot describe.
+func posPinString(pin int64) string {
+	if pin < PosPinMin || pin > PosPinMax {
+		return ""
+	}
+	return strconv.FormatInt(pin, 10)
+}
+
+// splitName turns a typed name into the two columns this schema has.
+func splitName(full string) (first, last string) {
+	parts := strings.Fields(strings.TrimSpace(full))
+	if len(parts) == 0 {
+		return "", ""
+	}
+	if len(parts) == 1 {
+		return parts[0], ""
+	}
+	return parts[0], strings.Join(parts[1:], " ")
+}
+
+// ValidateStaffUser applies the till's rules to a staff row from anywhere.
+//
+// Exported because the web console writes `app_users` too, through
+// `tenants/createstaff`, and that path had no validation whatsoever — no PIN
+// rules, no role check, no duplicate check. A cashier created there could be
+// given "0451", which a bigint column stores as 451, and would then type four
+// digits at the counter and be refused for ever with nothing to explain it.
+//
+// Two paths writing one table drift apart. This is the shared rule set, so a
+// person created from a browser and a person created from a till are subject to
+// the same constraints and behave the same way at the counter.
+//
+// Returns the parsed PIN, or an error a caller can show to whoever typed it.
+func ValidateStaffUser(user *models.User) (int64, error) {
+	if strings.TrimSpace(user.Firstname+user.Lastname) == "" {
+		return 0, fmt.Errorf("a name is required")
+	}
+
+	// Only the roles this platform actually defines. `roleid` 0 is the one that
+	// matters: it is not a role, it is what a row carries when nobody set one,
+	// and live data has riders and shop accounts sharing it.
+	if user.Roleid <= 0 {
+		return 0, fmt.Errorf("a role is required")
+	}
+
+	pin := int64(user.Pin)
+	if pin != 0 {
+		parsed, err := validatePosPin(strconv.FormatInt(pin, 10))
+		if err != nil {
+			return 0, err
+		}
+		pin = parsed
+	}
+
+	if pin == 0 && strings.TrimSpace(user.Password) == "" {
+		return 0, fmt.Errorf("set a PIN, a password, or both — otherwise this person cannot sign in")
+	}
+
+	return pin, nil
+}
+
+// StaffPinAvailable reports whether a PIN is free at an outlet.
+//
+// Exported for the same reason as [ValidateStaffUser]: the web console needs
+// the check the till already makes. Two people sharing a PIN would attribute a
+// bill to whichever row happened to be read first.
+func (r *posRepository) StaffPinAvailable(tenantID, locationID int, pin int64, exceptUser int) (bool, error) {
+	if pin == 0 {
+		return true, nil
+	}
+	taken, err := posPinTaken(r.db, tenantID, locationID, pin, exceptUser)
+	return !taken, err
+}
+
+// PosConfigidFor returns the configid an outlet's people already use.
+//
+// The console cannot sensibly be asked for this. It is a number nobody looks
+// up, it varies per tenant — live data has tenant 1087 spread across 1, 6 and
+// 15 — and getting it wrong creates an account that cannot sign into the portal
+// its colleagues use and is invisible to half the platform's queries.
+//
+// So it is inferred from whichever value that tenant's existing accounts most
+// commonly carry. Returns 0 for a tenant with no accounts at all, which is
+// simply what a fresh tenant looks like.
+func (r *posRepository) PosConfigidFor(tenantID int) int {
+	var configID int
+	r.db.Raw(`SELECT COALESCE(configid, 0) FROM app_users
+	          WHERE tenantid = ? AND COALESCE(configid, 0) > 0
+	          GROUP BY configid ORDER BY COUNT(*) DESC, configid LIMIT 1`,
+		tenantID).Scan(&configID)
+	return configID
+}

repositories/posUserRepository_test.go

@@ -0,0 +1,213 @@
+package repositories
+
+import (
+	"testing"
+
+	"nearle/models"
+)
+
+// A PIN has to survive a round trip through a `bigint` column, and has to be
+// hard enough to guess to be worth having. These cover both, because the schema
+// makes the first one non-obvious.
+
+func TestAPinMustSurviveTheColumnItIsStoredIn(t *testing.T) {
+	// `app_users.pin` is a bigint. "0451" stored there comes back as 451, so a
+	// cashier would type four digits and be refused for ever. Live data already
+	// holds one such account.
+	if _, err := validatePosPin("0451"); err == nil {
+		t.Fatal("a PIN starting with zero was accepted; it cannot round-trip through a bigint")
+	}
+
+	value, err := validatePosPin("4821")
+	if err != nil {
+		t.Fatalf("a good PIN was refused: %v", err)
+	}
+	if value != 4821 {
+		t.Fatalf("PIN parsed to %d, want 4821", value)
+	}
+}
+
+func TestAPinIsExactlyFourDigits(t *testing.T) {
+	for _, pin := range []string{"123", "12345", "abcd", "12a4", "  12 "} {
+		if _, err := validatePosPin(pin); err == nil {
+			t.Errorf("PIN %q was accepted", pin)
+		}
+	}
+}
+
+// The first thing anyone tries. Live data has 1234 on eleven accounts and 1111
+// on nine, which is exactly the outcome this prevents repeating.
+func TestAnObviousPinIsRefused(t *testing.T) {
+	for _, pin := range []string{"1234", "1111", "2345", "4321", "9999", "2222"} {
+		if _, err := validatePosPin(pin); err == nil {
+			t.Errorf("PIN %q was accepted despite being one of the first guessed", pin)
+		}
+	}
+}
+
+// An empty PIN is not an error — somebody may be given a password instead. The
+// caller decides whether having neither is a problem.
+func TestAnAbsentPinIsNotAnError(t *testing.T) {
+	value, err := validatePosPin("")
+	if err != nil {
+		t.Fatalf("an absent PIN was treated as invalid: %v", err)
+	}
+	if value != 0 {
+		t.Fatalf("an absent PIN parsed to %d, want 0", value)
+	}
+}
+
+// A stored PIN the schema cannot represent as four digits comes back empty
+// rather than short, because a three-digit PIN on screen is one a cashier
+// cannot type — and they would have no way to describe the fault.
+func TestAnUnrepresentablePinIsNotShown(t *testing.T) {
+	if got := posPinString(451); got != "" {
+		t.Fatalf("a three-digit PIN rendered as %q, want empty", got)
+	}
+	if got := posPinString(0); got != "" {
+		t.Fatalf("an unset PIN rendered as %q, want empty", got)
+	}
+	if got := posPinString(4821); got != "4821" {
+		t.Fatalf("PIN rendered as %q, want 4821", got)
+	}
+}
+
+func TestANameIsSplitAcrossTheTwoColumnsThisSchemaHas(t *testing.T) {
+	cases := []struct {
+		in          string
+		first, last string
+	}{
+		{"Asha", "Asha", ""},
+		{"Asha Kumar", "Asha", "Kumar"},
+		{"Ragul Kannan Selvam", "Ragul", "Kannan Selvam"},
+		{"   Divya   R  ", "Divya", "R"},
+		{"", "", ""},
+	}
+
+	for _, tc := range cases {
+		first, last := splitName(tc.in)
+		if first != tc.first || last != tc.last {
+			t.Errorf("splitName(%q) = (%q, %q), want (%q, %q)",
+				tc.in, first, last, tc.first, tc.last)
+		}
+	}
+}
+
+// Only a role that can actually be checked should grant anything. Zero is the
+// one that matters: it is not a role, it is what an account carries when nobody
+// set one, and live data has riders and shop accounts sharing it.
+func TestOnlyRealRolesCanManageStaff(t *testing.T) {
+	if models.PosRoleCanManageStaff(0) {
+		t.Error("roleid 0 was allowed to manage staff; it is unset, not a role")
+	}
+	if models.PosRoleCanManageStaff(models.PosRoleCashier) {
+		t.Error("a cashier was allowed to manage staff, so could promote themselves")
+	}
+	if !models.PosRoleCanManageStaff(models.PosRoleSupervisor) {
+		t.Error("a supervisor was refused staff management, which is their whole purpose")
+	}
+	// A Nearle Daily role is not a POS role. This once granted staff management
+	// to 1 through 6, on the reasoning that a browser administrator loses
+	// nothing by standing at the counter — which handed till-supervisor powers
+	// to 68 live accounts, 59 of them platform Super admins, not one of them
+	// anybody's POS administrator. The back office provisions a supervisor; it
+	// does not become one.
+	for _, role := range []int{1, 2, 3, 4, 5, 6} {
+		if models.PosRoleCanManageStaff(role) {
+			t.Errorf("back-office role %d was granted till staff management", role)
+		}
+	}
+}
+
+// The till and the Nearle Daily application share one table and nothing else.
+// Eligibility is provisioned, never inherited.
+func TestOnlyPosRolesCanOpenATill(t *testing.T) {
+	for _, role := range []int{models.PosRoleSupervisor, models.PosRoleCashier} {
+		if !models.PosRoleEligible(role) {
+			t.Errorf("POS role %d was refused a till", role)
+		}
+	}
+	// Zero matters most: it is not a role but the absence of one, and 22 live
+	// accounts carry it, including a delivery rider.
+	for _, role := range []int{0, 1, 2, 3, 4, 5, 6, 9, 99, -1} {
+		if models.PosRoleEligible(role) {
+			t.Errorf("non-POS role %d was allowed to open a till", role)
+		}
+	}
+}
+
+func TestARoleIsReadFromItsNameNotItsNumber(t *testing.T) {
+	if got := models.PosRoleFromName("supervisor"); got != models.PosRoleSupervisor {
+		t.Errorf("supervisor = %d, want %d", got, models.PosRoleSupervisor)
+	}
+	if got := models.PosRoleFromName("  Cashier "); got != models.PosRoleCashier {
+		t.Errorf("cashier = %d, want %d", got, models.PosRoleCashier)
+	}
+	// Anything unrecognised is zero, and every caller treats zero as a refusal
+	// rather than as a default — an unknown role must never become a supervisor.
+	for _, name := range []string{"", "admin", "manager", "owner", "7"} {
+		if got := models.PosRoleFromName(name); got != 0 {
+			t.Errorf("PosRoleFromName(%q) = %d, want 0", name, got)
+		}
+	}
+}
+
+// The web console writes `app_users` too, through `tenants/createstaff`, and
+// that path had no validation at all. These cover the shared rule set, so a
+// person created from a browser is subject to the same constraints as one
+// created at a till — two paths writing one table is how they drift.
+
+func TestStaffFromTheWebConsoleObeysTheTillsRules(t *testing.T) {
+	cases := []struct {
+		name string
+		user models.User
+		ok   bool
+	}{
+		{
+			name: "a usable cashier",
+			user: models.User{Firstname: "Asha", Roleid: models.PosRoleCashier, Pin: 7391},
+			ok:   true,
+		},
+		{
+			name: "a password instead of a PIN is fine",
+			user: models.User{Firstname: "Asha", Roleid: models.PosRoleCashier, Password: "s3cret"},
+			ok:   true,
+		},
+		{
+			name: "no name",
+			user: models.User{Roleid: models.PosRoleCashier, Pin: 7391},
+		},
+		{
+			name: "no role — 0 is unset, not a role",
+			user: models.User{Firstname: "Asha", Pin: 7391},
+		},
+		{
+			name: "no way at all to sign in",
+			user: models.User{Firstname: "Asha", Roleid: models.PosRoleCashier},
+		},
+		{
+			// 451 is what "0451" becomes in a bigint column. Accepting it here
+			// creates somebody who types four digits and is refused for ever.
+			name: "a PIN the column cannot hold",
+			user: models.User{Firstname: "Asha", Roleid: models.PosRoleCashier, Pin: 451},
+		},
+		{
+			name: "a PIN anyone would guess first",
+			user: models.User{Firstname: "Asha", Roleid: models.PosRoleCashier, Pin: 1234},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			user := tc.user
+			_, err := ValidateStaffUser(&user)
+
+			if tc.ok && err != nil {
+				t.Fatalf("refused a valid staff row: %v", err)
+			}
+			if !tc.ok && err == nil {
+				t.Fatal("accepted a staff row the till could not use")
+			}
+		})
+	}
+}

repositories/productRepository.go

@@ -22,14 +22,16 @@ type ProductRepository interface {
 	GetProductStocks(tenantID, locationID string) ([]models.Productstocks, error)
 	CreateProductStock(stocks []models.Productstock) error
 	UpdateProductStatus(productIDs []int, status string) 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 int) ([]models.Products, error)
+	GetProductByVariant(tenantid, variantid, locationid int) ([]models.Products, error)
 	GetSubcategories(categoryID int) ([]models.Subcategory, error)
 	GetProducts(params models.ProductFilter) ([]models.Products, error)
 	GetTenantInfo(tenantID, applocationID int) (map[string]interface{}, error)
@@ -87,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
 			COUNT(*) AS total,
-			SUM(CASE WHEN a.productstatus = 'available' THEN 1 ELSE 0 END) AS available,
+			SUM(CASE WHEN COALESCE(s.balance, 0) > 0 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 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
 	`
 
@@ -221,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 LOWER(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) = '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
@@ -250,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
@@ -263,6 +294,38 @@ func (r *productRepository) CreateProductStock(stocks []models.Productstock) err
 	return r.db.Table("productstocks").Create(&stocks).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.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
+		}
+	}
+	return nil
+}
+
 func (r *productRepository) UpdateProductStatus(productIDs []int, status string) error {
 	return r.db.Table("products").
 		Where("productid IN ?", productIDs).
@@ -327,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) -
+     		 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 )
+			           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,
@@ -387,11 +455,29 @@ 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 
+              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  
@@ -409,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)
@@ -423,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)
 
@@ -490,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.*,
 		b.status,
+		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
 				productid,
-				locationid,
+				tenantid,
-				SUM(CASE WHEN stocktype = 'in' THEN quantity ELSE 0 END) -
+				SUM(CASE WHEN LOWER(stocktype) = 'in' THEN quantity ELSE 0 END) -
-				SUM(CASE WHEN stocktype = 'out' THEN quantity ELSE 0 END) AS quantity
+				SUM(CASE WHEN LOWER(stocktype) = 'out' THEN quantity ELSE 0 END) AS quantity
 			FROM productstocks
-			GROUP BY productid, locationid
+			WHERE (? = 0 OR locationid = ?)
-		) ps ON ps.productid = a.productid
+			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")
 
@@ -530,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)
@@ -567,10 +786,19 @@ func (r *productRepository) FetchFilteredProducts(
 	return results, nil
 }
 
-func (r *productRepository) GetProductByVariant(tenantid, variantid int) ([]models.Products, error) {
+func (r *productRepository) GetProductByVariant(tenantid, variantid, locationid int) ([]models.Products, error) {
 
 	var data []models.Products
 
+	// 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(`
@@ -578,11 +806,25 @@ func (r *productRepository) GetProductByVariant(tenantid, variantid int) ([]mode
 			c.categoryname,
 			d.subcatname AS subcategoryname,
 			COALESCE(pd.discountvalue, 0) AS discountvalue,
-			pd.discountid
+			pd.discountid,
-		`).
+			pl.status AS locationstatus,
+			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 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").
+		Joins("LEFT JOIN productlocations pl ON pl.productid = p.productid AND pl.tenantid = p.tenantid AND pl.locationid = ?", locationid).
 		Where("p.tenantid = ? AND p.variants = ?", tenantid, variantid).
 		Order("p.productid DESC").
 		Scan(&data).Error
@@ -606,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)
@@ -632,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
+		COALESCE(pd.discountvalue, 0) AS discountvalue,
-	`).Find(&products).Error
+		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
 }

repositories/stockLedger.go

@@ -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
+}

repositories/tenantRepository.go

@@ -25,7 +25,7 @@ type TenantRepository interface {
 	GetStaffs(tid int) ([]models.StaffInfo, error)
 	CreateStaff(user models.User) error
 	UpdateStaff(user models.User) error
-	CreateTenantLocation(data models.Tenantlocations) error
+	CreateTenantLocation(data models.Tenantlocations) (models.Tenantlocations, error)
 	UpdateTenantLocation(data models.Tenantlocations) error
 	CheckTenantByNo(cno string) int
 	CreateTenantUser(data models.Tenants) (bool, error)
@@ -320,10 +320,13 @@ func (r *tenantRepository) GetStaffs(tid int) ([]models.StaffInfo, error) {
 	           a.email,a.contactno,a.address,a.suburb,a.city,
 	           a.state,a.postcode,a.userfcmtoken,a.pin,a.applocationid,
 	           a.roleid,a.partnerid,a.tenantid,a.locationid,
-	           b.locationname
+	           b.locationname,
+	           COALESCE(c.rolename,'') AS rolename
 	        FROM app_users a
 	        INNER JOIN tenantlocations b ON a.locationid = b.locationid
-	        WHERE a.tenantid = ?`
+	        LEFT JOIN app_roles c ON c.roleid = a.roleid
+	        WHERE a.tenantid = ?
+	          AND COALESCE(a.roleid, 0) NOT IN (7, 8)`
 
 	if err := r.db.Raw(q1, tid).Scan(&data).Error; err != nil {
 		return nil, err
@@ -332,7 +335,34 @@ func (r *tenantRepository) GetStaffs(tid int) ([]models.StaffInfo, error) {
 	return data, nil
 }
 
+// CreateStaff adds a person to a shop from the web console.
+//
+// Now subject to the same rules the till applies — see ValidateStaffUser. This
+// wrote whatever it was handed, so a cashier could be created with a PIN the
+// schema cannot store, a PIN somebody else already has, or no way to sign in at
+// all. The failure surfaced at the counter rather than on the screen that
+// caused it.
+//
+// `userid` is deliberately not set: it is a `GENERATED BY DEFAULT AS IDENTITY`
+// column and Postgres allocates it. Computing one here would leave the sequence
+// unadvanced and two allocators racing each other.
 func (r *tenantRepository) CreateStaff(user models.User) error {
+	pin, err := ValidateStaffUser(&user)
+	if err != nil {
+		return err
+	}
+	user.Pin = int(pin)
+
+	if pin > 0 && user.Tenantid > 0 && user.Locationid > 0 {
+		taken, err := posPinTaken(r.db, user.Tenantid, user.Locationid, pin, user.Userid)
+		if err != nil {
+			return err
+		}
+		if taken {
+			return fmt.Errorf("another person at this outlet already uses that PIN")
+		}
+	}
+
 	if err := r.db.Table("app_users").Create(&user).Error; err != nil {
 		return err
 	}
@@ -346,17 +376,26 @@ func (r *tenantRepository) UpdateStaff(user models.User) error {
 	return nil
 }
 
-func (r *tenantRepository) CreateTenantLocation(data models.Tenantlocations) error {
+func (r *tenantRepository) CreateTenantLocation(data models.Tenantlocations) (models.Tenantlocations, error) {
 	var user models.Tenantuser
 	tx := r.db.Begin()
 
-	// Set status BEFORE insert
+	// Default to Active if the caller didn't specify — matches
-	data.Status = "InActive"
+	// tenantlocations' own gorm default and the primary-location behavior
+	// from tenant onboarding. Forcing InActive here used to also block the
+	// spawned manager login (AppLogin checks account status before it ever
+	// gets to the "no password set" branch), so a new store's login could
+	// never reach the password-setup screen.
+	if data.Status == "" {
+		data.Status = "Active"
+	}
 
-	// Step 1: Insert into tenantlocations
+	// Step 1: Insert into tenantlocations. GORM writes the DB-assigned
+	// locationid back onto data, which callers need to build the store's
+	// QR code (payload is just {tenantid, locationid}) right after onboarding.
 	if err := tx.Create(&data).Error; err != nil {
 		tx.Rollback()
-		return err
+		return models.Tenantlocations{}, err
 	}
 
 	// Step 2: Insert into app_users
@@ -374,7 +413,7 @@ func (r *tenantRepository) CreateTenantLocation(data models.Tenantlocations) err
 	user.Locationid = data.Locationid
 	user.Applocationid = data.Applocationid
 	user.Configid = 1
-	user.Status = "InActive"
+	user.Status = data.Status
 	user.Roleid = 0
 	user.Authmode = 0
 	user.Password = ""
@@ -382,15 +421,15 @@ func (r *tenantRepository) CreateTenantLocation(data models.Tenantlocations) err
 
 	if err := tx.Table("app_users").Create(&user).Error; err != nil {
 		tx.Rollback()
-		return err
+		return models.Tenantlocations{}, err
 	}
 
 	// Commit
 	if err := tx.Commit().Error; err != nil {
-		return err
+		return models.Tenantlocations{}, err
 	}
 
-	return nil
+	return data, nil
 }
 
 func (r *tenantRepository) UpdateTenantLocation(input models.Tenantlocations) error {

repositories/userRepository.go

@@ -55,6 +55,18 @@ func (r *userRepository) GetAllUsers(roleID, tenantID, pageno, pagesize int, key
 		LEFT JOIN ridershifts c ON a.shiftid = c.shiftid
 		WHERE 1=1`)
 
+	// Till accounts are not Nearle Daily users and must not be listed as though
+	// they were. The two products share this table and nothing else: a cashier
+	// has no app login, no rider shift and no back-office screen, so a row
+	// returned here is one every action on the page would fail against.
+	//
+	// Asking for 7 or 8 by name still works, so the POS console can read its own
+	// people through the same endpoint — this hides them from the general list,
+	// it does not make them unreachable.
+	if roleID != models.PosRoleSupervisor && roleID != models.PosRoleCashier {
+		queryBuilder.WriteString(" AND COALESCE(a.roleid, 0) NOT IN (7, 8)")
+	}
+
 	if roleID != 0 {
 		queryBuilder.WriteString(" AND a.roleid = ?")
 		params = append(params, roleID)
@@ -78,8 +90,6 @@ func (r *userRepository) GetAllUsers(roleID, tenantID, pageno, pagesize int, key
 	queryBuilder.WriteString(" ORDER BY a.userid DESC LIMIT ? OFFSET ?")
 	params = append(params, pagesize, offset)
 
-	print(queryBuilder.String())
-
 	if err := r.db.Raw(queryBuilder.String(), params...).Scan(&users).Error; err != nil {
 		return nil, err
 	}
@@ -120,13 +130,15 @@ func (r *userRepository) Login(user models.User) (models.UserInfo, error) {
 	var q string
 	if user.Authname != "" {
 		q = `SELECT a.userid FROM app_users a
-			  WHERE a.authname = ? AND a.configid = ?`
+			  WHERE a.authname = ? AND a.configid = ?
+			    AND COALESCE(a.roleid, 0) NOT IN (7, 8)`
 		if err := r.db.Raw(q, user.Authname, user.Configid).Scan(&uid).Error; err != nil {
 			return models.UserInfo{}, err
 		}
 	} else {
 		q = `SELECT a.userid FROM app_users a
-			  WHERE a.contactno = ? AND a.configid = ?`
+			  WHERE a.contactno = ? AND a.configid = ?
+			    AND COALESCE(a.roleid, 0) NOT IN (7, 8)`
 		if err := r.db.Raw(q, user.Contactno, user.Configid).Scan(&uid).Error; err != nil {
 			return models.UserInfo{}, err
 		}
@@ -159,12 +171,16 @@ func (r *userRepository) FindUserID(authname, contactno string, configid int) (i
 	var query string
 
 	if authname != "" {
-		query = `SELECT a.userid FROM app_users a WHERE a.authname = ? AND a.configid = ?`
+		query = `SELECT a.userid FROM app_users a
+		         WHERE a.authname = ? AND a.configid = ?
+		           AND COALESCE(a.roleid, 0) NOT IN (7, 8)`
 		if err := r.db.Raw(query, authname, configid).Scan(&uid).Error; err != nil {
 			return 0, err
 		}
 	} else {
-		query = `SELECT a.userid FROM app_users a WHERE a.contactno = ? AND a.configid = ?`
+		query = `SELECT a.userid FROM app_users a
+		         WHERE a.contactno = ? AND a.configid = ?
+		           AND COALESCE(a.roleid, 0) NOT IN (7, 8)`
 		if err := r.db.Raw(query, contactno, configid).Scan(&uid).Error; err != nil {
 			return 0, err
 		}
@@ -189,10 +205,19 @@ func (r *userRepository) UpdateStaff(user models.User) error {
 	return r.db.Table("app_users").Where("userid = ?", user.Userid).Updates(&user).Error
 }
 
+// A till account is not a Nearle Daily user. The two products share this table
+// and nothing else, so every way into the application excludes roles 7 and 8 in
+// the lookup itself: a cashier is not "refused", they are simply not found.
+//
+// Doing it in the query rather than after it is deliberate. A check bolted on
+// afterwards has to be repeated at each of these call sites and is one edit away
+// from being forgotten at one of them, and that one would be the hole.
 func (r *userRepository) GetUserByAuthname(authname string, configid int) (int, string, string) {
 	var uid int
 	var password, status string
-	query := `SELECT userid, password, status FROM app_users WHERE authname = ? AND configid = ?`
+	query := `SELECT userid, password, status FROM app_users
+	          WHERE authname = ? AND configid = ?
+	            AND COALESCE(roleid, 0) NOT IN (7, 8)`
 	r.db.Raw(query, authname, configid).Row().Scan(&uid, &password, &status)
 	return uid, password, status
 }
@@ -200,7 +225,9 @@ func (r *userRepository) GetUserByAuthname(authname string, configid int) (int,
 func (r *userRepository) GetUserByContactNo(contactno string, configid int) (int, string, string) {
 	var uid int
 	var password, status string
-	query := `SELECT userid, password, status FROM app_users WHERE contactno = ? AND configid = ?`
+	query := `SELECT userid, password, status FROM app_users
+	          WHERE contactno = ? AND configid = ?
+	            AND COALESCE(roleid, 0) NOT IN (7, 8)`
 	r.db.Raw(query, contactno, configid).Row().Scan(&uid, &password, &status)
 	return uid, password, status
 }
@@ -282,7 +309,8 @@ func (r *userRepository) GetUserLogin(field, value string, configid int) (int, s
 	query := fmt.Sprintf(`
 		SELECT userid, password, status, roleid
 		FROM app_users
-		WHERE %s = ? AND configid = ?`, field)
+		WHERE %s = ? AND configid = ?
+		  AND COALESCE(roleid, 0) NOT IN (7, 8)`, field)
 
 	r.db.Raw(query, value, configid).Row().Scan(&uid, &password, &status, &roleid)
 

routes/orderroutes.go

@@ -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)

routes/posroutes.go

@@ -0,0 +1,109 @@
+package routes
+
+import (
+	"nearle/facade"
+	"nearle/middleware"
+
+	"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")
+
+	// Sign-in, and the only route on this group that runs before the guard —
+	// it is where a session comes from. A till posts the same `app_users`
+	// credentials the web console takes, and gets back a token plus the outlet
+	// that account is entitled to. The store id it will bill under is decided
+	// here, from the user's record, instead of being typed into Settings and
+	// taken on trust.
+	pos.Post("/login", f.PosController.Login)
+
+	// Everything past this point carries the session.
+	//
+	// The guard verifies the token and refuses a request naming an outlet the
+	// token's tenant does not own. Until `POS_AUTH_REQUIRED=true` is set it
+	// lets an unauthenticated request through, so the terminals already
+	// trading do not stop the day this deploys — see middleware.PosAuth.
+	pos.Use(middleware.PosAuth(f.PosService()))
+
+	pos.Get("/session", f.PosController.Session)
+
+	// Who may ring a bill here. Deliberately takes no location parameter — the
+	// answer carries PINs, so the outlet comes from the caller's own token.
+	pos.Get("/staff", f.PosController.Staff)
+
+	// Signing on by PIN, once a supervisor has opened the terminal with a real
+	// password. Sits behind the guard on purpose — see PinLogin.
+	pos.Post("/login/pin", f.PosController.PinLogin)
+
+	// The shop's own counter staff. A supervisor creates their cashiers; the
+	// outlet is always the caller's own, read from their token.
+	pos.Get("/users", f.PosController.ListPosUsers)
+	pos.Post("/users", f.PosController.CreatePosUser)
+	pos.Put("/users", f.PosController.UpdatePosUser)
+	pos.Delete("/users", f.PosController.DeletePosUser)
+
+	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)
+
+	registerPosStaffConsoleRoutes(api, f)
+}
+
+// Till staff, managed from the web console rather than from a counter.
+//
+// Under `/web` and `/mob` rather than `/pos`, because the callers are the back
+// office and the daily app — neither holds a terminal session, and putting them
+// behind the terminal guard would lock out the very screen an admin uses to set
+// a shop up in the first place.
+//
+// They run the same service calls as `/pos/users`. A supervisor created here is
+// the same row, with the same rules applied, as one created at a till.
+//
+// The outlet is asserted rather than proved, which is the real difference and
+// the weaker half: a terminal signs its outlet, a console just names one. It is
+// checked against the tenant before anything is written, and these should move
+// behind a session guard as soon as the console can hold one — until then, this
+// mints till credentials on the strength of an unauthenticated request, exactly
+// like every other route in this group.
+func registerPosStaffConsoleRoutes(api fiber.Router, f *facade.Facade) {
+	for _, group := range []string{"/v1/web/tenants", "/v1/mob/tenants"} {
+		g := api.Group(group)
+
+		// Served rather than hardcoded, so a console offering the choice does
+		// not have to know that supervisor is 7.
+		g.Get("/posroles", f.PosController.WebPosRoles)
+
+		g.Get("/getposusers", f.PosController.WebListPosUsers)
+		g.Post("/createposuser", f.PosController.WebCreatePosUser)
+		g.Put("/updateposuser", f.PosController.WebUpdatePosUser)
+		g.Delete("/deleteposuser", f.PosController.WebDeletePosUser)
+	}
+}

routes/productroutes.go

@@ -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)

routes/routes.go

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

routes/utilsroutes.go

@@ -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)

scratch/backfill_location_coordinates.go

@@ -0,0 +1,146 @@
+//go:build ignore
+
+package main
+
+import (
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	_ "github.com/jackc/pgx/v5/stdlib"
+)
+
+// One-off backfill for tenants/tenantlocations rows that were onboarded
+// before the admin console geocoded addresses automatically, so their
+// latitude/longitude columns were left blank. Geocodes each row's existing
+// address via OpenStreetMap Nominatim (same keyless provider
+// AddressAutocomplete.tsx already uses on the frontend) and writes the
+// result back. Run manually: `go run scratch/backfill_location_coordinates.go`
+// — do not wire this into any request path, it's a single pass over
+// historical rows.
+const nominatimURL = "https://nominatim.openstreetmap.org/search"
+
+// Nominatim's usage policy caps free lookups at ~1 request/sec.
+const rateLimit = 1100 * time.Millisecond
+
+type nominatimRow struct {
+	Lat string `json:"lat"`
+	Lon string `json:"lon"`
+}
+
+func geocode(client *http.Client, address string) (lat, lon string, ok bool) {
+	q := url.Values{}
+	q.Set("format", "json")
+	q.Set("limit", "1")
+	q.Set("q", address)
+
+	req, err := http.NewRequest("GET", nominatimURL+"?"+q.Encode(), nil)
+	if err != nil {
+		return "", "", false
+	}
+	// Required by Nominatim's usage policy — identifies the calling app.
+	req.Header.Set("User-Agent", "fiesta-backend-backfill/1.0 (care@nearle.in)")
+
+	resp, err := client.Do(req)
+	if err != nil {
+		fmt.Printf("  geocode request error: %v\n", err)
+		return "", "", false
+	}
+	defer resp.Body.Close()
+
+	var rows []nominatimRow
+	if err := json.NewDecoder(resp.Body).Decode(&rows); err != nil || len(rows) == 0 {
+		return "", "", false
+	}
+	return rows[0].Lat, rows[0].Lon, true
+}
+
+type row struct {
+	id      int
+	address string
+}
+
+func backfillTable(db *sql.DB, client *http.Client, table, idCol string) {
+	fmt.Printf("\n=== %s ===\n", table)
+
+	query := fmt.Sprintf(`
+		SELECT %s,
+		       TRIM(BOTH ', ' FROM CONCAT_WS(', ', address, suburb, city, state, postcode))
+		FROM %s
+		WHERE (latitude IS NULL OR latitude = '' OR latitude = '0')
+		  AND (address IS NOT NULL AND address <> '')`, idCol, table)
+
+	rows, err := db.Query(query)
+	if err != nil {
+		log.Fatalf("%s: query error: %v", table, err)
+	}
+	var targets []row
+	for rows.Next() {
+		var r row
+		if err := rows.Scan(&r.id, &r.address); err != nil {
+			log.Fatalf("%s: scan error: %v", table, err)
+		}
+		targets = append(targets, r)
+	}
+	rows.Close()
+
+	fmt.Printf("Found %d row(s) missing coordinates.\n", len(targets))
+
+	updated, skipped := 0, 0
+	for i, r := range targets {
+		if i > 0 {
+			time.Sleep(rateLimit)
+		}
+
+		lat, lon, ok := geocode(client, r.address)
+		if !ok {
+			fmt.Printf("  [%s=%d] %q — geocode FAILED, left untouched\n", idCol, r.id, r.address)
+			skipped++
+			continue
+		}
+
+		res, err := db.Exec(
+			fmt.Sprintf(`UPDATE %s SET latitude = $1, longitude = $2 WHERE %s = $3`, table, idCol),
+			lat, lon, r.id,
+		)
+		if err != nil {
+			fmt.Printf("  [%s=%d] update error: %v\n", idCol, r.id, err)
+			skipped++
+			continue
+		}
+		n, _ := res.RowsAffected()
+		if n > 0 {
+			fmt.Printf("  [%s=%d] %q -> lat=%s lon=%s\n", idCol, r.id, r.address, lat, lon)
+			updated++
+		}
+	}
+
+	fmt.Printf("%s: updated=%d skipped=%d\n", table, updated, skipped)
+}
+
+func main() {
+	dsn := "host=66.116.207.225 port=5433 user=admin password=Package@123# dbname=nearledb sslmode=disable"
+	db, err := sql.Open("pgx", dsn)
+	if err != nil {
+		log.Fatalf("open error: %v", err)
+	}
+	defer db.Close()
+
+	if err := db.Ping(); err != nil {
+		log.Fatalf("ping error: %v", err)
+	}
+	fmt.Println("Connected to nearledb.")
+
+	client := &http.Client{Timeout: 10 * time.Second}
+
+	backfillTable(db, client, "tenants", "tenantid")
+	backfillTable(db, client, "tenantlocations", "locationid")
+
+	fmt.Println(strings.Repeat("-", 40))
+	fmt.Println("Done.")
+}

scratch/dbinspect/cleanup.go

@@ -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)
+	}
+}

scratch/dbinspect/main.go

@@ -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)
+	}
+}

scratch/fix_kmartuser_configid.go

@@ -0,0 +1,72 @@
+//go:build ignore
+
+package main
+
+import (
+	"database/sql"
+	"fmt"
+	"log"
+
+	_ "github.com/jackc/pgx/v5/stdlib"
+)
+
+// One-off, tightly scoped fix for a single account stuck with the wrong
+// app_users.configid (a pre-fix Staff/Rider row created before the
+// UsersPanel.tsx / fiestaApi.ts configid bug was corrected). Only ever
+// touches the one row matching this exact authname/email.
+const targetEmail = "kmartuser@gmail.com"
+
+func printRows(db *sql.DB, label string) {
+	fmt.Printf("\n--- %s ---\n", label)
+	rows, err := db.Query(`
+		SELECT userid, authname, email, configid, roleid, tenantid, locationid, status
+		FROM app_users
+		WHERE lower(authname) = lower($1) OR lower(email) = lower($1)`, targetEmail)
+	if err != nil {
+		log.Fatalf("query error: %v", err)
+	}
+	defer rows.Close()
+
+	found := false
+	for rows.Next() {
+		found = true
+		var userid, configid, roleid, tenantid, locationid sql.NullInt64
+		var authname, email, status sql.NullString
+		if err := rows.Scan(&userid, &authname, &email, &configid, &roleid, &tenantid, &locationid, &status); err != nil {
+			log.Fatalf("scan error: %v", err)
+		}
+		fmt.Printf("userid=%d authname=%q email=%q configid=%d roleid=%d tenantid=%d locationid=%d status=%q\n",
+			userid.Int64, authname.String, email.String, configid.Int64, roleid.Int64, tenantid.Int64, locationid.Int64, status.String)
+	}
+	if !found {
+		fmt.Println("NO ROW FOUND — account does not exist under this authname/email.")
+	}
+}
+
+func main() {
+	dsn := "host=66.116.207.225 port=5433 user=admin password=Package@123# dbname=nearledb sslmode=disable"
+	db, err := sql.Open("pgx", dsn)
+	if err != nil {
+		log.Fatalf("open error: %v", err)
+	}
+	defer db.Close()
+
+	if err := db.Ping(); err != nil {
+		log.Fatalf("ping error: %v", err)
+	}
+	fmt.Println("Connected to nearledb.")
+
+	printRows(db, "BEFORE")
+
+	res, err := db.Exec(`
+		UPDATE app_users
+		SET configid = 1
+		WHERE (lower(authname) = lower($1) OR lower(email) = lower($1)) AND configid <> 1`, targetEmail)
+	if err != nil {
+		log.Fatalf("update error: %v", err)
+	}
+	n, _ := res.RowsAffected()
+	fmt.Printf("\nRows updated: %d\n", n)
+
+	printRows(db, "AFTER")
+}

scratch/gstrates/main.go

@@ -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)
+		}
+	}
+}

scratch/healthproof/main.go

@@ -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)
+	}
+}

scratch/liveloginproof/main.go

@@ -0,0 +1,130 @@
+// Proves sign-in end to end against the deployed API.
+//
+// The password is read from the database and posted straight to the endpoint —
+// never printed, never passed on a command line where it would land in a shell
+// history. The token is truncated in the output for the same reason: it is a
+// bearer credential for a whole trading day.
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"os"
+	"strings"
+
+	"github.com/joho/godotenv"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+const base = "https://fiesta.nearle.app/live/api/v1/pos"
+
+func main() {
+	who := "rsselvapuram@gmail.com"
+	if len(os.Args) > 1 {
+		who = 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)
+	}
+
+	var pw string
+	db.Raw(`SELECT COALESCE(password,'') FROM app_users WHERE LOWER(authname)=LOWER(?) LIMIT 1`, who).Scan(&pw)
+	if pw == "" {
+		log.Fatalf("%s has no password set", who)
+	}
+
+	body, _ := json.Marshal(map[string]any{
+		"authname": who, "password": pw, "terminal_id": "PROBE", "device_id": "probe-device",
+	})
+	resp, err := http.Post(base+"/login", "application/json", bytes.NewReader(body))
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer resp.Body.Close()
+	raw, _ := io.ReadAll(resp.Body)
+
+	fmt.Printf("POST /login  HTTP %d\n", resp.StatusCode)
+
+	var out struct {
+		Message string `json:"message"`
+		Details struct {
+			Token        string `json:"token"`
+			Expiresat    string `json:"expires_at"`
+			Tenantid     int    `json:"tenant_id"`
+			Tenantname   string `json:"tenant_name"`
+			Storeid      string `json:"store_id"`
+			Locationname string `json:"location_name"`
+			Gstin        string `json:"gstin"`
+			Locations    []struct {
+				Locationid   int    `json:"location_id"`
+				Locationname string `json:"location_name"`
+			} `json:"locations"`
+			Staff []struct {
+				Fullname string `json:"full_name"`
+				Role     string `json:"role"`
+			} `json:"staff"`
+		} `json:"details"`
+	}
+	if err := json.Unmarshal(raw, &out); err != nil {
+		fmt.Println(string(raw))
+		return
+	}
+	if resp.StatusCode != 200 {
+		fmt.Println("  ", out.Message)
+		return
+	}
+
+	t := out.Details.Token
+	fmt.Printf("  token       %s… (%d chars, signature verified below)\n", t[:12], len(t))
+	fmt.Printf("  expires     %s\n", out.Details.Expiresat)
+	fmt.Printf("  tenant      %d %s\n", out.Details.Tenantid, out.Details.Tenantname)
+	fmt.Printf("  store_id    %s  (%s)\n", out.Details.Storeid, out.Details.Locationname)
+	fmt.Printf("  gstin       %s\n", out.Details.Gstin)
+	fmt.Printf("  outlets     %d\n", len(out.Details.Locations))
+	fmt.Printf("  staff       %d\n", len(out.Details.Staff))
+	for _, s := range out.Details.Staff {
+		fmt.Printf("                %s (%s)\n", s.Fullname, s.Role)
+	}
+
+	// The token has to actually open the doors it claims to.
+	for _, path := range []string{"/session", "/staff", "/catalogue?store_id=" + out.Details.Storeid + "&page_size=1"} {
+		req, _ := http.NewRequest("GET", base+path, nil)
+		req.Header.Set("Authorization", "Bearer "+t)
+		r, err := http.DefaultClient.Do(req)
+		if err != nil {
+			log.Fatal(err)
+		}
+		b, _ := io.ReadAll(r.Body)
+		r.Body.Close()
+		fmt.Printf("\nGET %-28s HTTP %d  %s", strings.Split(path, "&")[0], r.StatusCode, truncate(string(b), 150))
+	}
+
+	// And must NOT open somebody else's.
+	req, _ := http.NewRequest("GET", base+"/catalogue?store_id=1185&page_size=1", nil)
+	req.Header.Set("Authorization", "Bearer "+t)
+	r, _ := http.DefaultClient.Do(req)
+	b, _ := io.ReadAll(r.Body)
+	r.Body.Close()
+	fmt.Printf("\n\nGET /catalogue (ANOTHER TENANT'S OUTLET 1185)  HTTP %d  %s\n",
+		r.StatusCode, truncate(string(b), 160))
+}
+
+func truncate(s string, n int) string {
+	s = strings.ReplaceAll(s, "\n", " ")
+	if len(s) > n {
+		return s[:n] + "…"
+	}
+	return s
+}

scratch/loginreach/main.go

@@ -0,0 +1,92 @@
+// Who can actually open a till, across the whole platform.
+//
+// Read-only. Answers the question the account model raises the moment sign-in
+// becomes real: the endpoint is open to every tenant, so *which* of them can
+// genuinely reach it, and does anyone reach it who should not.
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+
+	"github.com/joho/godotenv"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+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)
+	}
+
+	// The exact predicate posLoginCandidates + PosLogin apply.
+	eligible := `
+		FROM app_users a
+		WHERE LOWER(COALESCE(a.status,'active')) <> 'inactive'
+		  AND COALESCE(a.password,'') <> ''
+		  AND COALESCE(a.authname,'') <> ''
+		  AND COALESCE(a.tenantid,0) > 0
+		  AND EXISTS (SELECT 1 FROM tenantlocations l
+		              WHERE l.tenantid = a.tenantid
+		                AND LOWER(COALESCE(l.status,'active')) <> 'inactive'
+		                AND (COALESCE(a.locationid,0) = 0 OR l.locationid = a.locationid))`
+
+	var total, tenants int
+	db.Raw(`SELECT COUNT(*) ` + eligible).Scan(&total)
+	db.Raw(`SELECT COUNT(DISTINCT a.tenantid) ` + eligible).Scan(&tenants)
+
+	var allUsers, allTenants int
+	db.Raw(`SELECT COUNT(*) FROM app_users`).Scan(&allUsers)
+	db.Raw(`SELECT COUNT(*) FROM tenants`).Scan(&allTenants)
+
+	fmt.Printf("app_users rows          %d\n", allUsers)
+	fmt.Printf("  can open a till       %d\n", total)
+	fmt.Printf("tenants                 %d\n", allTenants)
+	fmt.Printf("  with a usable login   %d\n\n", tenants)
+
+	// Which tenants, and whether they have a catalogue to sell.
+	var rows []struct {
+		Tenantid   int
+		Tenantname string
+		Users      int
+		Outlets    int
+		Products   int
+	}
+	db.Raw(`
+		SELECT t.tenantid, COALESCE(t.tenantname,'') AS tenantname,
+		  (SELECT COUNT(*) FROM app_users a WHERE a.tenantid=t.tenantid
+		     AND LOWER(COALESCE(a.status,'active'))<>'inactive'
+		     AND COALESCE(a.password,'')<>'' AND COALESCE(a.authname,'')<>'') AS users,
+		  (SELECT COUNT(*) FROM tenantlocations l WHERE l.tenantid=t.tenantid
+		     AND LOWER(COALESCE(l.status,'active'))<>'inactive') AS outlets,
+		  (SELECT COUNT(*) FROM productlocations p WHERE p.tenantid=t.tenantid) AS products
+		FROM tenants t
+		WHERE EXISTS (SELECT 1 FROM app_users a WHERE a.tenantid=t.tenantid
+		     AND LOWER(COALESCE(a.status,'active'))<>'inactive'
+		     AND COALESCE(a.password,'')<>'' AND COALESCE(a.authname,'')<>'')
+		ORDER BY products DESC, t.tenantid`).Scan(&rows)
+
+	fmt.Printf("%-8s %-34s %6s %8s %9s\n", "tenant", "name", "logins", "outlets", "products")
+	fmt.Println("---------------------------------------------------------------------------")
+	for _, r := range rows {
+		fmt.Printf("%-8d %-34s %6d %8d %9d\n", r.Tenantid, r.Tenantname, r.Users, r.Outlets, r.Products)
+	}
+
+	// Roles. The POS login does not check one, so this says who slips through.
+	var roles []struct {
+		Roleid int
+		C      int
+	}
+	db.Raw(`SELECT COALESCE(a.roleid,0) AS roleid, COUNT(*) AS c ` + eligible + ` GROUP BY 1 ORDER BY c DESC`).Scan(&roles)
+	fmt.Println("\neligible logins by roleid:")
+	for _, r := range roles {
+		fmt.Printf("  role %-4d %d\n", r.Roleid, r.C)
+	}
+}

scratch/mqttpub/main.go

@@ -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)
+	}
+}

scratch/posloginproof/main.go

@@ -0,0 +1,241 @@
+// Proves POS sign-in against the live database, read-only.
+//
+// Written because the interesting half of this feature is not the token — that
+// has unit tests — but whether the *account model* actually holds up against
+// real rows: does a shop's user resolve to the right tenant, does the outlet
+// list come back non-empty, and does an account from one tenant get refused at
+// another tenant's outlet.
+//
+// Passwords are read out of the database and handed straight back into the
+// login so the happy path can be proven without anyone typing or printing one.
+// Nothing here is ever echoed.
+//
+//	go run ./scratch/posloginproof users 1087    # who could open a till
+//	go run ./scratch/posloginproof login 1087    # sign the first one in
+//	go run ./scratch/posloginproof cross         # refuse another tenant's outlet
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"strconv"
+	"strings"
+
+	"nearle/models"
+	"nearle/repositories"
+
+	"github.com/joho/godotenv"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+func main() {
+	mode := "users"
+	if len(os.Args) > 1 {
+		mode = os.Args[1]
+	}
+	tenantID := 1087
+	if len(os.Args) > 2 {
+		tenantID, _ = strconv.Atoi(os.Args[2])
+	}
+
+	_ = godotenv.Load()
+	if strings.TrimSpace(os.Getenv("POS_TOKEN_SECRET")) == "" {
+		// Only needed by the service layer; the repository probes below work
+		// without it. Set a throwaway so `login` can mint.
+		os.Setenv("POS_TOKEN_SECRET", "scratch-proof-signing-key-not-real")
+	}
+
+	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)
+	}
+
+	repo := repositories.NewPosRepository(db)
+
+	switch mode {
+	case "users":
+		listUsers(db, tenantID)
+	case "login":
+		proveLogin(db, repo, tenantID)
+	case "cross":
+		proveCrossTenantRefusal(db, repo)
+	default:
+		log.Fatalf("unknown mode %q", mode)
+	}
+}
+
+// listUsers shows who could open a till for a tenant, and whether their record
+// is complete enough to do it.
+func listUsers(db *gorm.DB, tenantID int) {
+	type row struct {
+		Userid     int
+		Authname   string
+		Roleid     int
+		Status     string
+		Locationid int
+		Haspw      bool
+	}
+
+	var rows []row
+	err := db.Raw(`
+		SELECT userid, COALESCE(authname,'') AS authname, COALESCE(roleid,0) AS roleid,
+		       COALESCE(status,'') AS status, COALESCE(locationid,0) AS locationid,
+		       (COALESCE(password,'') <> '') AS haspw
+		FROM app_users WHERE tenantid = ? ORDER BY userid`, tenantID).Scan(&rows).Error
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("tenant %d — %d user(s)\n", tenantID, len(rows))
+	fmt.Printf("%-8s %-34s %-6s %-10s %-10s %s\n", "userid", "authname", "role", "status", "location", "password set")
+	fmt.Println(strings.Repeat("-", 92))
+	for _, r := range rows {
+		loc := "any"
+		if r.Locationid > 0 {
+			loc = strconv.Itoa(r.Locationid)
+		}
+		fmt.Printf("%-8d %-34s %-6d %-10s %-10s %v\n",
+			r.Userid, r.Authname, r.Roleid, r.Status, loc, r.Haspw)
+	}
+
+	var locs []struct {
+		Locationid   int
+		Locationname string
+		Status       string
+	}
+	db.Raw(`SELECT locationid, COALESCE(locationname,'') AS locationname,
+	               COALESCE(status,'') AS status
+	        FROM tenantlocations WHERE tenantid = ? ORDER BY locationid`, tenantID).Scan(&locs)
+
+	fmt.Printf("\noutlets: %d\n", len(locs))
+	for _, l := range locs {
+		fmt.Printf("  %-8d %-40s %s\n", l.Locationid, l.Locationname, l.Status)
+	}
+}
+
+// proveLogin signs in the tenant's first usable account and reports what the
+// session resolved to.
+func proveLogin(db *gorm.DB, repo repositories.PosRepository, tenantID int) {
+	// An explicit account, when the interesting case is a particular one — the
+	// till's own outlet, or a proprietor who reaches several.
+	wanted := ""
+	if len(os.Args) > 3 {
+		wanted = strings.TrimSpace(os.Args[3])
+	}
+
+	var cred struct {
+		Authname string
+		Password string
+	}
+	query := `
+		SELECT COALESCE(authname,'') AS authname, COALESCE(password,'') AS password
+		FROM app_users
+		WHERE tenantid = ? AND COALESCE(password,'') <> '' AND COALESCE(authname,'') <> ''
+		  AND LOWER(COALESCE(status,'active')) <> 'inactive'`
+	params := []interface{}{tenantID}
+	if wanted != "" {
+		query += ` AND LOWER(authname) = LOWER(?)`
+		params = append(params, wanted)
+	}
+	query += ` ORDER BY userid LIMIT 1`
+
+	err := db.Raw(query, params...).Scan(&cred).Error
+	if err != nil {
+		log.Fatal(err)
+	}
+	if cred.Authname == "" {
+		log.Fatalf("tenant %d has no active account with a password set", tenantID)
+	}
+
+	fmt.Printf("signing in %s (password read from the database, not printed)\n\n", cred.Authname)
+
+	session, err := repo.PosLogin(models.PosLoginRequest{
+		Authname:   cred.Authname,
+		Password:   cred.Password,
+		Terminalid: "T5EDD",
+	})
+	if err != nil {
+		log.Fatalf("REFUSED: %v", err)
+	}
+
+	fmt.Printf("  user        %d  %s\n", session.Userid, session.Fullname)
+	fmt.Printf("  tenant      %d  %s\n", session.Tenantid, session.Tenantname)
+	fmt.Printf("  store_id    %s\n", session.Storeid)
+	fmt.Printf("  outlet      %d  %s\n", session.Locationid, session.Locationname)
+	fmt.Printf("  gstin       %s\n", session.Gstin)
+	fmt.Printf("  outlets     %d reachable\n", len(session.Locations))
+	for _, l := range session.Locations {
+		fmt.Printf("                %-8d %s\n", l.Locationid, l.Locationname)
+	}
+
+	// The check that matters: a wrong password must be refused, and refused
+	// with the same message a wrong email gets.
+	if _, err := repo.PosLogin(models.PosLoginRequest{
+		Authname: cred.Authname, Password: cred.Password + "x",
+	}); err == nil {
+		fmt.Println("\n  !! a wrong password was ACCEPTED")
+	} else {
+		fmt.Printf("\n  wrong password refused: %v\n", err)
+	}
+
+	if _, err := repo.PosLogin(models.PosLoginRequest{
+		Authname: "nobody@nowhere.invalid", Password: "whatever",
+	}); err != nil {
+		fmt.Printf("  unknown account refused: %v\n", err)
+	}
+}
+
+// proveCrossTenantRefusal is the authorisation test: an account from one tenant
+// must not be able to open a till at another tenant's outlet, which is exactly
+// what a till could do before by editing one field in Settings.
+func proveCrossTenantRefusal(db *gorm.DB, repo repositories.PosRepository) {
+	var cred struct {
+		Authname string
+		Password string
+		Tenantid int
+	}
+	err := db.Raw(`
+		SELECT COALESCE(a.authname,'') AS authname, COALESCE(a.password,'') AS password, a.tenantid
+		FROM app_users a
+		WHERE COALESCE(a.password,'') <> '' AND COALESCE(a.authname,'') <> '' AND a.tenantid > 0
+		  AND LOWER(COALESCE(a.status,'active')) <> 'inactive'
+		ORDER BY a.userid LIMIT 1`).Scan(&cred).Error
+	if err != nil || cred.Authname == "" {
+		log.Fatalf("no usable account to test with: %v", err)
+	}
+
+	// Somebody else's outlet.
+	var foreign int
+	db.Raw(`SELECT locationid FROM tenantlocations WHERE tenantid <> ? ORDER BY locationid LIMIT 1`,
+		cred.Tenantid).Scan(&foreign)
+	if foreign == 0 {
+		log.Fatal("only one tenant has outlets; nothing to cross")
+	}
+
+	fmt.Printf("account belongs to tenant %d; asking for outlet %d, which does not\n\n",
+		cred.Tenantid, foreign)
+
+	if _, err := repo.PosLogin(models.PosLoginRequest{
+		Authname: cred.Authname, Password: cred.Password, Locationid: foreign,
+	}); err == nil {
+		fmt.Println("  !! ACCEPTED — a tenant signed a till into another tenant's outlet")
+	} else {
+		fmt.Printf("  refused: %v\n", err)
+	}
+
+	allowed, err := repo.PosLocationAllowed(cred.Tenantid, foreign)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("  PosLocationAllowed(tenant %d, outlet %d) = %v (want false)\n",
+		cred.Tenantid, foreign, allowed)
+}

scratch/poslogins/main.go

@@ -0,0 +1,214 @@
+// Reports who can actually sign in at an outlet, and by which of the two ways.
+//
+// Read-only. Answers the question a shop asks on day one — "what do I type into
+// the till?" — by separating the two credentials that exist, because they are
+// not interchangeable:
+//
+//   - a password opens a *closed* terminal, and only a supervisor's does
+//     anything useful, because the shell it opens is decided by the account;
+//
+//   - a PIN switches operator on a terminal that is *already open*, and is
+//     useless on its own.
+//
+//     go run ./scratch/poslogins 1087 1135
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"strconv"
+	"strings"
+
+	"nearle/models"
+
+	"github.com/joho/godotenv"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+type row struct {
+	Userid                        int
+	Fullname, Authname, Contactno string
+	Password                      string
+	Pin                           int64
+	Roleid, Configid              int
+	Status                        string
+}
+
+func main() {
+	tenantID, locationID := 1087, 1135
+	if len(os.Args) > 2 {
+		tenantID, _ = strconv.Atoi(os.Args[1])
+		locationID, _ = strconv.Atoi(os.Args[2])
+	}
+
+	_ = 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)
+	}
+
+	// `top` ranks outlets by what a till would actually have to sell, so a demo
+	// is pointed at a shop with a catalogue rather than at one that opens empty.
+	if len(os.Args) > 1 && os.Args[1] == "top" {
+		type outletRow struct {
+			Tenantid, Locationid int
+			Tenantname, Locname  string
+			Products, Withpasswd int
+		}
+		var top []outletRow
+		db.Raw(`
+			SELECT t.tenantid, l.locationid,
+			       COALESCE(t.tenantname,'')   AS tenantname,
+			       COALESCE(l.locationname,'') AS locname,
+			       COUNT(DISTINCT a.productid) AS products,
+			       (SELECT COUNT(*) FROM app_users u
+			         WHERE u.tenantid = t.tenantid
+			           AND COALESCE(u.locationid,0) IN (l.locationid, 0)
+			           AND COALESCE(u.password,'') <> ''
+			           AND LOWER(COALESCE(u.status,'')) <> 'inactive') AS withpasswd
+			FROM tenantlocations l
+			JOIN tenants t ON t.tenantid = l.tenantid
+			JOIN productlocations b ON b.locationid = l.locationid AND b.tenantid = l.tenantid
+			JOIN products a ON a.productid = b.productid AND a.tenantid = b.tenantid
+			GROUP BY t.tenantid, l.locationid, t.tenantname, l.locationname
+			ORDER BY products DESC LIMIT 400`).Scan(&top)
+
+		fmt.Printf("%-8s %-10s %-22s %-26s %-9s %s\n",
+			"tenant", "outlet", "tenant name", "outlet name", "products", "can sign in")
+		shown := 0
+		for _, o := range top {
+			// Only outlets a person can actually open. A big catalogue behind a
+			// till nobody can sign in to is not a candidate for anything.
+			if o.Withpasswd == 0 || shown >= 12 {
+				continue
+			}
+			shown++
+			fmt.Printf("%-8d %-10d %-22s %-26s %-9d %d\n",
+				o.Tenantid, o.Locationid, trunc(o.Tenantname, 22),
+				trunc(o.Locname, 26), o.Products, o.Withpasswd)
+		}
+		return
+	}
+
+	var tenant, outlet string
+	db.Raw(`SELECT COALESCE(tenantname,'') FROM tenants WHERE tenantid=?`, tenantID).Scan(&tenant)
+	db.Raw(`SELECT COALESCE(locationname,'') FROM tenantlocations WHERE locationid=? AND tenantid=?`,
+		locationID, tenantID).Scan(&outlet)
+	if outlet == "" {
+		log.Fatalf("tenant %d has no outlet %d", tenantID, locationID)
+	}
+
+	// Counted the way /pos/catalogue counts them — products joined to this
+	// outlet — rather than per tenant. A tenant with a full catalogue can still
+	// have an outlet that stocks none of it, and that outlet's till opens empty.
+	var products int64
+	db.Raw(`SELECT COUNT(*)
+	        FROM products a
+	        INNER JOIN productlocations b
+	                ON a.productid = b.productid AND a.tenantid = b.tenantid
+	        WHERE a.tenantid = ? AND b.locationid = ?`, tenantID, locationID).Scan(&products)
+
+	fmt.Printf("tenant %d  %s\noutlet %d  %s\nproducts stocked at this outlet: %d\n",
+		tenantID, tenant, locationID, outlet, products)
+
+	// Everyone the outlet can see. locationid 0 is a tenant-wide account — a
+	// proprietor who is not pinned to one shop — and those can open any of
+	// their outlets, so they belong in this list too.
+	var rows []row
+	db.Raw(`
+		SELECT userid,
+		       TRIM(COALESCE(firstname,'') || ' ' || COALESCE(lastname,'')) AS fullname,
+		       COALESCE(authname,'')  AS authname,
+		       COALESCE(contactno,'') AS contactno,
+		       COALESCE(password,'')  AS password,
+		       COALESCE(pin,0)        AS pin,
+		       COALESCE(roleid,0)     AS roleid,
+		       COALESCE(configid,0)   AS configid,
+		       COALESCE(status,'')    AS status
+		FROM app_users
+		WHERE tenantid = ?
+		  AND COALESCE(locationid,0) IN (?, 0)
+		  AND LOWER(COALESCE(status,'')) <> 'inactive'
+		ORDER BY userid`, tenantID, locationID).Scan(&rows)
+
+	fmt.Printf("\n=== PASSWORD SIGN-IN  (POST /v1/pos/login) — opens a closed terminal ===\n")
+	fmt.Printf("%-7s %-24s %-30s %-12s %-6s %s\n",
+		"userid", "name", "authname (the username)", "role", "shell", "password")
+	any := false
+	for _, r := range rows {
+		if strings.TrimSpace(r.Password) == "" {
+			continue
+		}
+		any = true
+		shell := "cashier"
+		if models.PosRoleCanManageStaff(r.Roleid) {
+			shell = "SUPER"
+		}
+		role := models.PosRoleName(r.Roleid)
+		if role == "" {
+			role = fmt.Sprintf("(roleid %d)", r.Roleid)
+		}
+		id := r.Authname
+		if id == "" {
+			id = r.Contactno + "  (phone)"
+		}
+		fmt.Printf("%-7d %-24s %-30s %-12s %-6s %s\n",
+			r.Userid, trunc(r.Fullname, 24), trunc(id, 30), role, shell, r.Password)
+	}
+	if !any {
+		fmt.Println("  (nobody at this outlet has a password — the till cannot be opened)")
+	}
+
+	fmt.Printf("\n=== PIN SIGN-IN  (POST /v1/pos/login/pin) — switches operator, terminal already open ===\n")
+	fmt.Printf("%-7s %-24s %-12s %-6s %s\n", "userid", "name", "role", "shell", "pin")
+	any = false
+	seen := map[int64]int{}
+	for _, r := range rows {
+		if r.Pin == 0 {
+			continue
+		}
+		seen[r.Pin]++
+	}
+	for _, r := range rows {
+		if r.Pin == 0 {
+			continue
+		}
+		any = true
+		shell := "cashier"
+		if models.PosRoleCanManageStaff(r.Roleid) {
+			shell = "SUPER"
+		}
+		role := models.PosRoleName(r.Roleid)
+		if role == "" {
+			role = fmt.Sprintf("(roleid %d)", r.Roleid)
+		}
+		note := ""
+		if seen[r.Pin] > 1 {
+			note = "  <- DUPLICATE, refused at sign-in"
+		}
+		if r.Pin < 1000 {
+			note = "  <- under 4 digits, cannot be typed"
+		}
+		fmt.Printf("%-7d %-24s %-12s %-6s %04d%s\n",
+			r.Userid, trunc(r.Fullname, 24), role, shell, r.Pin, note)
+	}
+	if !any {
+		fmt.Println("  (nobody at this outlet has a PIN)")
+	}
+	fmt.Println()
+}
+
+func trunc(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n-1] + "…"
+}

scratch/posroles/main.go

@@ -0,0 +1,102 @@
+// Adds the two POS roles to app_roles.
+//
+// `app_roles` has no sequence on roleid — every id in it was assigned by hand —
+// so 7 and 8 are written explicitly and must match models.PosRoleSupervisor and
+// models.PosRoleCashier.
+//
+// configid is left NULL deliberately. Every other row is portal-specific, which
+// is why Admin appears twice (3 and 5) and Manager twice (4 and 6). A till is a
+// till whichever portal a tenant uses, and duplicating these per config would
+// be one more thing to remember on every onboarding.
+//
+//	go run ./scratch/posroles plan
+//	go run ./scratch/posroles apply
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+
+	"nearle/models"
+
+	"github.com/joho/godotenv"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+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)
+	}
+
+	wanted := []struct {
+		id   int
+		name string
+	}{
+		{models.PosRoleSupervisor, "Supervisor"},
+		{models.PosRoleCashier, "Cashier"},
+	}
+
+	write := mode == "apply"
+	changes := 0
+
+	for _, w := range wanted {
+		var existing string
+		db.Raw(`SELECT COALESCE(rolename,'') FROM app_roles WHERE roleid = ?`, w.id).Scan(&existing)
+
+		switch {
+		case existing == w.name:
+			fmt.Printf("  %-4d %-12s already present\n", w.id, w.name)
+		case existing != "":
+			// Refuses rather than overwrites. Renaming a role that something
+			// else already points at would silently re-permission real accounts.
+			fmt.Printf("  %-4d OCCUPIED by %q — refusing to overwrite\n", w.id, existing)
+		default:
+			fmt.Printf("  %-4d %-12s WOULD INSERT\n", w.id, w.name)
+			changes++
+			if write {
+				if err := db.Exec(
+					`INSERT INTO app_roles (roleid, rolename, configid) VALUES (?, ?, NULL)`,
+					w.id, w.name,
+				).Error; err != nil {
+					log.Fatalf("inserting role %d: %v", w.id, err)
+				}
+			}
+		}
+	}
+
+	fmt.Println()
+	if write {
+		fmt.Printf("APPLIED %d role(s).\n", changes)
+	} else {
+		fmt.Printf("%d role(s) would be added. Nothing written — run `apply`.\n", changes)
+	}
+
+	var rows []struct {
+		Roleid   int
+		Rolename string
+	}
+	db.Raw(`SELECT roleid, COALESCE(rolename,'') AS rolename FROM app_roles ORDER BY roleid`).Scan(&rows)
+	fmt.Println("\napp_roles now:")
+	for _, r := range rows {
+		fmt.Printf("  %-4d %s\n", r.Roleid, r.Rolename)
+	}
+
+	if len(rows) > 0 {
+		fmt.Println("\n-- undo:")
+		fmt.Printf("DELETE FROM app_roles WHERE roleid IN (%d, %d);\n",
+			models.PosRoleSupervisor, models.PosRoleCashier)
+	}
+}

scratch/posseparation/main.go

@@ -0,0 +1,179 @@
+// Proves the till and the Nearle Daily application no longer share accounts.
+//
+// Read-only. Four claims, each checked against live rows rather than asserted:
+//
+//  1. a provisioned supervisor can open a closed terminal;
+//
+//  2. a back-office account cannot, however senior it is;
+//
+//  3. a till account cannot reach the Nearle Daily application; and
+//
+//  4. a till account is not listed as though it were an app user.
+//
+//     go run ./scratch/posseparation
+package main
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"nearle/models"
+	"nearle/repositories"
+
+	"github.com/joho/godotenv"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+var failures int
+
+func check(claim string, ok bool, detail string) {
+	mark := "PASS"
+	if !ok {
+		mark = "FAIL"
+		failures++
+	}
+	fmt.Printf("  [%s] %s\n         %s\n", mark, claim, detail)
+}
+
+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 {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	pos := repositories.NewPosRepository(db)
+	users := repositories.NewUserRepository(db)
+
+	// A real provisioned supervisor, and its password, read back out.
+	var sup struct {
+		Userid                       int
+		Authname, Password           string
+		Configid, Tenantid, Location int
+	}
+	db.Raw(`SELECT userid, COALESCE(authname,'') authname, COALESCE(password,'') password,
+	               COALESCE(configid,0) configid, COALESCE(tenantid,0) tenantid,
+	               COALESCE(locationid,0) location
+	        FROM app_users
+	        WHERE COALESCE(roleid,0) = ? AND COALESCE(authname,'') <> ''
+	        ORDER BY userid LIMIT 1`, models.PosRoleSupervisor).Scan(&sup)
+	if sup.Userid == 0 {
+		fmt.Println("no provisioned supervisor to test with")
+		os.Exit(1)
+	}
+
+	fmt.Printf("supervisor under test: %d  %s  (tenant %d, outlet %d)\n\n",
+		sup.Userid, sup.Authname, sup.Tenantid, sup.Location)
+
+	fmt.Println("1. a provisioned supervisor opens a closed terminal")
+	session, err := pos.PosLogin(models.PosLoginRequest{
+		Authname: sup.Authname, Password: sup.Password,
+	})
+	check("supervisor signs in at the till",
+		err == nil && session != nil,
+		fmt.Sprintf("err=%v", err))
+	if session != nil {
+		check("and gets the supervisor shell",
+			session.Canmanagestaff && session.Roleid == models.PosRoleSupervisor,
+			fmt.Sprintf("role=%s can_manage_staff=%v", session.Role, session.Canmanagestaff))
+	}
+
+	// The same, for a cashier. A cashier opening a till on their own credentials
+	// is the point of this: a shop should not need two people present before it
+	// can sell anything.
+	var cash struct {
+		Userid             int
+		Authname, Password string
+	}
+	db.Raw(`SELECT userid, COALESCE(authname,'') authname, COALESCE(password,'') password
+	        FROM app_users
+	        WHERE COALESCE(roleid,0) = ? AND COALESCE(authname,'') <> ''
+	        ORDER BY userid LIMIT 1`, models.PosRoleCashier).Scan(&cash)
+
+	if cash.Userid == 0 {
+		check("a cashier has their own login", false, "no cashier has an authname")
+	} else {
+		cs, err := pos.PosLogin(models.PosLoginRequest{
+			Authname: cash.Authname, Password: cash.Password,
+		})
+		check(fmt.Sprintf("cashier %s opens a closed terminal alone", cash.Authname),
+			err == nil && cs != nil,
+			fmt.Sprintf("err=%v", err))
+		if cs != nil {
+			check("and is held to the billing-only shell",
+				!cs.Canmanagestaff && cs.Roleid == models.PosRoleCashier,
+				fmt.Sprintf("role=%s can_manage_staff=%v", cs.Role, cs.Canmanagestaff))
+		}
+	}
+
+	fmt.Println("\n2. back-office accounts cannot open a terminal at all")
+	var backOffice []struct {
+		Userid             int
+		Authname, Password string
+		Roleid             int
+	}
+	db.Raw(`SELECT userid, COALESCE(authname,'') authname, COALESCE(password,'') password,
+	               COALESCE(roleid,0) roleid
+	        FROM app_users
+	        WHERE COALESCE(roleid,0) IN (1,2,3,4,5,6)
+	          AND COALESCE(authname,'') <> '' AND COALESCE(password,'') <> ''
+	          AND LOWER(COALESCE(status,'active')) <> 'inactive'
+	        ORDER BY userid LIMIT 5`).Scan(&backOffice)
+	for _, b := range backOffice {
+		_, err := pos.PosLogin(models.PosLoginRequest{
+			Authname: b.Authname, Password: b.Password,
+		})
+		check(fmt.Sprintf("roleid %d (%s) refused at the till", b.Roleid, b.Authname),
+			err != nil && strings.Contains(err.Error(), "not set up for the till"),
+			fmt.Sprintf("err=%v", err))
+	}
+
+	fmt.Println("\n3. a till account cannot reach the Nearle Daily application")
+	uid, _, _ := users.GetUserByAuthname(sup.Authname, sup.Configid)
+	check("applogin lookup does not find the supervisor",
+		uid == 0,
+		fmt.Sprintf("GetUserByAuthname(%s) -> userid %d", sup.Authname, uid))
+
+	uid2, _, _, _ := users.GetUserLogin("authname", sup.Authname, sup.Configid)
+	check("tenant web login does not find the supervisor",
+		uid2 == 0,
+		fmt.Sprintf("GetUserLogin(%s) -> userid %d", sup.Authname, uid2))
+
+	uid3, _ := users.FindUserID(sup.Authname, "", sup.Configid)
+	check("password-setup lookup does not find the supervisor",
+		uid3 == 0,
+		fmt.Sprintf("FindUserID(%s) -> userid %d", sup.Authname, uid3))
+
+	fmt.Println("\n4. till accounts are not listed as app users")
+	list, err := users.GetAllUsers(0, sup.Tenantid, 1, 500, "")
+	leaked := 0
+	for _, u := range list {
+		if u.Roleid == models.PosRoleSupervisor || u.Roleid == models.PosRoleCashier {
+			leaked++
+		}
+	}
+	check("getallusers hides till accounts",
+		err == nil && leaked == 0,
+		fmt.Sprintf("%d of %d rows were till accounts", leaked, len(list)))
+
+	// ...but the POS console can still read its own people by asking for them.
+	sups, err := users.GetAllUsers(models.PosRoleSupervisor, sup.Tenantid, 1, 500, "")
+	check("asking for role 7 explicitly still works",
+		err == nil && len(sups) > 0,
+		fmt.Sprintf("%d supervisor(s) returned", len(sups)))
+
+	fmt.Println()
+	if failures > 0 {
+		fmt.Printf("%d CHECK(S) FAILED\n", failures)
+		os.Exit(1)
+	}
+	fmt.Println("all checks passed")
+}

scratch/posstaffsetup/main.go

@@ -0,0 +1,171 @@
+// Creates a supervisor and a cashier at an outlet, then proves both can sign in.
+//
+// Exists because outlet 1135 — the one the terminal ships pointed at — had no
+// staff at all, so the till fell back to the three PINs compiled into the app.
+// Real staff here are what retire those.
+//
+// PINs are generated rather than chosen, from crypto/rand, and printed once so
+// they can be handed to the shop. They are deliberately not derived from
+// anything guessable.
+//
+//	go run ./scratch/posstaffsetup plan  1087 1135
+//	go run ./scratch/posstaffsetup apply 1087 1135
+package main
+
+import (
+	"crypto/rand"
+	"fmt"
+	"log"
+	"math/big"
+	"os"
+	"strconv"
+
+	"nearle/models"
+	"nearle/repositories"
+
+	"github.com/joho/godotenv"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+func main() {
+	mode, tenantID, locationID := "plan", 1087, 1135
+	if len(os.Args) > 1 {
+		mode = os.Args[1]
+	}
+	if len(os.Args) > 3 {
+		tenantID, _ = strconv.Atoi(os.Args[2])
+		locationID, _ = strconv.Atoi(os.Args[3])
+	}
+
+	_ = 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)
+	}
+	repo := repositories.NewPosRepository(db)
+
+	var locName string
+	db.Raw(`SELECT COALESCE(locationname,'') FROM tenantlocations WHERE locationid=? AND tenantid=?`,
+		locationID, tenantID).Scan(&locName)
+	if locName == "" {
+		log.Fatalf("tenant %d has no outlet %d", tenantID, locationID)
+	}
+
+	// The configid the shop's other accounts use, so a new cashier is visible
+	// to the same portal as everybody else at that outlet.
+	var configID int
+	db.Raw(`SELECT COALESCE(configid,0) FROM app_users
+	        WHERE tenantid=? AND COALESCE(configid,0) > 0
+	        GROUP BY configid ORDER BY COUNT(*) DESC LIMIT 1`, tenantID).Scan(&configID)
+
+	fmt.Printf("tenant %d, outlet %d (%s), configid %d\n\n", tenantID, locationID, locName, configID)
+
+	existing, err := repo.ListPosUsers(tenantID, locationID, true)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("till users already at this outlet: %d\n", len(existing))
+	for _, u := range existing {
+		fmt.Printf("  %-6d %-22s %-12s pin=%s %s\n", u.Userid, u.Fullname, u.Role, u.Pin, u.Status)
+	}
+	if len(existing) > 0 {
+		fmt.Println("\nAlready set up. Nothing to do — this refuses to add duplicates.")
+		return
+	}
+
+	// Both roles get a username and a password as well as a PIN, and neither is
+	// stated here: CreatePosUser generates them and returns them once.
+	//
+	// A PIN cannot open a *closed* terminal — the PIN route requires a session
+	// that already exists — so a PIN-only account works only while somebody else
+	// is standing there to unlock the till first. For a supervisor that was an
+	// outright deadlock; for a cashier it means a shop that cannot open until
+	// two people have arrived. Whoever gets in at seven is as often the cashier
+	// as the supervisor.
+	wanted := []models.PosUserRequest{
+		{Fullname: "Store Supervisor", Role: "supervisor", Pin: newPin()},
+		{Fullname: "Counter Cashier", Role: "cashier", Pin: newPin()},
+	}
+	for wanted[0].Pin == wanted[1].Pin {
+		wanted[1].Pin = newPin()
+	}
+
+	fmt.Println("\nwould create:")
+	for _, w := range wanted {
+		fmt.Printf("  %-22s %-12s pin=%s  (login generated on create)\n",
+			w.Fullname, w.Role, w.Pin)
+	}
+
+	if mode != "apply" {
+		fmt.Println("\nNothing written — run `apply` to commit.")
+		return
+	}
+
+	fmt.Println()
+	for _, w := range wanted {
+		created, err := repo.CreatePosUser(tenantID, locationID, configID, w)
+		if err != nil {
+			log.Fatalf("creating %s: %v", w.Fullname, err)
+		}
+		fmt.Printf("  created userid %-6d %-22s %-12s PIN %s\n",
+			created.Userid, created.Fullname, created.Role, created.Pin)
+		fmt.Printf("         login %s / %s\n", created.Authname, created.Password)
+	}
+
+	// The point of the exercise: does the till now see real staff?
+	staff, err := repo.PosStaff(tenantID, locationID)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("\n/pos/staff now returns %d person(s):\n", len(staff))
+	for _, s := range staff {
+		fmt.Printf("  %-22s %-12s\n", s.Fullname, s.Role)
+	}
+
+	// And can they actually sign in?
+	fmt.Println("\nPIN sign-in:")
+	for _, w := range wanted {
+		session, err := repo.PosLoginByPin(tenantID, locationID, w.Pin)
+		if err != nil {
+			fmt.Printf("  %-22s REFUSED: %v\n", w.Fullname, err)
+			continue
+		}
+		fmt.Printf("  %-22s -> %s at %s, can_manage_staff=%v\n",
+			w.Fullname, session.Role, session.Locationname, session.Canmanagestaff)
+	}
+
+	if _, err := repo.PosLoginByPin(tenantID, locationID, "5555"); err != nil {
+		fmt.Printf("\n  an unknown PIN is refused: %v\n", err)
+	} else {
+		fmt.Println("\n  !! an unknown PIN was ACCEPTED")
+	}
+
+	fmt.Println("\n-- undo:")
+	fmt.Printf("UPDATE app_users SET status='InActive' WHERE tenantid=%d AND locationid=%d AND roleid IN (%d,%d);\n",
+		tenantID, locationID, models.PosRoleSupervisor, models.PosRoleCashier)
+}
+
+// newPin returns a four-digit PIN this schema can store, from crypto/rand.
+//
+// 1000–9999 because a leading zero cannot survive a bigint column, and the
+// obvious ones are rejected by validatePosPin anyway — retried here rather than
+// filtered, so the distribution stays even.
+func newPin() string {
+	for {
+		n, err := rand.Int(rand.Reader, big.NewInt(9000))
+		if err != nil {
+			log.Fatal(err)
+		}
+		pin := strconv.FormatInt(n.Int64()+1000, 10)
+		switch pin {
+		case "1234", "1111", "2345", "3456", "4321", "9999", "2222":
+			continue
+		}
+		return pin
+	}
+}

scratch/postilllogin/main.go

@@ -0,0 +1,131 @@
+// Gives every till account a way to open a closed terminal.
+//
+// A PIN cannot do it: the PIN route requires a session that already exists, so
+// a PIN-only account works only while somebody else is standing there to unlock
+// the till first. For a supervisor that was an outright deadlock. For a cashier
+// it means a shop that cannot open until two people have arrived — and whoever
+// gets in at seven is as often the cashier as the supervisor.
+//
+// So both roles get a username and a password. This backfills the ones created
+// before that was understood; new accounts get them from CreatePosUser.
+//
+//	go run ./scratch/postilllogin plan
+//	go run ./scratch/postilllogin apply
+package main
+
+import (
+	"crypto/rand"
+	"fmt"
+	"log"
+	"math/big"
+	"os"
+
+	"strings"
+
+	"nearle/models"
+	"nearle/repositories"
+
+	"github.com/joho/godotenv"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+func newPassword() string {
+	// No l/I/O/0/1 — these get read off a screen and typed at a counter.
+	const alphabet = "abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+	out := make([]byte, 14)
+	for i := range out {
+		n, err := rand.Int(rand.Reader, big.NewInt(int64(len(alphabet))))
+		if err != nil {
+			log.Fatalf("generating a password: %v", err)
+		}
+		out[i] = alphabet[n.Int64()]
+	}
+	return string(out)
+}
+
+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)
+	}
+	repo := repositories.NewPosRepository(db)
+
+	type target struct {
+		Userid, Tenantid, Locationid, Roleid int
+		Fullname, Locationname               string
+	}
+	var targets []target
+	db.Raw(`SELECT a.userid, a.tenantid, a.locationid, COALESCE(a.roleid,0) AS roleid,
+	               TRIM(COALESCE(a.firstname,'')||' '||COALESCE(a.lastname,'')) AS fullname,
+	               COALESCE(l.locationname,'') AS locationname
+	        FROM app_users a
+	        LEFT JOIN tenantlocations l
+	               ON l.locationid = a.locationid AND l.tenantid = a.tenantid
+	        WHERE COALESCE(a.roleid,0) IN (?, ?)
+	          AND (COALESCE(a.password,'') = '' OR COALESCE(a.authname,'') = '')
+	          AND LOWER(COALESCE(a.status,'active')) <> 'inactive'
+	        ORDER BY a.userid`, models.PosRoleSupervisor, models.PosRoleCashier).Scan(&targets)
+
+	if len(targets) == 0 {
+		fmt.Println("Every till account already has a login. Nothing to do.")
+		return
+	}
+
+	fmt.Printf("till accounts with no way to open a closed terminal: %d\n\n", len(targets))
+
+	for _, t := range targets {
+		authname := fmt.Sprintf("%s.%d@pos.nearle.in",
+			strings.ToLower(models.PosRoleName(t.Roleid)), t.Locationid)
+		password := newPassword()
+
+		if mode != "apply" {
+			fmt.Printf("  %-6d %-18s outlet %-6d %-26s -> %s / %s\n",
+				t.Userid, t.Fullname, t.Locationid, t.Locationname, authname, password)
+			continue
+		}
+
+		_, err := repo.UpdatePosUser(t.Tenantid, t.Locationid, models.PosUserRequest{
+			Userid:   t.Userid,
+			Authname: authname,
+			Password: password,
+		})
+		if err != nil {
+			fmt.Printf("  %-6d FAILED: %v\n", t.Userid, err)
+			continue
+		}
+
+		// Prove it, rather than assert it — the whole point of this tool is that
+		// a supervisor who cannot sign in is indistinguishable from one who can
+		// until somebody stands at a counter and tries.
+		session, err := repo.PosLogin(models.PosLoginRequest{
+			Authname: authname,
+			Password: password,
+		})
+		if err != nil {
+			fmt.Printf("  %-6d written, but sign-in still fails: %v\n", t.Userid, err)
+			continue
+		}
+
+		fmt.Printf("  %-6d %-18s outlet %-6d %-26s\n", t.Userid, t.Fullname, t.Locationid, t.Locationname)
+		fmt.Printf("         login    %s / %s\n", authname, password)
+		fmt.Printf("         opens as %s at %s, can_manage_staff=%v\n",
+			session.Role, session.Locationname, session.Canmanagestaff)
+	}
+
+	if mode != "apply" {
+		fmt.Println("\nNothing written — run `apply` to commit.")
+	}
+}

scratch/seedprices/main.go

@@ -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
+}

scratch/termfixcleanup/main.go

@@ -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)
+}

services/orderService.go

@@ -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)
 }

services/posService.go

@@ -0,0 +1,178 @@
+package services
+
+import (
+	"context"
+	"time"
+
+	"nearle/models"
+	"nearle/repositories"
+	"nearle/utils"
+)
+
+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)
+
+	// Login authenticates a person against the same account store the web
+	// console uses and mints the session a till carries for the trading day.
+	Login(req models.PosLoginRequest) (*models.PosSession, error)
+
+	// LocationAllowed is the authorisation check every other POS call rests on:
+	// does the tenant in the caller's token actually own this outlet.
+	LocationAllowed(tenantID, locationID int) (bool, error)
+
+	// Staff lists who may ring a bill at an outlet. Sent with the session and
+	// available on its own, so a shop that hires someone mid-shift can pull them
+	// down without signing the terminal out.
+	Staff(tenantID, locationID int) ([]models.PosStaffMember, error)
+
+	// Till staff management, all scoped to the caller's own outlet.
+	CreateUser(tenantID, locationID, configID int, req models.PosUserRequest) (*models.PosUser, error)
+	UpdateUser(tenantID, locationID int, req models.PosUserRequest) (*models.PosUser, error)
+	ListUsers(tenantID, locationID int, includeInactive bool) ([]models.PosUser, error)
+	DeactivateUser(tenantID, locationID, userID int) error
+
+	// LoginWithPin signs a person in at a terminal that is already open. Never
+	// reachable anonymously — four digits is not a barrier on its own.
+	LoginWithPin(tenantID, locationID int, pin string) (*models.PosSession, error)
+
+	// ConfigidFor infers which portal a tenant's people belong to, so the console
+	// is never asked for a number nobody can look up.
+	ConfigidFor(tenantID int) int
+}
+
+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)
+}
+
+// Login authenticates a terminal's operator and issues its session.
+//
+// The token is minted here rather than in the repository so that the signing
+// key stays out of the layer that talks to the database, and so a future change
+// of token format touches one function.
+func (s *posService) Login(req models.PosLoginRequest) (*models.PosSession, error) {
+	session, err := s.repo.PosLogin(req)
+	if err != nil {
+		return nil, err
+	}
+
+	return s.mint(session, req.Terminalid)
+}
+
+// mint signs a resolved session.
+//
+// Kept apart from the credential checks so the signing key stays out of the
+// layer that talks to the database, and so a change of token format touches one
+// function rather than every way in.
+func (s *posService) mint(session *models.PosSession, terminalID string) (*models.PosSession, error) {
+	token, expires, err := utils.MintPosToken(utils.PosClaims{
+		Userid:     session.Userid,
+		Tenantid:   session.Tenantid,
+		Locationid: session.Locationid,
+		Roleid:     session.Roleid,
+		Configid:   session.Configid,
+		Terminalid: terminalID,
+	}, time.Now())
+	if err != nil {
+		return nil, err
+	}
+
+	session.Token = token
+	session.Expiresat = expires.UTC().Format(time.RFC3339)
+
+	return session, nil
+}
+
+func (s *posService) LocationAllowed(tenantID, locationID int) (bool, error) {
+	return s.repo.PosLocationAllowed(tenantID, locationID)
+}
+
+func (s *posService) Staff(tenantID, locationID int) ([]models.PosStaffMember, error) {
+	return s.repo.PosStaff(tenantID, locationID)
+}
+
+func (s *posService) CreateUser(tenantID, locationID, configID int, req models.PosUserRequest) (*models.PosUser, error) {
+	return s.repo.CreatePosUser(tenantID, locationID, configID, req)
+}
+
+func (s *posService) UpdateUser(tenantID, locationID int, req models.PosUserRequest) (*models.PosUser, error) {
+	return s.repo.UpdatePosUser(tenantID, locationID, req)
+}
+
+func (s *posService) ListUsers(tenantID, locationID int, includeInactive bool) ([]models.PosUser, error) {
+	return s.repo.ListPosUsers(tenantID, locationID, includeInactive)
+}
+
+func (s *posService) DeactivateUser(tenantID, locationID, userID int) error {
+	return s.repo.DeactivatePosUser(tenantID, locationID, userID)
+}
+
+// LoginWithPin mints a fresh session for whoever the PIN belongs to.
+//
+// A new token rather than a reused one, because the token carries the role and
+// a cashier taking over from a supervisor must not inherit their permissions.
+func (s *posService) LoginWithPin(tenantID, locationID int, pin string) (*models.PosSession, error) {
+	session, err := s.repo.PosLoginByPin(tenantID, locationID, pin)
+	if err != nil {
+		return nil, err
+	}
+	return s.mint(session, "")
+}
+
+func (s *posService) ConfigidFor(tenantID int) int {
+	return s.repo.PosConfigidFor(tenantID)
+}

services/productService.go

@@ -22,8 +22,9 @@ 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 int) ([]models.Products, error)
+	GetProductByVariant(tenantid, variantid, locationid int) ([]models.Products, error)
 	GetProductsBySubcategory(params models.ProductFilter) (map[string]interface{}, error)
 	UpdateProductLocation(input models.Productlocations) error
 	CreateProductLocation(input []models.Productlocations) error
@@ -76,19 +77,35 @@ func (s *productService) CreateProductStock(stocks []models.Productstock) error
 		return err
 	}
 
-	idMap := make(map[int]struct{})
+	locMap := make(map[models.ProductLocationRef]struct{})
-	var productIDs []int
+	var locRefs []models.ProductLocationRef
-	for _, s := range stocks {
+	for _, stk := range stocks {
-		if s.Productid > 0 {
+		// Every entry gets synced, "in" and "out" alike: the status is now
-			if _, exists := idMap[s.Productid]; !exists {
+		// derived from the resulting balance rather than assumed from the
-				idMap[s.Productid] = struct{}{}
+		// direction of the movement, so an "out" that empties a location
-				productIDs = append(productIDs, s.Productid)
+		// 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{}{}
+				locRefs = append(locRefs, ref)
 			}
 		}
 	}
 
-	if len(productIDs) > 0 {
+	// products.productstatus is deliberately NOT touched here. It is a
-		if err := s.repo.UpdateProductStatus(productIDs, "available"); err != nil {
+	// 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.SyncProductLocationStatus(locRefs); err != nil {
 			return err
 		}
 	}
@@ -124,16 +141,20 @@ 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)
 }
 
-func (s *productService) GetProductByVariant(tenantid, variantid int) ([]models.Products, error) {
+func (s *productService) GetProductByVariant(tenantid, variantid, locationid int) ([]models.Products, error) {
 
 	var data []models.Products
 
-	result, err := s.repo.GetProductByVariant(tenantid, variantid)
+	result, err := s.repo.GetProductByVariant(tenantid, variantid, locationid)
 
 	if err != nil {
 		return nil, err
@@ -272,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,
@@ -279,6 +305,7 @@ func (s *productService) ImportCatalogueProduct(reqs []models.ImportCataloguePro
 			Quantity:   req.Quantity,
 			Stocktype:  req.Stocktype,
 			Status:     req.Status,
+			Price:      float32(req.Retailprice),
 		})
 	}
 

services/tenantService.go

@@ -107,7 +107,7 @@ func (s *tenantService) UpdateStaff(user models.User) error {
 }
 
 func (s *tenantService) CreateTenantLocation(data models.Tenantlocations) map[string]interface{} {
-	err := s.repo.CreateTenantLocation(data)
+	created, err := s.repo.CreateTenantLocation(data)
 	if err != nil {
 		return map[string]interface{}{
 			"code":    http.StatusConflict,
@@ -116,10 +116,14 @@ func (s *tenantService) CreateTenantLocation(data models.Tenantlocations) map[st
 		}
 	}
 
+	// "details" carries back the DB-assigned locationid so the frontend can
+	// build the store's QR code (tenantid+locationid) immediately after
+	// onboarding, instead of having to look the new location up separately.
 	return map[string]interface{}{
 		"code":    http.StatusCreated,
 		"message": "Tenant Location Successfully Created",
 		"status":  true,
+		"details": created,
 	}
 }
 

services/utilsService.go

@@ -48,5 +48,25 @@ func (s *utilsService) GetAppConfig(configID int) (models.Appconfig, error) {
 }
 
 func (s *utilsService) GetAppCategory() ([]models.AppCategory, error) {
-	return s.repo.GetAppCategory()
+	categories, err := s.repo.GetAppCategory()
+	if err != nil {
+		return nil, err
+	}
+
+	// "All" is a synthetic pseudo-category, not a real app_category row — it
+	// must never be inserted into app_category itself, since product-listing
+	// filters (e.g. ProductController.GetAllProducts) already treat
+	// categoryid=0 as "no category filter". Keeping this row's id at 0 reuses
+	// that existing convention instead of adding a new one.
+	all := models.AppCategory{
+		Categoryid:   0,
+		Categoryname: "All",
+		Categorytype: 7,
+		Sortorder:    0,
+		Crossaxis:    1,
+		Mainaxis:     1,
+		Status:       "Active",
+	}
+
+	return append([]models.AppCategory{all}, categories...), nil
 }

utils/postoken.go

@@ -0,0 +1,164 @@
+package utils
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+)
+
+// Session tokens for the POS terminal.
+//
+// A till is not a browser. It signs in once when a shop opens and then bills
+// for a whole trading day — often on a connection that comes and goes — so the
+// thing it carries has to survive a reboot, a lost network, and an hour in a
+// drawer. That rules out a server-side session table (a till that cannot reach
+// us must still be able to prove who it is when it comes back) and it rules out
+// a short expiry.
+//
+// So: a signed, self-describing token. Everything needed to authorise a request
+// is inside it, and the signature is what makes it trustworthy. No database
+// round trip on the hot path, and nothing to replicate between pods.
+//
+// Deliberately not JWT. The backend has no JWT dependency today, and the format
+// buys nothing here — there is exactly one issuer, one audience and one
+// algorithm, so the header that JWT spends bytes negotiating is a constant. The
+// `alg` field is also the source of JWT's worst-known footgun (`alg: none`),
+// and a format with no algorithm field cannot have that bug.
+//
+// Wire format is `base64url(payload).base64url(hmac-sha256)`, and the MAC is
+// taken over the encoded payload rather than the raw JSON so that verification
+// never has to re-serialise anything to check it.
+
+// PosClaims is what a terminal proves about itself on every request.
+//
+// Locationid is the load-bearing field. Before this existed the till named its
+// own store on the wire and was believed, so changing one number in Settings
+// moved a terminal into another tenant's books. Now the location is decided at
+// sign-in, from the user's own record, and sealed under the signature.
+type PosClaims struct {
+	Userid     int    `json:"uid"`
+	Tenantid   int    `json:"tid"`
+	Locationid int    `json:"lid"`
+	Roleid     int    `json:"rid"`
+	Configid   int    `json:"cid"`
+	Terminalid string `json:"trm,omitempty"`
+	Issuedat   int64  `json:"iat"`
+	Expiresat  int64  `json:"exp"`
+}
+
+// PosTokenTTL is how long a till stays signed in.
+//
+// Thirty days rather than hours. A shop signs the terminal in once and expects
+// it to keep working; forcing a re-login mid-shift would mean a queue of
+// customers waiting while somebody finds the manager's password. The exposure
+// that buys is bounded by the token naming a single location — a leaked one
+// bills into the shop it was already for.
+const PosTokenTTL = 30 * 24 * time.Hour
+
+// posTokenSecret is the signing key.
+//
+// Fails loudly rather than falling back to a baked-in default. A hardcoded
+// development secret has a way of reaching production, and a signing key that
+// everyone with the source can compute is the same as no signature at all —
+// anyone could mint a token for any tenant.
+func posTokenSecret() ([]byte, error) {
+	secret := strings.TrimSpace(os.Getenv("POS_TOKEN_SECRET"))
+	if secret == "" {
+		// Falls back to the key the config file already carries, so a
+		// deployment that set that one does not need a second variable.
+		secret = strings.TrimSpace(os.Getenv("JWT_SECRET_KEY"))
+	}
+	if secret == "" {
+		return nil, fmt.Errorf("POS_TOKEN_SECRET is not set; terminals cannot be issued sessions")
+	}
+	if len(secret) < 16 {
+		return nil, fmt.Errorf("POS_TOKEN_SECRET is too short to sign with; use at least 16 characters")
+	}
+	return []byte(secret), nil
+}
+
+// MintPosToken issues a session for a signed-in terminal.
+func MintPosToken(claims PosClaims, now time.Time) (string, time.Time, error) {
+	secret, err := posTokenSecret()
+	if err != nil {
+		return "", time.Time{}, err
+	}
+
+	expires := now.Add(PosTokenTTL)
+	claims.Issuedat = now.Unix()
+	claims.Expiresat = expires.Unix()
+
+	payload, err := json.Marshal(claims)
+	if err != nil {
+		return "", time.Time{}, err
+	}
+
+	encoded := base64.RawURLEncoding.EncodeToString(payload)
+	return encoded + "." + sign(encoded, secret), expires, nil
+}
+
+// ParsePosToken verifies a token and returns what it claims.
+//
+// Order matters: the signature is checked before the payload is trusted for
+// anything, including expiry. Reading `exp` out of an unverified payload and
+// acting on it would be taking the attacker's word for when their own token
+// runs out.
+func ParsePosToken(token string, now time.Time) (PosClaims, error) {
+	secret, err := posTokenSecret()
+	if err != nil {
+		return PosClaims{}, err
+	}
+
+	encoded, signature, found := strings.Cut(strings.TrimSpace(token), ".")
+	if !found || encoded == "" || signature == "" {
+		return PosClaims{}, fmt.Errorf("malformed session token")
+	}
+
+	// Constant time, so a caller cannot learn the right signature one byte at a
+	// time from how long the comparison took.
+	if !hmac.Equal([]byte(signature), []byte(sign(encoded, secret))) {
+		return PosClaims{}, fmt.Errorf("session token signature does not verify")
+	}
+
+	payload, err := base64.RawURLEncoding.DecodeString(encoded)
+	if err != nil {
+		return PosClaims{}, fmt.Errorf("malformed session token")
+	}
+
+	var claims PosClaims
+	if err := json.Unmarshal(payload, &claims); err != nil {
+		return PosClaims{}, fmt.Errorf("malformed session token")
+	}
+
+	if claims.Expiresat > 0 && now.Unix() >= claims.Expiresat {
+		return PosClaims{}, fmt.Errorf("session has expired; sign in again")
+	}
+
+	// A token that verifies but names no outlet would authorise nothing and
+	// must not be mistaken for one that authorises everything.
+	if claims.Locationid <= 0 || claims.Tenantid <= 0 {
+		return PosClaims{}, fmt.Errorf("session token names no outlet")
+	}
+
+	return claims, nil
+}
+
+func sign(encoded string, secret []byte) string {
+	mac := hmac.New(sha256.New, secret)
+	mac.Write([]byte(encoded))
+	return base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
+}
+
+// PosTokenConfigured reports whether sessions can be issued at all.
+//
+// Lets the server say "this deployment has no signing key" once at start-up
+// rather than answering every sign-in with a 500.
+func PosTokenConfigured() bool {
+	_, err := posTokenSecret()
+	return err == nil
+}

utils/postoken_test.go

@@ -0,0 +1,166 @@
+package utils
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+)
+
+func withSecret(t *testing.T, secret string) {
+	t.Helper()
+	t.Setenv("POS_TOKEN_SECRET", secret)
+}
+
+const testSecret = "a-test-signing-key-long-enough"
+
+func TestASessionSurvivesTheRoundTrip(t *testing.T) {
+	withSecret(t, testSecret)
+	now := time.Date(2026, 8, 6, 10, 0, 0, 0, time.UTC)
+
+	token, expires, err := MintPosToken(PosClaims{
+		Userid: 42, Tenantid: 1087, Locationid: 1135, Roleid: 3, Terminalid: "T5EDD",
+	}, now)
+	if err != nil {
+		t.Fatalf("minting: %v", err)
+	}
+
+	claims, err := ParsePosToken(token, now.Add(time.Hour))
+	if err != nil {
+		t.Fatalf("parsing a token we just issued: %v", err)
+	}
+
+	if claims.Tenantid != 1087 || claims.Locationid != 1135 {
+		t.Fatalf("the outlet did not survive: tenant %d location %d", claims.Tenantid, claims.Locationid)
+	}
+	if claims.Terminalid != "T5EDD" {
+		t.Fatalf("terminal id lost: %q", claims.Terminalid)
+	}
+	if !expires.After(now) {
+		t.Fatalf("expiry %v is not after issue %v", expires, now)
+	}
+}
+
+// The whole point of signing. Before this existed a till named its own outlet
+// on the wire and was believed, so this is the test that says it no longer can.
+func TestARewrittenOutletIsRefused(t *testing.T) {
+	withSecret(t, testSecret)
+	now := time.Date(2026, 8, 6, 10, 0, 0, 0, time.UTC)
+
+	token, _, err := MintPosToken(PosClaims{Userid: 1, Tenantid: 1087, Locationid: 1135}, now)
+	if err != nil {
+		t.Fatalf("minting: %v", err)
+	}
+
+	// Tamper: decode the payload, move it to another tenant's outlet, re-encode
+	// and keep the original signature — exactly what an attacker holding a real
+	// token would try.
+	encoded, signature, _ := strings.Cut(token, ".")
+	payload, err := base64.RawURLEncoding.DecodeString(encoded)
+	if err != nil {
+		t.Fatalf("decoding our own payload: %v", err)
+	}
+
+	var claims PosClaims
+	if err := json.Unmarshal(payload, &claims); err != nil {
+		t.Fatalf("unmarshalling our own payload: %v", err)
+	}
+	claims.Tenantid = 916
+	claims.Locationid = 1185
+
+	forged, _ := json.Marshal(claims)
+	tampered := base64.RawURLEncoding.EncodeToString(forged) + "." + signature
+
+	if _, err := ParsePosToken(tampered, now); err == nil {
+		t.Fatal("a token whose outlet was rewritten was accepted")
+	}
+}
+
+func TestAnExpiredSessionIsRefused(t *testing.T) {
+	withSecret(t, testSecret)
+	now := time.Date(2026, 8, 6, 10, 0, 0, 0, time.UTC)
+
+	token, _, err := MintPosToken(PosClaims{Userid: 1, Tenantid: 1087, Locationid: 1135}, now)
+	if err != nil {
+		t.Fatalf("minting: %v", err)
+	}
+
+	if _, err := ParsePosToken(token, now.Add(PosTokenTTL+time.Minute)); err == nil {
+		t.Fatal("an expired session was accepted")
+	}
+}
+
+// A token signed by somebody else must not verify here, or the signature is
+// decoration.
+func TestATokenFromAnotherKeyIsRefused(t *testing.T) {
+	withSecret(t, testSecret)
+	now := time.Date(2026, 8, 6, 10, 0, 0, 0, time.UTC)
+
+	token, _, err := MintPosToken(PosClaims{Userid: 1, Tenantid: 1087, Locationid: 1135}, now)
+	if err != nil {
+		t.Fatalf("minting: %v", err)
+	}
+
+	withSecret(t, "a-completely-different-key-here")
+	if _, err := ParsePosToken(token, now); err == nil {
+		t.Fatal("a token signed with another key verified")
+	}
+}
+
+func TestAMalformedTokenIsRefused(t *testing.T) {
+	withSecret(t, testSecret)
+	now := time.Now()
+
+	for _, token := range []string{
+		"",
+		"nodot",
+		".",
+		"only.",
+		".onlysignature",
+		"not-base64!.also-not-base64!",
+	} {
+		if _, err := ParsePosToken(token, now); err == nil {
+			t.Fatalf("malformed token %q was accepted", token)
+		}
+	}
+}
+
+// A deployment with no signing key must fail loudly rather than fall back to a
+// key anyone reading the source could compute.
+func TestNoSecretMeansNoSessions(t *testing.T) {
+	t.Setenv("POS_TOKEN_SECRET", "")
+	t.Setenv("JWT_SECRET_KEY", "")
+
+	if PosTokenConfigured() {
+		t.Fatal("reported configured with no secret set")
+	}
+	if _, _, err := MintPosToken(PosClaims{Tenantid: 1, Locationid: 1}, time.Now()); err == nil {
+		t.Fatal("minted a session with no signing key")
+	}
+}
+
+func TestAShortSecretIsRefused(t *testing.T) {
+	t.Setenv("POS_TOKEN_SECRET", "short")
+	t.Setenv("JWT_SECRET_KEY", "")
+
+	if _, _, err := MintPosToken(PosClaims{Tenantid: 1, Locationid: 1}, time.Now()); err == nil {
+		t.Fatal("signed with a secret too short to be worth signing with")
+	}
+}
+
+// A token that verifies but names no outlet authorises nothing, and must not be
+// mistaken for one that authorises everything.
+func TestASessionNamingNoOutletIsRefused(t *testing.T) {
+	withSecret(t, testSecret)
+	now := time.Date(2026, 8, 6, 10, 0, 0, 0, time.UTC)
+
+	token, _, err := MintPosToken(PosClaims{Userid: 1, Tenantid: 0, Locationid: 0}, now)
+	if err != nil {
+		t.Fatalf("minting: %v", err)
+	}
+
+	if _, err := ParsePosToken(token, now); err == nil {
+		t.Fatal("a session naming no outlet was accepted")
+	}
+}