@7365admin1/layer-common 4.108.0 → 4.109.1

package/utils/nfc-patrol-report.ts

@@ -8,6 +8,22 @@
  * client. The page walk and the month mapping live here so they have tests.
  */
 
+import type {
+  NFCPatrolActivity,
+  NFCPatrolMonthlyReport,
+  NFCPatrolReport,
+  NFCPatrolReportSummaryRow,
+  NFCPatrolRunDetail,
+  NFCPatrolSummaryReport,
+} from "../types/nfc-patrol-report.ts";
+import type { CsvSection } from "./report-export.ts";
+import {
+  actualPatrolSpan,
+  checkpointClock,
+  clockTime,
+  DEFAULT_PATROL_TIMEZONE,
+} from "./nfc-patrol-time.ts";
+
 /** One page of the patrol-log endpoint's reply. */
 export type TPatrolLogPage = {
   items?: Record<string, any>[];
@@ -62,6 +78,11 @@ export async function collectAllPages(
   return items;
 }
 
+/** The month (0-11) a patrol log counts under; NaN for a date that is not one. */
+export function monthIndexOf(log: Record<string, any>) {
+  return new Date(log?.date).getMonth();
+}
+
 /**
  * One row per calendar month. A month with no checkpoint due keeps its zero
  * counts - zero checkpoints really were checked - but reports `null` for both
@@ -80,7 +101,7 @@ export function mapLogsToMonthlyRows(
   }));
 
   for (const log of logs) {
-    const monthIndex = new Date(log?.date).getMonth();
+    const monthIndex = monthIndexOf(log);
     if (Number.isNaN(monthIndex)) continue;
 
     for (const checkpoint of log?.checkPoints ?? []) {
@@ -99,3 +120,220 @@ export function mapLogsToMonthlyRows(
 
   return rows;
 }
+
+function formatDuration(totalMinutes: number) {
+  if (totalMinutes < 60) return `${totalMinutes} mins`;
+
+  const hrs = Math.floor(totalMinutes / 60);
+  const mins = totalMinutes % 60;
+
+  if (mins === 0) return `${hrs} hrs`;
+  return `${hrs} hrs ${mins} mins`;
+}
+
+function diffMinutes(startIso?: string | Date, endIso?: string | Date) {
+  if (!startIso || !endIso) return "-";
+  const totalMinutes = Math.max(
+    0,
+    Math.round((new Date(endIso).getTime() - new Date(startIso).getTime()) / 60000),
+  );
+  return formatDuration(totalMinutes);
+}
+
+/**
+ * One patrol run as a report shows it: the schedule-vs-actual pair and a row
+ * per checkpoint. The Patrol tab draws one run; the daily summary keeps one per
+ * row for its route details dialog.
+ */
+export function mapLogToPatrolRun(
+  log: Record<string, any>,
+  siteTimezone?: string,
+): NFCPatrolRunDetail {
+  const checkpoints: Record<string, any>[] = log.checkPoints ?? [];
+  const timezone = log.timezone || siteTimezone || DEFAULT_PATROL_TIMEZONE;
+  const actual = actualPatrolSpan(log);
+
+  const activities: NFCPatrolActivity[] = checkpoints.map((cp) => {
+    const clock = checkpointClock(log, cp, siteTimezone);
+    return {
+      id: cp.nfcTag_id,
+      checkpoint: cp.nfcTag_name,
+      guardName: log.sign?.guardName,
+      guardSignatureFileId: log.sign?.guardSignatureFileId,
+      startTime: clock.start,
+      endTime: clock.end,
+      status: cp.status,
+      remarks: cp.skippedRemarks && cp.skippedRemarks !== "N/A" ? cp.skippedRemarks : undefined,
+      skippedPhotoFileId: cp.skippedPhotoFileId ? String(cp.skippedPhotoFileId) : undefined,
+    };
+  });
+
+  return {
+    routeSummary: {
+      routeName: log.route?.name,
+      tolerance: Number(log.route?.tolerance) || 0,
+      schedule: {
+        start: log.route?.startTime,
+        end: log.route?.endTime,
+        totalTime: diffMinutes(log.startDateTime, log.endDateTime),
+      },
+      actual: {
+        start: clockTime(actual.start, timezone),
+        end: clockTime(actual.end, timezone),
+        totalTime: diffMinutes(actual.start, actual.end),
+      },
+    },
+    activities,
+  };
+}
+
+/**
+ * One patrol run as a summary row: who patrolled, what was checked and
+ * missed, and the run itself for the route details dialog. `index` numbers
+ * the row ("1. WH01 Patrol Route").
+ */
+export function mapLogToSummaryRow(
+  log: Record<string, any>,
+  index: number,
+  siteTimezone?: string,
+): NFCPatrolReportSummaryRow {
+  const checkpoints: Record<string, any>[] = log.checkPoints ?? [];
+  const checked = checkpoints.filter((cp) => cp.status === "Completed").length;
+  const missed = checkpoints.filter((cp) => cp.status === "Skipped").length;
+
+  return {
+    id: log._id,
+    date: log.date,
+    routeName: `${index + 1}. ${log.route?.name ?? "-"}`,
+    securityCheckSchedule: log.route?.startTime ?? "-",
+    guardName: log.sign?.guardName,
+    guardSignatureFileId: log.sign?.guardSignatureFileId,
+    checked,
+    missed,
+    status: missed === 0 ? "Completed" : "Incomplete",
+    detail: mapLogToPatrolRun(log, siteTimezone),
+  };
+}
+
+/**
+ * The patrol runs of one month of the yearly report, in the order they ran -
+ * by day, then by scheduled start. Counted under the same month as the yearly
+ * table counts them (`monthIndexOf`), so a month's list adds up to its row.
+ */
+export function mapLogsToMonthRuns(
+  logs: Record<string, any>[],
+  monthIndex: number,
+  siteTimezone?: string,
+): NFCPatrolReportSummaryRow[] {
+  return logs
+    .filter((log) => monthIndexOf(log) === monthIndex)
+    .sort(
+      (a, b) =>
+        String(a.date).localeCompare(String(b.date)) ||
+        String(a.route?.startTime ?? "").localeCompare(String(b.route?.startTime ?? "")),
+    )
+    .map((log, index) => mapLogToSummaryRow(log, index, siteTimezone));
+}
+
+/** A file's URL, or "" when there is none. */
+type FileUrl = (id: string) => string;
+const urlOf = (fileUrl: FileUrl, id?: string) => (id ? fileUrl(id) : "");
+const isSkipped = (activity: NFCPatrolActivity) => activity.status === "Skipped";
+
+/**
+ * The Patrol report's CSV: schedule against actual, then every checkpoint -
+ * a skipped one with its remarks and the link to its photo on its own row.
+ */
+export function patrolReportCsv(report: NFCPatrolReport, fileUrl: FileUrl): CsvSection[] {
+  const sections: CsvSection[] = [];
+  const summary = report.routeSummary;
+
+  if (summary) {
+    sections.push({
+      title: `Patrol Route Summary: ${summary.routeName} (tolerance ${summary.tolerance} mins)`,
+      header: ["Time", "Start", "End", "Total time"],
+      rows: [
+        ["Schedule", summary.schedule.start, summary.schedule.end, summary.schedule.totalTime],
+        ["Actual", summary.actual.start, summary.actual.end, summary.actual.totalTime],
+      ],
+    });
+  }
+
+  sections.push({
+    title: "Patrol Activity",
+    header: ["Checkpoint", "Security Personnel", "Signature", "Start", "End", "Status", "Skip Remarks", "Skip Photo"],
+    rows: report.activities.map((activity) => [
+      activity.checkpoint,
+      activity.guardName ?? "",
+      urlOf(fileUrl, activity.guardSignatureFileId),
+      activity.startTime,
+      activity.endTime,
+      activity.status,
+      isSkipped(activity) ? activity.remarks ?? "" : "",
+      urlOf(fileUrl, activity.skippedPhotoFileId),
+    ]),
+  });
+
+  return sections;
+}
+
+/**
+ * The Daily report's CSV: one row per patrol run, then one row per skipped
+ * checkpoint naming the run it belongs to - a day of many runs stays sorted
+ * by run, and filters by run, in a spreadsheet.
+ */
+export function dailyReportCsv(report: NFCPatrolSummaryReport, fileUrl: FileUrl): CsvSection[] {
+  const sections: CsvSection[] = [
+    {
+      title: report.title,
+      header: ["Patrol Route Name", "Security Check Schedule", "Security Personnel", "Signature", "Checked", "Missed", "Status"],
+      rows: report.rows.map((row) => [
+        row.routeName,
+        row.securityCheckSchedule,
+        row.guardName ?? "",
+        urlOf(fileUrl, row.guardSignatureFileId),
+        String(row.checked),
+        String(row.missed),
+        row.status,
+      ]),
+    },
+  ];
+
+  const skips = report.rows.flatMap((row) =>
+    (row.detail?.activities ?? []).filter(isSkipped).map((activity) => [
+      row.routeName,
+      row.securityCheckSchedule,
+      activity.checkpoint,
+      activity.endTime,
+      activity.remarks ?? "",
+      urlOf(fileUrl, activity.skippedPhotoFileId),
+    ]),
+  );
+  if (skips.length) {
+    sections.push({
+      title: "Skipped Checkpoints",
+      header: ["Patrol Route Name", "Security Check Schedule", "Checkpoint", "Skipped At", "Skip Remarks", "Skip Photo"],
+      rows: skips,
+    });
+  }
+
+  return sections;
+}
+
+/** The Monthly report's CSV: the year's table as the screen shows it. */
+export function monthlyReportCsv(report: NFCPatrolMonthlyReport): CsvSection[] {
+  const percent = (value: number | null) => (value === null ? "-" : `${value}%`);
+  return [
+    {
+      title: report.title,
+      header: ["Month", "Checked", "% Checked", "Missed", "% Missed"],
+      rows: report.rows.map((row) => [
+        row.month,
+        String(row.checked),
+        percent(row.checkedPercentage),
+        String(row.missed),
+        percent(row.missedPercentage),
+      ]),
+    },
+  ];
+}

package/utils/nfc-patrol-schedule.ts

@@ -0,0 +1,73 @@
+/**
+ * A patrol route's schedule as a person reads it.
+ *
+ * The routes list printed its check windows as one comma-joined string in the
+ * order they were typed ("09:02-16:20, 09:01-14:40, 10:01-18:40, ...") and its
+ * days the same way ("Mon, Wed, Fri, Tue, Thu, Sat"). Here the windows come
+ * earliest first and say when one ends the next day, and the days come Monday
+ * first with a run of them written as a range.
+ */
+
+/** One check window: when it opens, when it closes, and whether that is tomorrow. */
+export type RouteWindow = { start: string; end: string; nextDay: boolean };
+
+function toMinutes(clock: string) {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(clock ?? "");
+  return match ? Number(match[1]) * 60 + Number(match[2]) : null;
+}
+
+function toClock(minutes: number) {
+  const m = ((minutes % 1440) + 1440) % 1440;
+  return `${String(Math.floor(m / 60)).padStart(2, "0")}:${String(m % 60).padStart(2, "0")}`;
+}
+
+/**
+ * Each start time's window - start to start + tolerance, as the route form
+ * draws it - earliest first. A start that is not a time is kept as written,
+ * with no end, rather than dropped.
+ */
+export function routeWindows(startTimes: string[] = [], tolerance: number | string = 0): RouteWindow[] {
+  const minutes = Number(tolerance) || 0;
+  return startTimes
+    .map((start) => {
+      const from = toMinutes(start);
+      if (from === null) return { start, end: "", nextDay: false };
+      return { start: toClock(from), end: toClock(from + minutes), nextDay: from + minutes >= 1440 };
+    })
+    .sort((a, b) => a.start.localeCompare(b.start));
+}
+
+/** The window as plain text, for a tooltip or a screen reader: "23:30 – 01:00 (next day)". */
+export function routeWindowLabel(window: RouteWindow) {
+  return window.end ? `${window.start} – ${window.end}${window.nextDay ? " (next day)" : ""}` : window.start;
+}
+
+const DAY_NAMES = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const MONDAY_FIRST = [1, 2, 3, 4, 5, 6, 0];
+
+/**
+ * The days a route runs, Monday first: "Every day", a run of three or more
+ * as a range ("Mon – Fri"), anything else listed ("Mon, Wed, Sat").
+ * `days` are 0 (Sunday) to 6, as the route stores them.
+ */
+export function formatRouteDays(days: number[] = []) {
+  const on = new Set(days.filter((day) => Number.isInteger(day) && day >= 0 && day <= 6));
+  if (on.size === 0) return "";
+  if (on.size === 7) return "Every day";
+
+  const ordered = MONDAY_FIRST.filter((day) => on.has(day));
+  const parts: string[] = [];
+  for (let i = 0; i < ordered.length; ) {
+    let j = i;
+    while (
+      j + 1 < ordered.length &&
+      MONDAY_FIRST.indexOf(ordered[j + 1]) === MONDAY_FIRST.indexOf(ordered[j]) + 1
+    ) {
+      j++;
+    }
+    if (j - i >= 2) parts.push(`${DAY_NAMES[ordered[i]]} – ${DAY_NAMES[ordered[j]]}`);
+    else for (let k = i; k <= j; k++) parts.push(DAY_NAMES[ordered[k]]);
+    i = j + 1;
+  }
+  return parts.join(", ");
+}

package/utils/report-export.ts

@@ -0,0 +1,120 @@
+/**
+ * What a report's PDF and CSV exports share: page planning for the PDF, the
+ * CSV file itself, and the dates and file names both are labelled with.
+ *
+ * Page planning for a report PDF.
+ *
+ * The report is drawn once, as one tall image, and laid onto A4 pages. It
+ * used to be cut every page-height wherever that fell - through a table row,
+ * through a photo - so a row's top half ended one page and its bottom half
+ * started the next. Here each page ends at the last place it can end cleanly
+ * (the bottom of a row, a photo or a section) and a page that carries on
+ * inside a table repeats that table's header row.
+ *
+ * Every measure is in the same unit (the report's CSS px, top = 0).
+ */
+
+export type PdfRange = { top: number; bottom: number };
+
+/** A table on the report: its whole extent and its header row. */
+export type PdfTable = PdfRange & { head: PdfRange };
+
+/** One page: the slice of the report it shows, and the header to repeat above it. */
+export type PdfPage = PdfRange & { head?: PdfRange };
+
+export function planPdfPages(
+  height: number,
+  pageHeight: number,
+  breaks: number[],
+  tables: PdfTable[] = [],
+): PdfPage[] {
+  const cuts = [...new Set(breaks)]
+    .filter((cut) => cut > 0 && cut < height)
+    .sort((a, b) => a - b);
+  const pages: PdfPage[] = [];
+  let top = 0;
+
+  while (height - top > 0.5) {
+    // A page that starts among a table's rows repeats the table's header -
+    // unless the header is so tall it would leave no room for the rows.
+    const table = tables.find((t) => top >= t.head.bottom && top < t.bottom);
+    const headHeight = table ? table.head.bottom - table.head.top : 0;
+    const head = table && headHeight < pageHeight / 2 ? table.head : undefined;
+    const limit = top + pageHeight - (head ? headHeight : 0);
+
+    let bottom = height;
+    if (limit < height) {
+      const fits = cuts.filter((cut) => cut > top && cut <= limit);
+      // Nothing ends on this page: a single block taller than a page is cut.
+      bottom = fits.length ? fits[fits.length - 1] : limit;
+    }
+
+    pages.push(head ? { top, bottom, head } : { top, bottom });
+    top = bottom;
+  }
+
+  return pages;
+}
+
+const SHORT_MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+/** "2026-10-07" as "7 Oct 2026"; anything else as it came. */
+export function formatReportDate(date: string) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date ?? "");
+  const month = match ? SHORT_MONTHS[Number(match[2]) - 1] : undefined;
+  return match && month ? `${Number(match[3])} ${month} ${match[1]}` : date;
+}
+
+/** "7 Oct 2026, 10:24": when an export was made. */
+export function formatGeneratedAt(date = new Date()) {
+  return date.toLocaleString("en-GB", {
+    day: "numeric",
+    month: "short",
+    year: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/** "Patrol Report - WH01 Patrol Route - 2026-10-07.pdf", minus what a file name cannot hold. */
+export function reportFileName(parts: Array<string | undefined>, extension: "pdf" | "csv") {
+  const name = parts
+    .map((part) => (part ?? "").replace(/[\\/:*?"<>|]+/g, " ").replace(/\s+/g, " ").trim())
+    .filter(Boolean)
+    .join(" - ");
+  return `${name || "report"}.${extension}`;
+}
+
+/** One table of a CSV export: a title line, a header row, the rows. */
+export type CsvSection = { title: string; header: string[]; rows: string[][] };
+
+/**
+ * One cell, quoted. A cell a spreadsheet would run as a formula - a guard's
+ * remarks starting "=" or "+", say - is kept as text with a leading
+ * apostrophe. A lone "-" is the reports' own blank, not a formula.
+ */
+function csvCell(value: string | number | null | undefined) {
+  let text = value == null ? "" : String(value);
+  if (/^[=+\-@\t\r]/.test(text) && text !== "-") text = `'${text}`;
+  return `"${text.replace(/"/g, '""')}"`;
+}
+
+/**
+ * A report as CSV: its name and details (site, route, date...) on the first
+ * lines, then each table under its own title, a blank line between. With a
+ * byte order mark, so Excel reads it as UTF-8, and CRLF line ends (RFC 4180).
+ */
+export function buildReportCsv(report: {
+  title: string;
+  details: Array<{ label: string; value?: string }>;
+  sections: CsvSection[];
+}) {
+  const lines: Array<Array<string | undefined>> = [[report.title]];
+  for (const { label, value } of report.details) {
+    if (value) lines.push([label, value]);
+  }
+  for (const section of report.sections) {
+    lines.push([], [section.title], section.header, ...section.rows);
+  }
+  return `\uFEFF${lines.map((line) => line.map(csvCell).join(",")).join("\r\n")}\r\n`;
+}