@7365admin1/layer-common 4.149.2 → 4.150.0

package/utils/hid-reader-audiences.ts

@@ -0,0 +1,557 @@
+/**
+ * WHO A READER IS FOR — the frontend's reading of it.
+ *
+ * Mirrors `hid-reader-audience.util.ts` in core, which is the authority and the
+ * only thing that enforces it. This repository cannot import core's copy, so
+ * there is one here — and it lives in a util with tests rather than inside a
+ * component, because the DEFAULT is the part that can take a door offline.
+ *
+ * A site with several doors rarely wants every door open to everybody: a service
+ * entrance for contractors, a lobby for residents. Declaring that on the reader
+ * is what lets an enrolment work out which readers a person belongs on.
+ */
+
+export const HID_READER_AUDIENCES = [
+  "resident",
+  "residentVisitor",
+  "member",
+  "serviceProvider",
+] as const;
+
+export type THidReaderAudience = (typeof HID_READER_AUDIENCES)[number];
+export type THidReaderAudiences = Record<THidReaderAudience, boolean>;
+
+/** What each switch is called, and what it means, on the reader form. */
+export const HID_READER_AUDIENCE_FIELDS: ReadonlyArray<{
+  value: THidReaderAudience;
+  label: string;
+  hint: string;
+}> = [
+  {
+    value: "resident",
+    label: "Resident",
+    hint: "Residents of this site may be enrolled on this reader.",
+  },
+  {
+    value: "residentVisitor",
+    label: "Resident visitor",
+    hint: "A resident may issue a visitor QR pass for this reader.",
+  },
+  {
+    value: "member",
+    label: "Member",
+    hint: "Property management staff may be enrolled on this reader.",
+  },
+  {
+    value: "serviceProvider",
+    label: "Service provider",
+    hint: "A service provider's people may be enrolled on this reader.",
+  },
+];
+
+/**
+ * ABSENT MEANS ALL FOUR, and that is the whole backward-compatibility story.
+ *
+ * Every reader registered before this field existed has no `audiences`. Reading
+ * that as "serves nobody" would show every existing reader as closed to
+ * everyone, and - worse - a save from that screen would then write those
+ * falsehoods and actually close them.
+ *
+ * A field that is present but missing a key is read the same way, so a partial
+ * record cannot quietly close a door either. Only a real `false` closes one.
+ */
+export function readerAudiences(
+  reader: Record<string, unknown> | null | undefined,
+): THidReaderAudiences {
+  const stored = reader?.audiences;
+  const record = stored && typeof stored === "object"
+    ? stored as Record<string, unknown>
+    : {};
+  return HID_READER_AUDIENCES.reduce((audiences, audience) => ({
+    ...audiences,
+    [audience]: record[audience] === undefined ? true : record[audience] === true,
+  }), {} as THidReaderAudiences);
+}
+
+/** Does this reader serve that audience? */
+export function readerServesAudience(
+  reader: Record<string, unknown> | null | undefined,
+  audience: THidReaderAudience,
+): boolean {
+  return readerAudiences(reader)[audience] === true;
+}
+
+/**
+ * The audience a permission category answers to.
+ *
+ * Both service-provider categories share one switch: a property manager thinks
+ * "may contractors use this door", not "may contractor companies use it as
+ * distinct from contractor people". Unrecognised returns null, so a category
+ * added later is visibly unmapped rather than silently lumped in with one.
+ */
+export function audienceOfCategory(category: unknown): THidReaderAudience | null {
+  switch (String(category ?? "")) {
+    case "resident":
+      return "resident";
+    case "property_management":
+      return "member";
+    case "service_provider":
+    case "service_provider_member":
+      return "serviceProvider";
+    default:
+      return null;
+  }
+}
+
+/**
+ * Which of the Access Permissions tabs this reader is worth showing.
+ *
+ * A reader that serves nobody in a category cannot hold a grant in it - core
+ * refuses the save - so a tab for it would be a list the operator can look at
+ * and never act on.
+ *
+ * NEVER RETURNS NOTHING. A reader with every audience switched off would leave a
+ * dialog with no tabs and no explanation, which reads as a broken screen; the
+ * first tab is kept so there is always something to show, and it will simply be
+ * empty. The caller is told whether that happened so it can say why.
+ */
+export function visibleAudienceTabs<T extends { category: unknown }>(
+  reader: Record<string, unknown> | null | undefined,
+  tabs: readonly T[],
+): { tabs: T[]; narrowed: boolean; emptied: boolean } {
+  const served = tabs.filter((tab) => {
+    const audience = audienceOfCategory(tab.category);
+    return audience ? readerServesAudience(reader, audience) : false;
+  });
+  if (!served.length) {
+    return { tabs: tabs.slice(0, 1), narrowed: true, emptied: true };
+  }
+  return { tabs: served, narrowed: served.length !== tabs.length, emptied: false };
+}
+
+/**
+ * WHICH SUBJECT TYPES CAN BE ENROLLED on the readers being targeted.
+ *
+ * Takes a SET of readers rather than one, deliberately. Today an enrolment goes
+ * to the reader selected on the screen, so the set has one member; once
+ * enrolment fans out to every reader whose audiences match, the same question is
+ * asked of several. Shaping it this way now means the call site changes later
+ * and this does not.
+ *
+ * Offering a type the reader will not accept is not merely untidy: the server
+ * refuses the grant, and it refuses it on SAVE - after the operator has chosen a
+ * person and captured a face, which on a reader is the expensive step.
+ *
+ * `category` on each option is the dropdown's own value, mapped to a permission
+ * category and then to an audience by composing the two functions that already
+ * exist, rather than by a third mapping that could drift from them.
+ */
+export function availableEnrolmentSubjects<T extends { value: unknown }>(
+  readers: ReadonlyArray<Record<string, unknown> | null | undefined>,
+  options: readonly T[],
+  categoryOfOption: (option: T) => unknown,
+): { options: T[]; narrowed: boolean; emptied: boolean } {
+  /*
+   * NO READER YET IS NOT "NO AUDIENCES". The dialog can be mounted before a
+   * reader has been chosen, and showing nothing then would read as a reader that
+   * serves nobody rather than as a question not yet answered.
+   */
+  const known = readers.filter(Boolean) as Array<Record<string, unknown>>;
+  if (!known.length) {
+    return { options: [...options], narrowed: false, emptied: false };
+  }
+
+  const served = options.filter((option) => {
+    const audience = audienceOfCategory(categoryOfOption(option));
+    if (!audience) return false;
+    // ANY of the targeted readers is enough: the enrolment lands on whichever
+    // of them serve this person, not on all of them.
+    return known.some((reader) => readerServesAudience(reader, audience));
+  });
+
+  return {
+    options: served,
+    narrowed: served.length !== options.length,
+    // Nothing offered at all. The caller says why rather than drawing an empty
+    // dropdown, which looks like a screen that failed to load.
+    emptied: !served.length,
+  };
+}
+
+/* ── WHAT SWITCHING ONE OFF COSTS ──────────────────────────────────────── */
+
+/** `counts` as `getSitePermissions` returns it, per category. */
+export type THidPermissionCounts = {
+  resident?: number;
+  propertyManagement?: number;
+  serviceProvider?: number;
+  serviceProviderMember?: number;
+};
+
+/**
+ * How many people on this reader lose access if an account type is switched off.
+ *
+ * Both service-provider categories answer to the one switch, so both are
+ * counted - a company grant and a named contractor are the same door to the
+ * person walking through it.
+ *
+ * RESIDENT VISITOR IS ALWAYS ZERO, and that is not an oversight. A visitor pass
+ * is not a permission assignment: it is bound through `user_access_rules` with
+ * its own expiry, so switching the account type off stops new passes being
+ * issued and leaves any already issued to run out on their own. Reporting a
+ * number there would promise a revocation that does not happen.
+ */
+export function peopleLosingAccess(
+  audience: THidReaderAudience,
+  counts: THidPermissionCounts | null | undefined,
+): number {
+  const read = (value: unknown) => {
+    const count = Number(value ?? 0);
+    return Number.isFinite(count) && count > 0 ? Math.floor(count) : 0;
+  };
+  switch (audience) {
+    case "resident":
+      return read(counts?.resident);
+    case "member":
+      return read(counts?.propertyManagement);
+    case "serviceProvider":
+      return read(counts?.serviceProvider) + read(counts?.serviceProviderMember);
+    case "residentVisitor":
+    default:
+      return 0;
+  }
+}
+
+/**
+ * The account types being switched OFF by this edit, with what each one costs.
+ *
+ * Only on-to-off transitions. An account type that was already off costs
+ * nothing to leave off, and listing it would make every save of an unrelated
+ * field look like a revocation.
+ */
+export function audienceRevocations(
+  before: THidReaderAudiences,
+  after: THidReaderAudiences,
+  counts: THidPermissionCounts | null | undefined,
+): Array<{ audience: THidReaderAudience; label: string; people: number }> {
+  return HID_READER_AUDIENCE_FIELDS
+    .filter((field) => before[field.value] === true && after[field.value] === false)
+    .map((field) => ({
+      audience: field.value,
+      label: field.label,
+      people: peopleLosingAccess(field.value, counts),
+    }));
+}
+
+/**
+ * Account types this edit would leave with NO reader at the site.
+ *
+ * A warning rather than a refusal: a site may genuinely have no door for
+ * contractors, and the last reader is sometimes switched off because it is being
+ * decommissioned. But doing it unknowingly means residents - or a whole category
+ * of people - quietly have no way in, and nothing else on the screen would say so.
+ *
+ * The reader being edited is judged by `after`, not by what is stored, so the
+ * warning describes the save about to happen rather than the state before it.
+ */
+export function audiencesLeftWithNoReader(
+  readerId: unknown,
+  after: THidReaderAudiences,
+  siteReaders: ReadonlyArray<Record<string, unknown>>,
+): Array<{ audience: THidReaderAudience; label: string }> {
+  const editing = String(readerId ?? "").trim();
+  return HID_READER_AUDIENCE_FIELDS
+    .filter((field) => {
+      const servedElsewhere = siteReaders.some((reader) => {
+        const id = String(reader?._id ?? "").trim();
+        // The reader being edited is judged by the pending values, not the stored
+        // ones - otherwise saving its own switch-off would never warn.
+        if (editing && id === editing) return false;
+        return readerServesAudience(reader, field.value);
+      });
+      return !servedElsewhere && after[field.value] === false;
+    })
+    .map((field) => ({ audience: field.value, label: field.label }));
+}
+
+/* ── WHICH READERS AN ENROLMENT LANDS ON ───────────────────────────────── */
+
+/**
+ * One reader's standing as a target for enrolling a person of some category.
+ *
+ * `reason` is what to tell the operator about a reader left out; `warning` what
+ * to tell them about one included that may not answer. Sentences, not codes —
+ * the only consumer is a list somebody reads before pressing Save.
+ */
+export type THidEnrolmentTarget = {
+  readerId: string;
+  name: string;
+  location: string;
+  included: boolean;
+  reason?: string;
+  warning?: string;
+};
+
+/**
+ * SPLIT A SITE'S READERS INTO THE ONES THIS PERSON BELONGS ON AND THE REST.
+ *
+ * Mirrors `partitionEnrolmentTargets` in core, which is the authority — core
+ * refuses a grant on a reader that does not serve the category, so this only
+ * decides what to draw. The copy exists because layer-common cannot import it.
+ *
+ * Three conditions, checked in the order that produces the most useful sentence
+ * rather than the order they are stored in. A reader that is switched off should
+ * say so; telling the operator it "does not serve residents" would be true of
+ * nothing and send them to the audience switches instead of the enable switch.
+ *
+ * AN OFFLINE READER IS STILL A TARGET. `offline` means we have not heard from
+ * it, not that it is unconfigured: the access grant is a database write that
+ * succeeds and the device write is retried. Excluding it would quietly deny
+ * somebody a door because a reader was asleep.
+ */
+export function partitionEnrolmentTargets(
+  readers: ReadonlyArray<Record<string, unknown> | null | undefined>,
+  category: unknown,
+): { targets: THidEnrolmentTarget[]; excluded: THidEnrolmentTarget[] } {
+  const targets: THidEnrolmentTarget[] = [];
+  const excluded: THidEnrolmentTarget[] = [];
+
+  for (const reader of readers) {
+    if (!reader) continue;
+    const readerId = String(reader._id ?? "").trim();
+    if (!readerId) continue;
+    const base = {
+      readerId,
+      name: String(reader.name ?? "").trim() || "HID Reader",
+      location: String(reader.location ?? "").trim(),
+    };
+
+    const status = String(reader.status ?? "");
+    if (reader.enabled === false || status === "inactive" || status === "deleted") {
+      excluded.push({ ...base, included: false, reason: "This reader is switched off." });
+      continue;
+    }
+    if (!reader.portalId || !String(reader.portalName ?? "").trim()) {
+      excluded.push({
+        ...base,
+        included: false,
+        reason: "No access portal is selected on this reader.",
+      });
+      continue;
+    }
+    const audience = audienceOfCategory(category);
+    if (!audience) {
+      excluded.push({
+        ...base,
+        included: false,
+        reason: "This kind of person cannot be granted a reader.",
+      });
+      continue;
+    }
+    if (!readerServesAudience(reader, audience)) {
+      excluded.push({
+        ...base,
+        included: false,
+        reason: `This reader does not serve ${audienceLabel(audience)}.`,
+      });
+      continue;
+    }
+
+    targets.push({
+      ...base,
+      included: true,
+      ...(status === "offline"
+        ? { warning: "Not heard from recently. Access is granted now and the reader updated when it answers." }
+        : {}),
+    });
+  }
+
+  return { targets, excluded };
+}
+
+/** What each account type is called in a sentence about a door. */
+export function audienceLabel(audience: unknown): string {
+  const labels: Record<string, string> = {
+    resident: "residents",
+    residentVisitor: "resident visitors",
+    member: "members",
+    serviceProvider: "service providers",
+  };
+  return labels[String(audience ?? "")] ?? "that kind of person";
+}
+
+/* ── HOW A FAN-OUT WENT ────────────────────────────────────────────────── */
+
+export type THidReaderStep = "waiting" | "working" | "done" | "failed";
+
+export type THidReaderOutcome = {
+  readerId: string;
+  name: string;
+  step: THidReaderStep;
+  /** What failed, in words the operator can act on. */
+  message?: string;
+  /** Whether a stored face is available, so Retry can be offered without the person. */
+  retryable?: boolean;
+};
+
+/** "2 of 4 readers" — what the progress line says while a save is running. */
+export function fanOutProgressText(outcomes: ReadonlyArray<THidReaderOutcome>): string {
+  const total = outcomes.length;
+  if (!total) return "";
+  const settled = outcomes.filter((o) => o.step === "done" || o.step === "failed").length;
+  return `${settled} of ${total} ${total === 1 ? "reader" : "readers"}`;
+}
+
+/**
+ * What to say once a fan-out has finished.
+ *
+ * A PARTIAL RESULT IS NOT A FAILURE, and must not read as one: the person has
+ * access on the readers that worked, and the rest can be retried without them
+ * being present. Saying "enrolment failed" would send the operator to re-do work
+ * that is already done.
+ */
+export function fanOutSummary(outcomes: ReadonlyArray<THidReaderOutcome>): {
+  tone: "success" | "partial" | "error";
+  message: string;
+} {
+  const total = outcomes.length;
+  const done = outcomes.filter((o) => o.step === "done").length;
+  const failed = outcomes.filter((o) => o.step === "failed").length;
+
+  if (!total) return { tone: "error", message: "No reader at this site serves this person." };
+  if (!failed) {
+    return {
+      tone: "success",
+      message: `Enrolled on ${done} ${done === 1 ? "reader" : "readers"}.`,
+    };
+  }
+  if (!done) {
+    return {
+      tone: "error",
+      message: `Could not enroll on any of the ${total} ${total === 1 ? "reader" : "readers"}. Nothing was changed on them.`,
+    };
+  }
+  return {
+    tone: "partial",
+    message: `Enrolled on ${done} of ${total} readers. ${failed} can be retried — the person does not need to be present.`,
+  };
+}
+
+/**
+ * What to say after an EDIT has been applied across readers.
+ *
+ * Different from an enrolment's summary in one way that matters: a PIN.
+ *
+ * A face that reached three readers of four is incomplete - the person opens
+ * three doors. A PIN that reached three of four is WORSE than incomplete: the
+ * old PIN still works on the fourth, so they hold two PINs and have no way to
+ * know which door wants which. That is the one partial state worth naming
+ * explicitly rather than folding into "2 of 3".
+ */
+export function editFanOutSummary(
+  outcomes: ReadonlyArray<THidReaderOutcome>,
+  pinChanged: boolean,
+): { tone: "success" | "partial" | "error"; message: string } {
+  const total = outcomes.length;
+  const done = outcomes.filter((o) => o.step === "done").length;
+  const failed = outcomes.filter((o) => o.step === "failed").length;
+
+  if (!total) return { tone: "error", message: "This person is not on any reader." };
+  if (!failed) {
+    return {
+      tone: "success",
+      message: total === 1
+        ? "Updated on this reader."
+        : `Updated on all ${total} readers.`,
+    };
+  }
+  if (!done) {
+    return {
+      tone: "error",
+      message: `Could not update any of the ${total} ${total === 1 ? "reader" : "readers"}.`,
+    };
+  }
+
+  const stale = outcomes.filter((o) => o.step === "failed").map((o) => o.name).join(", ");
+  return {
+    tone: "partial",
+    message: pinChanged
+      ? `Updated on ${done} of ${total} readers. ${stale} still ${failed === 1 ? "has" : "have"} the OLD PIN —`
+        + " this person now has two different PINs. Save again to finish."
+      : `Updated on ${done} of ${total} readers. ${stale} ${failed === 1 ? "was" : "were"} not reached. Save again to finish.`,
+  };
+}
+
+/* ── DELETING SOMEBODY WHO IS ON SEVERAL READERS ───────────────────────── */
+
+/**
+ * A delete used to be read as "remove this row", which was true when a person
+ * lived on one reader. Once enrolment fans out, the same person is on several,
+ * and "delete" is ambiguous in the one direction that matters: removing them
+ * everywhere when the operator meant one door is an access change they did not
+ * ask for and cannot see from this screen.
+ *
+ * So the dialog asks, and the default is the narrow one - this reader. Widening
+ * is a deliberate click.
+ */
+export function deleteScopeChoices(
+  readerCount: number,
+  hereName: string,
+): Array<{ label: string; value: "here" | "all" }> {
+  const here = { label: `This reader only (${hereName || "this reader"})`, value: "here" as const };
+  if (readerCount < 2) return [here];
+  return [here, { label: `All ${readerCount} readers`, value: "all" as const }];
+}
+
+/** "This person is also on Gym and Car Park." - said before, not after. */
+export function deleteReachText(
+  places: ReadonlyArray<{ readerId: string; name: string }>,
+  hereReaderId: string,
+): string {
+  const others = places
+    .filter((p) => p.readerId !== hereReaderId)
+    .map((p) => p.name || "a reader");
+  if (!others.length) return "This person is only on this reader.";
+  const names = others.length === 1
+    ? others[0]
+    : `${others.slice(0, -1).join(", ")} and ${others[others.length - 1]}`;
+  return `This person is also on ${names}.`;
+}
+
+/**
+ * What to say after a delete has run across readers.
+ *
+ * The failure here is the mirror of the edit's: a delete that reached three
+ * readers of four leaves the person still able to open the fourth door. Naming
+ * that reader is the whole message - "2 of 3" alone tells an operator a door is
+ * still open without telling them which.
+ */
+export function deleteFanOutSummary(
+  outcomes: ReadonlyArray<THidReaderOutcome>,
+): { tone: "success" | "partial" | "error"; message: string } {
+  const total = outcomes.length;
+  const done = outcomes.filter((o) => o.step === "done").length;
+  const failed = outcomes.filter((o) => o.step === "failed");
+
+  if (!total) return { tone: "error", message: "There was nothing to delete." };
+  if (!failed.length) {
+    return {
+      tone: "success",
+      message: total === 1
+        ? "Deleted from this reader."
+        : `Deleted from all ${total} readers.`,
+    };
+  }
+  if (!done) {
+    return {
+      tone: "error",
+      message: `Could not delete from any of the ${total} ${total === 1 ? "reader" : "readers"}.`,
+    };
+  }
+  const left = failed.map((o) => o.name).join(", ");
+  return {
+    tone: "partial",
+    message: `Deleted from ${done} of ${total} readers. This person can STILL open`
+      + ` ${left}. Delete again to finish.`,
+  };
+}

