image search

docs/SCAN_TO_ORDER.md

@@ -100,6 +100,10 @@ How to read it:
   cart/order calls exactly as you would from the catalogue screen.
 - `distance_km: -1` means the distance is unknown (no fix from the phone and
   no saved address, or the store has no coordinates). Do not render it as 0.
+  Send `latitude`/`longitude` on `/confirm` too if you display distance from
+  its reply: the saved address is only consulted there when the shelf is
+  empty and alternatives have to be ranked, so without a fix the store you
+  tapped comes back `-1`.
 
 ## `POST /confirm`
 
@@ -115,7 +119,7 @@ nothing is cached on this path.
 {
   "ok": false,
   "reason": "out_of_stock",           // in_stock | insufficient_stock | out_of_stock | not_sold_here | store_not_registered
-  "store":  { "…the store they tapped…" },
+  "store":  { "…the store they tapped…" },   // distance_km filled from the fix you send
   "option": { "productid": 100, "stock": 0, "…": "…" },
   "requested": 2,
   "alternative": {                     // absent when nobody has enough
@@ -167,10 +171,12 @@ Same `ScanStore` shape as inside `stores[]` above, without options.
   EMBEDDING_DIMENSIONS=384
   ```
   A bare label ("Milk Bikis") scores ~0.92 against its product's stored
-  vector and ~0.23 against an unrelated one, which is what the 0.30 floor in
-  `scanService.go` is set against. If the catalogue team ever re-embeds
-  with another model, change `EMBEDDING_MODEL`/`DIMENSIONS` here and
-  nothing else.
+  vector and ~0.23 against an unrelated one, which is what the 0.50 floor in
+  `scanService.go` is set against — the middle of that split, not the edge of
+  the noise. It was 0.30 until a near-miss got through in production
+  ("Paracetamol" → "Paneer Makhni 500ml", 0.304). If the catalogue team ever
+  re-embeds with another model, change `EMBEDDING_MODEL`/`DIMENSIONS` here
+  and nothing else.
 - **Speed**: the label's vector (7 days) and the ranked catalogue hits
   (30 min) are cached in Redis and in-process, so a popular product costs
   one model call platform-wide. Customer, stores and catalogue are read
@@ -232,7 +238,7 @@ you change ranking — it is the spec.
 |---|---|---|
 | `scanLookupTimeout` | 5 s | whole lookup, including the model call |
 | `scanCatalogueTopK` | 15 | rows taken from each brand table and from the merge |
-| `scanMinScore` | 0.30 | below this the best hit is not shown as a match |
+| `scanMinScore` | 0.50 | below this the best hit is not shown as a match |
 | `embedTimeout` (`utils/embedding.go`) | 4 s | one model call |
 | `scanVectorTTL` / `scanHitsTTL` (`scanRepository.go`) | 7 d / 30 min | cache lifetimes |