feat(modules): venue-module registry — entitled ∩ activated, requireModule, Setup panel

Groundwork for the Car Wash pilot (wiki/decisions/venue-modules.md, build-order steps 1 + 3). No Car Wash code yet; validation is the first module behind the seam, unchanged in behaviour. - @parking/shared: MODULE_IDS, ModuleManifest, MODULES (parking required; validation dependsOn parking), parseEntitledModules / resolveModuleActivation / effectiveModules as pure functions. - DB: site_config.modules_json (migration 0026, hand-written + journal; additive, nullable = everything entitled). - Server: modules.ts (entitledModules from MODULES_ENTITLED env, activated from site_config, effective set, requireModule preHandler → 403 module_disabled); modules/index.ts registers folder-based modules by iterating the registry (modules/validation); site-config GET exposes modules/modulesEntitled/modulesActivated, PUT takes the full desired set, enforces entitlement + dependency rules (400 with reason) and signs one config_change per module that actually flips; /api/auth/me carries the effective set; validation routes guarded requireModule → requirePermission. - Web: lib/modules.ts + modules/{index,validation}; router.tsx spreads WEB_MODULES into nav + route tree (validate route no longer named there); Setup → Site "Modules" panel (required shown disabled, dependencies as hints, server refusal shown verbatim); validation sections + programs fetch gated on the module; App invalidates the router whenever the session changes (route-context consumers only re-read on navigation — the nav was stale after a flip, and after every other setUser too). - Lavazh validation station retired (STATIONS = ["bar"]; rows untouched). - Deploy: MODULES_ENTITLED=parking,validation explicit in both booth stacks; documented in .env.example. - Tests: modules.test.ts (7); suite 329/329; web build clean; Playwright round-trip on /setup/site verified live. Claude-Session: https://claude.ai/code/session_01FWncR69HgGPuei1dLrW3cU
2026-09-05 11:04:39 +02:00
parent db9c3e0e31
commit 23d6379be8
27 changed files with 848 additions and 57 deletions
@@ -0,0 +1,6 @@
+-- Venue modules: which optional modules the site admin has ACTIVATED (JSON array of
+-- module ids, e.g. ["parking","validation"]). null = never set → everything the site is
+-- entitled to (MODULES_ENTITLED env). Effective set = entitled ∩ activated, computed server-
+-- side (apps/server/src/modules.ts); each change signs a config_change. Additive, nullable:
+-- existing deployments see no behaviour change. See wiki/decisions/venue-modules.md.
+ALTER TABLE `site_config` ADD `modules_json` text;
@@ -183,6 +183,13 @@
      "when": 1788078414270,
      "tag": "0025_backup_last_status",
      "breakpoints": true
+    },
+    {
+      "idx": 26,
+      "version": "6",
+      "when": 1788596918862,
+      "tag": "0026_site_modules",
+      "breakpoints": true
    }
  ]
