A customer number people can say out loud

Every id in the schema is a uuid and stays one. What was wrong was
putting one in front of a person: RecordVisit named every new customer
'Visitor ' || left(id::text, 8), so the arrivals feed, the shop PC and
the mobile app all read "Visitor 3446ec35" - the string a shop assistant
reads to a colleague and types into a search box. label is a stored
column staff can overwrite and SearchVisitors matches on, so formatting
around it in a front end would have left the data wrong on three
surfaces.

Migration 012 adds a per-client visitors.number, taken from a counter on
clients with UPDATE ... RETURNING inside the visit transaction. Per
client rather than global: a global sequence would tell any customer who
signs up how many people the whole platform has ever seen, from their
own first visitor number. The backfill numbers existing rows by
first_seen_at and relabels only the eight-hex pattern the old statement
produced, so a human-typed name is never overwritten.

Three of the four things anyone addresses by URL already had a human
name and the API simply refused it - a site has a slug, a camera has the
id the engine knows it by. refs.go accepts either form anywhere an id is
taken; a uuid resolves with no lookup, so every URL a client already
stored keeps working.

- An ambiguous camera name resolves to nothing, never to a guess: two
  shops may each have an "Office1" and acting on the first row would
  edit the wrong shop's camera.
- 404 on a path, 400 on a query filter. /api/visits answered fine and it
  was the filter that was wrong.
- site and site_id are both accepted everywhere now. They differed per
  endpoint, and an unknown query parameter is silently ignored, so
  getting it the wrong way round returned the whole estate.
- The search matches V-13, which is what the product now shows.

Two bugs found by running it rather than testing it:

- 'Visitor ' || $2::text beside number = $2 makes Postgres deduce two
  types for one parameter and refuse the insert. It compiled and passed
  every in-memory test; the first real database rejected it, along with
  the existing face tests that share the path.
- The fallback avatar said "V1" for Visitor 13, Visitor 10 and Visitor
  15 alike, and read as the V-1 reference for a fourth person. It shows
  the number now. The prop is customerRef, not ref - React reserves
  that name and it would never have arrived.

Verified on the live database and through the running API: 13 hex labels
became Visitor 1-13 in first-seen order, two typed names left alone, and
the same customer reachable by uuid, V-13 and 13.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HViLj9gYNRtSr7YVZmW5sn

server/internal/api/api.go

@@ -64,6 +64,14 @@ type Store interface {
 	Team(ctx context.Context, clientID string) ([]TeamMember, error)
 	UpdateTeamMember(ctx context.Context, clientID, userID string, up TeamUpdate) (TeamMember, error)
 
+	// --- public references ---
+	// Resolving the names people actually use to the uuids the schema stores.
+	// All three answer "" with a nil error when nothing matches; a found id is
+	// never empty, so a miss cannot be confused with a fault. See refs.go.
+	SiteIDBySlug(ctx context.Context, clientID, slug string) (string, error)
+	CameraIDByRef(ctx context.Context, clientID, ref string) (string, error)
+	VisitorIDByNumber(ctx context.Context, clientID string, number int64) (string, error)
+
 	// --- reports ---
 	Footfall(ctx context.Context, q ReportQuery) ([]FootfallPoint, Totals, error)
 	Conversion(ctx context.Context, q ReportQuery) (SalesReport, error)

server/internal/api/fake_test.go

@@ -179,7 +179,7 @@ func (f *fakeStore) CreateSession(_ context.Context, n NewSession) error {
 			FullName: rec.FullName, Role: rec.Role,
 		},
 		accessExp: n.AccessExpiry, refreshExp: n.RefreshExp,
-		device:    n.Device,
+		device: n.Device,
 	}
 	f.sessions[id] = s
 	f.byAccess[hex.EncodeToString(n.AccessHash)] = id
@@ -913,3 +913,85 @@ func (f *fakeStore) DeleteVisitFaces(_ context.Context, clientID string, keys []
 	}
 	return nil
 }
