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
-arrivals feed takes `site_id`. That is a wart, not a rule — but an unknown query
-parameter is silently ignored, so getting it wrong returns the whole estate
-rather than an error.
+**`site` and `site_id` are both accepted everywhere**, and either may be a slug
+or a uuid. They used to differ per endpoint, which mattered because an unknown
+query parameter is silently ignored — so getting it the wrong way round returned
+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.