@blackcode_sa/metaestetics-api 1.13.3 → 1.13.5

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

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