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

API.md

@@ -9,6 +9,42 @@ repository uses exactly these calls; anything it can do, an app can do.
 
 ---
 
+## 0. Identifiers — you do not have to use uuids
+
+Every id in the database is a uuid and every one of them still works. But a uuid
+is not something a person can say, type or recognise, so **anywhere a path or a
+`site` parameter takes an id, it also takes the name people actually use**:
+
+| thing | reference | example |
+|---|---|---|
+| customer | `V-<number>` | `V-42` — also accepts bare `42` |
+| shop | its slug | `chennai` |
+| camera | the id the engine knows it by | `Office1` |
+| person | their email address | `priya@tenext.in` |
+
+```
+GET /api/visitors/3446ec35-2c1f-4c8e-9a77-0d1e2f3a4b5c/history
+GET /api/visitors/V-42/history      ← the same customer
+GET /api/visits?site=chennai
+PATCH /api/cameras/Office1
+```
+
+The customer number is **per company**, so `V-42` at one tenant and `V-42` at
+another are different people, and a reference never resolves outside the tenant
+the session belongs to. It is also what the label says: a customer nobody has
+named is called `Visitor 42`, and `ref` on every customer object carries `V-42`
+for display.
+
+Two shops in one company may each have a camera called `Office1`. That is
+ambiguous, so it resolves to **nothing** rather than to a guess — use the uuid,
+or scope by site.
+
+An unknown reference in a **path** is `404`; an unknown one in a **query filter**
+is `400`, because the collection itself was fine and it was the filter that was
+wrong.
+
+---
+
 ## 1. Signing in
 
 ### `POST /api/auth/login`
@@ -179,7 +215,7 @@ in. Reactivating restores the account but not their old sessions.
 
 ### `GET /api/visits`
 
