@7365admin1/layer-common 4.97.0 → 4.97.1-staging.501

package/utils/nfc-patrol-time.ts

@@ -0,0 +1,99 @@
+/**
+ * Times on an NFC patrol log, read the way they were written.
+ *
+ * Logs created since core reads the patrol window on the site's clock carry
+ * `timezone`, and every time on them is a real instant: show it on that clock.
+ *
+ * Older logs have no `timezone`. Their SCHEDULED times - each checkpoint's
+ * window, and the end of one not scanned yet - are the site's wall clock
+ * written as UTC by the API container, so their UTC digits ARE the wall clock.
+ * Scan times were real instants on every log.
+ */
+
+export const DEFAULT_PATROL_TIMEZONE = "Asia/Singapore";
+
+type PatrolCheckpointTimes = {
+  status?: string;
+  startDateTime?: string | Date;
+  endDateTime?: string | Date;
+};
+
+type PatrolLogTimes = {
+  timezone?: string;
+  createdAt?: string | Date;
+  checkPoints?: PatrolCheckpointTimes[];
+};
+
+function toDate(value?: string | Date | null): Date | null {
+  if (!value) return null;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function formatClock(date: Date, timezone: string) {
+  return new Intl.DateTimeFormat("en-GB", {
+    hour: "2-digit",
+    minute: "2-digit",
+    hourCycle: "h23",
+    timeZone: timezone,
+  }).format(date);
+}
+
+/** "HH:mm" of an instant on `timezone`'s clock, or "-". */
+export function clockTime(value: string | Date | null | undefined, timezone: string) {
+  const date = toDate(value);
+  if (!date) return "-";
+  try {
+    return formatClock(date, timezone);
+  } catch {
+    // An unknown zone name throws; the site default is what the server assumes.
+    return formatClock(date, DEFAULT_PATROL_TIMEZONE);
+  }
+}
+
+/** "HH:mm" of a wall clock stored as UTC, or "-". */
+function storedWallClock(value?: string | Date | null) {
+  const date = toDate(value);
+  return date ? date.toISOString().slice(11, 16) : "-";
+}
+
+function isFinished(checkpoint: PatrolCheckpointTimes) {
+  return checkpoint.status === "Completed" || checkpoint.status === "Skipped";
+}
+
+/** The "HH:mm" a report shows for a checkpoint's start and end. */
+export function checkpointClock(
+  log: PatrolLogTimes,
+  checkpoint: PatrolCheckpointTimes,
+  siteTimezone?: string,
+) {
+  const timezone = log.timezone || siteTimezone || DEFAULT_PATROL_TIMEZONE;
+  const scheduled = (value?: string | Date) =>
+    log.timezone ? clockTime(value, timezone) : storedWallClock(value);
+
+  return {
+    start: scheduled(checkpoint.startDateTime),
+    end: isFinished(checkpoint)
+      ? clockTime(checkpoint.endDateTime, timezone)
+      : scheduled(checkpoint.endDateTime),
+  };
+}
+
+/**
+ * When the patrol really ran: from the guard pressing Start Patrolling (the
+ * log is created then, so its `createdAt`) to the last scan or skip. A guard
+ * who starts early in the site's early start allowance shows as early. Both
+ * are real instants on every log.
+ */
+export function actualPatrolSpan(log: PatrolLogTimes): { start?: Date; end?: Date } {
+  const start = toDate(log.createdAt) ?? undefined;
+
+  let end: Date | undefined;
+  for (const checkpoint of log.checkPoints ?? []) {
+    if (!isFinished(checkpoint)) continue;
+    const at = toDate(checkpoint.endDateTime);
+    if (at && (!end || at > end)) end = at;
+  }
+
+  return { start, end };
+}

package/utils/occupancy-role.ts

@@ -0,0 +1,109 @@
+/**
+ * OWNER / OCCUPANT / PERSON IN CHARGE - the three standings a business
+ * tenancy has, and everything the product says about them.
+ *
+ * One list, because three screens read it: the form that asks the question
+ * (`PeopleFormMgmt`), the list and preview that print the answer back, and
+ * the row menu that reassigns it (`people-mgmt`). The values are the ones the
+ * server stores and validates - `OccupancyRoles` in core's `person.model.ts`
+ * - so a value added on one side has to be added on the other.
+ */
+export const OCCUPANCY_ROLE_OPTIONS: TOccupancyRoleOption[] = [
+  {
+    value: "owner",
+    title: "Owner",
+    action: "Assign Owner",
+    prompt: "Assign Owner",
+    description:
+      "The legal titleholder or primary deed owner of the property.",
+  },
+  {
+    value: "occupant",
+    title: "Occupant",
+    action: "Assign Occupant",
+    prompt: "Assign Occupant",
+    description:
+      "The person currently living in, renting, or utilizing the physical unit.",
+  },
+  {
+    value: "person-in-charge",
+    title: "Person in Charge",
+    action: "Assign Person in Charge",
+    prompt: "Assign Person in Charge (PIC)",
+    description:
+      "The designated manager responsible for maintenance, emergencies, and daily operations.",
+  },
+];
+
+/**
+ * The same three, in the order the ROW MENU draws them, which is not the
+ * order the form's radio does. Derived rather than re-typed so the wording
+ * cannot drift between the two.
+ */
+export const OCCUPANCY_ROLE_ACTIONS: TOccupancyRoleOption[] = (
+  ["person-in-charge", "owner", "occupant"] as TOccupancyRole[]
+).map(
+  (value) =>
+    OCCUPANCY_ROLE_OPTIONS.find(
+      (option) => option.value === value,
+    ) as TOccupancyRoleOption,
+);
+
+/**
+ * The label for a stored role, or "" for a person who was never asked - which
+ * is everyone on a residential site and everyone saved before the question
+ * existed. Callers decide what to print instead; nobody should print a raw
+ * `person-in-charge` at a user.
+ */
+export function occupancyRoleLabel(role?: string | null): string {
+  return (
+    OCCUPANCY_ROLE_OPTIONS.find((option) => option.value === role)?.title ?? ""
+  );
+}
+
+/**
+ * Does this person hold OWNER at their unit?
+ *
+ * The role when there is one, `isOwner` when there is not - the same test the
+ * server applies (`holdsUnitOwner` in core's `unit-owner.util.ts`). A person
+ * recorded before the role existed carries only the flag, and the people list
+ * already prints them as "Owner".
+ */
+export function holdsUnitOwner(person?: {
+  occupancyRole?: string | null;
+  isOwner?: boolean;
+}): boolean {
+  if (!person) return false;
+
+  if (person.occupancyRole) return person.occupancyRole === "owner";
+
+  return person.isOwner === true;
+}
+
+/**
+ * MUST THIS PERSON HAND THE UNIT OVER BEFORE THEY CAN BE DEACTIVATED?
+ *
+ * The owner of a unit does not leave while they still own it - the standing
+ * moves to another tenant at the same block, level and unit first.
+ *
+ * Keyed to the ROLE and never to `isOwner`, exactly as the server keys it
+ * (`mustHandOverBeforeDeactivating` in core): the flag is on every resident in
+ * the estate, and no residential screen can change it, so a rule keyed to it
+ * would trap records that can never satisfy it.
+ */
+export function mustHandOverBeforeDeactivating(person?: {
+  occupancyRole?: string | null;
+}): boolean {
+  return person?.occupancyRole === "owner";
+}
+
+/**
+ * Why a deactivation was held back. The SERVER carries the enforcing copy of
+ * this rule and of these words (core `unit-owner.util.ts`); this one exists so
+ * the console can say it before the round trip rather than after.
+ */
+export function ownerHandoverRequiredMessage(name?: string): string {
+  const who = name?.trim() ? `"${name.trim()}"` : "This person";
+
+  return `${who} is the owner of this unit. Assign the owner role to another tenant at the same block, level and unit before deactivating them.`;
+}

package/utils/service-type.ts

@@ -0,0 +1,30 @@
+/**
+ * A SERVICE PROVIDER'S LINE OF BUSINESS, AS PEOPLE NAME IT.
+ *
+ * `/api/service-providers` returns the service CODE (`mechanical_electrical_services`),
+ * which is a database value, not something to show an operator. This is the same
+ * mapping `API-core src/utils/converter.ts spmServiceNewToOld` applies — copied
+ * rather than imported, because that is a server package this layer does not
+ * depend on.
+ *
+ * NOT the same labels as `utils/module-applications.ts APPLICATIONS`. Those name
+ * the seven role-permission applications ("Mechanical & electrical", "Pest
+ * control") and are keyed `mechanical-electrical`, not `*_services`. These are
+ * the shorter names the service-provider screens use ("M&E", "Pest Control").
+ *
+ * An unknown code is returned untouched: a new service type shows as its raw
+ * code, which is visibly odd, rather than vanishing from the row.
+ */
+const SERVICE_TYPE_LABELS: Readonly<Record<string, string>> = Object.freeze({
+  security_agency: "Security",
+  cleaning_services: "Cleaning",
+  pool_maintenance_services: "Pool Maintenance",
+  pest_control_services: "Pest Control",
+  landscaping_services: "Landscape",
+  mechanical_electrical_services: "Mechanical & Electrical",
+});
+
+export function serviceTypeLabel(service: string | null | undefined): string {
+  const code = String(service ?? "");
+  return SERVICE_TYPE_LABELS[code] ?? code;
+}