package/utils/hid-registration.ts

@@ -0,0 +1,24 @@
+/**
+ * THE NEXT REGISTRATION NUMBER ON ONE READER.
+ *
+ * Each reader numbers its own users, so the input is that reader's existing
+ * registration numbers (from the device, plus the roster on screen when it is
+ * the selected reader). Numeric ones count; the next is the highest plus one,
+ * zero padded to six digits or to the widest number already in use, whichever
+ * is wider. Anything that is not a plain number (`USR-...`, blank, undefined)
+ * is ignored rather than breaking the allocation.
+ *
+ * Pure. `HidUserEnrollment.vue` reads the lists and calls this.
+ */
+export function nextRegistration(registrations: readonly unknown[]): string {
+  let max = 0;
+  let width = 6;
+  for (const value of registrations) {
+    const text = String(value ?? "").trim();
+    const match = text.match(/^(\d+)$/);
+    if (!match) continue;
+    max = Math.max(max, Number(match[1]));
+    width = Math.max(width, match[1].length);
+  }
+  return String(max + 1).padStart(width, "0");
+}

package/utils/module-routes.ts

@@ -11,8 +11,10 @@
  * Only prefixes whose page each app gates on exactly one module are listed
  * (checked against every app's own `useLocalPermission` nav gate, 2026-09-11).
  * Shared or ambiguous pages stay out: calendar, keys (gated on `site-settings`),
- * access-mgmt (`site-settings:manage-entry-pass` also opens it), equipment and
- * inventory, service-providers and support tickets.
+ * the Cards and QR Tagging pages under access-mgmt (each app's own
+ * `access-card-mgmt` gate), equipment and inventory, service-providers and
+ * support tickets. The HID pages under access-mgmt ARE listed, one by one,
+ * because each is gated on `hid-mgmt` alone (`useHidAccessPermission`).
  *
  * NEVER MAPPED: the dashboard, settings, members, invitations and roles. A client
  * must always be able to run its own people and roles; the server never denies
@@ -68,6 +70,17 @@ export const MODULE_ROUTES: Readonly<Record<string, string>> = Object.freeze({
   "org-site-pool-schedule-area": "area-mgmt",
   "org-site-pool-schedule-unit": "unit-mgmt",
   "org-site-service-provider-mgmt": "service-provider-mgmt",
+  // HID access management (decision of 2026-10-16): the seven HID pages under
+  // `access-mgmt`, named one by one so the Cards and QR Tagging pages beside
+  // them stay unmapped. `hid-mgmt` is a governed module in core, so a client
+  // that was not given it loses the pages and the drawer group together.
+  "org-site-access-mgmt-hid-readers": "hid-mgmt",
+  "org-site-access-mgmt-administrator": "hid-mgmt",
+  "org-site-access-mgmt-hid-users": "hid-mgmt",
+  "org-site-access-mgmt-hid-qr-code": "hid-mgmt",
+  "org-site-access-mgmt-hid-cards": "hid-mgmt",
+  "org-site-access-mgmt-intercom": "hid-mgmt",
+  "org-site-access-mgmt-access-logs": "hid-mgmt",
   "org-site-online-forms": "online-form-configuration",
   "org-site-nfc": "nfc-patrol",
   "org-site-document-mgmt": "document-mgmt",

package/utils/nav-sections.ts

@@ -77,7 +77,7 @@ export const NAV_SECTIONS: Record<string, string> = {
   "SOA Mgmt": "PROPERTY",
 
   // SECURITY OPERATIONS
-  "HID Face Reader": "SECURITY OPERATIONS",
+  "HID Reader": "SECURITY OPERATIONS",
   "Daily Occurrence Books": "SECURITY OPERATIONS",
   Manpower: "SECURITY OPERATIONS",
   "Virtual Patrol": "SECURITY OPERATIONS",