-`?limit=50&cursor=…&site_id=…`
+`?limit=50&cursor=…&site=…` (`site_id` also accepted; a slug or a uuid)
 
 ```json
 {
@@ -187,7 +223,7 @@ in. Reactivating restores the account but not their old sessions.
     "visit_id": "…", "seq": 412,
     "occurred_at": "2026-09-05T06:01:45Z",
     "site_id": "…", "site": "TeNext Chennai", "camera_id": "Office1",
-    "visitor_id": "…", "label": "Priya",
+    "visitor_id": "…", "visitor_ref": "V-42", "label": "Priya",
     "is_new_visitor": false, "similarity": 0.71, "quality": 0.66,
     "attributes": { "gender": "Male", "age": 32, "emotion": "neutral" },
     "image": { "available": true,
@@ -261,12 +297,15 @@ two rows in *"who looked at my customers"* for one glance at one person.
 
 | | |
 |---|---|
-| `GET /api/visitors?q=…` | search by name or phone |
+| `GET /api/visitors?q=…` | search by name, phone, or customer number (`42`, `V-42`) |
 | `GET /api/visitors/{id}/history` | their past visits |
 | `PUT /api/visitors/{id}/profile` | name, phone, notes — staff and above |
 | `DELETE /api/visitors/{id}` | **erasure** — manager and above |
 | `POST /api/purchases` | link a sale to a visit |
 
+`{id}` is a uuid **or** `V-42` **or** `42`. Every customer object carries `ref`
+("V-42") beside `id`, and `label` reads "Visitor 42" until somebody names them.
+
 Erasure destroys the face template and the photo outright and keeps the visit
 rows, unlinked. It is irreversible. If the photo cannot be deleted the whole
 request fails with **502** and *nothing* is erased — so an error there means the
@@ -285,10 +324,10 @@ data is still there, and must be reported as a failure, never swallowed.
 | `GET /api/reports/footfall` | `?from=&to=&site=&tz=&bucket=` |
 | `GET /api/reports/conversion` | same parameters; revenue and basket size |
 
-**The site parameter is spelled differently here.** Reports take `site`; the
+**`site` and `site_id` are both accepted everywhere**, and either may be a slug
-arrivals feed takes `site_id`. That is a wart, not a rule — but an unknown query
+or a uuid. They used to differ per endpoint, which mattered because an unknown
-parameter is silently ignored, so getting it wrong returns the whole estate
+query parameter is silently ignored — so getting it the wrong way round returned
-rather than an error.
+the whole estate instead of an error. `site` is the documented spelling.
 
 Dates are `YYYY-MM-DD`. `to` is **inclusive**: "1st to the 7th" includes the
 7th.

CLAUDE.md

@@ -1954,6 +1954,105 @@ Verified live 2026-08-31, whole chain: enrol → upload-url → PUT → anonymou
 JPEG downloaded → erase → presigned GET **404**, 0 templates, 0 profiles, label
 `Erased`, visit row kept.
 
+## Identifiers: a customer number people can say (migration 012)
+
+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 from theirs:
+
+```sql
+UPDATE visitors SET label = 'Visitor ' || left(id::text, 8)
+```
+
+So the name on the arrivals feed, on the shop PC, and in the mobile app was
+**"Visitor 3446ec35"** — the string a shop assistant reads out to a colleague,
+writes on a card, and types into a search box. Not a display problem to paper
+over in a front end either: `label` is a stored column staff can overwrite and
+`SearchVisitors` matches on, so it had to be fixed where it is written.
+
+`visitors.number` is a **per-client** sequence and the label is now
+`Visitor 42`, referenced as **`V-42`**. Three properties, each ruling out an
+alternative:
+
+- **Speakable.** The whole point.
+- **Per client, not global.** A global sequence tells any customer who signs up
+  how many people the entire platform has ever seen, from their own first
+  visitor number. Per tenant it reveals a tenant's own count to that tenant's
+  own staff, who know it already.
+- **Not the primary key.** Ids are minted where nothing can ask a database for
+  the next value, and eleven tables reference `visitors.id`. This is a public
+  *reference* beside the key, which is the part humans needed.
+
+The counter is `clients.visitor_seq`, taken with `UPDATE ... RETURNING` inside
+the visit transaction. That returns the value **after** the update — the same
+semantics that silently broke the face prune in 011 by handing back what it had
+just written, and here exactly what is wanted. It row-locks the client for the
+length of the insert, which serialises new-visitor creation per tenant and costs
+nothing: it runs only for a face nobody in the estate has ever seen.
+
+The backfill numbers existing rows by `first_seen_at` and relabels **only** the
+eight-lowercase-hex pattern the old statement produced, so a name a human typed
+is never overwritten. Verified on the live database: 13 hex labels became
+Visitor 1-13 in first-seen order, two "Walk-in test" names were left alone, and
+`visitor_seq` landed on 15.
+
+### Three of the four things already had a human name; the API refused it
+
+That is the part worth keeping. Only visitors genuinely lacked a reference:
+
+| thing | reference | since |
+|---|---|---|
+| shop | `slug` — "chennai" | 001 |
+| camera | `camera_id` — "Office1", and what `visits.camera_id` holds | 005 |
+| customer | `V-<number>` | 012 |
+| person | email | 002 |
+
+`refs.go` accepts either form anywhere an id is taken. A uuid resolves with no
+lookup at all, so nothing that worked yesterday changes — including every URL a
+client has already stored. Only a non-uuid costs a query.
+
+- **A camera id is unique per SITE, not per tenant.** Two shops may each have an
+  `Office1`, so an ambiguous name resolves to **nothing** rather than to
+  whichever row sorted first — acting on a guess would edit the wrong shop's
+  camera.
+- **404 on a path, 400 on a query filter.** `/api/visits` exists and answered;
+  what was wrong was the filter, and a 404 there reads as "the arrivals feed is
+  gone". A path segment names the resource itself, so an unknown one *is* a 404.
+- **`site` and `site_id` are both accepted everywhere now.** Reports took one and
+  the arrivals feed the other, and an unknown query parameter is silently
+  ignored — so getting it the wrong way round returned the whole estate instead
+  of an error, which is a wrong number nobody would question.
+- **The search matches the reference.** `V-13` is what the product now shows, so
+  it is what gets pasted into the search box, and `label ILIKE '%V-13%'` finds
+  nothing because the label says "Visitor 13". A search that comes back empty
+  for the identifier you were just shown is worse than no search.
+
+The **edge** engine has always numbered its identities from a SQLite rowid, so
+"Visitor 3" there and "Visitor 47" here are the same person under two numbers.
+Left alone deliberately: making them agree means the shop PC asking the server
+for a number, which cannot work offline — and the edge number appears only on
+the engine's own diagnostic dashboard.
+
+### Two bugs, one from a real database and one from a real browser
+
+- **`'Visitor ' || $2::text` next to `number = $2`.** Postgres deduces two types
+  for one parameter and refuses the whole insert: *"inconsistent types deduced
+  for parameter $2"*. It compiled, it passed every in-memory test, and it failed
+  on the first real database — along with the existing face tests, which go
+  through the same path. The label is formatted in Go now.
+- **The avatar said `V1` for three different people.** With no photograph the
+  arrivals feed draws initials, and `initials("Visitor 13")` takes the first
+  letter of each word — `V1`, which is also what "Visitor 10" and "Visitor 15"
+  produce, and which reads as the `V-1` reference for a fourth person. It shows
+  the number itself now. Found by opening the page: every test here passes a
+  human name. The prop carrying it is `customerRef`, not `ref` — React reserves
+  that name, so it would never have reached the component.
+
+Fixture note: `embedding(seed)` fills every dimension with one value, so after
+L2 normalisation 0.31 and 0.62 are the **same direction** and the matcher
+correctly calls them one person. Tests that need several different people use
+`distinctFace(i)`, which is orthogonal per index.
+
+
 ## Setting up on a new machine
 
 1. Copy the `Behavision` folder **including `.env`** (gitignored, holds

desktop/frontend/dist/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Behavision</title>
-    <script type="module" crossorigin src="./assets/index-whFsTNQf.js"></script>
+    <script type="module" crossorigin src="./assets/index-B3nvDQ-a.js"></script>
     <link rel="stylesheet" crossorigin href="./assets/index-XjqO50wd.css">
   </head>
   <body>

desktop/frontend/src/views/Customers.jsx

@@ -56,7 +56,14 @@ export default function Customers({ session }) {
                 <tbody>
                   {rows.map(c => (
                     <tr key={c.id} className="click" onClick={() => setSelected(c)}>
-                      <td>{c.full_name || <span className="note">{c.label}</span>}</td>
+                      <td>
+                        {c.full_name || <span className="note">{c.label}</span>}
+                        {/* Only beside a name a human typed: the auto label
+                            already IS the number ("Visitor 13"), so showing
+                            both reads as two identifiers for one person. */}
+                        {c.full_name && c.ref &&
+                          <span className="note"> · {c.ref}</span>}
+                      </td>
                       <td className="mono">{c.phone || '—'}</td>
                       <td className="num">{c.visit_count}</td>
                       <td>{fmtDate(c.first_seen_at)}</td>

desktop/internal/cloud/client.go

@@ -545,7 +545,10 @@ func (c *Client) Sales(ctx context.Context, from, to string) (SalesReport, error
 }
 
 type Customer struct {
-	ID          string `json:"id"`
+	ID string `json:"id"`
+	// Ref is the customer number - "V-42" - and is what staff say to each
+	// other. It is accepted anywhere this customer's id is.
+	Ref         string `json:"ref"`
 	Label       string `json:"label"`
 	FullName    string `json:"full_name"`
 	Phone       string `json:"phone"`

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) {
+	if q.SiteID != "" {
-		badRequest(w, "site_id must be a site identifier")
+		var ok bool
-		return
+		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) {
+	if q.SiteID != "" {
-		badRequest(w, "site_id must be a site identifier")
+		var ok bool
-		return
+		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) {
+	if siteID != "" {
-		badRequest(w, "site_id must be a site identifier")
+		var ok bool
-		return
+		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")
+	siteID, ok := s.resolveSite(w, r, r.PathValue("site"))
-	if !looksLikeUUID(siteID) {
+	if !ok {
-		writeErr(w, http.StatusNotFound, "not_found", "That shop no longer exists.")
 		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")
+	id, ok := s.resolveCamera(w, r, r.PathValue("id"))
-	if !looksLikeUUID(id) {
+	if !ok {
-		writeErr(w, http.StatusNotFound, "not_found", "That camera no longer exists.")
 		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")
+	id, ok := s.resolveCamera(w, r, r.PathValue("id"))
-	if !looksLikeUUID(id) {
+	if !ok {
-		writeErr(w, http.StatusNotFound, "not_found", "That camera no longer exists.")
 		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")
+	id, ok := s.resolveCamera(w, r, r.PathValue("id"))
-	if !looksLikeUUID(id) {
+	if !ok {
-		writeErr(w, http.StatusNotFound, "not_found", "That camera no longer exists.")
 		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")
+	siteID, ok := s.resolveSite(w, r, r.PathValue("site"))
-	if !looksLikeUUID(siteID) {
+	if !ok {
-		writeErr(w, http.StatusNotFound, "not_found", "That shop no longer exists.")
 		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")
+	site, ok := s.resolveSite(w, r, r.PathValue("site"))
-	if !looksLikeUUID(site) {
+	if !ok {
-		writeErr(w, http.StatusNotFound, "not_found", "No such shop.")
 		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")
+	id, ok := s.resolveVisitor(w, r, r.PathValue("id"))
-	if !looksLikeUUID(id) {
+	if !ok {
-		writeErr(w, http.StatusNotFound, "not_found", "That customer no longer exists.")
 		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")
+	id, ok := s.resolveVisitor(w, r, r.PathValue("id"))
-	if !looksLikeUUID(id) {
+	if !ok {
-		writeErr(w, http.StatusNotFound, "not_found", "That customer no longer exists.")
 		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")
+	id, ok := s.resolveCamera(w, r, r.PathValue("id"))
-	if !looksLikeUUID(id) {
+	if !ok {
-		writeErr(w, http.StatusNotFound, "not_found", "No such camera.")
 		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")
+	// 404, not 400: to the caller a reference that is malformed and one that
-	if !looksLikeUUID(id) {
+	// names nobody are the same thing - the customer is not there.
-		// 404, not 400: to the caller a malformed id and an id that does not
+	id, ok := s.resolveVisitor(w, r, r.PathValue("id"))
-		// exist are the same thing - the customer is not there.
+	if !ok {
-		writeErr(w, http.StatusNotFound, "not_found", "That customer no longer exists.")
 		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")
+	visitorID, ok := s.resolveVisitor(w, r, r.PathValue("id"))
-	if !looksLikeUUID(body.VisitorID) {
+	if !ok {
-		writeErr(w, http.StatusNotFound, "not_found", "That customer no longer exists.")
 		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) {
+	visitorID, ok := s.resolveVisitor(w, r, body.VisitorID)
-		writeErr(w, http.StatusNotFound, "not_found", "That customer no longer exists.")
+	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

server/internal/store/api_arrivals.go

@@ -15,6 +15,7 @@ const arrivalColumns = `
 	vi.id::text, vi.seq, vi.occurred_at, vi.site_id::text, si.name, vi.camera_id,
 	vi.is_new_visitor, vi.similarity, vi.quality, vi.attributes, vi.image_key,
 	COALESCE(vi.visitor_id::text, ''),