+
+// ============================================ public reference resolution ===
+//
+// These behave rather than merely satisfy the interface. The properties the
+// handlers are trusted for - a reference resolves only within the caller's own
+// tenant, and an ambiguous camera name resolves to nothing rather than to
+// whichever row came first - are exactly what a fake that always said yes would
+// stop any test from checking.
+
+func (f *fakeStore) SiteIDBySlug(_ context.Context, clientID, slug string) (string, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	for _, s := range f.sites {
+		// An owner of "" is a site the fake was not told about, which is the
+		// ordinary case: SiteHealth carries no client id, and most tests seed
+		// one tenant. Tests that assert cross-tenant resolution seed a camera,
+		// which is what gives a site an owner here.
+		if owner := f.siteClient(s.Slug, s.SiteID); s.Slug == slug &&
+			(owner == "" || owner == clientID) {
+			return s.SiteID, nil
+		}
+	}
+	return "", nil
+}
+
+// siteClient answers which tenant a site belongs to. SiteHealth carries no
+// client id of its own - it is already scoped by the query that returns it - so
+// the fake reads ownership from the cameras it was seeded with.
+func (f *fakeStore) siteClient(_, siteID string) string {
+	for _, ref := range f.cameraRefs {
+		if ref.site == siteID {
+			return ref.client
+		}
+	}
+	for _, c := range f.cameras {
+		if c.SiteID == siteID {
+			return f.cameraOwner(c.ID)
+		}
+	}
+	return ""
+}
+
+func (f *fakeStore) cameraOwner(id string) string {
+	if ref, ok := f.cameraRefs[id]; ok {
+		return ref.client
+	}
+	return ""
+}
+
+func (f *fakeStore) CameraIDByRef(_ context.Context, clientID, ref string) (string, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	var found []string
+	for _, c := range f.cameras {
+		if c.CameraID != ref {
+			continue
+		}
+		if owner := f.cameraOwner(c.ID); owner != "" && owner != clientID {
+			continue
+		}
+		found = append(found, c.ID)
+	}
+	// A camera id is unique per site, not per tenant. Two shops may each have
+	// an "Office1", and acting on whichever sorted first would edit the wrong
+	// shop's camera, so ambiguity is no match.
+	if len(found) != 1 {
+		return "", nil
+	}
+	return found[0], nil
+}
+
+func (f *fakeStore) VisitorIDByNumber(_ context.Context, clientID string, number int64) (string, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	want := VisitorRef(number)
+	for _, v := range f.visitors {
+		if v.Ref == want {
+			return v.ID, nil
+		}
+	}
+	return "", nil
+}

server/internal/api/handlers_arrivals.go

