Device-agnostic driver registry + first-run setup

Make the device-adapter pattern selectable so the admin chooses hardware at install — per lane, from a catalog of supported drivers. Adding a device = registering one more driver; no business-logic change. packages/devices: - interfaces.ts: AccessControlDevice / ReaderDevice / CameraDevice / PrinterDevice (adds CameraDevice for entry/exit snapshot-on-event; access relay stays intent-only per "a barrier is not a door"). - registry.ts: driver catalog with per-driver config fields + factory, config validation, and a catalog payload for the setup UI. - drivers/: stub adapters — access (zkteco, esp32-relay), reader (wiegand, tcp-ip), camera (hikvision, dahua). Real vendor protocols TBD. packages/db: - lane_devices + setup_state tables (migration 0001); re-export query helpers. apps/server: - routes/setup.ts: GET /api/setup/catalog (public schema), and admin-only /assign, /state, /complete with registry validation before persisting. - extract auth.ts (requireJwtSecret, requireRole, JWT type aug). apps/web: - SetupWizard scaffold + api client: pick a driver per category for a lane, render its config fields. wiki: device-registry + first-run-setup concept pages; cross-link from device-adapter-pattern; index + log updated. Verified: full turbo build (5/5); catalog lists all drivers; admin assign persists; missing-config and no-token requests are rejected.
2026-06-14 07:59:46 +02:00
parent 7de5c74500
commit 72ba4099ea
24 changed files with 1138 additions and 71 deletions
@@ -0,0 +1,82 @@
+import { randomUUID } from "node:crypto";
+import type { FastifyInstance } from "fastify";
+import { eq, laneDevices, setupState, type Db } from "@parking/db";
+import {
+  registerBuiltinDrivers,
+  registry,
+  setDeviceLogSink,
+  type DeviceCategory,
+} from "@parking/devices";
+import { requireRole } from "../auth.js";
+
+// First-run setup API. The admin reads the driver catalog and assigns devices
+// per lane. See wiki/concepts/first-run-setup.md.
+
+interface AssignBody {
+  lane: number;
+  category: DeviceCategory;
+  driverId: string;
+  config: Record<string, string | number | boolean>;
+}
+
+export async function setupRoutes(app: FastifyInstance, db: Db): Promise<void> {
+  registerBuiltinDrivers();
+  setDeviceLogSink((line) => app.log.info(line));
+
+  // Catalog of selectable drivers per category (no secrets — schema only).
+  app.get("/api/setup/catalog", async () => registry.catalog());
+
+  // Current setup status + assignments.
+  app.get(
+    "/api/setup/state",
+    { preHandler: requireRole("admin") },
+    async () => {
+      const state = await db.select().from(setupState).where(eq(setupState.id, 1)).get();
+      const assignments = await db.select().from(laneDevices).all();
+      return { completedAt: state?.completedAt ?? null, assignments };
+    },
+  );
+
+  // Assign a device to a lane. Validates the chosen driver + config against the
+  // registry before persisting; rejects unknown drivers / missing config.
+  app.post<{ Body: AssignBody }>(
+    "/api/setup/assign",
+    { preHandler: requireRole("admin") },
+    async (req, reply) => {
+      const { lane, category, driverId, config } = req.body;
+      const driver = registry.get(driverId);
+      if (!driver || driver.category !== category) {
+        return reply.code(400).send({ error: `invalid driver for ${category}: ${driverId}` });
+      }
+      try {
+        registry.create(driverId, config); // validates required fields
+      } catch (err) {
+        return reply.code(400).send({ error: (err as Error).message });
+      }
+      const row = {
+        id: randomUUID(),
+        lane,
+        category,
+        driverId,
+        config,
+        enabled: true,
+      };
+      await db.insert(laneDevices).values(row);
+      return reply.code(201).send(row);
+    },
+  );
+
+  // Mark first-run setup complete.
+  app.post(
+    "/api/setup/complete",
+    { preHandler: requireRole("admin") },
+    async () => {
+      const completedAt = new Date().toISOString();
+      await db
+        .insert(setupState)
+        .values({ id: 1, completedAt })
+        .onConflictDoUpdate({ target: setupState.id, set: { completedAt } });
+      return { completedAt };
+    },
+  );
+}