+	COALESCE(vs.number, 0),
 	COALESCE(vs.label, ''),
 	COALESCE(p.full_name, '')`
 
@@ -111,11 +112,13 @@ func (s *Store) Arrivals(ctx context.Context, q api.ArrivalQuery) ([]api.Arrival
 		var at time.Time
 		var sim, qual *float64
 		var imageKey string
+		var number int64
 		if err := rows.Scan(&a.VisitID, &a.Seq, &at, &a.SiteID, &a.Site, &a.CameraID,
 			&a.IsNew, &sim, &qual, &a.Attributes, &imageKey,
-			&a.VisitorID, &a.Label, &a.Name); err != nil {
+			&a.VisitorID, &number, &a.Label, &a.Name); err != nil {
 			return nil, err
 		}
+		a.VisitorRef = api.VisitorRef(number)
 		a.OccurredAt = at.UTC().Format(time.RFC3339Nano)
 		if sim != nil {
 			a.Similarity = *sim

server/internal/store/api_arrivals_live_test.go

@@ -63,9 +63,9 @@ func seedTenant(t *testing.T, st *Store, name string, n int, withImages bool) (c
 	for i := 0; i < n; i++ {
 		var visitorID string
 		if err := st.pool.QueryRow(ctx, `
-			INSERT INTO visitors (client_id, label, first_seen_at)
+			INSERT INTO visitors (client_id, number, label, first_seen_at)
-			VALUES ($1::uuid, $2, $3) RETURNING id::text`,
+			VALUES ($1::uuid, $2, $3, $4) RETURNING id::text`,
-			clientID, fmt.Sprintf("Visitor %d", i), start).Scan(&visitorID); err != nil {
+			clientID, i+1, fmt.Sprintf("Visitor %d", i+1), start).Scan(&visitorID); err != nil {
 			t.Fatalf("seed visitor: %v", err)
 		}
 		key := ""

