@7365admin1/layer-common 4.90.1 → 4.90.2-staging.484

package/pages/[org]/[site]/access-mgmt/hid-cards/index.vue

@@ -5,7 +5,7 @@
       :org="orgId"
       message="Enable HID as a service for this site before managing physical HID cards."
     >
-      <HidUserEnrollment :site="siteId" card-management />
+      <HidUserEnrollment :site="siteId" :org="orgId" card-management />
     </HidEnabledGate>
   </v-container>
 </template>

package/pages/[org]/[site]/access-mgmt/hid-qr-code/index.vue

@@ -0,0 +1,23 @@
+<template>
+  <v-container fluid>
+    <HidEnabledGate
+      :site="siteId"
+      :org="orgId"
+      message="Enable HID as a service for this site before generating a QR code."
+    >
+      <HidProfileQrCode :site="siteId" />
+    </HidEnabledGate>
+  </v-container>
+</template>
+
+<script setup lang="ts">
+definePageMeta({
+  layout: "default",
+  middleware: ["01-auth", "02-org"],
+  memberOnly: true,
+});
+
+const route = useRoute();
+const siteId = computed(() => String(route.params.site ?? ""));
+const orgId = computed(() => String(route.params.org ?? ""));
+</script>

package/pages/[org]/[site]/access-mgmt/hid-readers/index.vue

@@ -5,7 +5,7 @@
       :org="orgId"
       message="Enable HID as a service for this site before managing HID readers."
     >
-      <HidReaderManagement :site="siteId" />
+      <HidReaderManagement :site="siteId" :org="orgId" />
     </HidEnabledGate>
   </v-container>
 </template>

package/types/document.d.ts

@@ -3,4 +3,18 @@ declare type TDocument = {
   name: string;
   attachment: string;
   type: string;
+  /**
+   * Set at upload or renewal, absent when the document never expires.
+   *
+   * An ISO instant on the way out of the API and a `YYYY-MM-DD` string on the
+   * way back in, which is what `InputDatePicker` binds to - hence the loose
+   * type rather than `string`.
+   */
+  expiryDate?: string | Date | null;
+  remarks?: string;
+  size?: number;
+  parentId?: string | null;
+  createdAt?: string | Date;
+  updatedAt?: string | Date;
+  status?: string;
 };

package/types/facility.d.ts

