parking_solution/apps/server/src/shift-service.ts

import { eq, devices, ledgerEvents, type Db } from "@parking/db";
import { registry, type PrinterDevice } from "@parking/devices";
import type { LedgerPayload } from "@parking/shared";
import type { FastifyBaseLogger } from "fastify";
import type { EventLog } from "./event-log.js";

// Shift service (manned mode only). A shift is an operator's accountability period,
// delimited by EXPLICIT marks — not a clock. Represented entirely as signed ledger
// events (no mutable table): `shift_open` … `shift_z_report`. At close, sum the
// `payment` events taken during the shift by tender and print a Z-report.
// See wiki/concepts/shift.md.

export class ShiftAlreadyOpenError extends Error {
  /** The operator who currently holds the open shift (may be someone else). */
  readonly heldBy: string;
  constructor(operator: string, heldBy: string) {
    super(
      heldBy === operator
        ? `operator ${operator} already has an open shift`
        : `another operator (${heldBy}) has an open shift; only one shift may be open at a time`,
    );
    this.name = "ShiftAlreadyOpenError";
    this.heldBy = heldBy;
  }
}
export class NoOpenShiftError extends Error {
  constructor(operator: string) {
    super(`operator ${operator} has no open shift`);
    this.name = "NoOpenShiftError";
  }
}
/** Thrown by the booth money path when NO shift is open site-wide — an operator
 *  must open a shift before any payment/exit can be attributed to a shift. */
export class NoShiftOpenError extends Error {
  constructor() {
    super("no shift is open — open a shift before processing tickets");
    this.name = "NoShiftOpenError";
  }
}

export interface ShiftReport {
  readonly operator: string;
  readonly startedAt: string;
  readonly endedAt: string;
  readonly cashTotalMinor: number;
  readonly cardTotalMinor: number;
  readonly currency: string | null;
  readonly paymentCount: number;
  // --- Drawer (physical cash till; carries across shifts) ---
  /** Cash in the drawer at shift start = prior shift's expected closing drawer. */
  readonly openingFloatMinor: number;
  /** Admin cash LOADED into the drawer during the shift (sum of + movements). */
  readonly cashAddedMinor: number;
  /** Admin cash REMOVED from the drawer during the shift (sum of − movements, as +). */
  readonly cashRemovedMinor: number;
  /** Expected drawer at close = opening + cashTaken + added − removed. Carries forward. */
  readonly expectedDrawerMinor: number;
  readonly printed: boolean;
}

export class InvalidCashMovementError extends Error {
  constructor(msg: string) {
    super(msg);
    this.name = "InvalidCashMovementError";
  }
}