server/internal/store/api_people.go

@@ -25,11 +25,27 @@ func likePattern(q string) string {
 	return "%" + r.Replace(q) + "%"
 }
 
+// searchNumber is the customer number behind a query, or 0 for a query that is
+// not one.
+//
+// The reference is what staff now READ on screen - "V-13" - so it is what they
+// paste into the search box, and matching only `label ILIKE '%V-13%'` finds
+// nothing at all, because the stored label says "Visitor 13". A search that
+// comes back empty for the identifier the product just showed you is worse
+// than no search at all.
+func searchNumber(query string) int64 {
+	n, ok := api.ParseVisitorRef(query)
+	if !ok {
+		return 0
+	}
+	return n
+}
+
 func (s *Store) SearchVisitors(ctx context.Context, clientID, query string, limit int) (
 	[]api.Customer, error) {
 
 	rows, err := s.pool.Query(ctx, `
-		SELECT v.id::text, v.label,
+		SELECT v.id::text, v.number, v.label,
 		       COALESCE(p.full_name, ''), COALESCE(p.phone, ''), COALESCE(p.email, ''),
 		       v.visit_count, v.first_seen_at, v.last_seen_at,
 		       (p.id IS NOT NULL),
@@ -39,13 +55,15 @@ func (s *Store) SearchVisitors(ctx context.Context, clientID, query string, limi
 		LEFT JOIN visitor_profiles p
 		       ON p.visitor_id = v.id AND p.client_id = v.client_id
 		WHERE v.client_id = $1 AND v.deleted_at IS NULL
-		  AND ($2 = '' OR v.label ILIKE $3 ESCAPE '\'
+		  AND ($2 = '' OR v.number = $5
+		               OR v.label ILIKE $3 ESCAPE '\'
 		               OR p.full_name ILIKE $3 ESCAPE '\'
 		               OR p.phone     ILIKE $3 ESCAPE '\'
 		               OR p.email     ILIKE $3 ESCAPE '\')
 		ORDER BY v.last_seen_at DESC NULLS LAST, v.first_seen_at DESC
 		LIMIT $4`,
-		clientID, strings.TrimSpace(query), likePattern(strings.TrimSpace(query)), limit)
+		clientID, strings.TrimSpace(query), likePattern(strings.TrimSpace(query)),
+		limit, searchNumber(query))
 	if err != nil {
 		return nil, err
 	}
