@blackcode_sa/metaestetics-api 1.12.72 → 1.13.1

package/src/services/analytics/utils/stored-analytics.utils.ts

@@ -0,0 +1,347 @@
+import { Firestore, Timestamp, doc, getDoc } from 'firebase/firestore';
+import {
+  ANALYTICS_COLLECTION,
+  PRACTITIONER_ANALYTICS_SUBCOLLECTION,
+  PROCEDURE_ANALYTICS_SUBCOLLECTION,
+  CLINIC_ANALYTICS_SUBCOLLECTION,
+  DASHBOARD_ANALYTICS_SUBCOLLECTION,
+  TIME_EFFICIENCY_ANALYTICS_SUBCOLLECTION,
+  CANCELLATION_ANALYTICS_SUBCOLLECTION,
+  NO_SHOW_ANALYTICS_SUBCOLLECTION,
+  REVENUE_ANALYTICS_SUBCOLLECTION,
+  AnalyticsPeriod,
+  ReadStoredAnalyticsOptions,
+  StoredPractitionerAnalytics,
+  StoredProcedureAnalytics,
+  StoredClinicAnalytics,
+  StoredDashboardAnalytics,
+  StoredTimeEfficiencyMetrics,
+  StoredCancellationMetrics,
+  StoredNoShowMetrics,
+  StoredRevenueMetrics,
+} from '../../../types/analytics';
+import { CLINICS_COLLECTION } from '../../../types/clinic';
+
+/**
+ * Checks if stored analytics data is fresh enough to use
+ *
+ * @param computedAt - Timestamp when analytics were computed
+ * @param maxAgeHours - Maximum age in hours
+ * @returns True if data is fresh enough
+ */
+export function isAnalyticsDataFresh(computedAt: Timestamp, maxAgeHours: number): boolean {
+  const now = Timestamp.now();
+  const ageMs = now.toMillis() - computedAt.toMillis();
+  const ageHours = ageMs / (1000 * 60 * 60);
+  return ageHours <= maxAgeHours;
+}
+
+/**
+ * Reads stored analytics document
+ *
+ * @param db - Firestore instance
+ * @param clinicBranchId - Clinic branch ID
+ * @param subcollection - Analytics subcollection name
+ * @param documentId - Document ID
+ * @param period - Analytics period
+ * @returns Stored analytics document or null
+ */
+async function readStoredAnalytics<T>(
+  db: Firestore,
+  clinicBranchId: string,
+  subcollection: string,
+  documentId: string,
+  period: AnalyticsPeriod,
+): Promise<T | null> {
+  try {
+    const docRef = doc(
+      db,
+      CLINICS_COLLECTION,
+      clinicBranchId,
+      ANALYTICS_COLLECTION,
+      subcollection,
+      period,
+      documentId,
+    );
+
+    const docSnap = await getDoc(docRef);
+    if (!docSnap.exists()) {
+      return null;
+    }
+
+    return docSnap.data() as T;
+  } catch (error) {
+    console.error(`[StoredAnalytics] Error reading ${subcollection}/${period}/${documentId}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Reads stored practitioner analytics
+ */
+export async function readStoredPractitionerAnalytics(
+  db: Firestore,
+  clinicBranchId: string,
+  practitionerId: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredPractitionerAnalytics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredPractitionerAnalytics>(
+    db,
+    clinicBranchId,
+    PRACTITIONER_ANALYTICS_SUBCOLLECTION,
+    practitionerId,
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  // Check if data is fresh enough
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored procedure analytics
+ */
+export async function readStoredProcedureAnalytics(
+  db: Firestore,
+  clinicBranchId: string,
+  procedureId: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredProcedureAnalytics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredProcedureAnalytics>(
+    db,
+    clinicBranchId,
+    PROCEDURE_ANALYTICS_SUBCOLLECTION,
+    procedureId,
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored clinic analytics
+ */
+export async function readStoredClinicAnalytics(
+  db: Firestore,
+  clinicBranchId: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredClinicAnalytics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredClinicAnalytics>(
+    db,
+    clinicBranchId,
+    CLINIC_ANALYTICS_SUBCOLLECTION,
+    'current',
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored dashboard analytics
+ */
+export async function readStoredDashboardAnalytics(
+  db: Firestore,
+  clinicBranchId: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredDashboardAnalytics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredDashboardAnalytics>(
+    db,
+    clinicBranchId,
+    DASHBOARD_ANALYTICS_SUBCOLLECTION,
+    'current',
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored time efficiency metrics
+ */
+export async function readStoredTimeEfficiencyMetrics(
+  db: Firestore,
+  clinicBranchId: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredTimeEfficiencyMetrics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredTimeEfficiencyMetrics>(
+    db,
+    clinicBranchId,
+    TIME_EFFICIENCY_ANALYTICS_SUBCOLLECTION,
+    'current',
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored revenue metrics
+ */
+export async function readStoredRevenueMetrics(
+  db: Firestore,
+  clinicBranchId: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredRevenueMetrics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredRevenueMetrics>(
+    db,
+    clinicBranchId,
+    REVENUE_ANALYTICS_SUBCOLLECTION,
+    'current',
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored cancellation metrics
+ */
+export async function readStoredCancellationMetrics(
+  db: Firestore,
+  clinicBranchId: string,
+  entityType: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredCancellationMetrics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredCancellationMetrics>(
+    db,
+    clinicBranchId,
+    CANCELLATION_ANALYTICS_SUBCOLLECTION,
+    entityType,
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+
+/**
+ * Reads stored no-show metrics
+ */
+export async function readStoredNoShowMetrics(
+  db: Firestore,
+  clinicBranchId: string,
+  entityType: string,
+  options: ReadStoredAnalyticsOptions = {},
+): Promise<StoredNoShowMetrics | null> {
+  const { useCache = true, maxCacheAgeHours = 12, period = 'all_time' } = options;
+
+  if (!useCache) {
+    return null;
+  }
+
+  const stored = await readStoredAnalytics<StoredNoShowMetrics>(
+    db,
+    clinicBranchId,
+    NO_SHOW_ANALYTICS_SUBCOLLECTION,
+    entityType,
+    period,
+  );
+
+  if (!stored) {
+    return null;
+  }
+
+  if (!isAnalyticsDataFresh(stored.metadata.computedAt, maxCacheAgeHours)) {
+    return null;
+  }
+
+  return stored;
+}
+

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

@@ -0,0 +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));
+}
+