@blackcode_sa/metaestetics-api 1.13.5 → 1.13.6

package/src/services/analytics/utils/time-calculation.utils.ts

@@ -1,186 +1,186 @@
-import { Appointment, AppointmentStatus } from '../../../types/appointment';
-import { Timestamp } from 'firebase/firestore';
-
-/**
- * Calculates time efficiency metrics for an appointment
- *
- * @param appointment - The appointment to calculate metrics for
- * @returns Time efficiency data or null if insufficient data
- */
-export function calculateTimeEfficiency(appointment: Appointment): {
-  bookedDuration: number; // minutes
-  actualDuration: number; // minutes
-  efficiency: number; // percentage
-  overrun: number; // minutes (positive if actual > booked)
-  underutilization: number; // minutes (positive if booked > actual)
-} | null {
-  const startTime = appointment.appointmentStartTime;
-  const endTime = appointment.appointmentEndTime;
-
-  if (!startTime || !endTime) {
-    return null;
-  }
-
-  // Calculate booked duration in minutes
-  const bookedDurationMs = endTime.toMillis() - startTime.toMillis();
-  const bookedDuration = Math.round(bookedDurationMs / (1000 * 60));
-
-  // Use actual duration if available, otherwise use booked duration
-  const actualDuration = appointment.actualDurationMinutes || bookedDuration;
-
-  // Calculate efficiency percentage
-  const efficiency = bookedDuration > 0 ? (actualDuration / bookedDuration) * 100 : 100;
-
-  // Calculate overrun (positive if actual > booked)
-  const overrun = actualDuration > bookedDuration ? actualDuration - bookedDuration : 0;
-
-  // Calculate underutilization (positive if booked > actual)
-  const underutilization = bookedDuration > actualDuration ? bookedDuration - actualDuration : 0;
-
-  return {
-    bookedDuration,
-    actualDuration,
-    efficiency,
-    overrun,
-    underutilization,
-  };
-}
-
-/**
- * Calculates average time metrics from an array of appointments
- *
- * @param appointments - Array of appointments
- * @returns Average time metrics
- */
-export function calculateAverageTimeMetrics(appointments: Appointment[]): {
-  averageBookedDuration: number;
-  averageActualDuration: number;
-  averageEfficiency: number;
-  totalOverrun: number;
-  totalUnderutilization: number;
-  averageOverrun: number;
-  averageUnderutilization: number;
-  appointmentsWithActualTime: number;
-} {
-  if (appointments.length === 0) {
-    return {
-      averageBookedDuration: 0,
-      averageActualDuration: 0,
-      averageEfficiency: 0,
-      totalOverrun: 0,
-      totalUnderutilization: 0,
-      averageOverrun: 0,
-      averageUnderutilization: 0,
-      appointmentsWithActualTime: 0,
-    };
-  }
-
-  let totalBookedDuration = 0;
-  let totalActualDuration = 0;
-  let totalOverrun = 0;
-  let totalUnderutilization = 0;
-  let appointmentsWithActualTime = 0;
-
-  appointments.forEach(appointment => {
-    const timeData = calculateTimeEfficiency(appointment);
-    if (timeData) {
-      totalBookedDuration += timeData.bookedDuration;
-      totalActualDuration += timeData.actualDuration;
-      totalOverrun += timeData.overrun;
-      totalUnderutilization += timeData.underutilization;
-
-      if (appointment.actualDurationMinutes !== undefined) {
-        appointmentsWithActualTime++;
-      }
-    }
-  });
-
-  const count = appointments.length;
-  const averageBookedDuration = count > 0 ? totalBookedDuration / count : 0;
-  const averageActualDuration = count > 0 ? totalActualDuration / count : 0;
-  const averageEfficiency = averageBookedDuration > 0 ? (averageActualDuration / averageBookedDuration) * 100 : 0;
-  const averageOverrun = count > 0 ? totalOverrun / count : 0;
-  const averageUnderutilization = count > 0 ? totalUnderutilization / count : 0;
-
-  return {
-    averageBookedDuration: Math.round(averageBookedDuration),
-    averageActualDuration: Math.round(averageActualDuration),
-    averageEfficiency: Math.round(averageEfficiency * 100) / 100,
-    totalOverrun,
-    totalUnderutilization,
-    averageOverrun: Math.round(averageOverrun),
-    averageUnderutilization: Math.round(averageUnderutilization),
-    appointmentsWithActualTime,
-  };
-}
-
-/**
- * Groups appointments by efficiency ranges
- *
- * @param appointments - Array of appointments
- * @returns Distribution of appointments by efficiency range
- */
-export function calculateEfficiencyDistribution(appointments: Appointment[]): Array<{
-  range: string;
-  count: number;
-  percentage: number;
-}> {
-  const ranges = [
-    { label: '0-50%', min: 0, max: 50 },
-    { label: '50-75%', min: 50, max: 75 },
-    { label: '75-100%', min: 75, max: 100 },
-    { label: '100%+', min: 100, max: Infinity },
-  ];
-
-  const distribution = ranges.map(range => ({
-    range: range.label,
-    count: 0,
-    percentage: 0,
-  }));
-
-  let validCount = 0;
-
-  appointments.forEach(appointment => {
-    const timeData = calculateTimeEfficiency(appointment);
-    if (timeData) {
-      validCount++;
-      const efficiency = timeData.efficiency;
-
-      for (let i = 0; i < ranges.length; i++) {
-        if (efficiency >= ranges[i].min && efficiency < ranges[i].max) {
-          distribution[i].count++;
-          break;
-        }
-      }
-    }
-  });
-
-  // Calculate percentages
-  if (validCount > 0) {
-    distribution.forEach(item => {
-      item.percentage = Math.round((item.count / validCount) * 100 * 100) / 100;
-    });
-  }
-
-  return distribution;
-}
-
-/**
- * Calculates cancellation lead time in hours
- *
- * @param appointment - The appointment to calculate lead time for
- * @returns Lead time in hours, or null if insufficient data
- */
-export function calculateCancellationLeadTime(appointment: Appointment): number | null {
-  if (!appointment.cancellationTime || !appointment.appointmentStartTime) {
-    return null;
-  }
-
-  const cancellationTime = appointment.cancellationTime.toMillis();
-  const appointmentTime = appointment.appointmentStartTime.toMillis();
-  const diffMs = appointmentTime - cancellationTime;
-
-  // Return positive hours (time before appointment)
-  return Math.max(0, diffMs / (1000 * 60 * 60));
-}
-
+import { Appointment, AppointmentStatus } from '../../../types/appointment';
+import { Timestamp } from 'firebase/firestore';
+
+/**
+ * Calculates time efficiency metrics for an appointment
+ *
+ * @param appointment - The appointment to calculate metrics for
+ * @returns Time efficiency data or null if insufficient data
+ */
+export function calculateTimeEfficiency(appointment: Appointment): {
+  bookedDuration: number; // minutes
+  actualDuration: number; // minutes
+  efficiency: number; // percentage
+  overrun: number; // minutes (positive if actual > booked)
+  underutilization: number; // minutes (positive if booked > actual)
+} | null {
+  const startTime = appointment.appointmentStartTime;
+  const endTime = appointment.appointmentEndTime;
+
+  if (!startTime || !endTime) {
+    return null;
+  }
+
+  // Calculate booked duration in minutes
+  const bookedDurationMs = endTime.toMillis() - startTime.toMillis();
+  const bookedDuration = Math.round(bookedDurationMs / (1000 * 60));
+
+  // Use actual duration if available, otherwise use booked duration
+  const actualDuration = appointment.actualDurationMinutes || bookedDuration;
+
+  // Calculate efficiency percentage
+  const efficiency = bookedDuration > 0 ? (actualDuration / bookedDuration) * 100 : 100;
+
+  // Calculate overrun (positive if actual > booked)
+  const overrun = actualDuration > bookedDuration ? actualDuration - bookedDuration : 0;
+
+  // Calculate underutilization (positive if booked > actual)
+  const underutilization = bookedDuration > actualDuration ? bookedDuration - actualDuration : 0;
+
+  return {
+    bookedDuration,
+    actualDuration,
+    efficiency,
+    overrun,
+    underutilization,
+  };
+}
+
+/**
+ * Calculates average time metrics from an array of appointments
+ *
+ * @param appointments - Array of appointments
+ * @returns Average time metrics
+ */
+export function calculateAverageTimeMetrics(appointments: Appointment[]): {
+  averageBookedDuration: number;
+  averageActualDuration: number;
+  averageEfficiency: number;
+  totalOverrun: number;
+  totalUnderutilization: number;
+  averageOverrun: number;
+  averageUnderutilization: number;
+  appointmentsWithActualTime: number;
+} {
+  if (appointments.length === 0) {
+    return {
+      averageBookedDuration: 0,
+      averageActualDuration: 0,
+      averageEfficiency: 0,
+      totalOverrun: 0,
+      totalUnderutilization: 0,
+      averageOverrun: 0,
+      averageUnderutilization: 0,
+      appointmentsWithActualTime: 0,
+    };
+  }
+
+  let totalBookedDuration = 0;
+  let totalActualDuration = 0;
+  let totalOverrun = 0;
+  let totalUnderutilization = 0;
+  let appointmentsWithActualTime = 0;
+
+  appointments.forEach(appointment => {
+    const timeData = calculateTimeEfficiency(appointment);
+    if (timeData) {
+      totalBookedDuration += timeData.bookedDuration;
+      totalActualDuration += timeData.actualDuration;
+      totalOverrun += timeData.overrun;
+      totalUnderutilization += timeData.underutilization;
+
+      if (appointment.actualDurationMinutes !== undefined) {
+        appointmentsWithActualTime++;
+      }
+    }
+  });
+
+  const count = appointments.length;
+  const averageBookedDuration = count > 0 ? totalBookedDuration / count : 0;
+  const averageActualDuration = count > 0 ? totalActualDuration / count : 0;
+  const averageEfficiency = averageBookedDuration > 0 ? (averageActualDuration / averageBookedDuration) * 100 : 0;
+  const averageOverrun = count > 0 ? totalOverrun / count : 0;
+  const averageUnderutilization = count > 0 ? totalUnderutilization / count : 0;
+
+  return {
+    averageBookedDuration: Math.round(averageBookedDuration),
+    averageActualDuration: Math.round(averageActualDuration),
+    averageEfficiency: Math.round(averageEfficiency * 100) / 100,
+    totalOverrun,
+    totalUnderutilization,
+    averageOverrun: Math.round(averageOverrun),
+    averageUnderutilization: Math.round(averageUnderutilization),
+    appointmentsWithActualTime,
+  };
+}
+
+/**
+ * Groups appointments by efficiency ranges
+ *
+ * @param appointments - Array of appointments
+ * @returns Distribution of appointments by efficiency range
+ */
+export function calculateEfficiencyDistribution(appointments: Appointment[]): Array<{
+  range: string;
+  count: number;
+  percentage: number;
+}> {
+  const ranges = [
+    { label: '0-50%', min: 0, max: 50 },
+    { label: '50-75%', min: 50, max: 75 },
+    { label: '75-100%', min: 75, max: 100 },
+    { label: '100%+', min: 100, max: Infinity },
+  ];
+
+  const distribution = ranges.map(range => ({
+    range: range.label,
+    count: 0,
+    percentage: 0,
+  }));
+
+  let validCount = 0;
+
+  appointments.forEach(appointment => {
+    const timeData = calculateTimeEfficiency(appointment);
+    if (timeData) {
+      validCount++;
+      const efficiency = timeData.efficiency;
+
+      for (let i = 0; i < ranges.length; i++) {
+        if (efficiency >= ranges[i].min && efficiency < ranges[i].max) {
+          distribution[i].count++;
+          break;
+        }
+      }
+    }
+  });
+
+  // Calculate percentages
+  if (validCount > 0) {
+    distribution.forEach(item => {
+      item.percentage = Math.round((item.count / validCount) * 100 * 100) / 100;
+    });
+  }
+
+  return distribution;
+}
+
+/**
+ * Calculates cancellation lead time in hours
+ *
+ * @param appointment - The appointment to calculate lead time for
+ * @returns Lead time in hours, or null if insufficient data
+ */
+export function calculateCancellationLeadTime(appointment: Appointment): number | null {
+  if (!appointment.cancellationTime || !appointment.appointmentStartTime) {
+    return null;
+  }
+
+  const cancellationTime = appointment.cancellationTime.toMillis();
+  const appointmentTime = appointment.appointmentStartTime.toMillis();
+  const diffMs = appointmentTime - cancellationTime;
+
+  // Return positive hours (time before appointment)
+  return Math.max(0, diffMs / (1000 * 60 * 60));
+}
+