@@ -56,10 +74,12 @@ func (s *Store) SearchVisitors(ctx context.Context, clientID, query string, limi
 		var c api.Customer
 		var first time.Time
 		var last *time.Time
-		if err := rows.Scan(&c.ID, &c.Label, &c.FullName, &c.Phone, &c.Email,
+		var number int64
+		if err := rows.Scan(&c.ID, &number, &c.Label, &c.FullName, &c.Phone, &c.Email,
 			&c.VisitCount, &first, &last, &c.HasProfile, &c.HasConsent); err != nil {
 			return nil, err
 		}
+		c.Ref = api.VisitorRef(number)
 		c.FirstSeenAt = first.UTC().Format(time.RFC3339)
 		if last != nil {
 			c.LastSeenAt = last.UTC().Format(time.RFC3339)

server/internal/store/api_refs.go

@@ -0,0 +1,81 @@
+package store
+
+import (
+	"context"
+	"errors"
+
+	"github.com/jackc/pgx/v5"
+)
+
+// Resolving a public reference to the uuid it names.
+//
+// Every id in this schema is a uuid and stays one. These three exist because a
+// uuid is not something a person can say, type or recognise, and three of the
+// four things anyone addresses by URL already HAD a human name that the API
+// simply refused to accept: a site has a slug, a camera has the id the engine
+// knows it by (and the one that lands in `visits.camera_id`), and a visitor now
+// has a per-tenant number. See api/refs.go for the formats.
+//
+// All three answer "" with a nil error when nothing matches. A found id is
+// never empty, so the two cases cannot be confused, and a mistyped reference is
+// a 404 rather than an error the handler has to classify.
+
+// SiteIDBySlug resolves a site slug within one tenant.
+func (s *Store) SiteIDBySlug(ctx context.Context, clientID, slug string) (string, error) {
+	var id string
+	err := s.pool.QueryRow(ctx, `
+		SELECT id::text FROM sites
+		 WHERE client_id = $1::uuid AND slug = $2`,
+		clientID, slug).Scan(&id)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return "", nil
+	}
+	return id, err
+}
+
+// CameraIDByRef resolves the engine's own camera id - "Office1" - to the row
+// uuid, within one tenant.
+//
+// A camera id is unique per SITE, not per tenant, so two shops may each have an
+// "Office1". Ambiguity is resolved as no match rather than by picking one:
+// silently acting on whichever row sorted first would edit or delete the wrong
+// shop's camera. A caller in that position has the uuid, or can scope by site.
+func (s *Store) CameraIDByRef(ctx context.Context, clientID, ref string) (string, error) {
+	rows, err := s.pool.Query(ctx, `
+		SELECT id::text FROM site_cameras
+		 WHERE client_id = $1::uuid AND camera_id = $2 AND deleted_at IS NULL
+		 LIMIT 2`, clientID, ref)
+	if err != nil {
+		return "", err
+	}
+	defer rows.Close()
+
+	var found []string
+	for rows.Next() {
+		var id string
+		if err := rows.Scan(&id); err != nil {
+			return "", err
+		}
+		found = append(found, id)
+	}
+	if err := rows.Err(); err != nil {
+		return "", err
+	}
+	if len(found) != 1 {
+		return "", nil
+	}
+	return found[0], nil
+}
+
+// VisitorIDByNumber resolves the number behind "V-42" within one tenant.
+func (s *Store) VisitorIDByNumber(ctx context.Context, clientID string, number int64) (string, error) {
+	var id string
+	err := s.pool.QueryRow(ctx, `
+		SELECT id::text FROM visitors
+		 WHERE client_id = $1::uuid AND number = $2`,
+		clientID, number).Scan(&id)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return "", nil
+	}
+	return id, err
+}

server/internal/store/api_refs_live_test.go

@@ -0,0 +1,182 @@
+package store
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/loyaly/behavision-server/internal/contract"
+	"github.com/loyaly/behavision-server/internal/ingest"
+)
+
+// The name a shop assistant actually reads.
+//
+// Before 012 this was `'Visitor ' || left(id::text, 8)`, so the arrivals feed
+// said "Visitor 3446ec35" - a string nobody can say out loud, write on a card
+// or type into a search box. The number is what fixes that, and it has to be
+// right at the point it is WRITTEN: `label` is a stored column that staff can
+// overwrite and that SearchVisitors matches on, so formatting around it in the
+// front end would have left the stored data wrong on three surfaces.
+//
+// Only a real database proves this. The counter lives on `clients` and is taken
+// with UPDATE ... RETURNING inside the visit transaction - the same semantics
+// that silently broke the face prune in 011 by returning the value it had just
+// written. Here that is exactly what is wanted, and an in-memory fake would
+// agree with any implementation.
+// distinctFace returns a vector pointing along its own axis, so any two of them
+// are orthogonal - cosine 0, far below any match threshold.
+//
+// `embedding(seed)` fills every dimension with one value, so after L2
+// normalisation 0.31 and 0.62 are the SAME direction and the matcher correctly
+// calls them one person. That is right for the face tests it was written for
+// and useless here, where the whole point is several different people.
+func distinctFace(i int) []float32 {
+	v := make([]float32, contract.EmbeddingDim)
+	v[i%contract.EmbeddingDim] = 1
+	return v
+}
+
+func TestLiveVisitorNumbersStartAtOneForEveryTenant(t *testing.T) {
+	st := liveStore(t)
+	ctx := context.Background()
+
+	// Two tenants, so a number that leaked across them would show up as a gap.
+	for _, tenant := range []string{"num-a-" + stamp(), "num-b-" + stamp()} {
+		site := seedAgentSite(t, st, tenant)
+
+		for i := 0; i < 3; i++ {
+			// A different face each time, so each becomes its own visitor.
+			ok, err := st.RecordVisit(ctx, site, &contract.Visit{
+				EventID:    fmt.Sprintf("%s-%d", tenant, i),
+				OccurredAt: time.Now().UTC().Add(time.Duration(i) * time.Second),
+				CameraID:   "door",
+				IsNew:      true,
+				Quality:    0.8,
+				Embedding:  distinctFace(i),
+			})
+			if err != nil || !ok {
+				t.Fatalf("%s visit %d: ok=%v err=%v", tenant, i, ok, err)
+			}
+		}
+
+		rows, err := st.pool.Query(ctx, `
+			SELECT number, label FROM visitors
+			 WHERE client_id = $1::uuid ORDER BY number`, site.ClientID)
+		if err != nil {
+			t.Fatal(err)
+		}
+		var got []string
+		for rows.Next() {
+			var n int64
+			var label string
+			if err := rows.Scan(&n, &label); err != nil {
+				t.Fatal(err)
+			}
+			got = append(got, fmt.Sprintf("%d=%s", n, label))
+		}
+		rows.Close()
+
+		want := []string{"1=Visitor 1", "2=Visitor 2", "3=Visitor 3"}
+		if len(got) != len(want) {
+			t.Fatalf("%s: got %v, want %v", tenant, got, want)
+		}
+		for i := range want {
+			if got[i] != want[i] {
+				t.Fatalf("%s: got %v, want %v", tenant, got, want)
+			}
+		}
+	}
+}
+
+// A number is a public reference, so it must resolve only within the tenant it
+// belongs to. Both tenants have a V-1; asking as one must never return the
+// other's customer.
+func TestLiveAVisitorNumberResolvesOnlyWithinItsOwnTenant(t *testing.T) {
+	st := liveStore(t)
+	ctx := context.Background()
+
+	mine := seedAgentSite(t, st, "ref-mine-"+stamp())
+	theirs := seedAgentSite(t, st, "ref-theirs-"+stamp())
+
+	for i, s := range []ingest.Site{mine, theirs} {
+		if ok, err := st.RecordVisit(ctx, s, &contract.Visit{
+			EventID:    s.Slug + "-1",
+			OccurredAt: time.Now().UTC(),
+			CameraID:   "door",
+			IsNew:      true,
+			Quality:    0.8,
+			Embedding:  distinctFace(i),
+		}); err != nil || !ok {
+			t.Fatalf("seed visit: ok=%v err=%v", ok, err)
+		}
+	}
+
+	mineID, err := st.VisitorIDByNumber(ctx, mine.ClientID, 1)
+	if err != nil || mineID == "" {
+		t.Fatalf("V-1 in my own tenant: %q %v", mineID, err)
+	}
+	theirsID, err := st.VisitorIDByNumber(ctx, theirs.ClientID, 1)
+	if err != nil || theirsID == "" {
+		t.Fatalf("V-1 in the other tenant: %q %v", theirsID, err)
+	}
+	if mineID == theirsID {
+		t.Fatal("V-1 resolved to the same customer for two different tenants")
+	}
+
+	// And a number nobody has is a miss, not an error - which is what lets the
+	// handler answer 404 without classifying an error first.
+	got, err := st.VisitorIDByNumber(ctx, mine.ClientID, 999999)
+	if err != nil || got != "" {
+		t.Fatalf("unknown number: got %q, err %v - want an empty miss", got, err)
+	}
+}
+
+// A site slug and a camera id are the other two references, and both already
+// existed in the schema; only the API refused to accept them.
+func TestLiveSiteAndCameraResolveByTheirOwnNames(t *testing.T) {
+	st := liveStore(t)
+	ctx := context.Background()
+	site := seedAgentSite(t, st, "names-"+stamp())
+
+	id, err := st.SiteIDBySlug(ctx, site.ClientID, site.Slug)
+	if err != nil || id != site.SiteID {
+		t.Fatalf("slug %q resolved to %q (want %q), err %v",
+			site.Slug, id, site.SiteID, err)
+	}
+	if got, err := st.SiteIDBySlug(ctx, site.ClientID, "no-such-shop"); err != nil || got != "" {
+		t.Fatalf("unknown slug: got %q, err %v", got, err)
+	}
+
+	var camUUID string
+	if err := st.pool.QueryRow(ctx, `
+		INSERT INTO site_cameras (client_id, site_id, camera_id, label, host)
+		VALUES ($1::uuid, $2::uuid, 'Office1', 'Front door', '10.0.0.5')
+		RETURNING id::text`, site.ClientID, site.SiteID).Scan(&camUUID); err != nil {
+		t.Fatal(err)
+	}
+	got, err := st.CameraIDByRef(ctx, site.ClientID, "Office1")
+	if err != nil || got != camUUID {
+		t.Fatalf("camera by name: got %q (want %q), err %v", got, camUUID, err)
+	}
+
+	// Two shops in one tenant may each have an "Office1". Acting on whichever
+	// row sorted first would edit the wrong shop's camera, so ambiguity must
+	// resolve to nothing rather than to a guess.
+	var secondSite string
+	if err := st.pool.QueryRow(ctx, `
+		INSERT INTO sites (client_id, name, slug) VALUES ($1::uuid, 'Second', $2)
+		RETURNING id::text`, site.ClientID, site.Slug+"-2").Scan(&secondSite); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := st.pool.Exec(ctx, `
+		INSERT INTO site_cameras (client_id, site_id, camera_id, label, host)
+		VALUES ($1::uuid, $2::uuid, 'Office1', 'Other door', '10.0.0.6')`,
+		site.ClientID, secondSite); err != nil {
+		t.Fatal(err)
+	}
+	if got, err := st.CameraIDByRef(ctx, site.ClientID, "Office1"); err != nil || got != "" {
+		t.Fatalf("an ambiguous camera name resolved to %q - it must resolve to "+
+			"nothing rather than pick one", got)
+	}
+}

