@7365admin1/module-hygiene 4.28.1-staging.7 → 4.28.1-staging.9

package/.changeset/hygiene-dashboard-metrics.md

@@ -0,0 +1,29 @@
+---
+"@7365admin1/module-hygiene": patch
+---
+
+Hygiene dashboard metrics: report the selected period honestly instead of fabricating figures
+
+The dashboard's metric calculations were computed inline inside
+`hygiene-dashboard.repository.ts` and were wrong in four ways. They now live in
+`src/utils/hygiene-dashboard-metrics.util.ts`, covered by unit tests (`yarn test`),
+so a change to a metric fails a test rather than a screen. What a consumer of the
+dashboard endpoints sees change:
+
+- **Trend comparisons follow the selected period.** The "vs previous" figure was
+  always computed against yesterday, whatever range the user picked, so a
+  month-to-month comparison was really a day-to-day one. It now compares the
+  selected period against the period immediately before it.
+- **Day boundaries are Singapore time.** Period start/end were taken from the
+  server host's midnight, so a host on UTC put work into the wrong day. All
+  boundaries are now computed in `Asia/Singapore`.
+- **No invented percentages on an empty prior period.** When the previous period
+  had no data, the change was reported as `100%` (or `0`) as if measured. It now
+  returns `null`, so the UI can show "no comparison available" rather than a
+  number nobody can reproduce.
+- **The supply alert percentage is no longer hard-coded.** It was emitted as a
+  fixed value regardless of stock; it is now derived, and reports its reason when
+  there is no prior period to compare against.
+
+No API surface changes and no consumer code change is required — the same fields
+are returned, with `null` now possible where a comparison genuinely cannot be made.

package/dist/index.js

