@blackcode_sa/metaestetics-api 1.12.72 → 1.13.1

package/src/services/analytics/utils/grouping.utils.ts

@@ -0,0 +1,434 @@
+import { Appointment, AppointmentStatus } from '../../../types/appointment';
+import { EntityType } from '../../../types/analytics';
+import {
+  GroupedRevenueMetrics,
+  GroupedProductUsageMetrics,
+  GroupedTimeEfficiencyMetrics,
+  GroupedPatientBehaviorMetrics,
+} from '../../../types/analytics/grouped-analytics.types';
+import { calculateAppointmentCost, extractProductUsage, calculateTotalRevenue } from './cost-calculation.utils';
+import { calculateTimeEfficiency, calculateAverageTimeMetrics } from './time-calculation.utils';
+import { getCompletedAppointments, getCanceledAppointments, getNoShowAppointments, calculatePercentage } from './appointment-filtering.utils';
+
+/**
+ * Helper to get technology ID from appointment
+ */
+function getTechnologyId(appointment: Appointment): string {
+  return (
+    appointment.procedureExtendedInfo?.procedureTechnologyId || 'unknown-technology'
+  );
+}
+
+/**
+ * Helper to get technology name from appointment
+ */
+function getTechnologyName(appointment: Appointment): string {
+  return (
+    appointment.procedureExtendedInfo?.procedureTechnologyName ||
+    appointment.procedureInfo?.technologyName ||
+    'Unknown'
+  );
+}
+
+/**
+ * Helper to get entity name from appointment
+ */
+function getEntityName(appointment: Appointment, entityType: EntityType): string {
+  switch (entityType) {
+    case 'clinic':
+      return appointment.clinicInfo?.name || 'Unknown';
+    case 'practitioner':
+      return appointment.practitionerInfo?.name || 'Unknown';
+    case 'patient':
+      return appointment.patientInfo?.fullName || 'Unknown';
+    case 'procedure':
+      return appointment.procedureInfo?.name || 'Unknown';
+    case 'technology':
+      return appointment.procedureExtendedInfo?.procedureTechnologyName || 
+             appointment.procedureInfo?.technologyName || 
+             'Unknown';
+  }
+}
+
+/**
+ * Helper to get entity ID from appointment
+ */
+function getEntityId(appointment: Appointment, entityType: EntityType): string {
+  switch (entityType) {
+    case 'clinic':
+      return appointment.clinicBranchId;
+    case 'practitioner':
+      return appointment.practitionerId;
+    case 'patient':
+      return appointment.patientId;
+    case 'procedure':
+      return appointment.procedureId;
+    case 'technology':
+      return appointment.procedureExtendedInfo?.procedureTechnologyId || 
+             'unknown-technology';
+  }
+}
+
+/**
+ * Groups appointments by entity type
+ */
+export function groupAppointmentsByEntity(
+  appointments: Appointment[],
+  entityType: EntityType,
+): Map<string, { name: string; appointments: Appointment[] }> {
+  const entityMap = new Map<string, { name: string; appointments: Appointment[] }>();
+
+  appointments.forEach(appointment => {
+    let entityId: string;
+    let entityName: string;
+
+    if (entityType === 'technology') {
+      entityId = getTechnologyId(appointment);
+      entityName = getTechnologyName(appointment);
+    } else {
+      entityId = getEntityId(appointment, entityType);
+      entityName = getEntityName(appointment, entityType);
+    }
+
+    if (!entityMap.has(entityId)) {
+      entityMap.set(entityId, { name: entityName, appointments: [] });
+    }
+    entityMap.get(entityId)!.appointments.push(appointment);
+  });
+
+  return entityMap;
+}
+
+/**
+ * Calculates grouped revenue metrics
+ * 
+ * IMPORTANT: Only COMPLETED appointments are included in revenue calculations.
+ * Confirmed, pending, canceled, and no-show appointments are excluded from financial metrics.
+ */
+export function calculateGroupedRevenueMetrics(
+  appointments: Appointment[],
+  entityType: EntityType,
+): GroupedRevenueMetrics[] {
+  const entityMap = groupAppointmentsByEntity(appointments, entityType);
+  const completed = getCompletedAppointments(appointments);
+
+  return Array.from(entityMap.entries()).map(([entityId, data]) => {
+    const entityAppointments = data.appointments;
+    const entityCompleted = entityAppointments.filter(a =>
+      completed.some(c => c.id === a.id),
+    );
+
+    const { totalRevenue, currency } = calculateTotalRevenue(entityCompleted);
+
+    // Calculate tax and subtotal
+    let totalTax = 0;
+    let totalSubtotal = 0;
+    let unpaidRevenue = 0;
+    let refundedRevenue = 0;
+
+    entityCompleted.forEach(appointment => {
+      const costData = calculateAppointmentCost(appointment);
+      if (costData.source === 'finalbilling') {
+        totalTax += costData.tax || 0;
+        totalSubtotal += costData.subtotal || 0;
+      } else {
+        totalSubtotal += costData.cost;
+      }
+
+      if (appointment.paymentStatus === 'unpaid') {
+        unpaidRevenue += costData.cost;
+      } else if (appointment.paymentStatus === 'refunded') {
+        refundedRevenue += costData.cost;
+      }
+    });
+
+    // Get practitioner info when grouping by procedure
+    let practitionerId: string | undefined;
+    let practitionerName: string | undefined;
+    if (entityType === 'procedure' && entityAppointments.length > 0) {
+      const firstAppointment = entityAppointments[0];
+      practitionerId = firstAppointment.practitionerId;
+      practitionerName = firstAppointment.practitionerInfo?.name;
+    }
+
+    return {
+      entityId,
+      entityName: data.name,
+      entityType,
+      totalRevenue,
+      averageRevenuePerAppointment:
+        entityCompleted.length > 0 ? totalRevenue / entityCompleted.length : 0,
+      totalAppointments: entityAppointments.length,
+      completedAppointments: entityCompleted.length,
+      currency,
+      unpaidRevenue,
+      refundedRevenue,
+      totalTax,
+      totalSubtotal,
+      ...(practitionerId && { practitionerId }),
+      ...(practitionerName && { practitionerName }),
+    };
+  });
+}
+
+/**
+ * Calculates grouped product usage metrics
+ * 
+ * IMPORTANT: Only COMPLETED appointments are included in product usage calculations.
+ * Products are only considered "used" when the procedure has been completed.
+ * Confirmed, pending, canceled, and no-show appointments are excluded from product metrics.
+ */
+export function calculateGroupedProductUsageMetrics(
+  appointments: Appointment[],
+  entityType: EntityType,
+): GroupedProductUsageMetrics[] {
+  const entityMap = groupAppointmentsByEntity(appointments, entityType);
+  const completed = getCompletedAppointments(appointments);
+
+  return Array.from(entityMap.entries()).map(([entityId, data]) => {
+    const entityAppointments = data.appointments;
+    const entityCompleted = entityAppointments.filter(a =>
+      completed.some(c => c.id === a.id),
+    );
+
+    // Extract all products from completed appointments
+    const productMap = new Map<
+      string,
+      {
+        name: string;
+        brandName: string;
+        quantity: number;
+        revenue: number;
+        usageCount: number;
+      }
+    >();
+
+    entityCompleted.forEach(appointment => {
+      const products = extractProductUsage(appointment);
+      products.forEach(product => {
+        if (productMap.has(product.productId)) {
+          const existing = productMap.get(product.productId)!;
+          existing.quantity += product.quantity;
+          existing.revenue += product.subtotal;
+          existing.usageCount++;
+        } else {
+          productMap.set(product.productId, {
+            name: product.productName,
+            brandName: product.brandName,
+            quantity: product.quantity,
+            revenue: product.subtotal,
+            usageCount: 1,
+          });
+        }
+      });
+    });
+
+    const topProducts = Array.from(productMap.entries())
+      .map(([productId, productData]) => ({
+        productId,
+        productName: productData.name,
+        brandName: productData.brandName,
+        totalQuantity: productData.quantity,
+        totalRevenue: productData.revenue,
+        usageCount: productData.usageCount,
+      }))
+      .sort((a, b) => b.totalRevenue - a.totalRevenue)
+      .slice(0, 10);
+
+    const totalProductRevenue = topProducts.reduce((sum, p) => sum + p.totalRevenue, 0);
+    const totalProductQuantity = topProducts.reduce((sum, p) => sum + p.totalQuantity, 0);
+
+    // Get practitioner info when grouping by procedure
+    let practitionerId: string | undefined;
+    let practitionerName: string | undefined;
+    if (entityType === 'procedure' && entityAppointments.length > 0) {
+      const firstAppointment = entityAppointments[0];
+      practitionerId = firstAppointment.practitionerId;
+      practitionerName = firstAppointment.practitionerInfo?.name;
+    }
+
+    return {
+      entityId,
+      entityName: data.name,
+      entityType,
+      totalProductsUsed: productMap.size,
+      uniqueProducts: productMap.size,
+      totalProductRevenue,
+      totalProductQuantity,
+      averageProductsPerAppointment:
+        entityCompleted.length > 0 ? productMap.size / entityCompleted.length : 0,
+      topProducts,
+      ...(practitionerId && { practitionerId }),
+      ...(practitionerName && { practitionerName }),
+    };
+  });
+}
+
+/**
+ * Calculates grouped time efficiency metrics
+ */
+export function calculateGroupedTimeEfficiencyMetrics(
+  appointments: Appointment[],
+  entityType: EntityType,
+): GroupedTimeEfficiencyMetrics[] {
+  const entityMap = groupAppointmentsByEntity(appointments, entityType);
+  const completed = getCompletedAppointments(appointments);
+
+  return Array.from(entityMap.entries()).map(([entityId, data]) => {
+    const entityAppointments = data.appointments;
+    const entityCompleted = entityAppointments.filter(a =>
+      completed.some(c => c.id === a.id),
+    );
+
+    const timeMetrics = calculateAverageTimeMetrics(entityCompleted);
+
+    // Get practitioner info when grouping by procedure
+    let practitionerId: string | undefined;
+    let practitionerName: string | undefined;
+    if (entityType === 'procedure' && entityAppointments.length > 0) {
+      const firstAppointment = entityAppointments[0];
+      practitionerId = firstAppointment.practitionerId;
+      practitionerName = firstAppointment.practitionerInfo?.name;
+    }
+
+    return {
+      entityId,
+      entityName: data.name,
+      entityType,
+      totalAppointments: entityCompleted.length,
+      appointmentsWithActualTime: timeMetrics.appointmentsWithActualTime,
+      averageBookedDuration: timeMetrics.averageBookedDuration,
+      averageActualDuration: timeMetrics.averageActualDuration,
+      averageEfficiency: timeMetrics.averageEfficiency,
+      totalOverrun: timeMetrics.totalOverrun,
+      totalUnderutilization: timeMetrics.totalUnderutilization,
+      averageOverrun: timeMetrics.averageOverrun,
+      averageUnderutilization: timeMetrics.averageUnderutilization,
+      ...(practitionerId && { practitionerId }),
+      ...(practitionerName && { practitionerName }),
+    };
+  });
+}
+
+/**
+ * Calculates grouped patient behavior metrics
+ */
+export function calculateGroupedPatientBehaviorMetrics(
+  appointments: Appointment[],
+  entityType: EntityType,
+): GroupedPatientBehaviorMetrics[] {
+  const entityMap = groupAppointmentsByEntity(appointments, entityType);
+  const canceled = getCanceledAppointments(appointments);
+  const noShow = getNoShowAppointments(appointments);
+
+  return Array.from(entityMap.entries()).map(([entityId, data]) => {
+    const entityAppointments = data.appointments;
+
+    // Group by patient to analyze behavior
+    const patientMap = new Map<
+      string,
+      {
+        name: string;
+        appointments: Appointment[];
+        noShows: Appointment[];
+        cancellations: Appointment[];
+      }
+    >();
+
+    entityAppointments.forEach(appointment => {
+      const patientId = appointment.patientId;
+      const patientName = appointment.patientInfo?.fullName || 'Unknown';
+
+      if (!patientMap.has(patientId)) {
+        patientMap.set(patientId, {
+          name: patientName,
+          appointments: [],
+          noShows: [],
+          cancellations: [],
+        });
+      }
+
+      const patientData = patientMap.get(patientId)!;
+      patientData.appointments.push(appointment);
+
+      if (noShow.some(ns => ns.id === appointment.id)) {
+        patientData.noShows.push(appointment);
+      }
+      if (canceled.some(c => c.id === appointment.id)) {
+        patientData.cancellations.push(appointment);
+      }
+    });
+
+    // Calculate patient-level metrics
+    const patientMetrics = Array.from(patientMap.entries()).map(([patientId, patientData]) => ({
+      patientId,
+      patientName: patientData.name,
+      noShowCount: patientData.noShows.length,
+      cancellationCount: patientData.cancellations.length,
+      totalAppointments: patientData.appointments.length,
+      noShowRate: calculatePercentage(
+        patientData.noShows.length,
+        patientData.appointments.length,
+      ),
+      cancellationRate: calculatePercentage(
+        patientData.cancellations.length,
+        patientData.appointments.length,
+      ),
+    }));
+
+    const patientsWithNoShows = patientMetrics.filter(p => p.noShowCount > 0).length;
+    const patientsWithCancellations = patientMetrics.filter(p => p.cancellationCount > 0).length;
+
+    const averageNoShowRate =
+      patientMetrics.length > 0
+        ? patientMetrics.reduce((sum, p) => sum + p.noShowRate, 0) / patientMetrics.length
+        : 0;
+
+    const averageCancellationRate =
+      patientMetrics.length > 0
+        ? patientMetrics.reduce((sum, p) => sum + p.cancellationRate, 0) / patientMetrics.length
+        : 0;
+
+    const topNoShowPatients = patientMetrics
+      .filter(p => p.noShowCount > 0)
+      .sort((a, b) => b.noShowRate - a.noShowRate)
+      .slice(0, 10)
+      .map(p => ({
+        patientId: p.patientId,
+        patientName: p.patientName,
+        noShowCount: p.noShowCount,
+        totalAppointments: p.totalAppointments,
+        noShowRate: p.noShowRate,
+      }));
+
+    const topCancellationPatients = patientMetrics
+      .filter(p => p.cancellationCount > 0)
+      .sort((a, b) => b.cancellationRate - a.cancellationRate)
+      .slice(0, 10)
+      .map(p => ({
+        patientId: p.patientId,
+        patientName: p.patientName,
+        cancellationCount: p.cancellationCount,
+        totalAppointments: p.totalAppointments,
+        cancellationRate: p.cancellationRate,
+      }));
+
+    // Determine new vs returning patients
+    const newPatients = patientMetrics.filter(p => p.totalAppointments === 1).length;
+    const returningPatients = patientMetrics.filter(p => p.totalAppointments > 1).length;
+
+    return {
+      entityId,
+      entityName: data.name,
+      entityType,
+      totalPatients: patientMap.size,
+      patientsWithNoShows,
+      patientsWithCancellations,
+      averageNoShowRate: Math.round(averageNoShowRate * 100) / 100,
+      averageCancellationRate: Math.round(averageCancellationRate * 100) / 100,
+      topNoShowPatients,
+      topCancellationPatients,
+    };
+  });
+}
+