export class ShiftService {
  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;
  }

  /** Current physical drawer balance (cash payments + cash_movements, by time). For
   *  the UI to show "inherited / in the drawer now". */
  drawerBalance(): { balanceMinor: number; currency: string | null } {
    return this.#drawerBalanceAt(new Date().toISOString());
  }

  /** Is there an open shift for this operator? Returns the open `shift_open` row or null. */
  openShiftFor(operator: string) {
    // Scan shift events for this operator; the shift is open if the most recent
    // shift event for them is a `shift_open` (not yet closed by a z_report).
    const rows = this.#db
      .select()
      .from(ledgerEvents)
      .where(eq(ledgerEvents.identity, operator))
      .orderBy(ledgerEvents.index)
      .all()
      .filter((r) => r.type === "shift_open" || r.type === "shift_z_report");
    const last = rows[rows.length - 1];
    return last && last.type === "shift_open" ? last : null;
  }

  /**
   * The SINGLE site-wide open shift, or null. A shift is a site-wide accountability
   * period: at most ONE may be open at a time (so booth takings are unambiguously
   * attributed to one operator). It's open iff the most recent shift event on the
   * whole chain is a `shift_open` (the matching `shift_z_report` hasn't been
   * appended yet). Returns that row so callers can read its operator/startedAt.
   */
  currentOpenShift() {
    const rows = this.#db
      .select()
      .from(ledgerEvents)
      .orderBy(ledgerEvents.index)
      .all()
      .filter((r) => r.type === "shift_open" || r.type === "shift_z_report");
    const last = rows[rows.length - 1];
    return last && last.type === "shift_open" ? last : null;
  }

  /** Require an open shift for the booth money path; returns it or throws. */
  requireOpenShift() {
    const open = this.currentOpenShift();
    if (!open) throw new NoShiftOpenError();
    return open;
  }

  /**
   * The physical drawer balance at `at`: a fold over the SIGNED chain BY TIME (not
   * by operator — a cash_movement is the admin's, not the shift operator's). Cash
   * payments add to the drawer; card payments never touch it; cash_movement amounts
   * (signed: + load, − removal) adjust it. This is what carries across shifts.
   */
  #drawerBalanceAt(at: string): { balanceMinor: number; currency: string | null } {
    const rows = this.#db
      .select()
      .from(ledgerEvents)
      .orderBy(ledgerEvents.index)
      .all()
      .filter((r) => r.occurredAt <= at && (r.type === "payment" || r.type === "cash_movement"));
    let balanceMinor = 0;
    let currency: string | null = null;
    for (const r of rows) {
      const pl = (r.payload ?? {}) as LedgerPayload;
      const amt = typeof pl.amountMinor === "number" ? pl.amountMinor : 0;
      if (r.type === "payment") {
        // Only CASH enters the till; card settles to the bank.
        if (pl.tender !== "card") balanceMinor += amt;
      } else {
        // cash_movement amount is signed (+ load, − removal).
        balanceMinor += amt;
      }
      if (pl.currency) currency = pl.currency;
    }
    return { balanceMinor, currency };
  }

  /**
   * Record an admin cash movement (load/remove drawer float). `amountMinor` is
   * signed: positive = cash loaded IN, negative = cash taken OUT. Signed +
   * attributed. Admin-only is enforced at the route. Returns the new drawer balance.
   */
  async recordCashMovement(
    operator: string,
    amountMinor: number,
    reason: string,
    currency?: string,
  ): Promise<{ amountMinor: number; balanceMinor: number }> {
    if (!Number.isInteger(amountMinor) || amountMinor === 0) {
      throw new InvalidCashMovementError("amountMinor must be a non-zero integer (minor units)");
    }
    const now = new Date().toISOString();
    await this.#log.append({
      type: "cash_movement",
      source: "manual",
      identity: operator, // who moved the cash (admin)
      payload: {
        amountMinor,
        ...(reason ? { reason } : {}),
        ...(currency ? { currency } : {}),
        operator,
      },
      occurredAt: now,
    });
    const { balanceMinor } = this.#drawerBalanceAt(now);
    this.#logger.info(
      `cash_movement ${amountMinor >= 0 ? "+" : ""}${amountMinor} by ${operator} (${reason || "no reason"}) → drawer ${balanceMinor}`,
    );
    return { amountMinor, balanceMinor };
  }

  /** Open a shift for the operator (explicit start). The opening float is auto-
   *  inherited from the chain = the drawer balance at the start instant. */
  async open(operator: string): Promise<{ startedAt: string; openingFloatMinor: number }> {
    // Site-wide single-open invariant: refuse if ANY shift is open — whether this
    // operator's own (double-open) or another operator's (handover not done). Only
    // one accountability period at a time.
    const current = this.currentOpenShift();
    if (current) throw new ShiftAlreadyOpenError(operator, current.identity ?? operator);
    const startedAt = new Date().toISOString();
    const { balanceMinor: openingFloatMinor } = this.#drawerBalanceAt(startedAt);
    await this.#log.append({
      type: "shift_open",
      source: "manual",
      identity: operator, // the shift's operator; `identity` keys the shift to them
      // Record the inherited opening float on the shift_open so it's reproducible
      // and the next operator's handover figure is fixed in the chain.
      payload: { operator, openingFloatMinor },
      occurredAt: startedAt,
    });
    this.#logger.info(`shift opened for ${operator} (opening float ${openingFloatMinor})`);
    return { startedAt, openingFloatMinor };
  }

  /** Close the operator's open shift: sum payments in the window, sign + print the Z-report. */
  async close(operator: string): Promise<ShiftReport> {
    const open = this.openShiftFor(operator);
    if (!open) throw new NoOpenShiftError(operator);
    const startedAt = open.occurredAt;
    const endedAt = new Date().toISOString();

    // All payments taken in [startedAt, endedAt], summed by tender. Payment time =
    // the operator who handled the money (decision: sum by payment time).
    const payments = this.#db
      .select()
      .from(ledgerEvents)
      .where(eq(ledgerEvents.type, "payment"))
      .all()
      .filter((r) => r.occurredAt >= startedAt && r.occurredAt <= endedAt);

    let cashTotalMinor = 0;
    let cardTotalMinor = 0;
    let currency: string | null = null;
    for (const p of payments) {
      const pl = (p.payload ?? {}) as LedgerPayload;
      const amt = typeof pl.amountMinor === "number" ? pl.amountMinor : 0;
      if (pl.tender === "card") cardTotalMinor += amt;
      else cashTotalMinor += amt;
      if (pl.currency) currency = pl.currency;
    }

    // --- Drawer figures ---
    // Opening float was fixed on shift_open (inherited from the chain at start);
    // fall back to a fresh fold if an older shift_open lacks it.
    const openPl = (open.payload ?? {}) as LedgerPayload & { openingFloatMinor?: number };
    const openingFloatMinor =
      typeof openPl.openingFloatMinor === "number"
        ? openPl.openingFloatMinor
        : this.#drawerBalanceAt(startedAt).balanceMinor;

    // Cash movements within the shift window, split into added (+) and removed (−).
    const movements = this.#db
      .select()
      .from(ledgerEvents)
      .where(eq(ledgerEvents.type, "cash_movement"))
      .all()
      .filter((r) => r.occurredAt >= startedAt && r.occurredAt <= endedAt);
    let cashAddedMinor = 0;
    let cashRemovedMinor = 0;
    for (const m of movements) {
      const pl = (m.payload ?? {}) as LedgerPayload;
      const amt = typeof pl.amountMinor === "number" ? pl.amountMinor : 0;
      if (amt >= 0) cashAddedMinor += amt;
      else cashRemovedMinor += -amt; // store as a positive magnitude
      if (pl.currency) currency = pl.currency;
    }

    // Expected drawer at close = opening + cash taken + added − removed. This is the
    // figure the NEXT shift inherits as its opening float.
    const expectedDrawerMinor = openingFloatMinor + cashTotalMinor + cashAddedMinor - cashRemovedMinor;

    const report: Omit<ShiftReport, "printed"> = {
      operator,
      startedAt,
      endedAt,
      cashTotalMinor,
      cardTotalMinor,
      currency,
      paymentCount: payments.length,
      openingFloatMinor,
      cashAddedMinor,
      cashRemovedMinor,
      expectedDrawerMinor,
    };

    await this.#log.append({
      type: "shift_z_report",
      source: "manual",
      identity: operator,
      payload: {
        operator,
        startedAt,
        endedAt,
        cashTotalMinor,
        cardTotalMinor,
        currency: currency ?? undefined,
        paymentCount: payments.length,
        openingFloatMinor,
        cashAddedMinor,
        cashRemovedMinor,
        expectedDrawerMinor,
      },
    });

    const printed = await this.#printZReport(report);

    this.#logger.info(
      `shift closed for ${operator}: cash ${cashTotalMinor} card ${cardTotalMinor} (${payments.length} payments); ` +
        `drawer open ${openingFloatMinor} +${cashAddedMinor} −${cashRemovedMinor} → expected ${expectedDrawerMinor}`,
    );
    return { ...report, printed };
  }

  /** Print the Z-report on a booth-receipt printer (best-effort; the signed event
   *  is the record — a failed print doesn't undo the close). */
  async #printZReport(r: Omit<ShiftReport, "printed">): Promise<boolean> {
    const printer = await this.#boothPrinter();
    if (!printer) {
      this.#logger.warn(`no booth-receipt printer — Z-report for ${r.operator} not printed (event is recorded)`);
      return false;
    }
    const cur = r.currency ?? "";
    const money = (m: number) => (m / 100).toFixed(2);
    const lines = [
      `Operator: ${r.operator}`,
      `From: ${r.startedAt}`,
      `To:   ${r.endedAt}`,
      "",
      `Payments: ${r.paymentCount}`,
      `Cash: ${money(r.cashTotalMinor)} ${cur}`,
      `Card: ${money(r.cardTotalMinor)} ${cur}`,
      "",
      "-- Drawer --",
      `Opening float: ${money(r.openingFloatMinor)} ${cur}`,
      `Cash taken:    ${money(r.cashTotalMinor)} ${cur}`,
      `Cash added:    ${money(r.cashAddedMinor)} ${cur}`,
      `Cash removed:  ${money(r.cashRemovedMinor)} ${cur}`,
      `Expected drawer: ${money(r.expectedDrawerMinor)} ${cur}`,
    ];
    try {
      await printer.printReport({ title: "SHIFT Z-REPORT", lines });
      return true;
    } catch (err) {
      this.#logger.warn(`Z-report print failed for ${r.operator}: ${(err as Error).message} (event recorded)`);
      return false;
    }
  }

  /** First enabled booth-receipt printer, or any enabled printer. */
  async #boothPrinter(): Promise<PrinterDevice | null> {
    const rows = await this.#db.select().from(devices).where(eq(devices.category, "printer")).all();
    const enabled = rows.filter((r) => r.enabled);
    const booth = enabled.find((r) => (r.config as { role?: string }).role === "booth-receipt") ?? enabled[0];
    if (!booth) return null;
    const driver = registry.get(booth.driverId);
    if (!driver) return null;
    try {
      return driver.create(booth.config as never) as PrinterDevice;
    } catch {
      return null;
    }
  }
}