@@ -93,9 +93,57 @@ var allowedStatus = [
 var allowedPeriods = ["today", "thisWeek", "thisMonth"];
 
 // src/repositories/hygiene-dashboard.repository.ts
-var import_moment_timezone = __toESM(require("moment-timezone"));
+var import_moment_timezone2 = __toESM(require("moment-timezone"));
 var import_mongodb = require("mongodb");
 var import_node_server_utils = require("@7365admin1/node-server-utils");
+
+// src/utils/hygiene-dashboard-metrics.util.ts
+var import_moment_timezone = __toESM(require("moment-timezone"));
+var DASHBOARD_TIMEZONE = "Asia/Singapore";
+var PERIOD_UNITS = {
+  thisWeek: { boundary: "isoWeek", step: "week" },
+  thisMonth: { boundary: "month", step: "month" }
+};
+var DAY_UNIT = {
+  boundary: "day",
+  step: "day"
+};
+function unitsOf(period) {
+  return PERIOD_UNITS[period] ?? DAY_UNIT;
+}
+function at(now) {
+  return now === void 0 || now === null ? import_moment_timezone.default.tz(DASHBOARD_TIMEZONE) : import_moment_timezone.default.tz(now, DASHBOARD_TIMEZONE);
+}
+function getPeriodRange(period, now) {
+  const { boundary } = unitsOf(period);
+  const point = at(now);
+  return {
+    $gte: point.clone().startOf(boundary).toDate(),
+    $lte: point.clone().endOf(boundary).toDate()
+  };
+}
+function getPreviousPeriodRange(period, now) {
+  const { boundary, step } = unitsOf(period);
+  const point = at(now).subtract(1, step);
+  return {
+    $gte: point.clone().startOf(boundary).toDate(),
+    $lte: point.clone().endOf(boundary).toDate()
+  };
+}
+function calculatePercentageChange(currentCount, previousCount) {
+  if (typeof currentCount !== "number" || !Number.isFinite(currentCount)) {
+    return null;
+  }
+  if (typeof previousCount !== "number" || !Number.isFinite(previousCount)) {
+    return null;
+  }
+  if (previousCount === 0)
+    return null;
+  return Math.round((currentCount - previousCount) / previousCount * 100 * 100) / 100;
+}
+var SUPPLY_ALERT_HAS_NO_PRIOR_PERIOD = "Supply alerts count what is out of stock right now, and the supply record keeps no history, so there is no earlier period to compare against.";
+
+// src/repositories/hygiene-dashboard.repository.ts
 function useHygieneDashboardRepository() {
   const db = import_node_server_utils.useAtlas.getDb();
   if (!db) {
@@ -166,59 +214,16 @@ function useHygieneDashboardRepository() {
       import_node_server_utils.logger.info(`Cache hit for dashboard: ${dashboardCacheKey}`);
       return cachedDashboard;
     }
-    function formatEndDate(date) {
-      if (typeof date === "string") {
-        const dateWithoutTimezone = date.replace(/\s*\+\d{2}:\d{2}$/, "");
-        date = new Date(dateWithoutTimezone);
-      }
-      const singaporeMoment = import_moment_timezone.default.tz(date, "Asia/Singapore");
-      singaporeMoment.set({
-        hour: 23,
-        minute: 59,
-        second: 59,
-        millisecond: 999
-      });
-      return singaporeMoment.toDate();
-    }
-    function getDateRange(p) {
-      const start = /* @__PURE__ */ new Date();
-      start.setHours(0, 0, 0, 0);
-      if (p === "today") {
-        return { $gte: start, $lte: formatEndDate(start) };
-      }
-      const days = p === "thisWeek" ? 7 : 30;
-      const rangeStart = /* @__PURE__ */ new Date();
-      rangeStart.setDate(start.getDate() - days);
-      rangeStart.setHours(0, 0, 0, 0);
-      return { $gte: rangeStart, $lte: formatEndDate(/* @__PURE__ */ new Date()) };
-    }
-    const calculatePercentageChange = (currentCount, previousCount) => {
-      if (previousCount === 0) {
-        return currentCount > 0 ? 100 : 0;
-      }
-      return Math.round(
-        (currentCount - previousCount) / previousCount * 100 * 100
-      ) / 100;
-    };
     const workOrderService = workOrderServiceMap[serviceType] ?? serviceType;
     try {
-      const today = /* @__PURE__ */ new Date();
-      today.setHours(0, 0, 0, 0);
-      const yesterday = /* @__PURE__ */ new Date();
-      yesterday.setDate(today.getDate() - 1);
-      yesterday.setHours(0, 0, 0, 0);
-      const yesterdayEnd = new Date(yesterday);
-      yesterdayEnd.setHours(23, 59, 59, 999);
-      const todayEnd = formatEndDate(/* @__PURE__ */ new Date());
-      const periodRange = getDateRange(period);
+      const periodRange = getPeriodRange(period);
+      const priorPeriodRange = getPreviousPeriodRange(period);
       const [
         workOrderReport,
         supplyAlertReport,
         taskCompletedReport,
-        yesterdayWorkOrderReport,
-        todayWorkOrderReport,
-        yesterdayTaskCompletedReport,
-        todayTaskCompletedReport
+        priorWorkOrderReport,
+        priorTaskCompletedReport
       ] = await Promise.all([
         // 1. Open work orders (period-filtered) with inProgress breakdown
         workOrderCollection.aggregate([
@@ -262,45 +267,28 @@ function useHygieneDashboardRepository() {
             }
           }
         ]).toArray(),
-        // 4. Yesterday open work orders (for % change)
+        /*
+                  4. Open work orders in the PREVIOUS period (for % change).
+        
+                  The current side of the comparison is no longer queried separately:
+                  it is now the same range as tile 1, so `wFacet.total` below IS the
+                  current count. Two aggregations dropped, not by cutting a measure but
+                  because the fix made them duplicates.
+                */
         workOrderCollection.aggregate([
           {
             $match: {
               site,
               service: workOrderService,
-              createdAt: { $gte: yesterday, $lte: yesterdayEnd },
+              createdAt: priorPeriodRange,
               status: { $nin: ["completed"] }
             }
           },
           { $count: "count" }
         ]).toArray(),
-        // 5. Today open work orders (for % change)
-        workOrderCollection.aggregate([
-          {
-            $match: {
-              site,
-              service: workOrderService,
-              createdAt: { $gte: today, $lte: todayEnd },
-              status: { $nin: ["completed"] }
-            }
-          },
-          { $count: "count" }
-        ]).toArray(),
-        // 6. Yesterday task completed — area checklists (for % change)
-        areaChecklistCollection.aggregate([
-          ...areaChecklistScheduleLookup(site, serviceType, {
-            $gte: yesterday,
-            $lte: yesterdayEnd
-          }),
-          { $match: { status: "completed" } },
-          { $count: "count" }
-        ]).toArray(),
-        // 7. Today task completed — area checklists (for % change)
+        // 5. Task completed in the PREVIOUS period — area checklists (for % change)
         areaChecklistCollection.aggregate([
-          ...areaChecklistScheduleLookup(site, serviceType, {
-            $gte: today,
-            $lte: todayEnd
-          }),
+          ...areaChecklistScheduleLookup(site, serviceType, priorPeriodRange),
           { $match: { status: "completed" } },
           { $count: "count" }
         ]).toArray()
@@ -316,21 +304,26 @@ function useHygieneDashboardRepository() {
           count: wFacet.total[0]?.count ?? 0,
           inProgress: wFacet.inProgress[0]?.count ?? 0,
           percentage: calculatePercentageChange(
-            todayWorkOrderReport[0]?.count ?? 0,
-            yesterdayWorkOrderReport[0]?.count ?? 0
+            wFacet.total[0]?.count ?? 0,
+            priorWorkOrderReport[0]?.count ?? 0
           )
         },
         supplyAlert: {
+          // The count is real: active supplies at qty 0 for this site and
+          // service. The percentage beside it was the literal 0 and had never
+          // been computed from anything — see the util for why there is no
+          // prior period to compute one from.
           count: supplyAlertReport[0]?.count ?? 0,
-          percentage: 0
+          percentage: null,
+          percentageUnavailableReason: SUPPLY_ALERT_HAS_NO_PRIOR_PERIOD
         },
         taskCompleted: {
           completed: tFacet.completed[0]?.count ?? 0,
           total: tFacet.total[0]?.count ?? 0,
           inProgress: tFacet.inProgress[0]?.count ?? 0,
           percentage: calculatePercentageChange(
-            todayTaskCompletedReport[0]?.count ?? 0,
-            yesterdayTaskCompletedReport[0]?.count ?? 0
+            tFacet.completed[0]?.count ?? 0,
+            priorTaskCompletedReport[0]?.count ?? 0
           )
         }
       };
@@ -368,8 +361,8 @@ function useHygieneDashboardRepository() {
       return cachedData;
     }
     const workOrderService = workOrderServiceMap[serviceType] ?? serviceType;
-    const weekStart = import_moment_timezone.default.tz("Asia/Singapore").startOf("isoWeek").toDate();
-    const weekEnd = import_moment_timezone.default.tz("Asia/Singapore").endOf("isoWeek").toDate();
+    const weekStart = import_moment_timezone2.default.tz("Asia/Singapore").startOf("isoWeek").toDate();
+    const weekEnd = import_moment_timezone2.default.tz("Asia/Singapore").endOf("isoWeek").toDate();
     const weekRange = { $gte: weekStart, $lte: weekEnd };
     const dayLabels = {
       1: "Sun",
@@ -449,8 +442,8 @@ function useHygieneDashboardRepository() {
       import_node_server_utils.logger.info(`Cache hit for todayTaskSchedule: ${cacheKey}`);
       return cachedData;
     }
-    const todayStart = import_moment_timezone.default.tz("Asia/Singapore").startOf("day").toDate();
-    const todayEnd = import_moment_timezone.default.tz("Asia/Singapore").endOf("day").toDate();
+    const todayStart = import_moment_timezone2.default.tz("Asia/Singapore").startOf("day").toDate();
+    const todayEnd = import_moment_timezone2.default.tz("Asia/Singapore").endOf("day").toDate();
     const todayRange = { $gte: todayStart, $lte: todayEnd };
     try {
       const [items, countResult] = await Promise.all([
@@ -554,8 +547,8 @@ function useHygieneDashboardRepository() {
       import_node_server_utils.logger.info(`Cache hit for staffAttendance: ${cacheKey}`);
       return cachedData;
     }
-    const todayStart = import_moment_timezone.default.tz("Asia/Singapore").startOf("day").toDate();
-    const todayEnd = import_moment_timezone.default.tz("Asia/Singapore").endOf("day").toDate();
+    const todayStart = import_moment_timezone2.default.tz("Asia/Singapore").startOf("day").toDate();
+    const todayEnd = import_moment_timezone2.default.tz("Asia/Singapore").endOf("day").toDate();
     const todayStartStr = todayStart.toISOString();
     const todayEndStr = todayEnd.toISOString();
     try {
@@ -2578,7 +2571,7 @@ function MParentChecklist(value) {
 
 // src/repositories/hygiene-parent-checklist.repository.ts
 var import_mongodb7 = require("mongodb");
-var import_moment_timezone2 = __toESM(require("moment-timezone"));
+var import_moment_timezone3 = __toESM(require("moment-timezone"));
 var import_node_server_utils14 = require("@7365admin1/node-server-utils");
 var import_core7 = require("@7365admin1/core");
 function useParentChecklistRepo() {
@@ -2874,11 +2867,11 @@ function useParentChecklistRepo() {
       cacheOptions.search = search;
     }
     const singaporeTz = "Asia/Singapore";
-    const normalizedStartDate = typeof startDate === "string" ? startDate : (0, import_moment_timezone2.default)(startDate).tz(singaporeTz).format("YYYY-MM-DD");
-    const normalizedEndDate = typeof endDate === "string" ? endDate : (0, import_moment_timezone2.default)(endDate).tz(singaporeTz).format("YYYY-MM-DD");
+    const normalizedStartDate = typeof startDate === "string" ? startDate : (0, import_moment_timezone3.default)(startDate).tz(singaporeTz).format("YYYY-MM-DD");
+    const normalizedEndDate = typeof endDate === "string" ? endDate : (0, import_moment_timezone3.default)(endDate).tz(singaporeTz).format("YYYY-MM-DD");
     if (startDate && endDate) {
-      const startOfDay = import_moment_timezone2.default.tz(normalizedStartDate, "YYYY-MM-DD", singaporeTz).startOf("day").toDate();
-      const endOfDay = import_moment_timezone2.default.tz(normalizedEndDate, "YYYY-MM-DD", singaporeTz).endOf("day").toDate();
+      const startOfDay = import_moment_timezone3.default.tz(normalizedStartDate, "YYYY-MM-DD", singaporeTz).startOf("day").toDate();
+      const endOfDay = import_moment_timezone3.default.tz(normalizedEndDate, "YYYY-MM-DD", singaporeTz).endOf("day").toDate();
       query.createdAt = {
         $gte: startOfDay,
         $lte: endOfDay
@@ -2887,12 +2880,12 @@ function useParentChecklistRepo() {
       cacheOptions.endDate = normalizedEndDate;
     } else if (startDate) {
       query.createdAt = {
-        $gte: import_moment_timezone2.default.tz(normalizedStartDate, "YYYY-MM-DD", singaporeTz).startOf("day").toDate()
+        $gte: import_moment_timezone3.default.tz(normalizedStartDate, "YYYY-MM-DD", singaporeTz).startOf("day").toDate()
       };
       cacheOptions.startDate = normalizedStartDate;
     } else if (endDate) {
       query.createdAt = {
-        $lte: import_moment_timezone2.default.tz(normalizedEndDate, "YYYY-MM-DD", singaporeTz).endOf("day").toDate()
+        $lte: import_moment_timezone3.default.tz(normalizedEndDate, "YYYY-MM-DD", singaporeTz).endOf("day").toDate()
       };
       cacheOptions.endDate = normalizedEndDate;
     }