@@ -73,6 +73,10 @@ declare type TFacility = {
   hourInterval?: number;
   isBookingFeeEnabled: boolean;
   isGuestEnabled: boolean;
+  /** Residents may complete this facility's checklist themselves. */
+  isResidentChecklistEnabled?: boolean;
+  /** Security may complete it. Mutually exclusive with the above. */
+  isSecurityChecklistEnabled?: boolean;
   bookingAmount: number | null;
   peakBookingFeeAmount?: number | null;
   bookingFeeGuestAmount?: number | null;

package/types/member.d.ts

@@ -10,6 +10,10 @@ declare type TMember = {
   customerOrgId?: string;
   customerSiteId?: string;
   status?: string;
+  email?: string;
+  /** The building unit this member manages (a unit's Management tab). */
+  unit?: string | null;
+  unitName?: string;
   createdAt?: string;
   updatedAt?: string;
   deletedAt?: string;

package/types/people.d.ts

@@ -22,11 +22,38 @@ declare type TPeople = {
   email?: string;
   files?: { name: string, id: string }[];
   isOwner?: boolean;
+  /**
+   * Owner / occupant / person-in-charge, as the BUSINESS people form asks it.
+   * Absent on everyone else - `isOwner` is still the flag that decides unit
+   * ownership, and the server derives it from this when it is sent. See
+   * `OccupancyRoles` in core's `person.model.ts`.
+   */
+  occupancyRole?: TOccupancyRole;
+  // Link to this person's `users` row. Empty for the person types that carry
+  // no login, and empty for a resident whose account was never written.
+  user?: string;
+};
+
+declare type TOccupancyRole = "owner" | "occupant" | "person-in-charge";
+
+/** One standing and everything the product says about it. See `utils/occupancy-role.ts`. */
+declare type TOccupancyRoleOption = {
+  value: TOccupancyRole;
+  /** The label a stored role is printed with. */
+  title: string;
+  /** The row menu's wording. */
+  action: string;
+  /** The confirmation's heading and its sentence. */
+  prompt: string;
+  description: string;
 };
 
 declare type TPlateNumber = { plateNumber: string, recNo?: string, _id?: string, status: TVehicleStatus, type: TVehicleType, anprCameras?: TVehicleAnprCamera[] };
 
 
-declare type TPeoplePayload = Pick<TGuest, "name" | "block" | "level" | "unit" | "unitName" | "contact" | "plateNumber" | "nric" | "contact" | "remarks" | "org" | "site" | "start" | "end" | "type" | "isOwner"> & { status?: string }
+// `""` is the FORM's "nothing picked yet" - it is stripped from the payload
+// before it is sent, because absence is what the server reads as "never
+// asked". See `PeopleFormMgmt.vue`.
+declare type TPeoplePayload = Pick<TGuest, "name" | "block" | "level" | "unit" | "unitName" | "contact" | "plateNumber" | "nric" | "contact" | "remarks" | "org" | "site" | "start" | "end" | "type" | "isOwner"> & { status?: string; user?: string; occupancyRole?: TOccupancyRole | "" }
 
 declare type TPeopleType = "guest" | "resident" | "tenant"

package/types/service-provider.d.ts

@@ -7,6 +7,11 @@ declare type TServiceProvider = {
   serviceProviderOrgId: string;
   type: string;
   nature: string;
+  status?: string;
+  email?: string;
+  /** The building unit this provider serves (a unit's Management tab). */
+  unit?: string | null;
+  unitName?: string;
 };
 
 declare type TServiceProviderName = {

package/types/site.d.ts

@@ -5,7 +5,10 @@ declare type THidQrCodeFormat = "0" | "1" | "2";
 declare type THidPermissionCategory =
   | "resident"
   | "property_management"
-  | "service_provider";
+  /** A provider COMPANY - granting one admits every active member of that org. */
+  | "service_provider"
+  /** ONE PERSON from a provider company, by their membership at this site. */
+  | "service_provider_member";
 
 declare type THidPermissionAssignment = {
   subjectId: string;
@@ -27,7 +30,10 @@ declare type THidSitePermissions = {
   counts: {
     resident: number;
     propertyManagement: number;
+    /** Provider COMPANIES granted. */
     serviceProvider: number;
+    /** Named provider people granted. Counted apart from the companies. */
+    serviceProviderMember: number;
     intercom: number;
   };
 };

package/utils/hid-enrolment-subject.ts

@@ -0,0 +1,344 @@
+/**
+ * WHO A HID ENROLMENT IS FOR — the pure decisions behind the subject picker.
+ *
+ * `HidUserEnrollment.vue` can enrol a resident or a staff member. The write path
+ * always carried both (`subjectLink` maps them onto `person` or `member`); what
+ * was missing was a way to choose. These are the parts of that choice worth
+ * testing on their own, kept here because a `.vue` component has no test harness
+ * in this repo.
+ */
+
+/**
+ * What the ENROLLING dropdown offers. Three of these four are the server's own
+ * permission categories; `service_provider_staff` is this screen's own value
+ * and deliberately not one of them - see `subjectLinkOf`.
+ */
+export type HidEnrolmentSubject =
+  | "resident"
+  | "property_management"
+  | "service_provider_staff";
+
+/**
+ * The dropdown's options, in the order they are drawn.
+ *
+ * `title`/`value` because `AppSelect` takes that shape.
+ */
+export const HID_ENROLMENT_SUBJECTS: ReadonlyArray<{
+  title: string;
+  value: HidEnrolmentSubject;
+}> = [
+  { title: "Resident", value: "resident" },
+  { title: "Member", value: "property_management" },
+  { title: "Service provider", value: "service_provider_staff" },
+];
+
+/**
+ * What an EDIT calls the subject it is already attached to.
+ *
+ * Wider than the dropdown on purpose. An identity's category cannot change after
+ * it is created, so an edit states it rather than offering it — and the records
+ * in the wild include `service_provider`, which the dropdown does not offer yet
+ * but `openEdit` does resolve. Falling back to the first option would label a
+ * contractor "Resident", which is worse than saying nothing useful.
+ */
+export function subjectCategoryLabel(category: unknown): string {
+  const labels: Record<string, string> = {
+    resident: "Resident",
+    property_management: "Member",
+    // The dropdown's own value: ONE PERSON from a provider company.
+    service_provider_staff: "Service provider",
+    // The server's category, which names a COMPANY. Records in the wild carry
+    // it, and an edit must not call such a row a resident.
+    service_provider: "Service provider",
+    visitor: "Visitor",
+  };
+  return labels[String(category ?? "")] ?? "Unknown";
+}
+
+/**
+ * One page of `GET /api/members`, read defensively.
+ *
+ * `paginate` puts `{ items, pages }` at the root, but `items` sits under `data`
+ * on some of this product's endpoints, so both are read — the same allowance
+ * `readCandidatePage` makes. A response that carries neither is an empty page
+ * rather than a thrown error: an empty staff picker with a placeholder beats a
+ * broken dialog.
+ */
+export function readMemberPage(response: unknown): {
+  items: Record<string, unknown>[];
+  pages: number;
+  total: number;
+} {
+  const source = (response && typeof response === "object" ? response : {}) as Record<string, unknown>;
+  const nested = (source.data && typeof source.data === "object" ? source.data : {}) as Record<string, unknown>;
+  const raw = Array.isArray(source.items)
+    ? source.items
+    : Array.isArray(nested.items)
+      ? nested.items
+      : [];
+  const pages = Number(source.pages ?? nested.pages ?? 1);
+  const items = raw.filter((row): row is Record<string, unknown> => Boolean(row) && typeof row === "object");
+  /*
+   * `total` drives "showing 10 of 23" and the Load more button. It falls back to
+   * the page's own length, not to zero, so a response without it simply reads as
+   * "this is everything" — a missing count must never make the button offer a
+   * page that is not there.
+   */
+  const total = Number(source.total ?? nested.total ?? items.length);
+  return {
+    items,
+    pages: Number.isFinite(pages) && pages > 0 ? Math.floor(pages) : 1,
+    total: Number.isFinite(total) && total >= 0 ? Math.floor(total) : items.length,
+  };
+}
+
+/**
+ * Can this member actually be enrolled?
+ *
+ * Reader access is bound by USER id — `resolvePermissionUserBindings` in
+ * `iservice365-core` drops every subject without one — so a member with no app
+ * account cannot be given access and is not a candidate. The id arrives as a
+ * string from JSON but may be an object if a caller passes a raw document, so
+ * both are read rather than trusting the shape.
+ */
+export function memberHasAccount(row: Record<string, unknown> | null | undefined): boolean {
+  const user = row?.user;
+  if (!user) return false;
+  if (typeof user === "object") {
+    const id = (user as { _id?: unknown; toString?: () => string })._id ?? user;
+    return Boolean(String(id ?? "").trim());
+  }
+  return Boolean(String(user).trim());
+}
+
+/**
+ * How a member reads in the picker: their name, and their role beneath it.
+ *
+ * THE ACCOUNT'S NAME FIRST, then the membership's. The two diverge — a
+ * membership is created with whatever name was typed at invite time, and the
+ * person may have set their own on the account since — and the account name is
+ * the one they are known by. `userName` comes from the members endpoint's own
+ * lookup into `users`; a member with no account has none, but such a row is not
+ * a candidate anyway (`memberHasAccount`).
+ *
+ * Every step falls back, because a row with no name at all still has to be
+ * selectable rather than blank, or it cannot be told apart from the next one.
+ */
+export function memberCandidateOf(row: Record<string, unknown>): {
+  subjectId: string;
+  name: string;
+  subtitle: string;
+} {
+  const text = (value: unknown) => String(value ?? "").trim();
+  return {
+    subjectId: text(row._id),
+    name: text(row.userName) || text(row.name) || text(row.email) || "Member",
+    subtitle: text(row.roleName) || text(row.email) || "",
+  };
+}
+
+/**
+ * Why somebody the operator can see elsewhere is not in this list.
+ *
+ * Left unexplained, an absence reads as a broken screen — the same reason the
+ * resident cascade carries `unitResidentNote`. Returns "" when there is nothing
+ * to say, so the caller can render it unconditionally.
+ */
+export function hiddenSubjectNote(count: number, noun: "resident" | "member"): string {
+  if (!Number.isFinite(count) || count <= 0) return "";
+  const whole = Math.floor(count);
+  const subject = whole === 1 ? `1 ${noun}` : `${whole} ${noun}s`;
+  const verb = whole === 1 ? "is" : "are";
+  const holder = whole === 1 ? "that person has" : "they have";
+  return `${subject} at this site ${verb} not listed:`
+    + ` HID enrollment needs an app account, and ${holder} none yet.`;
+}
+
+/* ── THE LINK THAT REACHES THE DEVICE ──────────────────────────────────── */
+
+/**
+ * WHICH SUBJECT FIELD AN ENROLMENT WRITES, and what the identity is called.
+ *
+ * This is the one decision in the dialog that changes who a door lets in, so it
+ * lives here with tests rather than inline in the template's script.
+ *
+ * `service_provider_staff` links through `member`, NOT `serviceProvider`, and
+ * that is the whole design:
+ *
+ * - `serviceProvider` names a `site.service-providers` row, which is a COMPANY.
+ *   `resolvePermissionUserBindings` expands one into every active member of
+ *   that organisation with NO site filter, so granting it puts a 200-person
+ *   firm on a door that eight of them attend.
+ * - A provider employee's membership lives in `members` with `siteId` set to
+ *   this site - `members` carries a unique index on `{org, siteId, user, type}`,
+ *   so it cannot exist there without one. That makes the person site-scoped by
+ *   construction, which is the whole point.
+ *
+ * The identity `type` is `"contractor"` rather than `"staff"`, and it is load
+ * bearing on the server as well as here: core's `permissionSubjectOfIdentity`
+ * reads it to tell a contractor's `member` link from a property-management one,
+ * and files the grant under `service_provider_member` or `property_management`
+ * accordingly. It is also what the Access Permissions tabs filter on.
+ *
+ * An earlier version filed provider staff under `property_management`, since that
+ * category's subject list already accepts these rows. It worked for access and
+ * failed for identity: `permissionIdentityType` derives the identity's type from
+ * the category, so every contractor came back as `staff` - and because the
+ * reconcile rewrites the identity it finds, the `"contractor"` written here was
+ * overwritten seconds later.
+ *
+ * An empty `subjectId` returns `{}` ON PURPOSE. Sending `person: ""` is not
+ * "leave this alone", it is "clear it": the server reads an empty string as the
+ * link being removed and then refuses the write for having no subject at all.
+ */
+export function subjectLinkOf(
+  category: unknown,
+  subjectId: unknown,
+): {
+  person?: string;
+  member?: string;
+  serviceProvider?: string;
+  type?: "resident" | "staff" | "contractor";
+} {
+  const id = String(subjectId ?? "").trim();
+  if (!id) return {};
+  const of = (
+    field: "person" | "member" | "serviceProvider",
+    type: "resident" | "staff" | "contractor",
+  ) => ({
+    person: field === "person" ? id : "",
+    member: field === "member" ? id : "",
+    serviceProvider: field === "serviceProvider" ? id : "",
+    type,
+  });
+  switch (String(category ?? "")) {
+    case "resident":
+      return of("person", "resident");
+    case "service_provider_staff":
+      return of("member", "contractor");
+    case "service_provider":
+      return of("serviceProvider", "contractor");
+    default:
+      return of("member", "staff");
+  }
+}
+
+/**
+ * Which PERMISSION CATEGORY an enrolment's access grant is stored under.
+ *
+ * Mirrors `permissionSubjectOfIdentity` in core, which reads the stored links
+ * rather than this dropdown: a `member` link resolves to `property_management`
+ * whatever the identity's `type` says. Provider staff therefore share the staff
+ * category, which is correct - they are validated against the same subject list
+ * - and the identity `type` is what tells them apart on screen.
+ */
+export function permissionCategoryOf(category: unknown): string {
+  const value = String(category ?? "");
+  if (value === "resident") return "resident";
+  if (value === "service_provider") return "service_provider";
+  if (value === "service_provider_staff") return "service_provider_member";
+  return "property_management";
+}
+
+/* ── PROVIDER STAFF AS PICKER ROWS ─────────────────────────────────────── */
+
+/**
+ * Can this provider employee be enrolled?
+ *
+ * Two conditions, and both have to be checked here rather than trusted from the
+ * list. An app account, because reader access is bound by user id
+ * (`memberHasAccount`). And an ACTIVE membership: `getProviderMembersBySite`
+ * returns everyone who is not deleted, so a suspended person is in the list the
+ * Members screen draws - marked, deliberately, so the property manager can see
+ * them. Offering a suspended person a door is a different matter.
+ */
+export function providerCanEnrol(
+  row: Record<string, unknown> | null | undefined,
+): boolean {
+  if (!memberHasAccount(row)) return false;
+  return String(row?.status ?? "").trim() === "active";
+}
+
+/**
+ * How a provider employee reads in the picker: their name, their company and
+ * the service beneath it.
+ *
+ * The company comes FIRST in the subtitle. Two contractors with the same first
+ * name are common, and which firm somebody belongs to is what the property
+ * manager actually recognises them by - the service type alone ("Security")
+ * describes half the list.
+ */
+export function providerCandidateOf(row: Record<string, unknown>): {
+  subjectId: string;
+  name: string;
+  subtitle: string;
+} {
+  const text = (value: unknown) => String(value ?? "").trim();
+  const parts = [text(row.company), text(row.typeLabel)].filter(Boolean);
+  return {
+    subjectId: text(row._id),
+    name: text(row.name) || text(row.email) || "Service provider",
+    subtitle: parts.join(" · ") || text(row.role) || text(row.email) || "",
+  };
+}
+
+/**
+ * Does this list tell us who has an app account?
+ *
+ * `GET /api/service-providers/site-members` only began returning `user` in core
+ * 3.130; before that the service layer dropped it even though the repository
+ * projected it. Frontend and backend deploy separately, so this screen can run
+ * against either. Asked of the ROWS rather than of a version number: the key is
+ * present on every row or on none.
+ *
+ * It matters because the answer flips a filter from "cannot be bound to a door"
+ * to "unknown", and a screen that silently reports NOBODY can be enrolled is
+ * worse than one that offers somebody the server then refuses by name.
+ */
+export function providerAccountsKnown(
+  rows: ReadonlyArray<Record<string, unknown>>,
+): boolean {
+  return rows.some((row) => Boolean(row) && typeof row === "object" && "user" in row);
+}
+
+/**
+ * Who may be offered a door, from whatever the endpoint returned.
+ *
+ * With accounts known, both conditions apply (`providerCanEnrol`). Without them,
+ * active membership is all that can be checked here — the server still refuses
+ * anyone it cannot bind, with a message naming them, which is a better failure
+ * than an empty picker.
+ */
+export function providerEnrollableRows<T extends Record<string, unknown>>(
+  rows: ReadonlyArray<T>,
+): T[] {
+  const known = providerAccountsKnown(rows);
+  return rows.filter((row) =>
+    known ? providerCanEnrol(row) : String(row?.status ?? "").trim() === "active",
+  );
+}
+
+/* ── THE SERVICE FILTER'S "ALL" ────────────────────────────────────────── */
+
+/**
+ * WHY "ALL SERVICES" CANNOT BE THE EMPTY STRING HERE.
+ *
+ * `filterProviderMembers` reads an empty `type` as "do not filter", and the
+ * Members screen's own filter uses `value: ""` for All services - but that screen
+ * draws a Vuetify `v-select`, which renders an empty value perfectly well.
+ *
+ * `AppSelect` does not. Its `hasSingleValue` is false for `""`, so the field
+ * falls back to the placeholder, draws in the placeholder's grey, and the option
+ * is never marked as the chosen one in the menu. The filter worked; it just
+ * looked like nothing was selected and like only the real services existed.
+ *
+ * So the option carries a real value here and is translated on the way to the
+ * filter. Changing `AppSelect` instead would touch every one of its callers.
+ */
+export const HID_ALL_SERVICES = "all";
+
+/** The `type` to filter by: "" for All services, the service code otherwise. */
+export function serviceFilterOf(selected: unknown): string {
+  const value = String(selected ?? "").trim();
+  return value === HID_ALL_SERVICES ? "" : value;
+}