@blackcode_sa/metaestetics-api 1.13.0 → 1.13.2

package/src/services/analytics/analytics.service.ts

@@ -13,6 +13,8 @@ import {
   RevenueMetrics,
   RevenueTrend,
   DurationTrend,
+  AppointmentTrend,
+  CancellationRateTrend,
   ProductUsageMetrics,
   ProductRevenueMetrics,
   ProductUsageByProcedure,
@@ -30,6 +32,7 @@ import {
   AnalyticsDateRange,
   AnalyticsFilters,
   GroupingPeriod,
+  TrendPeriod,
   EntityType,
 } from '../../types/analytics';
 
@@ -66,6 +69,12 @@ import {
   calculateGroupedTimeEfficiencyMetrics,
   calculateGroupedPatientBehaviorMetrics,
 } from './utils/grouping.utils';
+import {
+  groupAppointmentsByPeriod,
+  generatePeriods,
+  getTrendChange,
+  type TrendPeriod as TrendPeriodType,
+} from './utils/trend-calculation.utils';
 import { ReadStoredAnalyticsOptions, AnalyticsPeriod } from '../../types/analytics';
 import {
   GroupedRevenueMetrics,
@@ -73,6 +82,8 @@ import {
   GroupedTimeEfficiencyMetrics,
   GroupedPatientBehaviorMetrics,
 } from '../../types/analytics/grouped-analytics.types';
+import { ReviewAnalyticsService, ReviewAnalyticsMetrics, OverallReviewAverages, ReviewDetail } from './review-analytics.service';
+import { ReviewTrend } from '../../types/analytics';
 
 /**
  * AnalyticsService provides comprehensive financial and analytical intelligence
@@ -81,6 +92,7 @@ import {
  */
 export class AnalyticsService extends BaseService {
   private appointmentService: AppointmentService;
+  private reviewAnalyticsService: ReviewAnalyticsService;
 
   /**
    * Creates a new AnalyticsService instance.
@@ -93,6 +105,7 @@ export class AnalyticsService extends BaseService {
   constructor(db: Firestore, auth: Auth, app: FirebaseApp, appointmentService: AppointmentService) {
     super(db, auth, app);
     this.appointmentService = appointmentService;
+    this.reviewAnalyticsService = new ReviewAnalyticsService(db, auth, app, appointmentService);
   }
 
   /**
@@ -757,14 +770,20 @@ export class AnalyticsService extends BaseService {
     canceled: Appointment[],
     allAppointments: Appointment[],
   ): CancellationMetrics[] {
-    const procedureMap = new Map<string, { name: string; canceled: Appointment[]; all: Appointment[] }>();
+    const procedureMap = new Map<string, { name: string; canceled: Appointment[]; all: Appointment[]; practitionerId?: string; practitionerName?: string }>();
 
     allAppointments.forEach(appointment => {
       const procedureId = appointment.procedureId;
       const procedureName = appointment.procedureInfo?.name || 'Unknown';
 
       if (!procedureMap.has(procedureId)) {
-        procedureMap.set(procedureId, { name: procedureName, canceled: [], all: [] });
+        procedureMap.set(procedureId, { 
+          name: procedureName, 
+          canceled: [], 
+          all: [],
+          practitionerId: appointment.practitionerId,
+          practitionerName: appointment.practitionerInfo?.name,
+        });
       }
       procedureMap.get(procedureId)!.all.push(appointment);
     });
@@ -776,15 +795,20 @@ export class AnalyticsService extends BaseService {
       }
     });
 
-    return Array.from(procedureMap.entries()).map(([procedureId, data]) =>
-      this.calculateCancellationMetrics(
+    return Array.from(procedureMap.entries()).map(([procedureId, data]) => {
+      const metrics = this.calculateCancellationMetrics(
         procedureId,
         data.name,
         'procedure',
         data.canceled,
         data.all,
-      ),
-    );
+      );
+      return {
+        ...metrics,
+        ...(data.practitionerId && { practitionerId: data.practitionerId }),
+        ...(data.practitionerName && { practitionerName: data.practitionerName }),
+      };
+    });
   }
 
   /**
@@ -1051,14 +1075,20 @@ export class AnalyticsService extends BaseService {
     noShow: Appointment[],
     allAppointments: Appointment[],
   ): NoShowMetrics[] {
-    const procedureMap = new Map<string, { name: string; noShow: Appointment[]; all: Appointment[] }>();
+    const procedureMap = new Map<string, { name: string; noShow: Appointment[]; all: Appointment[]; practitionerId?: string; practitionerName?: string }>();
 
     allAppointments.forEach(appointment => {
       const procedureId = appointment.procedureId;
       const procedureName = appointment.procedureInfo?.name || 'Unknown';
 
       if (!procedureMap.has(procedureId)) {
-        procedureMap.set(procedureId, { name: procedureName, noShow: [], all: [] });
+        procedureMap.set(procedureId, { 
+          name: procedureName, 
+          noShow: [], 
+          all: [],
+          practitionerId: appointment.practitionerId,
+          practitionerName: appointment.practitionerInfo?.name,
+        });
       }
       procedureMap.get(procedureId)!.all.push(appointment);
     });
@@ -1077,6 +1107,8 @@ export class AnalyticsService extends BaseService {
       totalAppointments: data.all.length,
       noShowAppointments: data.noShow.length,
       noShowRate: calculatePercentage(data.noShow.length, data.all.length),
+      ...(data.practitionerId && { practitionerId: data.practitionerId }),
+      ...(data.practitionerName && { practitionerName: data.practitionerName }),
     }));
   }
 
@@ -1147,6 +1179,10 @@ export class AnalyticsService extends BaseService {
    * Get revenue metrics
    * First checks for stored analytics, then calculates if not available or stale
    *
+   * IMPORTANT: Financial calculations only consider COMPLETED appointments.
+   * Confirmed, pending, canceled, and no-show appointments are NOT included in revenue calculations.
+   * Only procedures that have been completed generate revenue.
+   *
    * @param filters - Optional filters
    * @param dateRange - Optional date range filter
    * @param options - Options for reading stored analytics
@@ -1179,13 +1215,13 @@ export class AnalyticsService extends BaseService {
 
     const { totalRevenue, currency } = calculateTotalRevenue(completed);
 
-    // Calculate revenue by status
+    // Calculate revenue by status - ONLY for COMPLETED appointments
+    // Financial calculations should only consider completed procedures
     const revenueByStatus: Partial<Record<AppointmentStatus, number>> = {};
-    Object.values(AppointmentStatus).forEach(status => {
-      const statusAppointments = appointments.filter(a => a.status === status);
-      const { totalRevenue: statusRevenue } = calculateTotalRevenue(statusAppointments);
-      revenueByStatus[status] = statusRevenue;
-    });
+    // Only calculate revenue for COMPLETED status (other statuses have no revenue)
+    const { totalRevenue: completedRevenue } = calculateTotalRevenue(completed);
+    revenueByStatus[AppointmentStatus.COMPLETED] = completedRevenue;
+    // All other statuses have 0 revenue (confirmed, pending, canceled, etc. don't generate revenue)
 
     // Calculate revenue by payment status
     const revenueByPaymentStatus: Partial<Record<PaymentStatus, number>> = {};
@@ -1253,15 +1289,21 @@ export class AnalyticsService extends BaseService {
   /**
    * Get 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.
+   *
    * @param productId - Optional product ID (if not provided, returns all products)
    * @param dateRange - Optional date range filter
+   * @param filters - Optional filters (e.g., clinicBranchId)
    * @returns Product usage metrics
    */
   async getProductUsageMetrics(
     productId?: string,
     dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
   ): Promise<ProductUsageMetrics | ProductUsageMetrics[]> {
-    const appointments = await this.fetchAppointments(undefined, dateRange);
+    const appointments = await this.fetchAppointments(filters, dateRange);
     const completed = getCompletedAppointments(appointments);
 
     const productMap = new Map<
@@ -1273,12 +1315,16 @@ export class AnalyticsService extends BaseService {
         quantity: number;
         revenue: number;
         usageCount: number;
+        appointmentIds: Set<string>; // Track which appointments used this product
         procedureMap: Map<string, { name: string; count: number; quantity: number }>;
       }
     >();
 
     completed.forEach(appointment => {
       const products = extractProductUsage(appointment);
+      // Track which products were used in this appointment to count appointments, not product entries
+      const productsInThisAppointment = new Set<string>();
+      
       products.forEach(product => {
         if (productId && product.productId !== productId) {
           return;
@@ -1292,6 +1338,7 @@ export class AnalyticsService extends BaseService {
             quantity: 0,
             revenue: 0,
             usageCount: 0,
+            appointmentIds: new Set(),
             procedureMap: new Map(),
           });
         }
@@ -1299,21 +1346,36 @@ export class AnalyticsService extends BaseService {
         const productData = productMap.get(product.productId)!;
         productData.quantity += product.quantity;
         productData.revenue += product.subtotal;
-        productData.usageCount++;
-
-        // Track usage by procedure
-        const procId = appointment.procedureId;
-        const procName = appointment.procedureInfo?.name || 'Unknown';
-        if (productData.procedureMap.has(procId)) {
-          const procData = productData.procedureMap.get(procId)!;
-          procData.count++;
-          procData.quantity += product.quantity;
-        } else {
-          productData.procedureMap.set(procId, {
-            name: procName,
-            count: 1,
-            quantity: product.quantity,
-          });
+        
+        // Track that this product was used in this appointment
+        productsInThisAppointment.add(product.productId);
+      });
+      
+      // After processing all products from this appointment, increment usageCount once per product
+      productsInThisAppointment.forEach(productId => {
+        const productData = productMap.get(productId)!;
+        if (!productData.appointmentIds.has(appointment.id)) {
+          productData.appointmentIds.add(appointment.id);
+          productData.usageCount++;
+          
+          // Track usage by procedure (only once per appointment)
+          const procId = appointment.procedureId;
+          const procName = appointment.procedureInfo?.name || 'Unknown';
+          if (productData.procedureMap.has(procId)) {
+            const procData = productData.procedureMap.get(procId)!;
+            procData.count++;
+            // Sum all quantities for this product in this appointment
+            const appointmentProducts = products.filter(p => p.productId === productId);
+            procData.quantity += appointmentProducts.reduce((sum, p) => sum + p.quantity, 0);
+          } else {
+            const appointmentProducts = products.filter(p => p.productId === productId);
+            const totalQuantity = appointmentProducts.reduce((sum, p) => sum + p.quantity, 0);
+            productData.procedureMap.set(procId, {
+              name: procName,
+              count: 1,
+              quantity: totalQuantity,
+            });
+          }
         }
       });
     });
@@ -1628,5 +1690,453 @@ export class AnalyticsService extends BaseService {
       recentActivity,
     };
   }
+
+  /**
+   * Calculate revenue trends over time
+   * Groups appointments by week/month/quarter/year and calculates revenue metrics
+   *
+   * @param dateRange - Date range for trend analysis (must align with period boundaries)
+   * @param period - Period type (week, month, quarter, year)
+   * @param filters - Optional filters for clinic, practitioner, procedure, patient
+   * @param groupBy - Optional entity type to group trends by (clinic, practitioner, procedure, technology, patient)
+   * @returns Array of revenue trends with percentage changes
+   */
+  async getRevenueTrends(
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    filters?: AnalyticsFilters,
+    groupBy?: EntityType,
+  ): Promise<RevenueTrend[]> {
+    const appointments = await this.fetchAppointments(filters);
+    const filtered = filterByDateRange(appointments, dateRange);
+
+    if (filtered.length === 0) {
+      return [];
+    }
+
+    // If grouping by entity, calculate trends per entity
+    if (groupBy) {
+      return this.getGroupedRevenueTrends(filtered, dateRange, period, groupBy);
+    }
+
+    // Calculate overall trends
+    const periodMap = groupAppointmentsByPeriod(filtered, period as TrendPeriodType);
+    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
+    const trends: RevenueTrend[] = [];
+
+    let previousRevenue = 0;
+    let previousAppointmentCount = 0;
+
+    periods.forEach(periodInfo => {
+      const periodAppointments = periodMap.get(periodInfo.period) || [];
+      const completed = getCompletedAppointments(periodAppointments);
+      const { totalRevenue, currency } = calculateTotalRevenue(completed);
+
+      const appointmentCount = completed.length;
+      const averageRevenue = appointmentCount > 0 ? totalRevenue / appointmentCount : 0;
+
+      const trend: RevenueTrend = {
+        period: periodInfo.period,
+        startDate: periodInfo.startDate,
+        endDate: periodInfo.endDate,
+        revenue: totalRevenue,
+        appointmentCount,
+        averageRevenue,
+        currency,
+      };
+
+      // Calculate percentage change from previous period
+      if (previousRevenue > 0 || previousAppointmentCount > 0) {
+        const revenueChange = getTrendChange(totalRevenue, previousRevenue);
+        trend.previousPeriod = {
+          revenue: previousRevenue,
+          appointmentCount: previousAppointmentCount,
+          percentageChange: revenueChange.percentageChange,
+          direction: revenueChange.direction,
+        };
+      }
+
+      trends.push(trend);
+      previousRevenue = totalRevenue;
+      previousAppointmentCount = appointmentCount;
+    });
+
+    return trends;
+  }
+
+  /**
+   * Calculate revenue trends grouped by entity
+   */
+  private async getGroupedRevenueTrends(
+    appointments: Appointment[],
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    groupBy: EntityType,
+  ): Promise<RevenueTrend[]> {
+    const periodMap = groupAppointmentsByPeriod(appointments, period as TrendPeriodType);
+    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
+    const trends: RevenueTrend[] = [];
+
+    // Group appointments by entity for each period
+    periods.forEach(periodInfo => {
+      const periodAppointments = periodMap.get(periodInfo.period) || [];
+      if (periodAppointments.length === 0) return;
+
+      const groupedMetrics = calculateGroupedRevenueMetrics(periodAppointments, groupBy);
+      
+      // Sum up all entities for this period
+      const totalRevenue = groupedMetrics.reduce((sum, m) => sum + m.totalRevenue, 0);
+      const totalAppointments = groupedMetrics.reduce((sum, m) => sum + m.totalAppointments, 0);
+      const currency = groupedMetrics[0]?.currency || 'CHF';
+      const averageRevenue = totalAppointments > 0 ? totalRevenue / totalAppointments : 0;
+
+      trends.push({
+        period: periodInfo.period,
+        startDate: periodInfo.startDate,
+        endDate: periodInfo.endDate,
+        revenue: totalRevenue,
+        appointmentCount: totalAppointments,
+        averageRevenue,
+        currency,
+      });
+    });
+
+    // Calculate percentage changes
+    for (let i = 1; i < trends.length; i++) {
+      const current = trends[i];
+      const previous = trends[i - 1];
+      const revenueChange = getTrendChange(current.revenue, previous.revenue);
+      
+      current.previousPeriod = {
+        revenue: previous.revenue,
+        appointmentCount: previous.appointmentCount,
+        percentageChange: revenueChange.percentageChange,
+        direction: revenueChange.direction,
+      };
+    }
+
+    return trends;
+  }
+
+  /**
+   * Calculate duration/efficiency trends over time
+   *
+   * @param dateRange - Date range for trend analysis
+   * @param period - Period type (week, month, quarter, year)
+   * @param filters - Optional filters
+   * @param groupBy - Optional entity type to group trends by
+   * @returns Array of duration trends with percentage changes
+   */
+  async getDurationTrends(
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    filters?: AnalyticsFilters,
+    groupBy?: EntityType,
+  ): Promise<DurationTrend[]> {
+    const appointments = await this.fetchAppointments(filters);
+    const filtered = filterByDateRange(appointments, dateRange);
+
+    if (filtered.length === 0) {
+      return [];
+    }
+
+    const periodMap = groupAppointmentsByPeriod(filtered, period as TrendPeriodType);
+    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
+    const trends: DurationTrend[] = [];
+
+    let previousEfficiency = 0;
+    let previousBookedDuration = 0;
+    let previousActualDuration = 0;
+
+    periods.forEach(periodInfo => {
+      const periodAppointments = periodMap.get(periodInfo.period) || [];
+      const completed = getCompletedAppointments(periodAppointments);
+
+      if (groupBy) {
+        // Group by entity and calculate average
+        const groupedMetrics = calculateGroupedTimeEfficiencyMetrics(completed, groupBy);
+        if (groupedMetrics.length === 0) return;
+
+        const totalAppointments = groupedMetrics.reduce((sum, m) => sum + m.totalAppointments, 0);
+        const weightedBooked = groupedMetrics.reduce(
+          (sum, m) => sum + m.averageBookedDuration * m.totalAppointments,
+          0,
+        );
+        const weightedActual = groupedMetrics.reduce(
+          (sum, m) => sum + m.averageActualDuration * m.totalAppointments,
+          0,
+        );
+        const weightedEfficiency = groupedMetrics.reduce(
+          (sum, m) => sum + m.averageEfficiency * m.totalAppointments,
+          0,
+        );
+
+        const averageBookedDuration = totalAppointments > 0 ? weightedBooked / totalAppointments : 0;
+        const averageActualDuration = totalAppointments > 0 ? weightedActual / totalAppointments : 0;
+        const averageEfficiency = totalAppointments > 0 ? weightedEfficiency / totalAppointments : 0;
+
+        const trend: DurationTrend = {
+          period: periodInfo.period,
+          startDate: periodInfo.startDate,
+          endDate: periodInfo.endDate,
+          averageBookedDuration,
+          averageActualDuration,
+          averageEfficiency,
+          appointmentCount: totalAppointments,
+        };
+
+        if (previousEfficiency > 0) {
+          const efficiencyChange = getTrendChange(averageEfficiency, previousEfficiency);
+          trend.previousPeriod = {
+            averageBookedDuration: previousBookedDuration,
+            averageActualDuration: previousActualDuration,
+            averageEfficiency: previousEfficiency,
+            efficiencyPercentageChange: efficiencyChange.percentageChange,
+            direction: efficiencyChange.direction,
+          };
+        }
+
+        trends.push(trend);
+        previousEfficiency = averageEfficiency;
+        previousBookedDuration = averageBookedDuration;
+        previousActualDuration = averageActualDuration;
+      } else {
+        // Overall trends
+        const timeMetrics = calculateAverageTimeMetrics(completed);
+
+        const trend: DurationTrend = {
+          period: periodInfo.period,
+          startDate: periodInfo.startDate,
+          endDate: periodInfo.endDate,
+          averageBookedDuration: timeMetrics.averageBookedDuration,
+          averageActualDuration: timeMetrics.averageActualDuration,
+          averageEfficiency: timeMetrics.averageEfficiency,
+          appointmentCount: timeMetrics.appointmentsWithActualTime,
+        };
+
+        if (previousEfficiency > 0) {
+          const efficiencyChange = getTrendChange(timeMetrics.averageEfficiency, previousEfficiency);
+          trend.previousPeriod = {
+            averageBookedDuration: previousBookedDuration,
+            averageActualDuration: previousActualDuration,
+            averageEfficiency: previousEfficiency,
+            efficiencyPercentageChange: efficiencyChange.percentageChange,
+            direction: efficiencyChange.direction,
+          };
+        }
+
+        trends.push(trend);
+        previousEfficiency = timeMetrics.averageEfficiency;
+        previousBookedDuration = timeMetrics.averageBookedDuration;
+        previousActualDuration = timeMetrics.averageActualDuration;
+      }
+    });
+
+    return trends;
+  }
+
+  /**
+   * Calculate appointment count trends over time
+   *
+   * @param dateRange - Date range for trend analysis
+   * @param period - Period type (week, month, quarter, year)
+   * @param filters - Optional filters
+   * @param groupBy - Optional entity type to group trends by
+   * @returns Array of appointment trends with percentage changes
+   */
+  async getAppointmentTrends(
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    filters?: AnalyticsFilters,
+    groupBy?: EntityType,
+  ): Promise<AppointmentTrend[]> {
+    const appointments = await this.fetchAppointments(filters);
+    const filtered = filterByDateRange(appointments, dateRange);
+
+    if (filtered.length === 0) {
+      return [];
+    }
+
+    const periodMap = groupAppointmentsByPeriod(filtered, period as TrendPeriodType);
+    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
+    const trends: AppointmentTrend[] = [];
+
+    let previousTotal = 0;
+    let previousCompleted = 0;
+
+    periods.forEach(periodInfo => {
+      const periodAppointments = periodMap.get(periodInfo.period) || [];
+      const completed = getCompletedAppointments(periodAppointments);
+      const canceled = getCanceledAppointments(periodAppointments);
+      const noShow = getNoShowAppointments(periodAppointments);
+      const pending = periodAppointments.filter(a => a.status === AppointmentStatus.PENDING);
+      const confirmed = periodAppointments.filter(a => a.status === AppointmentStatus.CONFIRMED);
+
+      const trend: AppointmentTrend = {
+        period: periodInfo.period,
+        startDate: periodInfo.startDate,
+        endDate: periodInfo.endDate,
+        totalAppointments: periodAppointments.length,
+        completedAppointments: completed.length,
+        canceledAppointments: canceled.length,
+        noShowAppointments: noShow.length,
+        pendingAppointments: pending.length,
+        confirmedAppointments: confirmed.length,
+      };
+
+      if (previousTotal > 0) {
+        const totalChange = getTrendChange(periodAppointments.length, previousTotal);
+        trend.previousPeriod = {
+          totalAppointments: previousTotal,
+          completedAppointments: previousCompleted,
+          percentageChange: totalChange.percentageChange,
+          direction: totalChange.direction,
+        };
+      }
+
+      trends.push(trend);
+      previousTotal = periodAppointments.length;
+      previousCompleted = completed.length;
+    });
+
+    return trends;
+  }
+
+  /**
+   * Calculate cancellation and no-show rate trends over time
+   *
+   * @param dateRange - Date range for trend analysis
+   * @param period - Period type (week, month, quarter, year)
+   * @param filters - Optional filters
+   * @param groupBy - Optional entity type to group trends by
+   * @returns Array of cancellation rate trends with percentage changes
+   */
+  async getCancellationRateTrends(
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    filters?: AnalyticsFilters,
+    groupBy?: EntityType,
+  ): Promise<CancellationRateTrend[]> {
+    const appointments = await this.fetchAppointments(filters);
+    const filtered = filterByDateRange(appointments, dateRange);
+
+    if (filtered.length === 0) {
+      return [];
+    }
+
+    const periodMap = groupAppointmentsByPeriod(filtered, period as TrendPeriodType);
+    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
+    const trends: CancellationRateTrend[] = [];
+
+    let previousCancellationRate = 0;
+    let previousNoShowRate = 0;
+
+    periods.forEach(periodInfo => {
+      const periodAppointments = periodMap.get(periodInfo.period) || [];
+      const canceled = getCanceledAppointments(periodAppointments);
+      const noShow = getNoShowAppointments(periodAppointments);
+
+      const cancellationRate = calculatePercentage(canceled.length, periodAppointments.length);
+      const noShowRate = calculatePercentage(noShow.length, periodAppointments.length);
+
+      const trend: CancellationRateTrend = {
+        period: periodInfo.period,
+        startDate: periodInfo.startDate,
+        endDate: periodInfo.endDate,
+        cancellationRate,
+        noShowRate,
+        totalAppointments: periodAppointments.length,
+        canceledAppointments: canceled.length,
+        noShowAppointments: noShow.length,
+      };
+
+      if (previousCancellationRate > 0 || previousNoShowRate > 0) {
+        const cancellationChange = getTrendChange(cancellationRate, previousCancellationRate);
+        const noShowChange = getTrendChange(noShowRate, previousNoShowRate);
+        
+        trend.previousPeriod = {
+          cancellationRate: previousCancellationRate,
+          noShowRate: previousNoShowRate,
+          cancellationRateChange: cancellationChange.percentageChange,
+          noShowRateChange: noShowChange.percentageChange,
+          direction: cancellationChange.direction, // Use cancellation direction as primary
+        };
+      }
+
+      trends.push(trend);
+      previousCancellationRate = cancellationRate;
+      previousNoShowRate = noShowRate;
+    });
+
+    return trends;
+  }
+
+  // ==========================================
+  // Review Analytics Methods
+  // ==========================================
+
+  /**
+   * Get review metrics for a specific entity (practitioner, procedure, etc.)
+   */
+  async getReviewMetricsByEntity(
+    entityType: 'practitioner' | 'procedure' | 'category' | 'subcategory' | 'technology',
+    entityId: string,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters
+  ): Promise<ReviewAnalyticsMetrics | null> {
+    return this.reviewAnalyticsService.getReviewMetricsByEntity(entityType, entityId, dateRange, filters);
+  }
+
+  /**
+   * Get review metrics for multiple entities (grouped)
+   */
+  async getReviewMetricsByEntities(
+    entityType: 'practitioner' | 'procedure' | 'category' | 'subcategory' | 'technology',
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters
+  ): Promise<ReviewAnalyticsMetrics[]> {
+    return this.reviewAnalyticsService.getReviewMetricsByEntities(entityType, dateRange, filters);
+  }
+
+  /**
+   * Get overall review averages for comparison
+   */
+  async getOverallReviewAverages(
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters
+  ): Promise<OverallReviewAverages> {
+    return this.reviewAnalyticsService.getOverallReviewAverages(dateRange, filters);
+  }
+
+  /**
+   * Get review details for a specific entity
+   */
+  async getReviewDetails(
+    entityType: 'practitioner' | 'procedure',
+    entityId: string,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters
+  ): Promise<ReviewDetail[]> {
+    return this.reviewAnalyticsService.getReviewDetails(entityType, entityId, dateRange, filters);
+  }
+
+  /**
+   * Calculate review trends over time
+   * Groups reviews by period and calculates rating and recommendation metrics
+   *
+   * @param dateRange - Date range for trend analysis
+   * @param period - Period type (week, month, quarter, year)
+   * @param filters - Optional filters for clinic, practitioner, procedure
+   * @param entityType - Optional entity type to group trends by
+   * @returns Array of review trends with percentage changes
+   */
+  async getReviewTrends(
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    filters?: AnalyticsFilters,
+    entityType?: 'practitioner' | 'procedure' | 'technology'
+  ): Promise<ReviewTrend[]> {
+    return this.reviewAnalyticsService.getReviewTrends(dateRange, period, filters, entityType);
+  }
 }