@@ -41,12 +41,14 @@ func (s *Server) handleArrivals(w http.ResponseWriter, r *http.Request) {
 
 	q := ArrivalQuery{
 		ClientID: p.ClientID,
-		SiteID:   trim(r.URL.Query().Get("site_id")),
+		SiteID:   siteParam(r),
 		Limit:    queryInt(r, "limit", defaultArrivals, maxArrivals),
 	}
-	if q.SiteID != "" && !looksLikeUUID(q.SiteID) {
-		badRequest(w, "site_id must be a site identifier")
-		return
+	if q.SiteID != "" {
+		var ok bool
+		if q.SiteID, ok = s.resolveSiteFilter(w, r, q.SiteID); !ok {
+			return
+		}
 	}
 	// The site is still filtered by client_id in SQL as well. A site_id from
 	// the query string is caller-controlled, and this is a read of other
@@ -157,12 +159,14 @@ func (s *Server) handleArrivalStream(w http.ResponseWriter, r *http.Request) {
 
 	q := ArrivalQuery{
 		ClientID: p.ClientID,
-		SiteID:   trim(r.URL.Query().Get("site_id")),
+		SiteID:   siteParam(r),
 		Limit:    queryInt(r, "limit", defaultArrivals, maxArrivals),
 	}
-	if q.SiteID != "" && !looksLikeUUID(q.SiteID) {
-		badRequest(w, "site_id must be a site identifier")
-		return
+	if q.SiteID != "" {
+		var ok bool
+		if q.SiteID, ok = s.resolveSiteFilter(w, r, q.SiteID); !ok {
+			return
+		}
 	}
 	// Last-Event-ID is what the browser's EventSource resends automatically on
 	// a dropped connection, so honouring it is what makes a reconnect lossless

server/internal/api/handlers_cameras.go

@@ -22,9 +22,11 @@ const snapshotTTL = 5 * time.Minute
 func (s *Server) handleCameras(w http.ResponseWriter, r *http.Request) {
 	p := PrincipalFrom(r.Context())
 	siteID := trim(r.URL.Query().Get("site_id"))
-	if siteID != "" && !looksLikeUUID(siteID) {
-		badRequest(w, "site_id must be a site identifier")
-		return
+	if siteID != "" {
+		var ok bool
+		if siteID, ok = s.resolveSiteFilter(w, r, siteID); !ok {
+			return
+		}
 	}
 	cams, err := s.Store.Cameras(r.Context(), p.ClientID, siteID)
 	if err != nil {
@@ -91,9 +93,8 @@ func (s *Server) handleCreateCamera(w http.ResponseWriter, r *http.Request) {
 			"Your account cannot change camera settings.")
 		return
 	}
-	siteID := r.PathValue("site")
-	if !looksLikeUUID(siteID) {
-		writeErr(w, http.StatusNotFound, "not_found", "That shop no longer exists.")
+	siteID, ok := s.resolveSite(w, r, r.PathValue("site"))
+	if !ok {
 		return
 	}
 	var in CameraInput
@@ -129,9 +130,8 @@ func (s *Server) handleUpdateCamera(w http.ResponseWriter, r *http.Request) {
 			"Your account cannot change camera settings.")
 		return
 	}
-	id := r.PathValue("id")
-	if !looksLikeUUID(id) {
-		writeErr(w, http.StatusNotFound, "not_found", "That camera no longer exists.")
+	id, ok := s.resolveCamera(w, r, r.PathValue("id"))
+	if !ok {
 		return
 	}
 	existing, err := s.Store.CameraByID(r.Context(), p.ClientID, id)
@@ -192,9 +192,8 @@ func (s *Server) handleDeleteCamera(w http.ResponseWriter, r *http.Request) {
 			"Your account cannot change camera settings.")
 		return
 	}
-	id := r.PathValue("id")
-	if !looksLikeUUID(id) {
-		writeErr(w, http.StatusNotFound, "not_found", "That camera no longer exists.")
+	id, ok := s.resolveCamera(w, r, r.PathValue("id"))
+	if !ok {
 		return
 	}
 	cam, err := s.Store.DeleteCamera(r.Context(), p.ClientID, id)

server/internal/api/handlers_checks.go

@@ -33,9 +33,8 @@ func (s *Server) handleRequestCheck(w http.ResponseWriter, r *http.Request) {
 			"Your account cannot run camera checks.")
 		return
 	}
-	id := r.PathValue("id")
-	if !looksLikeUUID(id) {
-		writeErr(w, http.StatusNotFound, "not_found", "That camera no longer exists.")
+	id, ok := s.resolveCamera(w, r, r.PathValue("id"))
+	if !ok {
 		return
 	}
 	var req CheckRequest
@@ -129,9 +128,8 @@ func (s *Server) handleAgentCheckResult(w http.ResponseWriter, r *http.Request,
 // and printing it next to a real failure buries the real failure.
 func (s *Server) handleSiteCheck(w http.ResponseWriter, r *http.Request) {
 	p := PrincipalFrom(r.Context())
-	siteID := r.PathValue("site")
-	if !looksLikeUUID(siteID) {
-		writeErr(w, http.StatusNotFound, "not_found", "That shop no longer exists.")
+	siteID, ok := s.resolveSite(w, r, r.PathValue("site"))
+	if !ok {
 		return
 	}
 	sites, err := s.Store.SiteHealth(r.Context(), p.ClientID)

server/internal/api/handlers_enrolment.go

@@ -25,9 +25,8 @@ func (s *Server) handleIssueEnrolmentCode(w http.ResponseWriter, r *http.Request
 			"Your account cannot set up shop computers. Ask a manager or the owner.")
 		return
 	}
-	site := r.PathValue("site")
-	if !looksLikeUUID(site) {
-		writeErr(w, http.StatusNotFound, "not_found", "No such shop.")
+	site, ok := s.resolveSite(w, r, r.PathValue("site"))
+	if !ok {
 		return
 	}
 	var in NewEnrolmentCodeInput

server/internal/api/handlers_images.go

@@ -86,9 +86,8 @@ const (
 // link stops working, not that we stop publishing it.
 func (s *Server) handleVisitorImage(w http.ResponseWriter, r *http.Request) {
 	p := PrincipalFrom(r.Context())
-	id := r.PathValue("id")
-	if !looksLikeUUID(id) {
-		writeErr(w, http.StatusNotFound, "not_found", "That customer no longer exists.")
+	id, ok := s.resolveVisitor(w, r, r.PathValue("id"))
+	if !ok {
 		return
 	}
 	key, err := s.Store.VisitorImageKey(r.Context(), p.ClientID, id)
@@ -140,9 +139,8 @@ func (s *Server) handleForgetVisitor(w http.ResponseWriter, r *http.Request) {
 			"Your account cannot delete customer records.")
 		return
 	}
-	id := r.PathValue("id")
-	if !looksLikeUUID(id) {
-		writeErr(w, http.StatusNotFound, "not_found", "That customer no longer exists.")
+	id, ok := s.resolveVisitor(w, r, r.PathValue("id"))
+	if !ok {
 		return
 	}
 

server/internal/api/handlers_live.go

@@ -32,9 +32,8 @@ const (
 // - would be a much worse trade than the 33% base64 costs.
 func (s *Server) handleWatchLive(w http.ResponseWriter, r *http.Request) {
 	p := PrincipalFrom(r.Context())
-	id := r.PathValue("id")
-	if !looksLikeUUID(id) {
-		writeErr(w, http.StatusNotFound, "not_found", "No such camera.")
+	id, ok := s.resolveCamera(w, r, r.PathValue("id"))
+	if !ok {
 		return
 	}
 	// Ownership is checked HERE, once, before anything is streamed. Everything

server/internal/api/handlers_people.go

@@ -26,11 +26,10 @@ func (s *Server) handleVisitors(w http.ResponseWriter, r *http.Request) {
 
 func (s *Server) handleVisitorHistory(w http.ResponseWriter, r *http.Request) {
 	p := PrincipalFrom(r.Context())
-	id := r.PathValue("id")
-	if !looksLikeUUID(id) {
-		// 404, not 400: to the caller a malformed id and an id that does not
-		// exist are the same thing - the customer is not there.
-		writeErr(w, http.StatusNotFound, "not_found", "That customer no longer exists.")
+	// 404, not 400: to the caller a reference that is malformed and one that
+	// names nobody are the same thing - the customer is not there.
+	id, ok := s.resolveVisitor(w, r, r.PathValue("id"))
+	if !ok {
 		return
 	}
 	rows, err := s.Store.VisitorHistory(r.Context(), p.ClientID, id,
@@ -65,11 +64,11 @@ func (s *Server) handleSaveProfile(w http.ResponseWriter, r *http.Request) {
 	}
 	// The path wins over the body. Trusting the body would let a client PUT to
 	// one customer's URL and write to another's record.
-	body.VisitorID = r.PathValue("id")
-	if !looksLikeUUID(body.VisitorID) {
-		writeErr(w, http.StatusNotFound, "not_found", "That customer no longer exists.")
+	visitorID, ok := s.resolveVisitor(w, r, r.PathValue("id"))
+	if !ok {
 		return
 	}
+	body.VisitorID = visitorID
 	body.FullName = clip(trim(body.FullName), 200)
 	body.Phone = clip(trim(body.Phone), 40)
 	body.Email = auth.NormalizeEmail(body.Email)
@@ -124,10 +123,11 @@ func (s *Server) handlePurchase(w http.ResponseWriter, r *http.Request) {
 		badRequest(w, "visitor_id is required")
 		return
 	}
-	if !looksLikeUUID(body.VisitorID) {
-		writeErr(w, http.StatusNotFound, "not_found", "That customer no longer exists.")
+	visitorID, ok := s.resolveVisitor(w, r, body.VisitorID)
+	if !ok {
 		return
 	}
+	body.VisitorID = visitorID
 	if body.Amount < 0 {
 		// A refund is a different record with a different meaning, not a
 		// negative sale. Allowing it here would quietly deflate the revenue

server/internal/api/handlers_reports.go

@@ -25,7 +25,21 @@ func (s *Server) reportQuery(r *http.Request) (ReportQuery, error) {
 
 	// The tenant comes from the session. A client_id parameter would be a
 	// cross-tenant read waiting for somebody to try it.
-	out := ReportQuery{ClientID: p.ClientID, SiteID: trim(q.Get("site"))}
+	out := ReportQuery{ClientID: p.ClientID}
+
+	// A shop may be named by uuid or by its slug. Resolved here, where an
+	// unknown one is a 400 the caller can read, rather than in Postgres where
+	// a malformed uuid is a cast error and surfaces as a 500.
+	if raw := siteParam(r); raw != "" {
+		id, err := s.siteIDFor(r.Context(), p.ClientID, raw)
+		if err != nil {
+			return out, fmt.Errorf("could not look up that shop: %w", err)
+		}
+		if id == "" {
+			return out, fmt.Errorf("no shop called %q", raw)
+		}
+		out.SiteID = id
+	}
 
 	now := s.now()
 	from, err := parseDay(q.Get("from"), now.AddDate(0, 0, -29))

server/internal/api/refs.go

@@ -0,0 +1,192 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"strconv"
+	"strings"
+)
+
+// Public references: the names people use for the things this API addresses.
+//
+// Every id in the schema is a uuid and stays one. A uuid is the right primary
+// key here - ids are minted in places that cannot ask a database for the next
+// value, and eleven tables reference them - but it is the wrong thing to put in
+// front of a person. "Which customer?" "3446ec35-2c1f-4c8e-9a77-0d1e2f3a4b5c."
+// Nobody says that, writes it on a card, or reads it back down a phone without
+// getting it wrong.
+//
+// The fix is not a new key. Three of the four things anyone addresses by URL
+// ALREADY had a human name that this API simply refused to accept:
+//
+//	site     slug        "chennai"      - in the schema since 001
+//	camera   camera_id   "Office1"      - and it is what visits.camera_id holds
+//	visitor  V-<number>  "V-42"         - added in 012
+//	user     email                      - already the login
+//
+// So a caller may use either form anywhere an id is taken. A uuid resolves with
+// no lookup at all, exactly as before; only a non-uuid costs a query. That
+// keeps this additive: nothing that worked yesterday changes, including every
+// URL a client has already stored.
+//
+// The visitor number is per TENANT, which is what makes it safe to show. A
+// global sequence would tell any customer who signs up how many people the
+// whole platform has ever seen, from their own first visitor number.
+
+// VisitorRefPrefix is deliberately a letter and a dash rather than bare digits.
+// It is what makes "V-42" recognisable as a customer rather than an order, a
+// till or a visit, and it is why a reference pasted into the wrong route fails
+// to parse instead of quietly matching a different record with that number.
+const VisitorRefPrefix = "V-"
+
+// VisitorRef renders a customer number for display and for URLs.
+func VisitorRef(number int64) string {
+	if number <= 0 {
+		return ""
+	}
+	return VisitorRefPrefix + strconv.FormatInt(number, 10)
+}
+
+// ParseVisitorRef accepts "V-42", "v-42" and bare "42".
+//
+// Bare digits are accepted because a shop assistant reading a number off a
+// screen will type the number, and refusing it teaches them to distrust the
+// field. There is nothing for it to collide with: a uuid is checked first and
+// is never all digits.
+func ParseVisitorRef(s string) (int64, bool) {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return 0, false
+	}
+	if len(s) > 2 && (s[0] == 'V' || s[0] == 'v') && s[1] == '-' {
+		s = s[2:]
+	}
+	n, err := strconv.ParseInt(s, 10, 64)
+	if err != nil || n <= 0 {
+		return 0, false
+	}
+	return n, true
+}
+
+// looksLikeName bounds a slug or camera id before it reaches SQL. Not a
+// validity check - the lookup decides that - only a guard so a path segment
+// full of junk is answered as "no such thing" without a round trip.
+func looksLikeName(s string) bool {
+	if s == "" || len(s) > 64 {
+		return false
+	}
+	for _, c := range s {
+		ok := (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') ||
+			(c >= '0' && c <= '9') || c == '-' || c == '_' || c == '.'
+		if !ok {
+			return false
+		}
+	}
+	return true
+}
+
+// Each reference has two resolvers: an inner one that answers ("", nil) for
+// "no such thing", and an outer one that writes the response itself so a call
+// site stays the same three lines the uuid check was. Both exist because a
+// query parameter is validated where a 400 is the right answer and a path
+// segment where a 404 is - splitting them lets one implementation serve both.
+//
+// A reference that does not resolve is 404 on a path, never 400, for the reason
+// the old shape check gave: to the caller, a malformed reference and one that
+// names nothing are the same thing - it is not there.
+
+func (s *Server) visitorIDFor(ctx context.Context, clientID, raw string) (string, error) {
+	if looksLikeUUID(raw) {
+		return raw, nil
+	}
+	number, ok := ParseVisitorRef(raw)
+	if !ok {
+		return "", nil
+	}
+	return s.Store.VisitorIDByNumber(ctx, clientID, number)
+}
+
+func (s *Server) siteIDFor(ctx context.Context, clientID, raw string) (string, error) {
+	if looksLikeUUID(raw) {
+		return raw, nil
+	}
+	if !looksLikeName(raw) {
+		return "", nil
+	}
+	return s.Store.SiteIDBySlug(ctx, clientID, strings.ToLower(raw))
+}
+
+func (s *Server) cameraIDFor(ctx context.Context, clientID, raw string) (string, error) {
+	if looksLikeUUID(raw) {
+		return raw, nil
+	}
+	if !looksLikeName(raw) {
+		return "", nil
+	}
+	return s.Store.CameraIDByRef(ctx, clientID, raw)
+}
+
+func (s *Server) resolveVisitor(w http.ResponseWriter, r *http.Request, raw string) (string, bool) {
+	return s.resolve(w, r, raw, s.visitorIDFor, "customer",
+		"That customer no longer exists.")
+}
+
+func (s *Server) resolveSite(w http.ResponseWriter, r *http.Request, raw string) (string, bool) {
+	return s.resolve(w, r, raw, s.siteIDFor, "site",
+		"That shop no longer exists.")
+}
+
+func (s *Server) resolveCamera(w http.ResponseWriter, r *http.Request, raw string) (string, bool) {
+	return s.resolve(w, r, raw, s.cameraIDFor, "camera",
+		"That camera no longer exists.")
+}
+
+// resolveSiteFilter is the query-string form: 400, not 404.
+//
+// The distinction is not pedantry. `/api/visits` exists and answered - what was
+// wrong was the filter the caller attached to it, and a 404 there reads as "the
+// arrivals feed is gone", which is a very different thing to go and investigate.
+// A path segment names the resource itself, so an unknown one IS a 404.
+func (s *Server) resolveSiteFilter(w http.ResponseWriter, r *http.Request, raw string) (string, bool) {
+	p := PrincipalFrom(r.Context())
+	id, err := s.siteIDFor(r.Context(), p.ClientID, raw)
+	if err != nil {
+		s.serverError(w, "resolve site", err)
+		return "", false
+	}
+	if id == "" {
+		badRequest(w, "no shop called "+strconv.Quote(raw))
+		return "", false
+	}
+	return id, true
+}
+
+func (s *Server) resolve(w http.ResponseWriter, r *http.Request, raw string,
+	lookup func(context.Context, string, string) (string, error),
+	what, gone string) (string, bool) {
+
+	p := PrincipalFrom(r.Context())
+	id, err := lookup(r.Context(), p.ClientID, raw)
+	if err != nil {
+		s.serverError(w, "resolve "+what, err)
+		return "", false
+	}
+	if id == "" {
+		writeErr(w, http.StatusNotFound, "not_found", gone)
+		return "", false
+	}
+	return id, true
+}
+
+// siteParam reads "which shop" off a query string.
+//
+// Reports have always taken `site` and the arrivals feed `site_id`, which is a
+// wart rather than a rule - and an unknown query parameter is silently ignored,
+// so getting it the wrong way round returns the whole estate instead of an
+// error. Both names are accepted everywhere now; `site` is the documented one.
+func siteParam(r *http.Request) string {
+	if v := trim(r.URL.Query().Get("site")); v != "" {
+		return v
+	}
+	return trim(r.URL.Query().Get("site_id"))
+}

server/internal/api/refs_test.go

@@ -0,0 +1,110 @@
+package api
+
+import (
+	"net/http"
+	"testing"
+)
+
+func TestVisitorRefRoundTrips(t *testing.T) {
+	for _, n := range []int64{1, 42, 999999} {
+		ref := VisitorRef(n)
+		got, ok := ParseVisitorRef(ref)
+		if !ok || got != n {
+			t.Fatalf("VisitorRef(%d) = %q, parsed back as (%d, %v)", n, ref, got, ok)
+		}
+	}
+	if got := VisitorRef(0); got != "" {
+		t.Fatalf("an unnumbered visitor must render as no reference, got %q", got)
+	}
+}
+
+// A shop assistant reading "Visitor 42" off a screen types 42. Refusing that
+// teaches them the field is unreliable, so bare digits are accepted - and there
+// is nothing for them to collide with, because a uuid is checked first and is
+// never all digits.
+func TestVisitorRefAcceptsWhatSomebodyWouldActuallyType(t *testing.T) {
+	for _, in := range []string{"V-42", "v-42", "42", " V-42 "} {
+		n, ok := ParseVisitorRef(in)
+		if !ok || n != 42 {
+			t.Fatalf("ParseVisitorRef(%q) = (%d, %v), want 42", in, n, ok)
+		}
+	}
+	for _, in := range []string{"", "V-", "V-0", "-1", "V-x", "abc", "4 2",
+		"3446ec35-2c1f-4c8e-9a77-0d1e2f3a4b5c"} {
+		if _, ok := ParseVisitorRef(in); ok {
+			t.Fatalf("ParseVisitorRef(%q) accepted a reference it should not", in)
+		}
+	}
+}
+
+func TestLooksLikeNameRejectsJunkBeforeItReachesSQL(t *testing.T) {
+	for _, ok := range []string{"chennai", "Office1", "cam_2", "a.b-c"} {
+		if !looksLikeName(ok) {
+			t.Fatalf("%q should be a usable name", ok)
+		}
+	}
+	for _, bad := range []string{"", "a b", "a/b", "a'b", "../etc", "%", string(make([]byte, 65))} {
+		if looksLikeName(bad) {
+			t.Fatalf("%q should not reach a query", bad)
+		}
+	}
+}
+
+// The point of the whole scheme: a customer is addressable by the number staff
+// read on screen, and the uuid that clients already stored keeps working.
+func TestACustomerIsReachableByNumberAndByUUID(t *testing.T) {
+	const id = "3446ec35-2c1f-4c8e-9a77-0d1e2f3a4b5c"
+	srv, fs := newServer(t)
+	seedUser(fs)
+	fs.visitors = []Customer{{ID: id, Ref: "V-42", Label: "Visitor 42"}}
+	fs.history = []VisitRow{{Site: "Chennai"}}
+	tok := login(t, srv, "manager@acme.com", "correct horse battery").Token
+
+	for _, path := range []string{"/api/visitors/" + id + "/history",
+		"/api/visitors/V-42/history", "/api/visitors/42/history"} {
+		rec := do(t, srv, http.MethodGet, path, tok, nil)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("GET %s = %d, want 200", path, rec.Code)
+		}
+	}
+}
+
+// A reference that names nobody is 404 on a path, and a filter that names no
+// shop is 400 on a query string. The difference matters: `/api/visits` answered
+// fine and what was wrong was the filter, so a 404 there would send somebody
+// looking for a missing arrivals feed.
+func TestAnUnknownReferenceIs404OnAPathAnd400OnAFilter(t *testing.T) {
+	srv, fs := newServer(t)
+	seedUser(fs)
+	tok := login(t, srv, "manager@acme.com", "correct horse battery").Token
+
+	rec := do(t, srv, http.MethodGet, "/api/visitors/V-999/history", tok, nil)
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("unknown customer = %d, want 404", rec.Code)
+	}
+	rec = do(t, srv, http.MethodGet, "/api/visits?site=nowhere", tok, nil)
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("unknown shop filter = %d, want 400", rec.Code)
+	}
+}
+
+// Reports have always taken `site` and the arrivals feed `site_id`. Both work
+// everywhere now, because an unknown query parameter is silently ignored - so
+// getting it the wrong way round returned the whole estate rather than an
+// error, which is a wrong number nobody would question.
+func TestBothSiteParameterNamesAreAccepted(t *testing.T) {
+	srv, fs := newServer(t)
+	seedUser(fs)
+	fs.sites = []SiteHealth{{SiteID: "11111111-1111-4111-8111-111111111111", Slug: "chennai"}}
+	tok := login(t, srv, "manager@acme.com", "correct horse battery").Token
+
+	for _, q := range []string{"site=chennai", "site_id=chennai"} {
+		fs.arrivalQ = ArrivalQuery{}
+		if rec := do(t, srv, http.MethodGet, "/api/visits?"+q, tok, nil); rec.Code != http.StatusOK {
+			t.Fatalf("GET /api/visits?%s = %d", q, rec.Code)
+		}
+		if got := fs.arrivalQ.SiteID; got != "11111111-1111-4111-8111-111111111111" {
+			t.Fatalf("%s resolved to %q", q, got)
+		}
+	}
+}

server/internal/api/types.go

@@ -109,7 +109,11 @@ type SalesReport struct {
 }
 
 type Customer struct {
-	ID          string `json:"id"`
+	ID string `json:"id"`
+	// Ref is the customer number - "V-42" - and is accepted anywhere this
+	// customer's id is. It ships alongside the uuid rather than replacing it
+	// because a client that stored a uuid must keep working; see refs.go.
+	Ref         string `json:"ref,omitempty"`
 	Label       string `json:"label"`
 	FullName    string `json:"full_name"`
 	Phone       string `json:"phone"`
@@ -252,6 +256,9 @@ type Arrival struct {
 	// appear in the feed - a shop watching arrivals would otherwise see fewer
 	// people than walked in.
 	VisitorID string `json:"visitor_id,omitempty"`
+	// VisitorRef is the same person as "V-42": what staff read on screen and
+	// type into a search box. Empty exactly when VisitorID is.
+	VisitorRef string `json:"visitor_ref,omitempty"`
 	// Label is the system's own name ("Visitor 12"); Name is what a human
 	// typed. Both are sent so the client does not have to guess which is
 	// present, and so a screen can show the real name and still let staff