feat(vision): configurability — SetupWizard ANPR toggle, footer health chip, env docs

Make the vision service genuinely configurable (was env-only). - SetupWizard: an "ANPR" checkbox on the camera form (writes config.anpr; persisted only when on; sq+en) — opt-in is no longer raw JSON. - DeviceMonitor optionally takes the VisionClient and probes /health each tick, emitting a "vision" pseudo-device → a Vision chip (ready/degraded/offline + recognizer) in the booth footer when VISION_ENABLED, no chip when off. Widened the DeviceStatus category union (server + web) + footer maps + devices.catVision. Verified: ready/fast_alpr when up, 0 chips when disabled. - apps/vision/.env.example (Python service) + a VISION_* block in apps/server/.env.example (Node side) + a Configuration section in opencv-anpr-service.md covering all four layers and the caveats: the two processes share the VISION_ prefix but need SEPARATE .env files; bind /analyze to 127.0.0.1; cache model weights at deploy; an unbound anpr camera recognizes but every read is refused. Build + lint green. Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
2026-06-19 16:41:29 +02:00
parent 540b333b06
commit 4af8b56dda
13 changed files with 168 additions and 23 deletions
@@ -29,3 +29,15 @@ EVENT_SIGNING_KEY=
 # Comma-separated extra origins allowed to open the booth WebSocket (/api/ws).
 # In dev, set the Vite SPA origin. Same-origin is always allowed without this.
 WS_ALLOWED_ORIGINS=http://localhost:5173