server/internal/store/store.go

@@ -222,18 +222,34 @@ func (s *Store) matchOrCreateVisitor(ctx context.Context, tx pgx.Tx,
 	}
 
 	// New person for this client.
+	//
+	// The number comes off the tenant's own counter rather than being derived
+	// from the uuid, because it is what a human will read, say and search for:
+	// "Visitor 42", not "Visitor 3446ec35". UPDATE ... RETURNING yields the
+	// value AFTER the update, which is what is wanted here, and it row-locks
+	// the client for the length of the insert so two shops cannot take the
+	// same number. That lock is free - this runs only for a face nobody in the
+	// estate has ever seen, not once per visit.
+	var number int64
+	if err := tx.QueryRow(ctx, `
+		UPDATE clients SET visitor_seq = visitor_seq + 1
+		WHERE id = $1 RETURNING visitor_seq`,
+		site.ClientID).Scan(&number); err != nil {
+		return "", fmt.Errorf("next visitor number: %w", err)
+	}
+	// The label is formatted here rather than as `'Visitor ' || $2::text` in
+	// the statement: reusing one parameter as a bigint and as a string operand
+	// makes Postgres deduce two types for it and refuse the whole insert
+	// ("inconsistent types deduced for parameter $2"). It compiled, it passed
+	// every in-memory test, and it failed on the first real database.
 	var newID string
 	if err := tx.QueryRow(ctx, `
-		INSERT INTO visitors (client_id, label, first_seen_at)
+		INSERT INTO visitors (client_id, number, label, first_seen_at)
-		VALUES ($1, '', $2) RETURNING id::text`,
+		VALUES ($1, $2, $3, $4) RETURNING id::text`,
-		site.ClientID, v.OccurredAt).Scan(&newID); err != nil {
+		site.ClientID, number, fmt.Sprintf("Visitor %d", number),
+		v.OccurredAt).Scan(&newID); err != nil {
 		return "", fmt.Errorf("create visitor: %w", err)
 	}
-	if _, err := tx.Exec(ctx, `
-		UPDATE visitors SET label = 'Visitor ' || left(id::text, 8)
-		WHERE id = $1 AND label = ''`, newID); err != nil {
-		return "", err
-	}
 	if _, err := tx.Exec(ctx, `
 		INSERT INTO visitor_embeddings
 		  (visitor_id, client_id, model, embedding, quality, source_site_id)

server/internal/web/dist/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="color-scheme" content="dark" />
     <title>Behavision</title>
-    <script type="module" crossorigin src="/assets/index-Dv7hKDIX.js"></script>
+    <script type="module" crossorigin src="/assets/index-BI5JLIeo.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-Bgt5SnW3.css">
   </head>
   <body>

server/migrations/012_visitor_numbers.sql

@@ -0,0 +1,81 @@
+-- A customer number a person can say out loud.
+--
+-- Until now `RecordVisit` named every new customer with eight hex characters
+-- off their uuid:
+--
+--     UPDATE visitors SET label = 'Visitor ' || left(id::text, 8)
+--
+-- So the name a shop assistant reads on the arrivals feed, and reads back to a
+-- colleague, and types into a search box, was "Visitor 3446ec35". That is not
+-- a display problem to paper over in the front end - `label` is a stored
+-- column that staff can overwrite, it is what `SearchVisitors` matches on, and
+-- it is what the desktop app, the web console and the mobile feed all show.
+-- It had to be fixed where it is written.
+--
+-- The replacement is a per-CLIENT sequential number: "Visitor 42", referenced
+-- as `V-42`. Three properties, each of which rules out an alternative:
+--
+--   * Speakable and typeable. This is the whole point. A number is read down a
+--     phone, written on a card and searched for; a uuid is copy-pasted or got
+--     wrong.
+--   * Per client, not global. A global sequence tells any customer who signs
+--     up how many people the entire platform has ever seen, from their own
+--     first visitor number - the German-tank estimate, and a number no
+--     customer should be able to compute. Per tenant it only reveals a
+--     tenant's own count to that tenant's own staff, who know it already.
+--   * Not the primary key. `visitors.id` stays a uuid. The ids in this schema
+--     are generated in places that cannot ask a database for the next value,
+--     and swapping a PK that eleven tables reference for a sequence buys
+--     nothing internal while risking everything. This is a public REFERENCE
+--     sitting beside the key, which is the part humans needed all along.
+--
+-- The counter lives on `clients`, and `UPDATE ... RETURNING` returns the value
+-- AFTER the update - which is exactly what is wanted here, and is the same
+-- semantics that silently broke the face prune in 011 by returning the value
+-- it had just written. Taking the number this way row-locks the client for the
+-- length of the insert, serialising new-visitor creation per tenant. That is
+-- free: a new visitor row is written only for a face nobody in the estate has
+-- ever seen, not once per visit. Computing MAX(number)+1 instead would race
+-- two shops onto one number.
+
+BEGIN;
+
+ALTER TABLE clients  ADD COLUMN IF NOT EXISTS visitor_seq bigint NOT NULL DEFAULT 0;
+ALTER TABLE visitors ADD COLUMN IF NOT EXISTS number      bigint;
+
+-- Existing rows are numbered in the order they were first seen, so a customer
+-- who has been coming for a year has a lower number than one who arrived
+-- yesterday. Ties break on id only so the result is deterministic.
+WITH numbered AS (
+    SELECT id,
+           row_number() OVER (PARTITION BY client_id
+                              ORDER BY first_seen_at, id) AS n
+      FROM visitors
+)
+UPDATE visitors v
+   SET number = numbered.n
+  FROM numbered
+ WHERE v.id = numbered.id
+   AND v.number IS NULL;
+
+UPDATE clients c
+   SET visitor_seq = COALESCE((SELECT max(number) FROM visitors
+                                WHERE client_id = c.id), 0);
+
+-- Rename ONLY the labels this system generated. The pattern is exactly the
+-- eight lowercase hex characters the old statement produced, so a name a human
+-- typed - including one that legitimately starts with the word Visitor - is
+-- left alone. Overwriting a staff-assigned name would be silent data loss of
+-- the kind nobody would notice until a customer was greeted wrongly.
+UPDATE visitors
+   SET label = 'Visitor ' || number
+ WHERE number IS NOT NULL
+   AND label ~ '^Visitor [0-9a-f]{8}$';
+
+ALTER TABLE visitors ALTER COLUMN number SET NOT NULL;
+
+-- Unique per tenant, and the index `V-42` is resolved through.
+CREATE UNIQUE INDEX IF NOT EXISTS visitors_number_idx
+    ON visitors (client_id, number);
+
+COMMIT;

web/src/views/Customers.jsx

@@ -55,6 +55,11 @@ export default function Customers({ user }) {
                       onKeyDown={e => e.key === 'Enter' && setOpen(c)}>
                     <td>
                       <strong>{c.full_name || c.label}</strong>
+                      {/* The number is shown next to a name a human typed, and
+                          not next to the auto label, which already IS the
+                          number ("Visitor 13"). Printing "Visitor 13 · V-13"
+                          would read as two identifiers for one person. */}
+                      {c.full_name && c.ref && <span className="sub"> · {c.ref}</span>}
                       {c.phone && <span className="sub"> · {c.phone}</span>}
                     </td>
                     <td className="num">{c.visit_count}</td>
@@ -118,6 +123,8 @@ function Drawer({ customer, user, onClose, onSaved }) {
         <header className="drawer-head">
           <div>
             <h2>{customer.full_name || customer.label}</h2>
+            {customer.full_name && customer.ref &&
+              <p className="sub">{customer.ref}</p>}
             <p className="sub">{customer.visit_count} visits · last seen {ago(customer.last_seen_at)}</p>
           </div>
           <button className="ghost" onClick={onClose}>Close</button>

web/src/views/Live.jsx

@@ -86,10 +86,14 @@ function Arrival({ a }) {
   const name = a.name || a.label || 'Unidentified'
   return (
     <li className="card arrival">
-      <Face image={a.image} name={name} />
+      <Face image={a.image} name={name} customerRef={a.visitor_ref} />
       <div className="who-col">
         <strong>{name}</strong>
         <span className="sub">
+          {/* Only beside a name somebody typed. The auto label already IS the
+              number, so "Visitor 13 · V-13" would read as two identifiers for
+              one person. */}
+          {a.name && a.visitor_ref ? `${a.visitor_ref} · ` : ''}
           {a.site}{a.camera_id ? ` · ${a.camera_id}` : ''} · {ago(a.occurred_at)}
         </span>
         {a.attributes && <Attributes attrs={a.attributes} />}
@@ -111,17 +115,37 @@ function Arrival({ a }) {
 // be loaded by an <img> at all — it needs the session — so a plain src here
 // showed a broken image on exactly the deployments that had just started
 // storing photos.
-function Face({ image, name }) {
+// customerRef, not `ref`: React reserves that prop name, so it would never
+// reach this component's props.
+function Face({ image, name, customerRef }) {
   if (image?.available) {
     return <span className="face"><Shot image={image} alt="" /></span>
   }
   return (
     <span className="face initials" title={image?.reason || ''} aria-hidden="true">
-      {initials(name)}
+      {avatarText(name, customerRef)}
     </span>
   )
 }
 
+// What goes in the circle when there is no photograph.
+//
+// Initials of a name a human typed; the NUMBER for a customer the system named
+// itself. Running initials() over "Visitor 13" takes the first letter of each
+// word and produces "V1" - which is also what "Visitor 10" and "Visitor 15"
+// produce, so three different people wore the same badge, and it read as the
+// V-1 reference for a fourth. Found by opening the page: every unit test here
+// passes a human name.
+function avatarText(name, customerRef) {
+  const auto = /^Visitor (\d+)$/.exec(String(name).trim())
+  if (auto) return auto[1]
+  if (customerRef) {
+    const n = /^V-(\d+)$/.exec(customerRef)
+    if (n) return n[1]
+  }
+  return initials(name)
+}
+
 function initials(name) {
   const parts = String(name).trim().split(/\s+/).filter(Boolean)
   if (!parts.length) return '?'