@blackcode_sa/metaestetics-api 1.13.0 → 1.13.2

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

@@ -67,7 +67,11 @@ export function calculateAppointmentCost(appointment: Appointment): {
 /**
  * Calculates total revenue from an array of appointments
  *
- * @param appointments - Array of appointments
+ * IMPORTANT: This function should only be called with COMPLETED appointments.
+ * Only completed procedures generate revenue. Confirmed, pending, canceled, and no-show
+ * appointments should be filtered out before calling this function.
+ *
+ * @param appointments - Array of appointments (should be filtered to COMPLETED only)
  * @returns Total revenue and currency
  */
 export function calculateTotalRevenue(appointments: Appointment[]): {
@@ -96,8 +100,19 @@ export function calculateTotalRevenue(appointments: Appointment[]): {
 /**
  * Extracts product usage from appointment metadata
  *
- * @param appointment - The appointment to extract products from
- * @returns Array of product usage data
+ * IMPORTANT: This function should only be called with COMPLETED appointments.
+ * Products are only considered "used" when the procedure has been completed.
+ * Only completed procedures generate product usage and revenue.
+ *
+ * NOTE ON PRICING:
+ * - Price overrides (priceOverrideAmount) are always applied if available
+ * - Subtotal is recalculated to ensure price overrides are reflected
+ * - Product revenue shows SUBTOTAL (before tax) - tax is applied at appointment level
+ * - Tax is included in appointment revenue (finalbilling.finalPrice) but not in product revenue
+ * - Product subtotals should sum to finalbilling.subtotalAll (before tax)
+ *
+ * @param appointment - The appointment to extract products from (should be COMPLETED)
+ * @returns Array of product usage data with subtotal (before tax)
  */
 export function extractProductUsage(appointment: Appointment): Array<{
   productId: string;
@@ -131,9 +146,22 @@ export function extractProductUsage(appointment: Appointment): Array<{
   Object.values(zonesData).forEach(items => {
     items.forEach(item => {
       if (item.type === 'item' && item.productId) {
+        // Always use priceOverrideAmount if available, otherwise use price
+        // This ensures price overrides are properly applied to product calculations
         const price = item.priceOverrideAmount || item.price || 0;
         const quantity = item.quantity || 1;
-        const subtotal = item.subtotal || price * quantity;
+        
+        // Always recalculate subtotal based on the actual price (with override)
+        // This ensures price overrides are reflected in product revenue
+        // Use stored subtotal only if it matches the calculated value (to handle rounding)
+        const calculatedSubtotal = price * quantity;
+        const storedSubtotal = item.subtotal || 0;
+        
+        // Use stored subtotal if it's close to calculated (within 0.01 for rounding differences)
+        // Otherwise recalculate to ensure price override is applied correctly
+        const subtotal = Math.abs(storedSubtotal - calculatedSubtotal) < 0.01 
+          ? storedSubtotal 
+          : calculatedSubtotal;
 
         products.push({
           productId: item.productId,

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

@@ -101,6 +101,9 @@ export function groupAppointmentsByEntity(
 
 /**
  * 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[],
@@ -139,6 +142,15 @@ export function calculateGroupedRevenueMetrics(
       }
     });
 
+    // 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,
@@ -153,12 +165,18 @@ export function calculateGroupedRevenueMetrics(
       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[],
@@ -220,6 +238,15 @@ export function calculateGroupedProductUsageMetrics(
     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,
@@ -231,6 +258,8 @@ export function calculateGroupedProductUsageMetrics(
       averageProductsPerAppointment:
         entityCompleted.length > 0 ? productMap.size / entityCompleted.length : 0,
       topProducts,
+      ...(practitionerId && { practitionerId }),
+      ...(practitionerName && { practitionerName }),
     };
   });
 }
@@ -253,6 +282,15 @@ export function calculateGroupedTimeEfficiencyMetrics(
 
     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,
@@ -266,6 +304,8 @@ export function calculateGroupedTimeEfficiencyMetrics(
       totalUnderutilization: timeMetrics.totalUnderutilization,
       averageOverrun: timeMetrics.averageOverrun,
       averageUnderutilization: timeMetrics.averageUnderutilization,
+      ...(practitionerId && { practitionerId }),
+      ...(practitionerName && { practitionerName }),
     };
   });
 }

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

@@ -0,0 +1,200 @@
+import { Appointment } from '../../../types/appointment';
+import { Timestamp } from 'firebase/firestore';
+
+/**
+ * Trend period type
+ */
+export type TrendPeriod = 'week' | 'month' | 'quarter' | 'year';
+
+/**
+ * Period information for trend grouping
+ */
+export interface PeriodInfo {
+  period: string; // e.g., "2024-W01", "2024-01", "2024-Q1", "2024"
+  startDate: Date;
+  endDate: Date;
+}
+
+/**
+ * Calculates the start and end dates for a given period
+ */
+export function getPeriodDates(date: Date, period: TrendPeriod): PeriodInfo {
+  const year = date.getFullYear();
+  const month = date.getMonth();
+  const day = date.getDate();
+
+  let startDate: Date;
+  let endDate: Date;
+  let periodString: string;
+
+  switch (period) {
+    case 'week': {
+      // Get Monday of the week
+      const dayOfWeek = date.getDay();
+      const diff = date.getDate() - dayOfWeek + (dayOfWeek === 0 ? -6 : 1); // Adjust when day is Sunday
+      startDate = new Date(year, month, diff);
+      startDate.setHours(0, 0, 0, 0);
+      
+      endDate = new Date(startDate);
+      endDate.setDate(endDate.getDate() + 6);
+      endDate.setHours(23, 59, 59, 999);
+
+      // ISO week format: YYYY-Www
+      const weekNumber = getWeekNumber(date);
+      periodString = `${year}-W${weekNumber.toString().padStart(2, '0')}`;
+      break;
+    }
+
+    case 'month': {
+      startDate = new Date(year, month, 1);
+      startDate.setHours(0, 0, 0, 0);
+      
+      endDate = new Date(year, month + 1, 0);
+      endDate.setHours(23, 59, 59, 999);
+
+      periodString = `${year}-${(month + 1).toString().padStart(2, '0')}`;
+      break;
+    }
+
+    case 'quarter': {
+      const quarter = Math.floor(month / 3);
+      const quarterStartMonth = quarter * 3;
+      
+      startDate = new Date(year, quarterStartMonth, 1);
+      startDate.setHours(0, 0, 0, 0);
+      
+      endDate = new Date(year, quarterStartMonth + 3, 0);
+      endDate.setHours(23, 59, 59, 999);
+
+      periodString = `${year}-Q${quarter + 1}`;
+      break;
+    }
+
+    case 'year': {
+      startDate = new Date(year, 0, 1);
+      startDate.setHours(0, 0, 0, 0);
+      
+      endDate = new Date(year, 11, 31);
+      endDate.setHours(23, 59, 59, 999);
+
+      periodString = `${year}`;
+      break;
+    }
+  }
+
+  return {
+    period: periodString,
+    startDate,
+    endDate,
+  };
+}
+
+/**
+ * Gets ISO week number for a date
+ */
+function getWeekNumber(date: Date): number {
+  const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
+  const dayNum = d.getUTCDay() || 7;
+  d.setUTCDate(d.getUTCDate() + 4 - dayNum);
+  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+  return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+}
+
+/**
+ * Groups appointments by trend period
+ */
+export function groupAppointmentsByPeriod(
+  appointments: Appointment[],
+  period: TrendPeriod,
+): Map<string, Appointment[]> {
+  const periodMap = new Map<string, Appointment[]>();
+
+  appointments.forEach(appointment => {
+    const appointmentDate = appointment.appointmentStartTime.toDate();
+    const periodInfo = getPeriodDates(appointmentDate, period);
+    const periodKey = periodInfo.period;
+
+    if (!periodMap.has(periodKey)) {
+      periodMap.set(periodKey, []);
+    }
+    periodMap.get(periodKey)!.push(appointment);
+  });
+
+  return periodMap;
+}
+
+/**
+ * Generates all periods between start and end date for a given period type
+ */
+export function generatePeriods(
+  startDate: Date,
+  endDate: Date,
+  period: TrendPeriod,
+): PeriodInfo[] {
+  const periods: PeriodInfo[] = [];
+  const current = new Date(startDate);
+
+  while (current <= endDate) {
+    const periodInfo = getPeriodDates(current, period);
+    
+    // Only add if period overlaps with our date range
+    if (periodInfo.endDate >= startDate && periodInfo.startDate <= endDate) {
+      periods.push(periodInfo);
+    }
+
+    // Move to next period
+    switch (period) {
+      case 'week':
+        current.setDate(current.getDate() + 7);
+        break;
+      case 'month':
+        current.setMonth(current.getMonth() + 1);
+        break;
+      case 'quarter':
+        current.setMonth(current.getMonth() + 3);
+        break;
+      case 'year':
+        current.setFullYear(current.getFullYear() + 1);
+        break;
+    }
+  }
+
+  return periods.sort((a, b) => a.startDate.getTime() - b.startDate.getTime());
+}
+
+/**
+ * Calculates percentage change between two values
+ * @param current - Current value
+ * @param previous - Previous value
+ * @returns Percentage change (positive = increase, negative = decrease)
+ */
+export function calculatePercentageChange(current: number, previous: number): number {
+  if (previous === 0) {
+    return current > 0 ? 100 : 0;
+  }
+  return ((current - previous) / previous) * 100;
+}
+
+/**
+ * Gets trend direction and percentage change
+ */
+export interface TrendChange {
+  value: number;
+  previousValue: number;
+  percentageChange: number;
+  direction: 'up' | 'down' | 'stable';
+}
+
+export function getTrendChange(current: number, previous: number): TrendChange {
+  const percentageChange = calculatePercentageChange(current, previous);
+  const direction: 'up' | 'down' | 'stable' =
+    percentageChange > 0.01 ? 'up' : percentageChange < -0.01 ? 'down' : 'stable';
+
+  return {
+    value: current,
+    previousValue: previous,
+    percentageChange: Math.abs(percentageChange),
+    direction,
+  };
+}
+

package/src/services/appointment/appointment.service.ts

@@ -1833,6 +1833,12 @@ export class AppointmentService extends BaseService {
         finalizationNotes: null,
       };
 
+      // Update payment status if billing data exists but status is NOT_APPLICABLE
+      // This handles cases where appointment was created with price 0 but billing was added later
+      const shouldUpdatePaymentStatus =
+        finalbilling.finalPrice > 0 &&
+        appointment.paymentStatus === PaymentStatus.NOT_APPLICABLE;
+
       const updateData: UpdateAppointmentData = {
         metadata: {
           selectedZones: currentMetadata.selectedZones,
@@ -1848,6 +1854,9 @@ export class AppointmentService extends BaseService {
           finalbilling,
           finalizationNotes: currentMetadata.finalizationNotes,
         },
+        ...(shouldUpdatePaymentStatus && {
+          paymentStatus: PaymentStatus.UNPAID,
+        }),
         updatedAt: serverTimestamp(),
       };