+
+# Vision / ANPR (optional) -------------------------------------------------
+# OFF by default. The Node SERVER's view of the vision microservice (apps/vision),
+# which runs as a separate process with its OWN apps/vision/.env. Both sides share the
+# VISION_ prefix but are different processes — keep the two .env files separate.
+# See wiki/entities/opencv-anpr-service.md "Configuration".
+# VISION_ENABLED=1                       # master switch — nothing runs without it
+# VISION_URL=http://127.0.0.1:8089       # must match apps/vision VISION_HOST:VISION_PORT
+# VISION_TIMEOUT_MS=1500                 # per-request cap so a slow call can't hang the lane
+# VISION_POLL_MS=2000                    # how often each anpr camera is polled
+# VISION_DEDUPE_MS=15000                 # suppress re-firing the same plate while a car sits in frame
+# VISION_MIN_CONFIDENCE=0.5              # confidence floor; keep in sync with the service
@@ -60,7 +60,7 @@ export interface PrinterStatusEvent {
 export interface DeviceStatusEvent {
  readonly deviceId: string; // devices id
  readonly driverId: string;
-  readonly category: "access" | "reader" | "camera" | "printer";
+  readonly category: "access" | "reader" | "camera" | "printer" | "vision";
  /**
   * The device's ROLE descriptor for the footer label — NOT the vendor. A
   * direction-style token the client localises and pairs with the category, so the
@@ -3,6 +3,11 @@ import { devices, type Db, type DeviceRow } from "@parking/db";
 import { isMonitorable, registry } from "@parking/devices";
 import { deviceEvents, type DeviceStatusEvent } from "./device-events.js";
 import { directionOf, relaysOf } from "./device-resolve.js";
+import type { VisionClient } from "./vision-client.js";
+
+/** Synthetic device id for the vision service in the status footer (it's a service,
+ *  not a device row, but shares the footer's traffic-light + WS plumbing). */
+const VISION_STATUS_ID = "vision-service";

 // Unified live DEVICE monitor — the source for the booth's device-status footer.
 // Every enabled, configured device is probed on an interval, regardless of
@@ -60,10 +65,15 @@ export class DeviceMonitor {
  #timer: ReturnType<typeof setInterval> | null = null;
  #ticking = false;

-  constructor(db: Db, log: FastifyBaseLogger, pollMs = POLL_MS) {
+  /** Optional: the vision service client. When present + enabled, the monitor probes
+   *  its /health each tick and shows it as a "vision" chip in the footer. */
+  readonly #vision: VisionClient | null;
+
+  constructor(db: Db, log: FastifyBaseLogger, pollMs = POLL_MS, vision: VisionClient | null = null) {
    this.#db = db;
    this.#log = log;
    this.#pollMs = pollMs;
+    this.#vision = vision;
  }

  /** Begin polling. Idempotent. */
@@ -97,12 +107,16 @@ export class DeviceMonitor {
      const enabled = rows.filter((r) => r.enabled);
      const present = new Set(enabled.map((r) => r.id));

+      // The vision service is a pseudo-device — keep it in the present set when enabled
+      // so the cleanup below doesn't evict it.
+      if (this.#vision?.enabled) present.add(VISION_STATUS_ID);
+
      // Drop devices that are gone/disabled (so the footer doesn't show stale ones).
      for (const id of [...this.#latest.keys()]) {
        if (!present.has(id)) this.#latest.delete(id);
      }

-      await Promise.all(enabled.map((r) => this.#poll(r)));
+      await Promise.all([...enabled.map((r) => this.#poll(r)), this.#pollVision()]);
    } catch (err) {
      this.#log.warn(`device-monitor tick failed: ${(err as Error).message}`);
    } finally {
@@ -144,11 +158,33 @@ export class DeviceMonitor {
      }
    }

-    const prev = this.#latest.get(row.id);
-    this.#latest.set(row.id, next);
+    this.#publish(row.id, next);
+  }
+
+  /** Probe the vision service /health and publish it as a "vision" footer chip. Skipped
+   *  entirely when no client is wired or it's disabled (no chip then). */
+  async #pollVision(): Promise<void> {
+    if (!this.#vision?.enabled) return;
+    const h = await this.#vision.health();
+    const state: DeviceStatusEvent["state"] = h.ok && h.ready ? "ready" : h.ready ? "degraded" : "offline";
+    this.#publish(VISION_STATUS_ID, {
+      deviceId: VISION_STATUS_ID,
+      driverId: "vision",
+      category: "vision",
+      roleKind: null,
+      state,
+      detail: h.ready ? h.recognizer : (h.detail ?? "not ready"),
+      checkedAt: new Date().toISOString(),
+    });
+  }
+
+  /** Cache + emit a status, but only when it CHANGED (state or detail). */
+  #publish(id: string, next: DeviceStatusEvent): void {
+    const prev = this.#latest.get(id);
+    this.#latest.set(id, next);
    if (!prev || prev.state !== next.state || prev.detail !== next.detail) {
      this.#log.info(
-        `device-monitor: ${next.category}/${next.roleKind ?? "—"} ${row.id} -> ${next.state}${next.detail ? ` (${next.detail})` : ""}`,
+        `device-monitor: ${next.category}/${next.roleKind ?? "—"} ${id} -> ${next.state}${next.detail ? ` (${next.detail})` : ""}`,
      );
      deviceEvents.emitDeviceStatus(next);
    }
@@ -112,11 +112,17 @@ export async function buildServer(opts: BuildOptions = {}): Promise<FastifyInsta
  app.addHook("onReady", async () => printerMonitor.start());
  app.addHook("onClose", async () => printerMonitor.stop());

+  // Vision (ANPR) client — built early so the device monitor can include the vision
+  // service's health in the footer. Opt-in (VISION_ENABLED) + fail-soft; advisory only.
+  // See wiki/entities/opencv-anpr-service.md.
+  const visionClient = new VisionClient(app.log);
+  if (visionClient.enabled) app.log.info("vision client enabled");
+
  // Unified device-status monitor: polls EVERY configured device (relays/readers/
-  // cameras via healthCheck, printers via rich readStatus) and feeds the booth's
-  // device-status footer over the WS. Read-only — never drives a relay.
+  // cameras via healthCheck, printers via rich readStatus) PLUS the vision service's
+  // /health, and feeds the booth's device-status footer over the WS. Read-only.
  // See wiki/concepts/device-status-monitoring.md.
-  const deviceMonitor = new DeviceMonitor(db, app.log);
+  const deviceMonitor = new DeviceMonitor(db, app.log, undefined, visionClient);
  await deviceStatusRoutes(app, deviceMonitor);
  app.addHook("onReady", async () => deviceMonitor.start());
  app.addHook("onClose", async () => deviceMonitor.stop());
@@ -163,15 +169,6 @@ export async function buildServer(opts: BuildOptions = {}): Promise<FastifyInsta
  });
  app.addHook("onClose", async () => unsubscribeRead());

-  // Vision (ANPR) client: the adapter to the host vision microservice (apps/vision),
-  // talking localhost HTTP. ADVISORY ONLY + opt-in (VISION_ENABLED) + fail-soft — a
-  // plate read is an identity hint/evidence, never the sole authority to open a paid
-  // barrier. Constructed here and available for the (separate, not-yet-wired) read
-  // trigger that snapshots an opt-in camera and emits a plate read. See
-  // wiki/entities/opencv-anpr-service.md "Fitness for the entry/exit flows".
-  const visionClient = new VisionClient(app.log);
-  if (visionClient.enabled) app.log.info("vision client enabled");
-
  // Vision READER: polls opt-in (config.anpr) cameras, recognizes a plate via the
  // vision client, and emits a kind:"plate" read onto the SAME read bus a physical
  // reader uses → the dispatcher routes it to the subscription/exit flow unchanged. A
@@ -0,0 +1,22 @@
+# apps/vision — the ANPR microservice's own env (copy to apps/vision/.env).
+# This is the PYTHON SERVICE's config only. The Node server has its OWN VISION_* vars
+# (in apps/server/.env) — keep the two .env files SEPARATE (they share the VISION_
+# prefix but are different processes). See wiki/entities/opencv-anpr-service.md "Configuration".
+
+# Recognizer: "stub" (no models, recognizes nothing — boots anywhere, for dev/CI) or
+# "fast_alpr" (the real MIT YOLOv9+CCT/ONNX stack — needs `uv sync --extra alpr`).
+VISION_RECOGNIZER=fast_alpr
+
+# Bind. On the appliance prefer 127.0.0.1 — the Node backend is the only caller, so the
+# /analyze endpoint should NOT be reachable off-host. (0.0.0.0 only if you must.)
+VISION_HOST=127.0.0.1
+VISION_PORT=8089
+
+# fast-alpr models (only used when recognizer=fast_alpr). The defaults won the Albanian
+# benchmark; change the OCR to european-plates-mobile-vit-v2-model only to re-test.
+VISION_DETECTOR_MODEL=yolo-v9-t-384-license-plate-end2end
+VISION_OCR_MODEL=cct-xs-v2-global-model
+
+# Confidence floor — a best plate below this is flagged low_confidence so the Node side
+# treats it as advisory and falls back to the ticket path. Keep in sync with the server.
+VISION_MIN_CONFIDENCE=0.5
@@ -57,12 +57,21 @@ country European model to benchmark Albanian plates. For GPU/NPU, install `onnxr
 The Node side POSTs `Snapshot.bytes` directly (no multipart). `vehicle` is scaffolded but not yet
 populated — fast-alpr is plate-only; the vehicle stage (Job 2) is built later on the same runtime.

-## Config (env, prefix `VISION_`)
+## Config (env, prefix `VISION_`) — see `.env.example`
+
+This service's env only. The **Node server has its own `VISION_*`** (`apps/server/.env`:
+`VISION_ENABLED`, `VISION_URL`, `VISION_POLL_MS`, …) — same prefix, **separate process, separate
+`.env`**. Don't merge them.

 | Var | Default | Meaning |
 | --- | --- | --- |
 | `VISION_RECOGNIZER` | `stub` | `stub` (no models) or `fast_alpr` (real) |
-| `VISION_PORT` | `8089` | listen port |
+| `VISION_HOST` | `0.0.0.0` | bind address — prefer `127.0.0.1` on the appliance (Node is the only caller) |
+| `VISION_PORT` | `8089` | listen port (must match the server's `VISION_URL`) |
 | `VISION_DETECTOR_MODEL` | `yolo-v9-t-384-license-plate-end2end` | fast-alpr detector |
-| `VISION_OCR_MODEL` | `cct-xs-v2-global-model` | fast-alpr OCR |
+| `VISION_OCR_MODEL` | `cct-xs-v2-global-model` | fast-alpr OCR (won the AL benchmark) |
 | `VISION_MIN_CONFIDENCE` | `0.5` | below this → `low_confidence=true` |
+
+To use it from the booth: set `VISION_ENABLED=1` on the **server**, run this service, then tick
+**ANPR** on a camera in the SetupWizard (the camera must also be bound to a barrier). The booth footer
+shows a **Vision** chip when enabled. Full config guide: `wiki/entities/opencv-anpr-service.md`.
@@ -322,6 +322,10 @@ function DeviceForm({
  const canDiscover = !editing && selected != null && discoverableIds.includes(selected.id);
  const pushesToBackend = selected != null && pushCapableIds.includes(selected.id);
  const isController = category === "access";
+  const isCamera = category === "camera";
+  // ANPR opt-in for a camera: when true, the VisionReader polls this camera for plates
+  // (config.anpr). Off by default. See wiki/entities/opencv-anpr-service.md.
+  const [anpr, setAnpr] = useState<boolean>(editCfg?.anpr === true);

  // Pre-fill scalar config fields from the existing assignment when editing.
  // (relays/controllerId/relay are model fields handled by their own state below.)
@@ -429,6 +433,8 @@ function DeviceForm({
      out.controllerId = controllerId;
      out.relay = boundRelay;
    }
+    // Camera ANPR opt-in (only persisted when on, to keep configs minimal).
+    if (isCamera && anpr) out.anpr = true;
    return out;
  }

@@ -584,6 +590,22 @@ function DeviceForm({
            />
          )}

+          {/* CAMERA: opt this camera into ANPR (the VisionReader polls it for plates). */}
+          {isCamera && (
+            <label className="my-2 flex items-start gap-2 rounded-term border border-term-border bg-term-bg p-2 text-[12px]">
+              <input
+                type="checkbox"
+                className="mt-0.5"
+                checked={anpr}
+                onChange={(e) => setAnpr(e.target.checked)}
+              />
+              <span>
+                <span className="font-semibold text-term-text">{t("setup.anpr")}</span>
+                <span className="hint mt-0.5 block">{t("setup.anprHint")}</span>
+              </span>
+            </label>
+          )}
+
          {/* Test (no save/no device change) then Save (configures + persists). */}
          <div className="mt-3 flex items-center gap-2">
            <button type="button" className="btn btn-sm" onClick={test} disabled={testing}>
@@ -647,7 +647,7 @@ export function fetchOccupancy(): Promise<Occupancy> {
 export interface DeviceStatus {
  deviceId: string;
  driverId: string;
-  category: "access" | "reader" | "camera" | "printer";
+  category: "access" | "reader" | "camera" | "printer" | "vision";
  /** Role/direction token for the footer label (NOT the vendor) — the client
   *  localises it next to the category, e.g. "Lexuesi hyrje", "Printer kabina". */
  roleKind: "entry" | "exit" | "both" | "mixed" | "lane" | "booth" | null;
@@ -63,6 +63,7 @@ export const en: Catalog = {
    catReader: "Reader",
    catCamera: "Camera",
    catPrinter: "Printer",
+    catVision: "Vision",
    // Role/direction suffixes for the chip label (e.g. "Reader entry").
    role: {
      entry: "entry",
@@ -297,6 +298,9 @@ export const en: Catalog = {
    entryCooldownHint:
      "When there's no presence loop: repeat button presses are suppressed for this many seconds after a ticket. A fallback (not a guarantee) — a determined abuser can wait it out.",
    addRelay: "+ Add relay",
+    anpr: "Plate recognition (ANPR)",
+    anprHint:
+      "Enable to scan plates on this camera: the vision service reads the plate from a snapshot and feeds it as a read (advisory only — it never opens a barrier on its own). Requires the vision service running.",
    whichBarrier: "Which barrier does this device serve?",
    controller: "Controller",
    choose: "Choose…",
@@ -65,6 +65,7 @@ export const sq = {
    catReader: "Lexuesi",
    catCamera: "Kamera",
    catPrinter: "Printer",
+    catVision: "Vizioni",
    // Role/direction suffixes for the chip label (e.g. "Lexuesi hyrje").
    role: {
      entry: "hyrje",
@@ -306,6 +307,10 @@ export const sq = {
    entryCooldownHint:
      "Kur nuk ka sensor pranie: shtypjet e përsëritura të butonit shtypen për kaq sekonda pas një bilete. Zgjidhje rezervë (jo garanci) — një abuzues mund ta presë afatin.",
    addRelay: "+ Shto rele",
+    // Camera ANPR opt-in.
+    anpr: "Njohja e targave (ANPR)",
+    anprHint:
+      "Aktivizo që ky aparat të skanojë targat: shërbimi i vizionit lexon targën nga pamja dhe e dërgon si lexim (vetëm këshillues — nuk hap vetë barrierën). Kërkon shërbimin e vizionit aktiv.",
    // Binding picker.
    whichBarrier: "Cilën barrierë shërben kjo pajisje?",
    controller: "Kontrolluesi",
@@ -32,6 +32,7 @@ const CATEGORY_KEY: Record<DeviceStatus["category"], string> = {
  reader: "devices.catReader",
  camera: "devices.catCamera",
  printer: "devices.catPrinter",
+  vision: "devices.catVision",
 };

 /** i18n key for the role/direction token (null = no suffix). */
@@ -45,6 +46,7 @@ const ORDER: Record<DeviceStatus["category"], number> = {
  reader: 1,
  camera: 2,
  printer: 3,
+  vision: 4,
 };

 /** "Lexuesi hyrje" — category word + localised role/direction (when known). */
@@ -197,7 +197,39 @@ the threshold on real on-site captures (angle/night/dirt). (4) the **weight-prov
 **Bottom line: consume it as a gated advisory identity source feeding the existing `kind:"plate"` path
 — not as sole authority — and Job 2 is still required for the anti-spoofing value.** The
 adapter + the opt-in poll→read trigger are now **both built and verified end-to-end**; remaining is
-field tuning (3), the provenance check (4), the SetupWizard `anpr` toggle, and Job 2.
+field tuning (3), the provenance check (4), and Job 2.
+
+## Configuration (2026-06-19)
+
+Turning it on touches **four layers** — two env sets (one per process), per-camera data, and deploy.
+The Python service and the Node server **both** read the `VISION_` prefix but are **separate
+processes**, so give each its **own `.env`** (`apps/vision/.env` and `apps/server/.env`) — don't merge
+them. `.env.example` files document both.
+
+**1. The Python service (`apps/vision/.env`):** `VISION_RECOGNIZER=fast_alpr` (the default `stub`
+recognizes nothing), `VISION_HOST`/`VISION_PORT` (prefer **`127.0.0.1`** — only the Node backend calls
+`/analyze`, so don't expose it off-host), `VISION_OCR_MODEL`/`VISION_DETECTOR_MODEL` (leave defaults —
+the AL-benchmark winners), `VISION_MIN_CONFIDENCE`. Install the models with `uv sync --extra alpr`;
+weights download on first run, so **cache them at build/deploy** for the air-gapped appliance.
+
+**2. The Node server (`apps/server/.env`):** `VISION_ENABLED=1` is the **master switch** (off by
+default — nothing polls or shows without it); `VISION_URL` must match the service's host:port;
+`VISION_TIMEOUT_MS` (slow-call cap so a lane never hangs), `VISION_POLL_MS`, `VISION_DEDUPE_MS`,
+`VISION_MIN_CONFIDENCE` (re-applied client-side).
+
+**3. Per-camera opt-in (device config, not env):** a camera does ANPR only when its config has **both**
+`anpr: true` **and** a relay binding (`controllerId` + `relay`). The `anpr` flag is a **checkbox on the
+camera form in the [[first-run-setup|SetupWizard]]** (built 2026-06-19). Without the binding the
+[[entry-exit-points|dispatcher]] refuses every read ("reader not bound to a barrier") — so an
+unbound ANPR camera recognizes but every read is rejected (and logged with its snapshot).
+
+**4. Footer health:** when `VISION_ENABLED`, the [[device-status-monitoring|DeviceMonitor]] probes the
+service's `/health` each tick and shows a **"Vision" chip** in the booth footer (ready/degraded/offline
+ the recognizer name); no chip when disabled. So the operator sees at a glance whether vision is up.
+
+> **Network isolation** ([[network-isolation]]): cameras live on the isolated device VLAN, so the
+> vision service must reach that VLAN to pull snapshots — but its own `/analyze` should bind
+> **localhost** (Node is the only caller). Keep the AGPL/heavy stack contained to this process.

 ## Open

@@ -936,3 +936,7 @@ Wired the vision service into the entry/exit flows via the READ BUS. VisionReade
 ## [2026-06-19] feat | Persist every recognized plate + snapshot (ANPR audit trail, non-blocking)

 VisionReader now PERSISTS every confident plate read so a recognition is investigable — and switched from emitRead to calling ReadDispatcher.dispatch directly (like qr-reader) to capture the OUTCOME. On a confident plate it: (1) stores the SNAPSHOT bytes in `snapshots` keyed by identity=PLATE — the SAME identity the flow signs its anomaly/event with — so GET /api/snapshots/by-identity/:plate (the booth event-detail modal's SnapshotStrip, which already uses e.identity) shows the car's photo against that anomaly with ZERO UI changes; (2) records an unsigned device_events{kind:"read"} breadcrumb with plate/confidence/region/modelVersion/snapshotId + the dispatch outcome (accepted + reason) = a queryable ANPR log independent of the signed ledger; (3) dispatches the read — NON-BLOCKING: a refused read just returns rejected (no barrier hold), logged with its snapshot for investigation. Plate stays advisory (exit demands payment; subscription matches only a bound plate). VERIFIED e2e: a recognized AL plate (AA558EE) with no open session → signed exit.refused.noSession anomaly (identity=plate), stored a 555KB snapshot under that plate, read-breadcrumb accepted:false reason:"no open session", and by-identity returned the image (status 200, 1 snapshot) → the refused read is investigable with its picture. Build+lint green. VisionReader constructor now takes the ReadDispatcher (wired in server.ts). Answers "is a recognized plate saved?" — now YES for both transient + subscriber, as telemetry + evidence image, regardless of match. Updated [[opencv-anpr-service]].
+
+## [2026-06-19] feat | Vision service configuration — SetupWizard ANPR toggle, footer health chip, .env.example
+
+Made the vision service genuinely configurable (was env-only). THREE additions: (1) SetupWizard CAMERA form now has an "ANPR / Njohja e targave" checkbox (writes config.anpr; only persisted when on; sq+en) — opt-in is no longer raw JSON. (2) DeviceMonitor now optionally takes the VisionClient and probes its /health each tick, emitting a "vision" pseudo-device status (id vision-service, category "vision" — widened the DeviceStatusEvent + frontend DeviceStatus category unions + the footer CATEGORY_KEY/ORDER maps + devices.catVision sq/en) → a "Vision · ready/degraded/offline" chip in the booth footer; NO chip when VISION_ENABLED off. Verified: emits ready/fast_alpr when up, 0 chips when disabled. (3) apps/vision/.env.example (the Python service env) + VISION_* block appended to apps/server/.env.example (the Node side) + a "Configuration" section in [[opencv-anpr-service]] documenting all FOUR layers (python env / node env / per-camera anpr+binding / footer health) and the caveats: the two processes SHARE the VISION_ prefix but need SEPARATE .env files; bind /analyze to 127.0.0.1 (Node is the only caller); models download on first run so cache at deploy; an unbound anpr camera recognizes but every read is refused. Build+lint green. Updated [[opencv-anpr-service]] (Configuration section; SetupWizard-toggle gap closed), vision README.