server: pay station + fee calc — full transient loop now passes

computeFee() in @parking/shared: pure integer fee over a TariffStructure (stepped blocks, rolling-24h cap). Two edges fixed under test: grace uses RAW duration (not rounded-up minutes), and the block ladder resets each 24h day. PayStation + routes (GET /api/pay/quote, POST /api/pay): look up the open session, resolve the active tariff version (latest effectiveFrom <= entry), computeFee, append a signed payment event (amount/currency/tender/ tariffVersionId/graceExitMin). overrideMinor handles lost-ticket/dispute. PCI stays out of the app: tender only records cash/card. Verified end to end: entry -> quote (300 for 90min) -> pay -> exit opens and closes the session, verifyChain ok.
2026-06-15 19:15:53 +02:00
parent a8c6d6e714
commit f18e28eeca
6 changed files with 297 additions and 2 deletions
@@ -0,0 +1,140 @@
+import { desc, eq, ledgerEvents, sessions, tariffVersions, tariffs, type Db } from "@parking/db";
+import { computeFee, type TariffStructure, type Tender } from "@parking/shared";
+import type { FastifyBaseLogger } from "fastify";
+import type { EventLog } from "./event-log.js";
+
+// The PAY STATION: a customer pays for an open session BEFORE walking back to the
+// car (pay-on-foot — payment is decoupled from exit). Two steps:
+//   1. quote(identity)  → look up the open session, price it against the tariff in
+//      force at entry, return the amount due (no side effect).
+//   2. pay(identity, tender) → re-price, append a SIGNED `payment` event carrying
+//      the amount, currency, tender, tariffVersionId, and graceExitMin (so the exit
+//      flow can validate paid + within walk-back grace). Payment is a signed ledger
+//      event, never a mutable "paid" flag — an operator can't forge or delete it.
+// See wiki/concepts/tariff.md, parking-session.md.
+
+export class NoOpenSessionError extends Error {
+  constructor(identity: string) {
+    super(`no open session for ${identity}`);
+    this.name = "NoOpenSessionError";
+  }
+}
+export class NoTariffError extends Error {
+  constructor() {
+    super("no active tariff configured");
+    this.name = "NoTariffError";
+  }
+}
+
+export interface Quote {
+  readonly identity: string;
+  readonly enteredAt: string;
+  readonly amountMinor: number;
+  readonly currency: string;
+  readonly tariffVersionId: string;
+  readonly graceExitMin: number;
+}
+
+export class PayStation {
+  readonly #db: Db;
+  readonly #log: EventLog;
+  readonly #logger: FastifyBaseLogger;
+
+  constructor(db: Db, log: EventLog, logger: FastifyBaseLogger) {
+    this.#db = db;
+    this.#log = log;
+    this.#logger = logger;
+  }
+
+  /** Price an open session against the tariff in force at its entry. No side effect. */
+  quote(identity: string): Quote {
+    const entry = this.#openEntry(identity);
+    if (!entry) throw new NoOpenSessionError(identity);
+
+    const tv = this.#tariffVersionFor(entry.occurredAt);
+    if (!tv) throw new NoTariffError();
+    const structure = tv.structure as unknown as TariffStructure;
+
+    const amountMinor = computeFee(entry.occurredAt, new Date().toISOString(), structure);
+    return {
+      identity,
+      enteredAt: entry.occurredAt,
+      amountMinor,
+      currency: tv.currency,
+      tariffVersionId: tv.id,
+      graceExitMin: structure.gracePeriodExitMin,
+    };
+  }
+
+  /**
+   * Take payment for a session and append the signed `payment` event. Re-quotes at
+   * the moment of payment (the customer pays for time parked SO FAR). For an
+   * overstay top-up the same call re-prices entry→now and the exit flow's
+   * grace-window restarts from this payment. `overrideMinor` lets the operator set
+   * an arbitrary amount (lost ticket / dispute) — recorded as the charged amount.
+   */
+  async pay(
+    identity: string,
+    tender: Tender,
+    overrideMinor?: number,
+  ): Promise<{ amountMinor: number; currency: string }> {
+    const q = this.quote(identity);
+    const amountMinor = overrideMinor ?? q.amountMinor;
+
+    await this.#log.append({
+      type: "payment",
+      lane: -1, // payment happens at a central station, not a lane
+      source: "manual",
+      identity,
+      payload: {
+        sessionRef: identity,
+        amountMinor,
+        currency: q.currency,
+        tender,
+        tariffVersionId: q.tariffVersionId,
+        // The exit flow reads graceExitMin off the payment to validate the
+        // walk-back window without re-resolving the tariff.
+        graceExitMin: q.graceExitMin,
+        ...(overrideMinor != null ? { reason: "operator-set amount", quotedMinor: q.amountMinor } : {}),
+      },
+    });
+
+    // Update the projection cache (rebuildable; not the source of truth).
+    try {
+      this.#db.update(sessions).set({ state: "paid" }).where(eq(sessions.id, identity)).run();
+    } catch (err) {
+      this.#logger.error(`session-cache mark-paid failed for ${identity}: ${(err as Error).message}`);
+    }
+
+    this.#logger.info(`payment ${amountMinor} ${q.currency} (${tender}) for ${identity}`);
+    return { amountMinor, currency: q.currency };
+  }
+
+  /** The vehicle_entry of an OPEN session for this identity (no later exit), or null. */
+  #openEntry(identity: string) {
+    const rows = this.#db
+      .select()
+      .from(ledgerEvents)
+      .where(eq(ledgerEvents.identity, identity))
+      .orderBy(ledgerEvents.index)
+      .all();
+    const entry = rows.find((r) => r.type === "vehicle_entry");
+    if (!entry) return null;
+    if (rows.some((r) => r.type === "vehicle_exit")) return null; // already closed
+    return entry;
+  }
+
+  /** The tariff version in force at `at` — latest effectiveFrom ≤ at, for the
+   *  (single, for now) active site tariff. */
+  #tariffVersionFor(at: string) {
+    const tariff = this.#db.select().from(tariffs).where(eq(tariffs.scope, "site")).get();
+    if (!tariff) return null;
+    const versions = this.#db
+      .select()
+      .from(tariffVersions)
+      .where(eq(tariffVersions.tariffId, tariff.id))
+      .orderBy(desc(tariffVersions.effectiveFrom))
+      .all();
+    return versions.find((v) => v.effectiveFrom <= at) ?? null;
+  }
+}
@@ -0,0 +1,69 @@
+import type { FastifyInstance } from "fastify";
+import { requireRole } from "../auth.js";
+import {
+  NoOpenSessionError,
+  NoTariffError,
+  type PayStation,
+} from "../pay-station.js";
+
+// Pay-station endpoints (pay-on-foot). The terminal/operator UI quotes a session
+// then takes payment; the payment becomes a signed ledger event. PCI scope stays
+// OUT of the app — actual card capture is a standalone P2PE terminal; here `tender`
+// just records cash vs. card. See wiki/concepts/tariff.md, parking-session.md, bom.md.
+
+interface QuoteQuery {
+  identity: string;
+}
+interface PayBody {
+  identity: string;
+  tender: "cash" | "card";
+  /** Operator-set amount (lost ticket / dispute) — overrides the computed fee. */
+  overrideMinor?: number;
+}
+
+export async function payRoutes(app: FastifyInstance, payStation: PayStation): Promise<void> {
+  // Cashier/operator/admin operate the pay station; readonly may not.
+  const guard = requireRole("admin", "operator", "cashier");
+
+  // Quote: what does this session owe right now? (No side effect.)
+  app.get<{ Querystring: QuoteQuery }>(
+    "/api/pay/quote",
+    { preHandler: guard },
+    async (req, reply) => {
+      const identity = (req.query.identity ?? "").trim();
+      if (!identity) return reply.code(400).send({ error: "identity required" });
+      try {
+        return payStation.quote(identity);
+      } catch (err) {
+        return mapError(reply, err);
+      }
+    },
+  );
+
+  // Pay: take payment and append the signed `payment` event.
+  app.post<{ Body: PayBody }>(
+    "/api/pay",
+    { preHandler: guard },
+    async (req, reply) => {
+      const { identity, tender, overrideMinor } = req.body ?? {};
+      if (!identity || (tender !== "cash" && tender !== "card")) {
+        return reply.code(400).send({ error: "identity and tender (cash|card) required" });
+      }
+      if (overrideMinor != null && (!Number.isInteger(overrideMinor) || overrideMinor < 0)) {
+        return reply.code(400).send({ error: "overrideMinor must be a non-negative integer (minor units)" });
+      }
+      try {
+        const res = await payStation.pay(identity, tender, overrideMinor);
+        return reply.code(201).send(res);
+      } catch (err) {
+        return mapError(reply, err);
+      }
+    },
+  );
+}
+
+function mapError(reply: import("fastify").FastifyReply, err: unknown) {
+  if (err instanceof NoOpenSessionError) return reply.code(404).send({ error: err.message });
+  if (err instanceof NoTariffError) return reply.code(409).send({ error: err.message });
+  return reply.code(500).send({ error: (err as Error).message });
+}