-}
+}
@@ -233,6 +233,12 @@ export const siteConfig = sqliteTable("site_config", {
   *  own price and may differ. null = no site default set. See
   *  wiki/entities/subscription.md. */
  subscriptionMonthlyPriceMinor: integer("subscription_monthly_price_minor"),
+  /** Venue modules the site admin has ACTIVATED (JSON array of ModuleId, e.g.
+   *  ["parking","validation"]). null = never set → everything the site is entitled to.
+   *  The effective set is entitled (MODULES_ENTITLED env) ∩ this, computed server-side
+   *  (apps/server/src/modules.ts); each change signs a config_change. Disabling a module
+   *  never deletes anything. See wiki/decisions/venue-modules.md. */
+  modulesJson: text("modules_json"),
  /** When ON, the occupancy/full gate RESERVES a spot for each active subscriber's car
   *  (by quantity) even when they're not parked — so transients see "full" sooner and
   *  the subscriber's spot is held. When OFF (default), only cars physically inside
@@ -1705,3 +1705,136 @@ export interface Signer {
   *  verifies via its public key). */
  verify(payload: string, signature: string): boolean;
 }
+
+// --- Venue modules -------------------------------------------------------------
+// Optional per-site features (Car Wash, Bar, …) and — deliberately — the parking
+// product itself are MODULES on a shared venue core (identity/roles, the signed
+// ledger, devices, shift/cash, printing, reports, site config). One binary; a module
+// is enabled per site at RUNTIME as `entitled ∩ activated`:
+//   - entitled  = what the vendor deployed for this site (MODULES_ENTITLED env, set in
+//                 the Komodo stack; unset = every registered module — existing
+//                 deployments keep working unchanged);
+//   - activated = what the site admin has switched on in Setup → Site
+//                 (site_config.modules_json; null = everything entitled).
+// The server ENFORCES the effective set (requireModule guard, apps/server/src/
+// modules.ts); the web only HIDES nav/routes from it. Disabling never deletes:
+// tables stay migrated, history stays, role grants stay; routes reject and UI hides.
+// Design + rationale: wiki/decisions/venue-modules.md.
+
+export const MODULE_IDS = ["parking", "validation"] as const;
+export type ModuleId = (typeof MODULE_IDS)[number];
+
+export interface ModuleManifest {
+  readonly id: ModuleId;
+  /** Cannot be deactivated (and is always entitled). Parking is the product today. */
+  readonly required: boolean;
+  /** Modules that must be effective for this one to be activated. Enforced at the point
+   *  of change (activating with a dependency off is refused; deactivating a dependency of
+   *  an active module is refused) and again when computing the effective set. */
+  readonly dependsOn: readonly ModuleId[];
+  /** Permission resources this module contributes to the catalog (informational for the
+   *  role composer; the core resources belong to no module). */
+  readonly resources: readonly Resource[];
+  /** Ledger event types this module appends (informational; the union stays ONE
+   *  append-only type — see LedgerEventType). */
+  readonly ledgerEventTypes: readonly LedgerEventType[];
+}
+
+/** The registry. Adding a module = one entry here + its server/web folders
+ *  (apps/server/src/modules/<id>, apps/web/src/modules/<id>). Order = display order. */
+export const MODULES: readonly ModuleManifest[] = [
+  {
+    id: "parking",
+    required: true,
+    dependsOn: [],
+    resources: ["tariff", "subscription", "payment", "session"],
+    ledgerEventTypes: ["vehicle_entry", "vehicle_exit", "payment", "barrier_open_command", "barrier_open_observed"],
+  },
+  {
+    // Merchant-scan ticket validation, kept for the Bar until a Bar module absorbs it
+    // (wiki/decisions/venue-modules.md, decision 1).
+    id: "validation",
+    required: false,
+    dependsOn: ["parking"],
+    resources: ["validation"],
+    ledgerEventTypes: ["validation"],
+  },
+];
+
+export function isModuleId(v: unknown): v is ModuleId {
+  return typeof v === "string" && (MODULE_IDS as readonly string[]).includes(v);
+}
+
+export function moduleManifest(id: ModuleId): ModuleManifest {
+  const m = MODULES.find((x) => x.id === id);
+  if (!m) throw new Error(`unknown module: ${id}`);
+  return m;
+}
+
+/** Ids of the modules that can never be off. */
+export const REQUIRED_MODULE_IDS: readonly ModuleId[] = MODULES.filter((m) => m.required).map((m) => m.id);
+
+/** Parse a comma-separated entitlement list (the MODULES_ENTITLED env). Unknown ids
+ *  are dropped (returned in `unknown` so the caller can warn); required modules are
+ *  always included; unset/blank = everything registered. */
+export function parseEntitledModules(raw: string | undefined | null): { entitled: ModuleId[]; unknown: string[] } {
+  const trimmed = (raw ?? "").trim();
+  if (trimmed === "") return { entitled: [...MODULE_IDS], unknown: [] };
+  const entitled = new Set<ModuleId>(REQUIRED_MODULE_IDS);
+  const unknown: string[] = [];
+  for (const part of trimmed.split(",")) {
+    const id = part.trim();
+    if (id === "") continue;
+    if (isModuleId(id)) entitled.add(id);
+    else unknown.push(id);
+  }
+  return { entitled: MODULE_IDS.filter((id) => entitled.has(id)), unknown };
+}
+
+export type ModuleActivationResult =
+  | { ok: true; modules: ModuleId[] }
+  | { ok: false; error: string };
+
+/** Validate a requested activation set against the entitlement. Required modules are
+ *  always included; anything not entitled or with an inactive dependency is refused
+ *  with a human-readable reason (the UI shows it verbatim). Returns the normalized set
+ *  in registry order. */
+export function resolveModuleActivation(
+  entitled: readonly ModuleId[],
+  requested: readonly ModuleId[],
+): ModuleActivationResult {
+  const active = new Set<ModuleId>(REQUIRED_MODULE_IDS);
+  for (const id of requested) active.add(id);
+  for (const id of active) {
+    if (!entitled.includes(id)) return { ok: false, error: `module "${id}" is not entitled for this site` };
+  }
+  for (const id of active) {
+    for (const dep of moduleManifest(id).dependsOn) {
+      if (!active.has(dep)) return { ok: false, error: `module "${id}" requires "${dep}" to be enabled` };
+    }
+  }
+  return { ok: true, modules: MODULE_IDS.filter((id) => active.has(id)) };
+}
+
+/** The effective set = required ∪ (entitled ∩ activated), then any module whose
+ *  dependency is not effective is dropped (defensive: an entitlement can shrink after
+ *  activation was recorded). `activated === null` means "never set" → everything
+ *  entitled. Registry order. */
+export function effectiveModules(entitled: readonly ModuleId[], activated: readonly ModuleId[] | null): ModuleId[] {
+  const on = new Set<ModuleId>(REQUIRED_MODULE_IDS);
+  for (const id of activated ?? entitled) {
+    if (entitled.includes(id)) on.add(id);
+  }
+  // Drop dependency-broken modules until stable (the registry is tiny; a loop is fine).
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const id of [...on]) {
+      if (moduleManifest(id).dependsOn.some((dep) => !on.has(dep))) {
+        on.delete(id);
+        changed = true;
+      }
+    }
+  }
+  return MODULE_IDS.filter((id) => on.has(id));
+}