@blackcode_sa/metaestetics-api 1.12.68 → 1.13.0

package/src/services/analytics/index.ts

@@ -0,0 +1,3 @@
+export * from './analytics.service';
+export * from './analytics-cloud.service';
+

package/src/services/analytics/utils/appointment-filtering.utils.ts

@@ -0,0 +1,138 @@
+import { Appointment, AppointmentStatus } from '../../../types/appointment';
+import { AnalyticsDateRange, AnalyticsFilters } from '../../../types/analytics';
+
+/**
+ * Filters appointments by date range
+ *
+ * @param appointments - Array of appointments
+ * @param dateRange - Date range filter
+ * @returns Filtered appointments
+ */
+export function filterByDateRange(
+  appointments: Appointment[],
+  dateRange?: AnalyticsDateRange,
+): Appointment[] {
+  if (!dateRange) {
+    return appointments;
+  }
+
+  const startTime = dateRange.start.getTime();
+  const endTime = dateRange.end.getTime();
+
+  return appointments.filter(appointment => {
+    const appointmentTime = appointment.appointmentStartTime.toMillis();
+    return appointmentTime >= startTime && appointmentTime <= endTime;
+  });
+}
+
+/**
+ * Filters appointments by various criteria
+ *
+ * @param appointments - Array of appointments
+ * @param filters - Filter criteria
+ * @returns Filtered appointments
+ */
+export function filterAppointments(
+  appointments: Appointment[],
+  filters?: AnalyticsFilters,
+): Appointment[] {
+  if (!filters) {
+    return appointments;
+  }
+
+  return appointments.filter(appointment => {
+    if (filters.clinicBranchId && appointment.clinicBranchId !== filters.clinicBranchId) {
+      return false;
+    }
+    if (filters.practitionerId && appointment.practitionerId !== filters.practitionerId) {
+      return false;
+    }
+    if (filters.procedureId && appointment.procedureId !== filters.procedureId) {
+      return false;
+    }
+    if (filters.patientId && appointment.patientId !== filters.patientId) {
+      return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * Filters appointments by status
+ *
+ * @param appointments - Array of appointments
+ * @param statuses - Array of statuses to include
+ * @returns Filtered appointments
+ */
+export function filterByStatus(
+  appointments: Appointment[],
+  statuses: AppointmentStatus[],
+): Appointment[] {
+  return appointments.filter(appointment => statuses.includes(appointment.status));
+}
+
+/**
+ * Gets completed appointments (status = COMPLETED)
+ *
+ * @param appointments - Array of appointments
+ * @returns Completed appointments
+ */
+export function getCompletedAppointments(appointments: Appointment[]): Appointment[] {
+  return filterByStatus(appointments, [AppointmentStatus.COMPLETED]);
+}
+
+/**
+ * Gets canceled appointments (all cancellation statuses)
+ *
+ * @param appointments - Array of appointments
+ * @returns Canceled appointments
+ */
+export function getCanceledAppointments(appointments: Appointment[]): Appointment[] {
+  return filterByStatus(appointments, [
+    AppointmentStatus.CANCELED_PATIENT,
+    AppointmentStatus.CANCELED_CLINIC,
+    AppointmentStatus.CANCELED_PATIENT_RESCHEDULED,
+  ]);
+}
+
+/**
+ * Gets no-show appointments
+ *
+ * @param appointments - Array of appointments
+ * @returns No-show appointments
+ */
+export function getNoShowAppointments(appointments: Appointment[]): Appointment[] {
+  return filterByStatus(appointments, [AppointmentStatus.NO_SHOW]);
+}
+
+/**
+ * Gets active appointments (not canceled or no-show)
+ *
+ * @param appointments - Array of appointments
+ * @returns Active appointments
+ */
+export function getActiveAppointments(appointments: Appointment[]): Appointment[] {
+  const inactiveStatuses = [
+    AppointmentStatus.CANCELED_PATIENT,
+    AppointmentStatus.CANCELED_CLINIC,
+    AppointmentStatus.CANCELED_PATIENT_RESCHEDULED,
+    AppointmentStatus.NO_SHOW,
+  ];
+
+  return appointments.filter(appointment => !inactiveStatuses.includes(appointment.status));
+}
+
+/**
+ * Calculates percentage
+ *
+ * @param part - Part value
+ * @param total - Total value
+ * @returns Percentage (0-100)
+ */
+export function calculatePercentage(part: number, total: number): number {
+  if (total === 0) {
+    return 0;
+  }
+  return Math.round((part / total) * 100 * 100) / 100;
+}
+

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

@@ -0,0 +1,154 @@
+import { Appointment, AppointmentMetadata, FinalBilling, ZoneItemData } from '../../../types/appointment';
+
+/**
+ * Calculates the total cost from an appointment's metadata
+ * Priority: finalbilling.finalPrice > zonesData subtotals > appointment.cost
+ *
+ * @param appointment - The appointment to calculate cost for
+ * @returns Object with cost, currency, and calculation source
+ */
+export function calculateAppointmentCost(appointment: Appointment): {
+  cost: number;
+  currency: string;
+  source: 'finalbilling' | 'zonesData' | 'baseCost';
+  subtotal?: number;
+  tax?: number;
+} {
+  const metadata = appointment.metadata;
+  const currency = appointment.currency || 'CHF';
+
+  // Priority 1: Use finalbilling if available
+  if (metadata?.finalbilling) {
+    const finalbilling = metadata.finalbilling as FinalBilling;
+    return {
+      cost: finalbilling.finalPrice,
+      currency: finalbilling.currency || currency,
+      source: 'finalbilling',
+      subtotal: finalbilling.subtotalAll,
+      tax: finalbilling.taxPrice,
+    };
+  }
+
+  // Priority 2: Calculate from zonesData
+  if (metadata?.zonesData) {
+    const zonesData = metadata.zonesData as Record<string, ZoneItemData[]>;
+    let subtotal = 0;
+    let foundCurrency = currency;
+
+    Object.values(zonesData).forEach(items => {
+      items.forEach(item => {
+        if (item.type === 'item' && item.subtotal) {
+          subtotal += item.subtotal;
+          if (item.currency && !foundCurrency) {
+            foundCurrency = item.currency;
+          }
+        }
+      });
+    });
+
+    if (subtotal > 0) {
+      return {
+        cost: subtotal, // Note: This doesn't include tax, but zonesData might not have tax info
+        currency: foundCurrency,
+        source: 'zonesData',
+        subtotal,
+      };
+    }
+  }
+
+  // Priority 3: Fallback to base appointment cost
+  return {
+    cost: appointment.cost || 0,
+    currency,
+    source: 'baseCost',
+  };
+}
+
+/**
+ * Calculates total revenue from an array of appointments
+ *
+ * @param appointments - Array of appointments
+ * @returns Total revenue and currency
+ */
+export function calculateTotalRevenue(appointments: Appointment[]): {
+  totalRevenue: number;
+  currency: string;
+} {
+  if (appointments.length === 0) {
+    return { totalRevenue: 0, currency: 'CHF' };
+  }
+
+  let totalRevenue = 0;
+  const currencies = new Set<string>();
+
+  appointments.forEach(appointment => {
+    const costData = calculateAppointmentCost(appointment);
+    totalRevenue += costData.cost;
+    currencies.add(costData.currency);
+  });
+
+  // Use the most common currency, or first one found
+  const currency = currencies.size > 0 ? Array.from(currencies)[0] : 'CHF';
+
+  return { totalRevenue, currency };
+}
+
+/**
+ * Extracts product usage from appointment metadata
+ *
+ * @param appointment - The appointment to extract products from
+ * @returns Array of product usage data
+ */
+export function extractProductUsage(appointment: Appointment): Array<{
+  productId: string;
+  productName: string;
+  brandId: string;
+  brandName: string;
+  quantity: number;
+  price: number;
+  subtotal: number;
+  currency: string;
+}> {
+  const products: Array<{
+    productId: string;
+    productName: string;
+    brandId: string;
+    brandName: string;
+    quantity: number;
+    price: number;
+    subtotal: number;
+    currency: string;
+  }> = [];
+
+  const metadata = appointment.metadata;
+  if (!metadata?.zonesData) {
+    return products;
+  }
+
+  const zonesData = metadata.zonesData as Record<string, ZoneItemData[]>;
+  const currency = appointment.currency || 'CHF';
+
+  Object.values(zonesData).forEach(items => {
+    items.forEach(item => {
+      if (item.type === 'item' && item.productId) {
+        const price = item.priceOverrideAmount || item.price || 0;
+        const quantity = item.quantity || 1;
+        const subtotal = item.subtotal || price * quantity;
+
+        products.push({
+          productId: item.productId,
+          productName: item.productName || 'Unknown Product',
+          brandId: item.productBrandId || '',
+          brandName: item.productBrandName || '',
+          quantity,
+          price,
+          subtotal,
+          currency: item.currency || currency,
+        });
+      }
+    });
+  });
+
+  return products;
+}
+

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

@@ -0,0 +1,394 @@
+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
+ */
+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;
+      }
+    });
+
+    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,
+    };
+  });
+}
+
+/**
+ * Calculates grouped product usage 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);
+
+    return {
+      entityId,
+      entityName: data.name,
+      entityType,
+      totalProductsUsed: productMap.size,
+      uniqueProducts: productMap.size,
+      totalProductRevenue,
+      totalProductQuantity,
+      averageProductsPerAppointment:
+        entityCompleted.length > 0 ? productMap.size / entityCompleted.length : 0,
+      topProducts,
+    };
+  });
+}
+
+/**
+ * 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);
+
+    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,
+    };
+  });
+}
+
+/**
+ * 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,
+    };
+  });
+}
+