@blackcode_sa/metaestetics-api 1.13.3 → 1.13.5

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

@@ -1,941 +1,941 @@
-import { Firestore, collection, query, where, getDocs, getDoc, doc, Timestamp } from 'firebase/firestore';
-import { BaseService } from '../base.service';
-import { Review, PractitionerReview, ProcedureReview, REVIEWS_COLLECTION } from '../../types/reviews';
-import { Appointment, APPOINTMENTS_COLLECTION } from '../../types/appointment';
-import { AnalyticsDateRange, AnalyticsFilters, ReviewTrend, TrendPeriod } from '../../types/analytics';
-import { AppointmentService } from '../appointment/appointment.service';
-import { 
-  groupAppointmentsByPeriod,
-  generatePeriods,
-  getTrendChange,
-  type TrendPeriod as TrendPeriodType,
-  type PeriodInfo,
-} from './utils/trend-calculation.utils';
-
-/**
- * Review metrics for a specific entity (practitioner, procedure, etc.)
- * Full review analytics metrics with detailed breakdowns
- */
-export interface ReviewAnalyticsMetrics {
-  entityId: string;
-  entityName: string;
-  entityType: 'practitioner' | 'procedure' | 'category' | 'subcategory' | 'technology';
-  
-  // Overall metrics
-  totalReviews: number;
-  averageRating: number;
-  recommendationRate: number; // % that would recommend
-  
-  // For Practitioner reviews
-  practitionerMetrics?: {
-    averageKnowledgeAndExpertise: number;
-    averageCommunicationSkills: number;
-    averageBedSideManner: number;
-    averageThoroughness: number;
-    averageTrustworthiness: number;
-  };
-  
-  // For Procedure reviews
-  procedureMetrics?: {
-    averageEffectiveness: number;
-    averageOutcomeExplanation: number;
-    averagePainManagement: number;
-    averageFollowUpCare: number;
-    averageValueForMoney: number;
-  };
-  
-  // Comparison to overall average
-  comparisonToOverall: {
-    ratingDifference: number; // Positive = above average, negative = below
-    recommendationDifference: number; // % difference
-  };
-}
-
-/**
- * Review detail with full information
- */
-export interface ReviewDetail {
-  reviewId: string;
-  appointmentId: string;
-  patientId: string;
-  patientName?: string;
-  createdAt: Date;
-  
-  // Relevant sub-review based on entityType
-  practitionerReview?: PractitionerReview;
-  procedureReview?: ProcedureReview;
-  
-  // Context from appointment
-  procedureName?: string;
-  practitionerName?: string;
-  appointmentDate: Date;
-}
-
-/**
- * Overall review averages for comparison
- */
-export interface OverallReviewAverages {
-  // Overall practitioner averages
-  practitionerAverage: {
-    totalReviews: number;
-    averageRating: number;
-    recommendationRate: number;
-    averageKnowledgeAndExpertise: number;
-    averageCommunicationSkills: number;
-    averageBedSideManner: number;
-    averageThoroughness: number;
-    averageTrustworthiness: number;
-  };
-  
-  // Overall procedure averages
-  procedureAverage: {
-    totalReviews: number;
-    averageRating: number;
-    recommendationRate: number;
-    averageEffectiveness: number;
-    averageOutcomeExplanation: number;
-    averagePainManagement: number;
-    averageFollowUpCare: number;
-    averageValueForMoney: number;
-  };
-}
-
-/**
- * Review Analytics Service
- * Provides review metrics and analytics for practitioners, procedures, categories, and technologies
- */
-export class ReviewAnalyticsService extends BaseService {
-  private appointmentService: AppointmentService;
-
-  constructor(db: Firestore, auth: any, app: any, appointmentService?: AppointmentService) {
-    super(db, auth, app);
-    // AppointmentService is optional - will be set if provided
-    this.appointmentService = appointmentService as AppointmentService;
-  }
-  /**
-   * Fetches reviews filtered by date range and optional filters
-   * Properly filters by clinic branch by checking appointment's clinicId
-   */
-  private async fetchReviews(
-    dateRange?: AnalyticsDateRange,
-    filters?: AnalyticsFilters
-  ): Promise<Review[]> {
-    let q = query(collection(this.db, REVIEWS_COLLECTION));
-    
-    // Apply date range filter
-    if (dateRange) {
-      const startTimestamp = Timestamp.fromDate(dateRange.start);
-      const endTimestamp = Timestamp.fromDate(dateRange.end);
-      q = query(q, where('createdAt', '>=', startTimestamp), where('createdAt', '<=', endTimestamp));
-    }
-    
-    const snapshot = await getDocs(q);
-    const reviews = snapshot.docs.map(doc => {
-      const data = doc.data();
-      return {
-        ...data,
-        id: doc.id,
-        createdAt: data.createdAt?.toDate ? data.createdAt.toDate() : new Date(data.createdAt),
-        updatedAt: data.updatedAt?.toDate ? data.updatedAt.toDate() : new Date(data.updatedAt),
-      } as Review;
-    });
-    
-    console.log(`[ReviewAnalytics] Fetched ${reviews.length} reviews in date range`);
-    
-    // Filter by clinic branch if specified
-    if (filters?.clinicBranchId && reviews.length > 0) {
-      // We need to fetch appointments to check which clinic they belong to
-      // Firestore 'in' operator supports max 10 items, so we batch
-      const appointmentIds = [...new Set(reviews.map(r => r.appointmentId))];
-      console.log(`[ReviewAnalytics] Filtering by clinic ${filters.clinicBranchId}, checking ${appointmentIds.length} appointments`);
-      
-      const validAppointmentIds = new Set<string>();
-      
-      // Process in batches of 10
-      for (let i = 0; i < appointmentIds.length; i += 10) {
-        const batch = appointmentIds.slice(i, i + 10);
-        const appointmentsQuery = query(
-          collection(this.db, APPOINTMENTS_COLLECTION),
-          where('id', 'in', batch)
-        );
-        const appointmentSnapshot = await getDocs(appointmentsQuery);
-        
-        appointmentSnapshot.docs.forEach(doc => {
-          const appointment = doc.data() as Appointment;
-          // Appointment uses 'clinicBranchId' field directly
-          if (appointment.clinicBranchId === filters.clinicBranchId) {
-            validAppointmentIds.add(doc.id);
-          }
-        });
-      }
-      
-      const filteredReviews = reviews.filter(review => validAppointmentIds.has(review.appointmentId));
-      console.log(`[ReviewAnalytics] After clinic filter: ${filteredReviews.length} reviews (from ${validAppointmentIds.size} valid appointments)`);
-      
-      return filteredReviews;
-    }
-    
-    return reviews;
-  }
-  
-  /**
-   * Gets review metrics for a specific entity
-   */
-  async getReviewMetricsByEntity(
-    entityType: 'practitioner' | 'procedure' | 'category' | 'subcategory' | 'technology',
-    entityId: string,
-    dateRange?: AnalyticsDateRange,
-    filters?: AnalyticsFilters
-  ): Promise<ReviewAnalyticsMetrics | null> {
-    const reviews = await this.fetchReviews(dateRange, filters);
-    
-    // Filter reviews based on entity type
-    let relevantReviews: Review[] = [];
-    
-    if (entityType === 'practitioner') {
-      relevantReviews = reviews.filter(r => r.practitionerReview?.practitionerId === entityId);
-    } else if (entityType === 'procedure') {
-      relevantReviews = reviews.filter(r => r.procedureReview?.procedureId === entityId);
-    } else if (entityType === 'category' || entityType === 'subcategory') {
-      // For category/subcategory, we need to get reviews for all procedures in that category
-      // This requires fetching appointments to get procedure info
-      // For now, we'll need to enhance this with appointment data
-      relevantReviews = reviews; // Placeholder - will be enhanced
-    }
-    
-    if (relevantReviews.length === 0) {
-      return null;
-    }
-    
-    // Calculate metrics
-    return this.calculateReviewMetrics(relevantReviews, entityType, entityId);
-  }
-  
-  /**
-   * Gets review metrics for multiple entities (grouped)
-   */
-  async getReviewMetricsByEntities(
-    entityType: 'practitioner' | 'procedure' | 'category' | 'subcategory' | 'technology',
-    dateRange?: AnalyticsDateRange,
-    filters?: AnalyticsFilters
-  ): Promise<ReviewAnalyticsMetrics[]> {
-    const reviews = await this.fetchReviews(dateRange, filters);
-    const entityMap = new Map<string, { reviews: Review[]; name: string }>();
-    
-    // For practitioner, procedure, and technology, we fetch appointments to get actual names
-    // (Reviews have IDs stored in name fields, not actual names)
-    let practitionerNameMap: Map<string, string> | null = null;
-    let procedureNameMap: Map<string, string> | null = null;
-    let procedureToTechnologyMap: Map<string, { id: string; name: string }> | null = null;
-    
-    if (entityType === 'practitioner' || entityType === 'procedure' || entityType === 'technology') {
-      if (!this.appointmentService) {
-        console.warn(`[ReviewAnalytics] AppointmentService not available for ${entityType} name resolution`);
-        return [];
-      }
-      
-      console.log(`[ReviewAnalytics] Grouping by ${entityType}, fetching appointments for name resolution...`);
-      
-      // Fetch all appointments to build name mapping tables
-      const searchParams: any = {
-        ...filters,
-      };
-      if (dateRange) {
-        searchParams.startDate = dateRange.start;
-        searchParams.endDate = dateRange.end;
-      }
-      const appointmentsResult = await this.appointmentService.searchAppointments(searchParams);
-      const appointments = appointmentsResult.appointments || [];
-      
-      console.log(`[ReviewAnalytics] Found ${appointments.length} appointments for name resolution`);
-      
-      // Build all name mapping tables
-      practitionerNameMap = new Map<string, string>();
-      procedureNameMap = new Map<string, string>();
-      procedureToTechnologyMap = new Map<string, { id: string; name: string }>();
-      
-      appointments.forEach((appointment: Appointment) => {
-        // Map practitioner ID -> name
-        if (appointment.practitionerId && appointment.practitionerInfo?.name) {
-          practitionerNameMap!.set(appointment.practitionerId, appointment.practitionerInfo.name);
-        }
-        
-        // Map main procedure ID -> name
-        if (appointment.procedureId) {
-          if (appointment.procedureInfo?.name) {
-            procedureNameMap!.set(appointment.procedureId, appointment.procedureInfo.name);
-          }
-          
-          // Map procedure -> technology
-          const mainTechnologyId = appointment.procedureExtendedInfo?.procedureTechnologyId || 'unknown-technology';
-          const mainTechnologyName = appointment.procedureExtendedInfo?.procedureTechnologyName ||
-                                    appointment.procedureInfo?.name ||
-                                    'Unknown Technology';
-          procedureToTechnologyMap!.set(appointment.procedureId, {
-            id: mainTechnologyId,
-            name: mainTechnologyName,
-          });
-        }
-        
-        // Map extended procedures
-        if (appointment.metadata?.extendedProcedures) {
-          appointment.metadata.extendedProcedures.forEach((extendedProc) => {
-            if (extendedProc.procedureId) {
-              if (extendedProc.procedureName) {
-                procedureNameMap!.set(extendedProc.procedureId, extendedProc.procedureName);
-              }
-              
-              const extTechnologyId = extendedProc.procedureTechnologyId || 'unknown-technology';
-              const extTechnologyName = extendedProc.procedureTechnologyName || 'Unknown Technology';
-              procedureToTechnologyMap!.set(extendedProc.procedureId, {
-                id: extTechnologyId,
-                name: extTechnologyName,
-              });
-            }
-          });
-        }
-      });
-      
-      console.log(`[ReviewAnalytics] Built name maps: ${practitionerNameMap.size} practitioners, ${procedureNameMap.size} procedures, ${procedureToTechnologyMap.size} technologies`);
-    }
-    
-    // Now group reviews based on entity type
-    if (entityType === 'technology' && procedureToTechnologyMap) {
-      let processedReviewCount = 0;
-      
-      reviews.forEach(review => {
-        // Process main procedure review
-        if (review.procedureReview?.procedureId) {
-          const techInfo = procedureToTechnologyMap!.get(review.procedureReview.procedureId);
-          if (techInfo) {
-            if (!entityMap.has(techInfo.id)) {
-              entityMap.set(techInfo.id, { reviews: [], name: techInfo.name });
-            }
-            entityMap.get(techInfo.id)!.reviews.push(review);
-            processedReviewCount++;
-          }
-        }
-        
-        // Process extended procedure reviews
-        if (review.extendedProcedureReviews && review.extendedProcedureReviews.length > 0) {
-          review.extendedProcedureReviews.forEach((extendedReview) => {
-            if (extendedReview.procedureId) {
-              const techInfo = procedureToTechnologyMap!.get(extendedReview.procedureId);
-              if (techInfo) {
-                if (!entityMap.has(techInfo.id)) {
-                  entityMap.set(techInfo.id, { reviews: [], name: techInfo.name });
-                }
-                const reviewWithExtendedOnly: Review = {
-                  ...review,
-                  procedureReview: extendedReview,
-                  extendedProcedureReviews: undefined,
-                };
-                entityMap.get(techInfo.id)!.reviews.push(reviewWithExtendedOnly);
-                processedReviewCount++;
-              }
-            }
-          });
-        }
-      });
-      
-      console.log(`[ReviewAnalytics] Processed ${processedReviewCount} procedure reviews into ${entityMap.size} technology groups`);
-      entityMap.forEach((data, techId) => {
-        console.log(`[ReviewAnalytics]   - ${data.name} (${techId}): ${data.reviews.length} reviews`);
-      });
-    } else if (entityType === 'procedure' && procedureNameMap) {
-      let processedReviewCount = 0;
-      
-      reviews.forEach(review => {
-        // Process main procedure review
-        if (review.procedureReview) {
-          const procedureId = review.procedureReview.procedureId;
-          // Use actual name from appointment, fallback to review name, then 'Unknown'
-          const procedureName = (procedureId && procedureNameMap!.get(procedureId)) ||
-                                review.procedureReview.procedureName ||
-                                'Unknown Procedure';
-          
-          if (procedureId) {
-            if (!entityMap.has(procedureId)) {
-              entityMap.set(procedureId, { reviews: [], name: procedureName });
-            }
-            entityMap.get(procedureId)!.reviews.push(review);
-            processedReviewCount++;
-          }
-        }
-        
-        // Process extended procedure reviews
-        if (review.extendedProcedureReviews && review.extendedProcedureReviews.length > 0) {
-          review.extendedProcedureReviews.forEach((extendedReview) => {
-            const procedureId = extendedReview.procedureId;
-            // Use actual name from appointment, fallback to review name, then 'Unknown'
-            const procedureName = (procedureId && procedureNameMap!.get(procedureId)) ||
-                                  extendedReview.procedureName ||
-                                  'Unknown Procedure';
-            
-            if (procedureId) {
-              if (!entityMap.has(procedureId)) {
-                entityMap.set(procedureId, { reviews: [], name: procedureName });
-              }
-              const reviewWithExtendedOnly: Review = {
-                ...review,
-                procedureReview: extendedReview,
-                extendedProcedureReviews: undefined,
-              };
-              entityMap.get(procedureId)!.reviews.push(reviewWithExtendedOnly);
-              processedReviewCount++;
-            }
-          });
-        }
-      });
-      
-      console.log(`[ReviewAnalytics] Processed ${processedReviewCount} procedure reviews into ${entityMap.size} procedure groups`);
-      entityMap.forEach((data, procId) => {
-        console.log(`[ReviewAnalytics]   - ${data.name} (${procId}): ${data.reviews.length} reviews`);
-      });
-    } else if (entityType === 'practitioner' && practitionerNameMap) {
-      // Group reviews by practitioner
-      reviews.forEach(review => {
-        if (review.practitionerReview) {
-          const practitionerId = review.practitionerReview.practitionerId;
-          // Use actual name from appointment, fallback to review name, then 'Unknown'
-          const practitionerName = (practitionerId && practitionerNameMap!.get(practitionerId)) ||
-                                   review.practitionerReview.practitionerName ||
-                                   'Unknown Practitioner';
-          
-          if (practitionerId) {
-            if (!entityMap.has(practitionerId)) {
-              entityMap.set(practitionerId, { reviews: [], name: practitionerName });
-            }
-            entityMap.get(practitionerId)!.reviews.push(review);
-          }
-        }
-      });
-      
-      console.log(`[ReviewAnalytics] Processed ${reviews.length} reviews into ${entityMap.size} practitioner groups`);
-      entityMap.forEach((data, practId) => {
-        console.log(`[ReviewAnalytics]   - ${data.name} (${practId}): ${data.reviews.length} reviews`);
-      });
-    } else {
-      // Handle other entity types (category, subcategory, etc.)
-      reviews.forEach(review => {
-        let entityId: string | undefined;
-        let entityName: string | undefined;
-        
-        // TODO: Handle category/subcategory grouping
-        
-        if (entityId) {
-          if (!entityMap.has(entityId)) {
-            entityMap.set(entityId, { reviews: [], name: entityName || entityId });
-          }
-          entityMap.get(entityId)!.reviews.push(review);
-        }
-      });
-    }
-    
-    // Calculate metrics for each entity
-    const metrics: ReviewAnalyticsMetrics[] = [];
-    for (const [entityId, data] of entityMap.entries()) {
-      const metric = this.calculateReviewMetrics(data.reviews, entityType, entityId);
-      if (metric) {
-        metric.entityName = data.name; // Use the mapped name
-        metrics.push(metric);
-      }
-    }
-    
-    return metrics;
-  }
-  
-  /**
-   * Calculates review metrics from a list of reviews
-   */
-  private calculateReviewMetrics(
-    reviews: Review[],
-    entityType: 'practitioner' | 'procedure' | 'category' | 'subcategory' | 'technology',
-    entityId: string
-  ): ReviewAnalyticsMetrics | null {
-    if (reviews.length === 0) {
-      return null;
-    }
-    
-    let totalRating = 0;
-    let recommendationCount = 0;
-      let practitionerMetrics: ReviewAnalyticsMetrics['practitionerMetrics'];
-      let procedureMetrics: ReviewAnalyticsMetrics['procedureMetrics'];
-    let entityName = entityId; // Default, will be enhanced from appointments
-    
-    if (entityType === 'practitioner') {
-      const practitionerReviews = reviews.filter(r => r.practitionerReview).map(r => r.practitionerReview!);
-      
-      if (practitionerReviews.length === 0) {
-        return null;
-      }
-      
-      // Get entity name from first review
-      entityName = practitionerReviews[0].practitionerName || entityId;
-      
-      // Calculate averages
-      totalRating = practitionerReviews.reduce((sum, r) => sum + r.overallRating, 0);
-      recommendationCount = practitionerReviews.filter(r => r.wouldRecommend).length;
-      
-      practitionerMetrics = {
-        averageKnowledgeAndExpertise: this.calculateAverage(practitionerReviews.map(r => r.knowledgeAndExpertise)),
-        averageCommunicationSkills: this.calculateAverage(practitionerReviews.map(r => r.communicationSkills)),
-        averageBedSideManner: this.calculateAverage(practitionerReviews.map(r => r.bedSideManner)),
-        averageThoroughness: this.calculateAverage(practitionerReviews.map(r => r.thoroughness)),
-        averageTrustworthiness: this.calculateAverage(practitionerReviews.map(r => r.trustworthiness)),
-      };
-    } else if (entityType === 'procedure' || entityType === 'technology') {
-      // Technology uses the same logic as procedure since technology reviews are procedure reviews
-      const procedureReviews = reviews.filter(r => r.procedureReview).map(r => r.procedureReview!);
-      
-      if (procedureReviews.length === 0) {
-        return null;
-      }
-      
-      // Get entity name from first review (or use the name that was passed in for technology)
-      if (entityType === 'procedure') {
-        entityName = procedureReviews[0].procedureName || entityId;
-      }
-      // For technology, entityName is already set from the calling method
-      
-      // Calculate averages
-      totalRating = procedureReviews.reduce((sum, r) => sum + r.overallRating, 0);
-      recommendationCount = procedureReviews.filter(r => r.wouldRecommend).length;
-      
-      procedureMetrics = {
-        averageEffectiveness: this.calculateAverage(procedureReviews.map(r => r.effectivenessOfTreatment)),
-        averageOutcomeExplanation: this.calculateAverage(procedureReviews.map(r => r.outcomeExplanation)),
-        averagePainManagement: this.calculateAverage(procedureReviews.map(r => r.painManagement)),
-        averageFollowUpCare: this.calculateAverage(procedureReviews.map(r => r.followUpCare)),
-        averageValueForMoney: this.calculateAverage(procedureReviews.map(r => r.valueForMoney)),
-      };
-    }
-    
-    const averageRating = totalRating / reviews.length;
-    const recommendationRate = (recommendationCount / reviews.length) * 100;
-    
-    const result: ReviewAnalyticsMetrics = {
-      entityId,
-      entityName,
-      entityType,
-      totalReviews: reviews.length,
-      averageRating,
-      recommendationRate,
-      practitionerMetrics,
-      procedureMetrics,
-      comparisonToOverall: {
-        ratingDifference: 0, // Will be calculated when comparing to overall
-        recommendationDifference: 0,
-      },
-    };
-    
-    return result;
-  }
-  
-  /**
-   * Gets overall review averages for comparison
-   */
-  async getOverallReviewAverages(
-    dateRange?: AnalyticsDateRange,
-    filters?: AnalyticsFilters
-  ): Promise<OverallReviewAverages> {
-    const reviews = await this.fetchReviews(dateRange, filters);
-    
-    const practitionerReviews = reviews
-      .filter(r => r.practitionerReview)
-      .map(r => r.practitionerReview!);
-    
-    const procedureReviews = reviews
-      .filter(r => r.procedureReview)
-      .map(r => r.procedureReview!);
-    
-    return {
-      practitionerAverage: {
-        totalReviews: practitionerReviews.length,
-        averageRating: practitionerReviews.length > 0
-          ? this.calculateAverage(practitionerReviews.map(r => r.overallRating))
-          : 0,
-        recommendationRate: practitionerReviews.length > 0
-          ? (practitionerReviews.filter(r => r.wouldRecommend).length / practitionerReviews.length) * 100
-          : 0,
-        averageKnowledgeAndExpertise: this.calculateAverage(practitionerReviews.map(r => r.knowledgeAndExpertise)),
-        averageCommunicationSkills: this.calculateAverage(practitionerReviews.map(r => r.communicationSkills)),
-        averageBedSideManner: this.calculateAverage(practitionerReviews.map(r => r.bedSideManner)),
-        averageThoroughness: this.calculateAverage(practitionerReviews.map(r => r.thoroughness)),
-        averageTrustworthiness: this.calculateAverage(practitionerReviews.map(r => r.trustworthiness)),
-      },
-      procedureAverage: {
-        totalReviews: procedureReviews.length,
-        averageRating: procedureReviews.length > 0
-          ? this.calculateAverage(procedureReviews.map(r => r.overallRating))
-          : 0,
-        recommendationRate: procedureReviews.length > 0
-          ? (procedureReviews.filter(r => r.wouldRecommend).length / procedureReviews.length) * 100
-          : 0,
-        averageEffectiveness: this.calculateAverage(procedureReviews.map(r => r.effectivenessOfTreatment)),
-        averageOutcomeExplanation: this.calculateAverage(procedureReviews.map(r => r.outcomeExplanation)),
-        averagePainManagement: this.calculateAverage(procedureReviews.map(r => r.painManagement)),
-        averageFollowUpCare: this.calculateAverage(procedureReviews.map(r => r.followUpCare)),
-        averageValueForMoney: this.calculateAverage(procedureReviews.map(r => r.valueForMoney)),
-      },
-    };
-  }
-  
-  /**
-   * Gets review details for a specific entity
-   */
-  async getReviewDetails(
-    entityType: 'practitioner' | 'procedure',
-    entityId: string,
-    dateRange?: AnalyticsDateRange,
-    filters?: AnalyticsFilters
-  ): Promise<ReviewDetail[]> {
-    const reviews = await this.fetchReviews(dateRange, filters);
-    
-    // Filter reviews based on entity type
-    let relevantReviews: Review[] = [];
-    
-    if (entityType === 'practitioner') {
-      relevantReviews = reviews.filter(r => r.practitionerReview?.practitionerId === entityId);
-    } else if (entityType === 'procedure') {
-      relevantReviews = reviews.filter(r => r.procedureReview?.procedureId === entityId);
-    }
-    
-    // Enhance with appointment data
-    const details: ReviewDetail[] = [];
-    for (const review of relevantReviews) {
-      try {
-        const appointmentDocRef = doc(this.db, APPOINTMENTS_COLLECTION, review.appointmentId);
-        const appointmentDoc = await getDoc(appointmentDocRef);
-        
-        let appointment: Appointment | null = null;
-        if (appointmentDoc.exists()) {
-          appointment = appointmentDoc.data() as Appointment;
-        }
-        
-        const createdAt = review.createdAt instanceof Timestamp ? review.createdAt.toDate() : new Date(review.createdAt);
-        const appointmentDate = appointment?.appointmentStartTime 
-          ? (appointment.appointmentStartTime instanceof Timestamp 
-              ? appointment.appointmentStartTime.toDate() 
-              : appointment.appointmentStartTime)
-          : createdAt;
-        
-        details.push({
-          reviewId: review.id,
-          appointmentId: review.appointmentId,
-          patientId: review.patientId,
-          patientName: review.patientName || appointment?.patientInfo?.fullName,
-          createdAt,
-          practitionerReview: review.practitionerReview,
-          procedureReview: review.procedureReview,
-          procedureName: appointment?.procedureInfo?.name,
-          practitionerName: appointment?.practitionerInfo?.name,
-          appointmentDate,
-        });
-      } catch (error) {
-        console.warn(`Failed to enhance review ${review.id}:`, error);
-      }
-    }
-    
-    return details;
-  }
-  
-  /**
-   * Helper method to calculate average
-   */
-  private calculateAverage(values: number[]): number {
-    if (values.length === 0) return 0;
-    const sum = values.reduce((acc, val) => acc + val, 0);
-    return sum / values.length;
-  }
-
-  /**
-   * Calculate review trends over time
-   * Groups reviews by period and calculates rating and recommendation 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
-   * @param entityType - Optional entity type to group trends by (practitioner, procedure, technology)
-   * @returns Array of review trends with percentage changes
-   */
-  async getReviewTrends(
-    dateRange: AnalyticsDateRange,
-    period: TrendPeriod,
-    filters?: AnalyticsFilters,
-    entityType?: 'practitioner' | 'procedure' | 'technology'
-  ): Promise<ReviewTrend[]> {
-    // Fetch all reviews in the date range
-    const reviews = await this.fetchReviews(dateRange, filters);
-    
-    if (reviews.length === 0) {
-      return [];
-    }
-
-    // If grouping by entity, calculate trends per entity
-    if (entityType) {
-      return this.getGroupedReviewTrends(reviews, dateRange, period, entityType, filters);
-    }
-
-    // Calculate overall trends
-    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
-    const trends: ReviewTrend[] = [];
-
-    let previousAvgRating = 0;
-    let previousRecRate = 0;
-
-    periods.forEach((periodInfo: PeriodInfo) => {
-      // Filter reviews for this period
-      const periodReviews = reviews.filter(review => {
-        const reviewDate = review.createdAt instanceof Date ? review.createdAt : (review.createdAt as Timestamp).toDate();
-        return reviewDate >= periodInfo.startDate && reviewDate <= periodInfo.endDate;
-      });
-
-      if (periodReviews.length === 0) {
-        // No reviews in this period, skip or use 0
-        trends.push({
-          period: periodInfo.period,
-          startDate: periodInfo.startDate,
-          endDate: periodInfo.endDate,
-          averageRating: 0,
-          recommendationRate: 0,
-          totalReviews: 0,
-          previousPeriod: undefined,
-        });
-        previousAvgRating = 0;
-        previousRecRate = 0;
-        return;
-      }
-
-      // Calculate weighted average rating across practitioner and procedure reviews
-      let totalRatingSum = 0;
-      let totalRatingCount = 0;
-      let totalRecommendations = 0;
-      let totalRecommendationCount = 0;
-
-      periodReviews.forEach(review => {
-        if (review.practitionerReview) {
-          totalRatingSum += review.practitionerReview.overallRating;
-          totalRatingCount++;
-          if (review.practitionerReview.wouldRecommend) {
-            totalRecommendations++;
-          }
-          totalRecommendationCount++;
-        }
-        if (review.procedureReview) {
-          totalRatingSum += review.procedureReview.overallRating;
-          totalRatingCount++;
-          if (review.procedureReview.wouldRecommend) {
-            totalRecommendations++;
-          }
-          totalRecommendationCount++;
-        }
-        if (review.extendedProcedureReviews && review.extendedProcedureReviews.length > 0) {
-          review.extendedProcedureReviews.forEach(extReview => {
-            totalRatingSum += extReview.overallRating;
-            totalRatingCount++;
-            if (extReview.wouldRecommend) {
-              totalRecommendations++;
-            }
-            totalRecommendationCount++;
-          });
-        }
-      });
-
-      const currentAvgRating = totalRatingCount > 0 ? totalRatingSum / totalRatingCount : 0;
-      const currentRecRate = totalRecommendationCount > 0 ? (totalRecommendations / totalRecommendationCount) * 100 : 0;
-
-      // Calculate trend comparison
-      const trendChange = getTrendChange(currentAvgRating, previousAvgRating);
-
-      trends.push({
-        period: periodInfo.period,
-        startDate: periodInfo.startDate,
-        endDate: periodInfo.endDate,
-        averageRating: currentAvgRating,
-        recommendationRate: currentRecRate,
-        totalReviews: periodReviews.length,
-        previousPeriod: previousAvgRating > 0 ? {
-          averageRating: previousAvgRating,
-          recommendationRate: previousRecRate,
-          percentageChange: Math.abs(trendChange.percentageChange),
-          direction: trendChange.direction,
-        } : undefined,
-      });
-
-      previousAvgRating = currentAvgRating;
-      previousRecRate = currentRecRate;
-    });
-
-    return trends;
-  }
-
-  /**
-   * Calculate grouped review trends (by practitioner, procedure, or technology)
-   * Returns the AVERAGE across all entities of that type for each period
-   * @private
-   */
-  private async getGroupedReviewTrends(
-    reviews: Review[],
-    dateRange: AnalyticsDateRange,
-    period: TrendPeriod,
-    entityType: 'practitioner' | 'procedure' | 'technology',
-    filters?: AnalyticsFilters
-  ): Promise<ReviewTrend[]> {
-    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
-    const trends: ReviewTrend[] = [];
-
-    // Fetch appointments if needed for technology mapping
-    let appointments: Appointment[] = [];
-    let procedureToTechnologyMap = new Map<string, { id: string; name: string }>();
-    
-    if (entityType === 'technology' && this.appointmentService) {
-      const searchParams: any = { ...filters };
-      if (dateRange) {
-        searchParams.startDate = dateRange.start;
-        searchParams.endDate = dateRange.end;
-      }
-      const appointmentsResult = await this.appointmentService.searchAppointments(searchParams);
-      appointments = appointmentsResult.appointments || [];
-      
-      // Build procedure -> technology map
-      appointments.forEach((appointment: Appointment) => {
-        if (appointment.procedureId && appointment.procedureExtendedInfo?.procedureTechnologyId) {
-          procedureToTechnologyMap.set(appointment.procedureId, {
-            id: appointment.procedureExtendedInfo.procedureTechnologyId,
-            name: appointment.procedureExtendedInfo.procedureTechnologyName || 'Unknown Technology',
-          });
-        }
-        if (appointment.metadata?.extendedProcedures) {
-          appointment.metadata.extendedProcedures.forEach(extProc => {
-            if (extProc.procedureId && extProc.procedureTechnologyId) {
-              procedureToTechnologyMap.set(extProc.procedureId, {
-                id: extProc.procedureTechnologyId,
-                name: extProc.procedureTechnologyName || 'Unknown Technology',
-              });
-            }
-          });
-        }
-      });
-    }
-
-    let previousAvgRating = 0;
-    let previousRecRate = 0;
-
-    periods.forEach((periodInfo: PeriodInfo) => {
-      // Filter reviews for this period
-      const periodReviews = reviews.filter(review => {
-        const reviewDate = review.createdAt instanceof Date ? review.createdAt : (review.createdAt as Timestamp).toDate();
-        return reviewDate >= periodInfo.startDate && reviewDate <= periodInfo.endDate;
-      });
-
-      if (periodReviews.length === 0) {
-        trends.push({
-          period: periodInfo.period,
-          startDate: periodInfo.startDate,
-          endDate: periodInfo.endDate,
-          averageRating: 0,
-          recommendationRate: 0,
-          totalReviews: 0,
-          previousPeriod: undefined,
-        });
-        previousAvgRating = 0;
-        previousRecRate = 0;
-        return;
-      }
-
-      // Calculate entity-specific averages
-      let totalRatingSum = 0;
-      let totalRatingCount = 0;
-      let totalRecommendations = 0;
-      let totalRecommendationCount = 0;
-
-      periodReviews.forEach(review => {
-        if (entityType === 'practitioner' && review.practitionerReview) {
-          totalRatingSum += review.practitionerReview.overallRating;
-          totalRatingCount++;
-          if (review.practitionerReview.wouldRecommend) {
-            totalRecommendations++;
-          }
-          totalRecommendationCount++;
-        } else if (entityType === 'procedure' && review.procedureReview) {
-          totalRatingSum += review.procedureReview.overallRating;
-          totalRatingCount++;
-          if (review.procedureReview.wouldRecommend) {
-            totalRecommendations++;
-          }
-          totalRecommendationCount++;
-          
-          // Include extended procedure reviews
-          if (review.extendedProcedureReviews && review.extendedProcedureReviews.length > 0) {
-            review.extendedProcedureReviews.forEach(extReview => {
-              totalRatingSum += extReview.overallRating;
-              totalRatingCount++;
-              if (extReview.wouldRecommend) {
-                totalRecommendations++;
-              }
-              totalRecommendationCount++;
-            });
-          }
-        } else if (entityType === 'technology') {
-          // For technology, map procedure reviews to their technology
-          if (review.procedureReview?.procedureId) {
-            const tech = procedureToTechnologyMap.get(review.procedureReview.procedureId);
-            if (tech) {
-              totalRatingSum += review.procedureReview.overallRating;
-              totalRatingCount++;
-              if (review.procedureReview.wouldRecommend) {
-                totalRecommendations++;
-              }
-              totalRecommendationCount++;
-            }
-          }
-          
-          // Include extended procedure reviews mapped to technology
-          if (review.extendedProcedureReviews && review.extendedProcedureReviews.length > 0) {
-            review.extendedProcedureReviews.forEach(extReview => {
-              if (extReview.procedureId) {
-                const tech = procedureToTechnologyMap.get(extReview.procedureId);
-                if (tech) {
-                  totalRatingSum += extReview.overallRating;
-                  totalRatingCount++;
-                  if (extReview.wouldRecommend) {
-                    totalRecommendations++;
-                  }
-                  totalRecommendationCount++;
-                }
-              }
-            });
-          }
-        }
-      });
-
-      const currentAvgRating = totalRatingCount > 0 ? totalRatingSum / totalRatingCount : 0;
-      const currentRecRate = totalRecommendationCount > 0 ? (totalRecommendations / totalRecommendationCount) * 100 : 0;
-
-      // Calculate trend comparison
-      const trendChange = getTrendChange(currentAvgRating, previousAvgRating);
-
-      trends.push({
-        period: periodInfo.period,
-        startDate: periodInfo.startDate,
-        endDate: periodInfo.endDate,
-        averageRating: currentAvgRating,
-        recommendationRate: currentRecRate,
-        totalReviews: totalRatingCount, // Count of reviews for this entity type
-        previousPeriod: previousAvgRating > 0 ? {
-          averageRating: previousAvgRating,
-          recommendationRate: previousRecRate,
-          percentageChange: Math.abs(trendChange.percentageChange),
-          direction: trendChange.direction,
-        } : undefined,
-      });
-
-      previousAvgRating = currentAvgRating;
-      previousRecRate = currentRecRate;
-    });
-
-    return trends;
-  }
-}
-
+import { Firestore, collection, query, where, getDocs, getDoc, doc, Timestamp } from 'firebase/firestore';
+import { BaseService } from '../base.service';
+import { Review, PractitionerReview, ProcedureReview, REVIEWS_COLLECTION } from '../../types/reviews';
+import { Appointment, APPOINTMENTS_COLLECTION } from '../../types/appointment';
+import { AnalyticsDateRange, AnalyticsFilters, ReviewTrend, TrendPeriod } from '../../types/analytics';
+import { AppointmentService } from '../appointment/appointment.service';
+import { 
+  groupAppointmentsByPeriod,
+  generatePeriods,
+  getTrendChange,
+  type TrendPeriod as TrendPeriodType,
+  type PeriodInfo,
+} from './utils/trend-calculation.utils';
+
+/**
+ * Review metrics for a specific entity (practitioner, procedure, etc.)
+ * Full review analytics metrics with detailed breakdowns
+ */
+export interface ReviewAnalyticsMetrics {
+  entityId: string;
+  entityName: string;
+  entityType: 'practitioner' | 'procedure' | 'category' | 'subcategory' | 'technology';
+  
+  // Overall metrics
+  totalReviews: number;
+  averageRating: number;
+  recommendationRate: number; // % that would recommend
+  
+  // For Practitioner reviews
+  practitionerMetrics?: {
+    averageKnowledgeAndExpertise: number;
+    averageCommunicationSkills: number;
+    averageBedSideManner: number;
+    averageThoroughness: number;
+    averageTrustworthiness: number;
+  };
+  
+  // For Procedure reviews
+  procedureMetrics?: {
+    averageEffectiveness: number;
+    averageOutcomeExplanation: number;
+    averagePainManagement: number;
+    averageFollowUpCare: number;
+    averageValueForMoney: number;
+  };
+  
+  // Comparison to overall average
+  comparisonToOverall: {
+    ratingDifference: number; // Positive = above average, negative = below
+    recommendationDifference: number; // % difference
+  };
+}
+
+/**
+ * Review detail with full information
+ */
+export interface ReviewDetail {
+  reviewId: string;
+  appointmentId: string;
+  patientId: string;
+  patientName?: string;
+  createdAt: Date;
+  
+  // Relevant sub-review based on entityType
+  practitionerReview?: PractitionerReview;
+  procedureReview?: ProcedureReview;
+  
+  // Context from appointment
+  procedureName?: string;
+  practitionerName?: string;
+  appointmentDate: Date;
+}
+
+/**
+ * Overall review averages for comparison
+ */
+export interface OverallReviewAverages {
+  // Overall practitioner averages
+  practitionerAverage: {
+    totalReviews: number;
+    averageRating: number;
+    recommendationRate: number;
+    averageKnowledgeAndExpertise: number;
+    averageCommunicationSkills: number;
+    averageBedSideManner: number;
+    averageThoroughness: number;
+    averageTrustworthiness: number;
+  };
+  
+  // Overall procedure averages
+  procedureAverage: {
+    totalReviews: number;
+    averageRating: number;
+    recommendationRate: number;
+    averageEffectiveness: number;
+    averageOutcomeExplanation: number;
+    averagePainManagement: number;
+    averageFollowUpCare: number;
+    averageValueForMoney: number;
+  };
+}
+
+/**
+ * Review Analytics Service
+ * Provides review metrics and analytics for practitioners, procedures, categories, and technologies
+ */
+export class ReviewAnalyticsService extends BaseService {
+  private appointmentService: AppointmentService;
+
+  constructor(db: Firestore, auth: any, app: any, appointmentService?: AppointmentService) {
+    super(db, auth, app);
+    // AppointmentService is optional - will be set if provided
+    this.appointmentService = appointmentService as AppointmentService;
+  }
+  /**
+   * Fetches reviews filtered by date range and optional filters
+   * Properly filters by clinic branch by checking appointment's clinicId
+   */
+  private async fetchReviews(
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters
+  ): Promise<Review[]> {
+    let q = query(collection(this.db, REVIEWS_COLLECTION));
+    
+    // Apply date range filter
+    if (dateRange) {
+      const startTimestamp = Timestamp.fromDate(dateRange.start);
+      const endTimestamp = Timestamp.fromDate(dateRange.end);
+      q = query(q, where('createdAt', '>=', startTimestamp), where('createdAt', '<=', endTimestamp));
+    }
+    
+    const snapshot = await getDocs(q);
+    const reviews = snapshot.docs.map(doc => {
+      const data = doc.data();
+      return {
+        ...data,
+        id: doc.id,
+        createdAt: data.createdAt?.toDate ? data.createdAt.toDate() : new Date(data.createdAt),
+        updatedAt: data.updatedAt?.toDate ? data.updatedAt.toDate() : new Date(data.updatedAt),
+      } as Review;
+    });
+    
+    console.log(`[ReviewAnalytics] Fetched ${reviews.length} reviews in date range`);
+    
+    // Filter by clinic branch if specified
+    if (filters?.clinicBranchId && reviews.length > 0) {
+      // We need to fetch appointments to check which clinic they belong to
+      // Firestore 'in' operator supports max 10 items, so we batch
+      const appointmentIds = [...new Set(reviews.map(r => r.appointmentId))];
+      console.log(`[ReviewAnalytics] Filtering by clinic ${filters.clinicBranchId}, checking ${appointmentIds.length} appointments`);
+      
+      const validAppointmentIds = new Set<string>();
+      
+      // Process in batches of 10
+      for (let i = 0; i < appointmentIds.length; i += 10) {
+        const batch = appointmentIds.slice(i, i + 10);
+        const appointmentsQuery = query(
+          collection(this.db, APPOINTMENTS_COLLECTION),
+          where('id', 'in', batch)
+        );
+        const appointmentSnapshot = await getDocs(appointmentsQuery);
+        
+        appointmentSnapshot.docs.forEach(doc => {
+          const appointment = doc.data() as Appointment;
+          // Appointment uses 'clinicBranchId' field directly
+          if (appointment.clinicBranchId === filters.clinicBranchId) {
+            validAppointmentIds.add(doc.id);
+          }
+        });
+      }
+      
+      const filteredReviews = reviews.filter(review => validAppointmentIds.has(review.appointmentId));
+      console.log(`[ReviewAnalytics] After clinic filter: ${filteredReviews.length} reviews (from ${validAppointmentIds.size} valid appointments)`);
+      
+      return filteredReviews;
+    }
+    
+    return reviews;
+  }
+  
+  /**
+   * Gets review metrics for a specific entity
+   */
+  async getReviewMetricsByEntity(
+    entityType: 'practitioner' | 'procedure' | 'category' | 'subcategory' | 'technology',
+    entityId: string,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters
+  ): Promise<ReviewAnalyticsMetrics | null> {
+    const reviews = await this.fetchReviews(dateRange, filters);
+    
+    // Filter reviews based on entity type
+    let relevantReviews: Review[] = [];
+    
+    if (entityType === 'practitioner') {
+      relevantReviews = reviews.filter(r => r.practitionerReview?.practitionerId === entityId);
+    } else if (entityType === 'procedure') {
+      relevantReviews = reviews.filter(r => r.procedureReview?.procedureId === entityId);
+    } else if (entityType === 'category' || entityType === 'subcategory') {
+      // For category/subcategory, we need to get reviews for all procedures in that category
+      // This requires fetching appointments to get procedure info
+      // For now, we'll need to enhance this with appointment data
+      relevantReviews = reviews; // Placeholder - will be enhanced
+    }
+    
+    if (relevantReviews.length === 0) {
+      return null;
+    }
+    
+    // Calculate metrics
+    return this.calculateReviewMetrics(relevantReviews, entityType, entityId);
+  }
+  
+  /**
+   * Gets review metrics for multiple entities (grouped)
+   */
+  async getReviewMetricsByEntities(
+    entityType: 'practitioner' | 'procedure' | 'category' | 'subcategory' | 'technology',
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters
+  ): Promise<ReviewAnalyticsMetrics[]> {
+    const reviews = await this.fetchReviews(dateRange, filters);
+    const entityMap = new Map<string, { reviews: Review[]; name: string }>();
+    
+    // For practitioner, procedure, and technology, we fetch appointments to get actual names
+    // (Reviews have IDs stored in name fields, not actual names)
+    let practitionerNameMap: Map<string, string> | null = null;
+    let procedureNameMap: Map<string, string> | null = null;
+    let procedureToTechnologyMap: Map<string, { id: string; name: string }> | null = null;
+    
+    if (entityType === 'practitioner' || entityType === 'procedure' || entityType === 'technology') {
+      if (!this.appointmentService) {
+        console.warn(`[ReviewAnalytics] AppointmentService not available for ${entityType} name resolution`);
+        return [];
+      }
+      
+      console.log(`[ReviewAnalytics] Grouping by ${entityType}, fetching appointments for name resolution...`);
+      
+      // Fetch all appointments to build name mapping tables
+      const searchParams: any = {
+        ...filters,
+      };
+      if (dateRange) {
+        searchParams.startDate = dateRange.start;
+        searchParams.endDate = dateRange.end;
+      }
+      const appointmentsResult = await this.appointmentService.searchAppointments(searchParams);
+      const appointments = appointmentsResult.appointments || [];
+      
+      console.log(`[ReviewAnalytics] Found ${appointments.length} appointments for name resolution`);
+      
+      // Build all name mapping tables
+      practitionerNameMap = new Map<string, string>();
+      procedureNameMap = new Map<string, string>();
+      procedureToTechnologyMap = new Map<string, { id: string; name: string }>();
+      
+      appointments.forEach((appointment: Appointment) => {
+        // Map practitioner ID -> name
+        if (appointment.practitionerId && appointment.practitionerInfo?.name) {
+          practitionerNameMap!.set(appointment.practitionerId, appointment.practitionerInfo.name);
+        }
+        
+        // Map main procedure ID -> name
+        if (appointment.procedureId) {
+          if (appointment.procedureInfo?.name) {
+            procedureNameMap!.set(appointment.procedureId, appointment.procedureInfo.name);
+          }
+          
+          // Map procedure -> technology
+          const mainTechnologyId = appointment.procedureExtendedInfo?.procedureTechnologyId || 'unknown-technology';
+          const mainTechnologyName = appointment.procedureExtendedInfo?.procedureTechnologyName ||
+                                    appointment.procedureInfo?.name ||
+                                    'Unknown Technology';
+          procedureToTechnologyMap!.set(appointment.procedureId, {
+            id: mainTechnologyId,
+            name: mainTechnologyName,
+          });
+        }
+        
+        // Map extended procedures
+        if (appointment.metadata?.extendedProcedures) {
+          appointment.metadata.extendedProcedures.forEach((extendedProc) => {
+            if (extendedProc.procedureId) {
+              if (extendedProc.procedureName) {
+                procedureNameMap!.set(extendedProc.procedureId, extendedProc.procedureName);
+              }
+              
+              const extTechnologyId = extendedProc.procedureTechnologyId || 'unknown-technology';
+              const extTechnologyName = extendedProc.procedureTechnologyName || 'Unknown Technology';
+              procedureToTechnologyMap!.set(extendedProc.procedureId, {
+                id: extTechnologyId,
+                name: extTechnologyName,
+              });
+            }
+          });
+        }
+      });
+      
+      console.log(`[ReviewAnalytics] Built name maps: ${practitionerNameMap.size} practitioners, ${procedureNameMap.size} procedures, ${procedureToTechnologyMap.size} technologies`);
+    }
+    
+    // Now group reviews based on entity type
+    if (entityType === 'technology' && procedureToTechnologyMap) {
+      let processedReviewCount = 0;
+      
+      reviews.forEach(review => {
+        // Process main procedure review
+        if (review.procedureReview?.procedureId) {
+          const techInfo = procedureToTechnologyMap!.get(review.procedureReview.procedureId);
+          if (techInfo) {
+            if (!entityMap.has(techInfo.id)) {
+              entityMap.set(techInfo.id, { reviews: [], name: techInfo.name });
+            }
+            entityMap.get(techInfo.id)!.reviews.push(review);
+            processedReviewCount++;
+          }
+        }
+        
+        // Process extended procedure reviews
+        if (review.extendedProcedureReviews && review.extendedProcedureReviews.length > 0) {
+          review.extendedProcedureReviews.forEach((extendedReview) => {
+            if (extendedReview.procedureId) {
+              const techInfo = procedureToTechnologyMap!.get(extendedReview.procedureId);
+              if (techInfo) {
+                if (!entityMap.has(techInfo.id)) {
+                  entityMap.set(techInfo.id, { reviews: [], name: techInfo.name });
+                }
+                const reviewWithExtendedOnly: Review = {
+                  ...review,
+                  procedureReview: extendedReview,
+                  extendedProcedureReviews: undefined,
+                };
+                entityMap.get(techInfo.id)!.reviews.push(reviewWithExtendedOnly);
+                processedReviewCount++;
+              }
+            }
+          });
+        }
+      });
+      
+      console.log(`[ReviewAnalytics] Processed ${processedReviewCount} procedure reviews into ${entityMap.size} technology groups`);
+      entityMap.forEach((data, techId) => {
+        console.log(`[ReviewAnalytics]   - ${data.name} (${techId}): ${data.reviews.length} reviews`);
+      });
+    } else if (entityType === 'procedure' && procedureNameMap) {
+      let processedReviewCount = 0;
+      
+      reviews.forEach(review => {
+        // Process main procedure review
+        if (review.procedureReview) {
+          const procedureId = review.procedureReview.procedureId;
+          // Use actual name from appointment, fallback to review name, then 'Unknown'
+          const procedureName = (procedureId && procedureNameMap!.get(procedureId)) ||
+                                review.procedureReview.procedureName ||
+                                'Unknown Procedure';
+          
+          if (procedureId) {
+            if (!entityMap.has(procedureId)) {
+              entityMap.set(procedureId, { reviews: [], name: procedureName });
+            }
+            entityMap.get(procedureId)!.reviews.push(review);
+            processedReviewCount++;
+          }
+        }
+        
+        // Process extended procedure reviews
+        if (review.extendedProcedureReviews && review.extendedProcedureReviews.length > 0) {
+          review.extendedProcedureReviews.forEach((extendedReview) => {
+            const procedureId = extendedReview.procedureId;
+            // Use actual name from appointment, fallback to review name, then 'Unknown'
+            const procedureName = (procedureId && procedureNameMap!.get(procedureId)) ||
+                                  extendedReview.procedureName ||
+                                  'Unknown Procedure';
+            
+            if (procedureId) {
+              if (!entityMap.has(procedureId)) {
+                entityMap.set(procedureId, { reviews: [], name: procedureName });
+              }
+              const reviewWithExtendedOnly: Review = {
+                ...review,
+                procedureReview: extendedReview,
+                extendedProcedureReviews: undefined,
+              };
+              entityMap.get(procedureId)!.reviews.push(reviewWithExtendedOnly);
+              processedReviewCount++;
+            }
+          });
+        }
+      });
+      
+      console.log(`[ReviewAnalytics] Processed ${processedReviewCount} procedure reviews into ${entityMap.size} procedure groups`);
+      entityMap.forEach((data, procId) => {
+        console.log(`[ReviewAnalytics]   - ${data.name} (${procId}): ${data.reviews.length} reviews`);
+      });
+    } else if (entityType === 'practitioner' && practitionerNameMap) {
+      // Group reviews by practitioner
+      reviews.forEach(review => {
+        if (review.practitionerReview) {
+          const practitionerId = review.practitionerReview.practitionerId;
+          // Use actual name from appointment, fallback to review name, then 'Unknown'
+          const practitionerName = (practitionerId && practitionerNameMap!.get(practitionerId)) ||
+                                   review.practitionerReview.practitionerName ||
+                                   'Unknown Practitioner';
+          
+          if (practitionerId) {
+            if (!entityMap.has(practitionerId)) {
+              entityMap.set(practitionerId, { reviews: [], name: practitionerName });
+            }
+            entityMap.get(practitionerId)!.reviews.push(review);
+          }
+        }
+      });
+      
+      console.log(`[ReviewAnalytics] Processed ${reviews.length} reviews into ${entityMap.size} practitioner groups`);
+      entityMap.forEach((data, practId) => {
+        console.log(`[ReviewAnalytics]   - ${data.name} (${practId}): ${data.reviews.length} reviews`);
+      });
+    } else {
+      // Handle other entity types (category, subcategory, etc.)
+      reviews.forEach(review => {
+        let entityId: string | undefined;
+        let entityName: string | undefined;
+        
+        // TODO: Handle category/subcategory grouping
+        
+        if (entityId) {
+          if (!entityMap.has(entityId)) {
+            entityMap.set(entityId, { reviews: [], name: entityName || entityId });
+          }
+          entityMap.get(entityId)!.reviews.push(review);
+        }
+      });
+    }
+    
+    // Calculate metrics for each entity
+    const metrics: ReviewAnalyticsMetrics[] = [];
+    for (const [entityId, data] of entityMap.entries()) {
+      const metric = this.calculateReviewMetrics(data.reviews, entityType, entityId);
+      if (metric) {
+        metric.entityName = data.name; // Use the mapped name
+        metrics.push(metric);
+      }
+    }
+    
+    return metrics;
+  }
+  
+  /**
+   * Calculates review metrics from a list of reviews
+   */
+  private calculateReviewMetrics(
+    reviews: Review[],
+    entityType: 'practitioner' | 'procedure' | 'category' | 'subcategory' | 'technology',
+    entityId: string
+  ): ReviewAnalyticsMetrics | null {
+    if (reviews.length === 0) {
+      return null;
+    }
+    
+    let totalRating = 0;
+    let recommendationCount = 0;
+      let practitionerMetrics: ReviewAnalyticsMetrics['practitionerMetrics'];
+      let procedureMetrics: ReviewAnalyticsMetrics['procedureMetrics'];
+    let entityName = entityId; // Default, will be enhanced from appointments
+    
+    if (entityType === 'practitioner') {
+      const practitionerReviews = reviews.filter(r => r.practitionerReview).map(r => r.practitionerReview!);
+      
+      if (practitionerReviews.length === 0) {
+        return null;
+      }
+      
+      // Get entity name from first review
+      entityName = practitionerReviews[0].practitionerName || entityId;
+      
+      // Calculate averages
+      totalRating = practitionerReviews.reduce((sum, r) => sum + r.overallRating, 0);
+      recommendationCount = practitionerReviews.filter(r => r.wouldRecommend).length;
+      
+      practitionerMetrics = {
+        averageKnowledgeAndExpertise: this.calculateAverage(practitionerReviews.map(r => r.knowledgeAndExpertise)),
+        averageCommunicationSkills: this.calculateAverage(practitionerReviews.map(r => r.communicationSkills)),
+        averageBedSideManner: this.calculateAverage(practitionerReviews.map(r => r.bedSideManner)),
+        averageThoroughness: this.calculateAverage(practitionerReviews.map(r => r.thoroughness)),
+        averageTrustworthiness: this.calculateAverage(practitionerReviews.map(r => r.trustworthiness)),
+      };
+    } else if (entityType === 'procedure' || entityType === 'technology') {
+      // Technology uses the same logic as procedure since technology reviews are procedure reviews
+      const procedureReviews = reviews.filter(r => r.procedureReview).map(r => r.procedureReview!);
+      
+      if (procedureReviews.length === 0) {
+        return null;
+      }
+      
+      // Get entity name from first review (or use the name that was passed in for technology)
+      if (entityType === 'procedure') {
+        entityName = procedureReviews[0].procedureName || entityId;
+      }
+      // For technology, entityName is already set from the calling method
+      
+      // Calculate averages
+      totalRating = procedureReviews.reduce((sum, r) => sum + r.overallRating, 0);
+      recommendationCount = procedureReviews.filter(r => r.wouldRecommend).length;
+      
+      procedureMetrics = {
+        averageEffectiveness: this.calculateAverage(procedureReviews.map(r => r.effectivenessOfTreatment)),
+        averageOutcomeExplanation: this.calculateAverage(procedureReviews.map(r => r.outcomeExplanation)),
+        averagePainManagement: this.calculateAverage(procedureReviews.map(r => r.painManagement)),
+        averageFollowUpCare: this.calculateAverage(procedureReviews.map(r => r.followUpCare)),
+        averageValueForMoney: this.calculateAverage(procedureReviews.map(r => r.valueForMoney)),
+      };
+    }
+    
+    const averageRating = totalRating / reviews.length;
+    const recommendationRate = (recommendationCount / reviews.length) * 100;
+    
+    const result: ReviewAnalyticsMetrics = {
+      entityId,
+      entityName,
+      entityType,
+      totalReviews: reviews.length,
+      averageRating,
+      recommendationRate,
+      practitionerMetrics,
+      procedureMetrics,
+      comparisonToOverall: {
+        ratingDifference: 0, // Will be calculated when comparing to overall
+        recommendationDifference: 0,
+      },
+    };
+    
+    return result;
+  }
+  
+  /**
+   * Gets overall review averages for comparison
+   */
+  async getOverallReviewAverages(
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters
+  ): Promise<OverallReviewAverages> {
+    const reviews = await this.fetchReviews(dateRange, filters);
+    
+    const practitionerReviews = reviews
+      .filter(r => r.practitionerReview)
+      .map(r => r.practitionerReview!);
+    
+    const procedureReviews = reviews
+      .filter(r => r.procedureReview)
+      .map(r => r.procedureReview!);
+    
+    return {
+      practitionerAverage: {
+        totalReviews: practitionerReviews.length,
+        averageRating: practitionerReviews.length > 0
+          ? this.calculateAverage(practitionerReviews.map(r => r.overallRating))
+          : 0,
+        recommendationRate: practitionerReviews.length > 0
+          ? (practitionerReviews.filter(r => r.wouldRecommend).length / practitionerReviews.length) * 100
+          : 0,
+        averageKnowledgeAndExpertise: this.calculateAverage(practitionerReviews.map(r => r.knowledgeAndExpertise)),
+        averageCommunicationSkills: this.calculateAverage(practitionerReviews.map(r => r.communicationSkills)),
+        averageBedSideManner: this.calculateAverage(practitionerReviews.map(r => r.bedSideManner)),
+        averageThoroughness: this.calculateAverage(practitionerReviews.map(r => r.thoroughness)),
+        averageTrustworthiness: this.calculateAverage(practitionerReviews.map(r => r.trustworthiness)),
+      },
+      procedureAverage: {
+        totalReviews: procedureReviews.length,
+        averageRating: procedureReviews.length > 0
+          ? this.calculateAverage(procedureReviews.map(r => r.overallRating))
+          : 0,
+        recommendationRate: procedureReviews.length > 0
+          ? (procedureReviews.filter(r => r.wouldRecommend).length / procedureReviews.length) * 100
+          : 0,
+        averageEffectiveness: this.calculateAverage(procedureReviews.map(r => r.effectivenessOfTreatment)),
+        averageOutcomeExplanation: this.calculateAverage(procedureReviews.map(r => r.outcomeExplanation)),
+        averagePainManagement: this.calculateAverage(procedureReviews.map(r => r.painManagement)),
+        averageFollowUpCare: this.calculateAverage(procedureReviews.map(r => r.followUpCare)),
+        averageValueForMoney: this.calculateAverage(procedureReviews.map(r => r.valueForMoney)),
+      },
+    };
+  }
+  
+  /**
+   * Gets review details for a specific entity
+   */
+  async getReviewDetails(
+    entityType: 'practitioner' | 'procedure',
+    entityId: string,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters
+  ): Promise<ReviewDetail[]> {
+    const reviews = await this.fetchReviews(dateRange, filters);
+    
+    // Filter reviews based on entity type
+    let relevantReviews: Review[] = [];
+    
+    if (entityType === 'practitioner') {
+      relevantReviews = reviews.filter(r => r.practitionerReview?.practitionerId === entityId);
+    } else if (entityType === 'procedure') {
+      relevantReviews = reviews.filter(r => r.procedureReview?.procedureId === entityId);
+    }
+    
+    // Enhance with appointment data
+    const details: ReviewDetail[] = [];
+    for (const review of relevantReviews) {
+      try {
+        const appointmentDocRef = doc(this.db, APPOINTMENTS_COLLECTION, review.appointmentId);
+        const appointmentDoc = await getDoc(appointmentDocRef);
+        
+        let appointment: Appointment | null = null;
+        if (appointmentDoc.exists()) {
+          appointment = appointmentDoc.data() as Appointment;
+        }
+        
+        const createdAt = review.createdAt instanceof Timestamp ? review.createdAt.toDate() : new Date(review.createdAt);
+        const appointmentDate = appointment?.appointmentStartTime 
+          ? (appointment.appointmentStartTime instanceof Timestamp 
+              ? appointment.appointmentStartTime.toDate() 
+              : appointment.appointmentStartTime)
+          : createdAt;
+        
+        details.push({
+          reviewId: review.id,
+          appointmentId: review.appointmentId,
+          patientId: review.patientId,
+          patientName: review.patientName || appointment?.patientInfo?.fullName,
+          createdAt,
+          practitionerReview: review.practitionerReview,
+          procedureReview: review.procedureReview,
+          procedureName: appointment?.procedureInfo?.name,
+          practitionerName: appointment?.practitionerInfo?.name,
+          appointmentDate,
+        });
+      } catch (error) {
+        console.warn(`Failed to enhance review ${review.id}:`, error);
+      }
+    }
+    
+    return details;
+  }
+  
+  /**
+   * Helper method to calculate average
+   */
+  private calculateAverage(values: number[]): number {
+    if (values.length === 0) return 0;
+    const sum = values.reduce((acc, val) => acc + val, 0);
+    return sum / values.length;
+  }
+
+  /**
+   * Calculate review trends over time
+   * Groups reviews by period and calculates rating and recommendation 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
+   * @param entityType - Optional entity type to group trends by (practitioner, procedure, technology)
+   * @returns Array of review trends with percentage changes
+   */
+  async getReviewTrends(
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    filters?: AnalyticsFilters,
+    entityType?: 'practitioner' | 'procedure' | 'technology'
+  ): Promise<ReviewTrend[]> {
+    // Fetch all reviews in the date range
+    const reviews = await this.fetchReviews(dateRange, filters);
+    
+    if (reviews.length === 0) {
+      return [];
+    }
+
+    // If grouping by entity, calculate trends per entity
+    if (entityType) {
+      return this.getGroupedReviewTrends(reviews, dateRange, period, entityType, filters);
+    }
+
+    // Calculate overall trends
+    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
+    const trends: ReviewTrend[] = [];
+
+    let previousAvgRating = 0;
+    let previousRecRate = 0;
+
+    periods.forEach((periodInfo: PeriodInfo) => {
+      // Filter reviews for this period
+      const periodReviews = reviews.filter(review => {
+        const reviewDate = review.createdAt instanceof Date ? review.createdAt : (review.createdAt as Timestamp).toDate();
+        return reviewDate >= periodInfo.startDate && reviewDate <= periodInfo.endDate;
+      });
+
+      if (periodReviews.length === 0) {
+        // No reviews in this period, skip or use 0
+        trends.push({
+          period: periodInfo.period,
+          startDate: periodInfo.startDate,
+          endDate: periodInfo.endDate,
+          averageRating: 0,
+          recommendationRate: 0,
+          totalReviews: 0,
+          previousPeriod: undefined,
+        });
+        previousAvgRating = 0;
+        previousRecRate = 0;
+        return;
+      }
+
+      // Calculate weighted average rating across practitioner and procedure reviews
+      let totalRatingSum = 0;
+      let totalRatingCount = 0;
+      let totalRecommendations = 0;
+      let totalRecommendationCount = 0;
+
+      periodReviews.forEach(review => {
+        if (review.practitionerReview) {
+          totalRatingSum += review.practitionerReview.overallRating;
+          totalRatingCount++;
+          if (review.practitionerReview.wouldRecommend) {
+            totalRecommendations++;
+          }
+          totalRecommendationCount++;
+        }
+        if (review.procedureReview) {
+          totalRatingSum += review.procedureReview.overallRating;
+          totalRatingCount++;
+          if (review.procedureReview.wouldRecommend) {
+            totalRecommendations++;
+          }
+          totalRecommendationCount++;
+        }
+        if (review.extendedProcedureReviews && review.extendedProcedureReviews.length > 0) {
+          review.extendedProcedureReviews.forEach(extReview => {
+            totalRatingSum += extReview.overallRating;
+            totalRatingCount++;
+            if (extReview.wouldRecommend) {
+              totalRecommendations++;
+            }
+            totalRecommendationCount++;
+          });
+        }
+      });
+
+      const currentAvgRating = totalRatingCount > 0 ? totalRatingSum / totalRatingCount : 0;
+      const currentRecRate = totalRecommendationCount > 0 ? (totalRecommendations / totalRecommendationCount) * 100 : 0;
+
+      // Calculate trend comparison
+      const trendChange = getTrendChange(currentAvgRating, previousAvgRating);
+
+      trends.push({
+        period: periodInfo.period,
+        startDate: periodInfo.startDate,
+        endDate: periodInfo.endDate,
+        averageRating: currentAvgRating,
+        recommendationRate: currentRecRate,
+        totalReviews: periodReviews.length,
+        previousPeriod: previousAvgRating > 0 ? {
+          averageRating: previousAvgRating,
+          recommendationRate: previousRecRate,
+          percentageChange: Math.abs(trendChange.percentageChange),
+          direction: trendChange.direction,
+        } : undefined,
+      });
+
+      previousAvgRating = currentAvgRating;
+      previousRecRate = currentRecRate;
+    });
+
+    return trends;
+  }
+
+  /**
+   * Calculate grouped review trends (by practitioner, procedure, or technology)
+   * Returns the AVERAGE across all entities of that type for each period
+   * @private
+   */
+  private async getGroupedReviewTrends(
+    reviews: Review[],
+    dateRange: AnalyticsDateRange,
+    period: TrendPeriod,
+    entityType: 'practitioner' | 'procedure' | 'technology',
+    filters?: AnalyticsFilters
+  ): Promise<ReviewTrend[]> {
+    const periods = generatePeriods(dateRange.start, dateRange.end, period as TrendPeriodType);
+    const trends: ReviewTrend[] = [];
+
+    // Fetch appointments if needed for technology mapping
+    let appointments: Appointment[] = [];
+    let procedureToTechnologyMap = new Map<string, { id: string; name: string }>();
+    
+    if (entityType === 'technology' && this.appointmentService) {
+      const searchParams: any = { ...filters };
+      if (dateRange) {
+        searchParams.startDate = dateRange.start;
+        searchParams.endDate = dateRange.end;
+      }
+      const appointmentsResult = await this.appointmentService.searchAppointments(searchParams);
+      appointments = appointmentsResult.appointments || [];
+      
+      // Build procedure -> technology map
+      appointments.forEach((appointment: Appointment) => {
+        if (appointment.procedureId && appointment.procedureExtendedInfo?.procedureTechnologyId) {
+          procedureToTechnologyMap.set(appointment.procedureId, {
+            id: appointment.procedureExtendedInfo.procedureTechnologyId,
+            name: appointment.procedureExtendedInfo.procedureTechnologyName || 'Unknown Technology',
+          });
+        }
+        if (appointment.metadata?.extendedProcedures) {
+          appointment.metadata.extendedProcedures.forEach(extProc => {
+            if (extProc.procedureId && extProc.procedureTechnologyId) {
+              procedureToTechnologyMap.set(extProc.procedureId, {
+                id: extProc.procedureTechnologyId,
+                name: extProc.procedureTechnologyName || 'Unknown Technology',
+              });
+            }
+          });
+        }
+      });
+    }
+
+    let previousAvgRating = 0;
+    let previousRecRate = 0;
+
+    periods.forEach((periodInfo: PeriodInfo) => {
+      // Filter reviews for this period
+      const periodReviews = reviews.filter(review => {
+        const reviewDate = review.createdAt instanceof Date ? review.createdAt : (review.createdAt as Timestamp).toDate();
+        return reviewDate >= periodInfo.startDate && reviewDate <= periodInfo.endDate;
+      });
+
+      if (periodReviews.length === 0) {
+        trends.push({
+          period: periodInfo.period,
+          startDate: periodInfo.startDate,
+          endDate: periodInfo.endDate,
+          averageRating: 0,
+          recommendationRate: 0,
+          totalReviews: 0,
+          previousPeriod: undefined,
+        });
+        previousAvgRating = 0;
+        previousRecRate = 0;
+        return;
+      }
+
+      // Calculate entity-specific averages
+      let totalRatingSum = 0;
+      let totalRatingCount = 0;
+      let totalRecommendations = 0;
+      let totalRecommendationCount = 0;
+
+      periodReviews.forEach(review => {
+        if (entityType === 'practitioner' && review.practitionerReview) {
+          totalRatingSum += review.practitionerReview.overallRating;
+          totalRatingCount++;
+          if (review.practitionerReview.wouldRecommend) {
+            totalRecommendations++;
+          }
+          totalRecommendationCount++;
+        } else if (entityType === 'procedure' && review.procedureReview) {
+          totalRatingSum += review.procedureReview.overallRating;
+          totalRatingCount++;
+          if (review.procedureReview.wouldRecommend) {
+            totalRecommendations++;
+          }
+          totalRecommendationCount++;
+          
+          // Include extended procedure reviews
+          if (review.extendedProcedureReviews && review.extendedProcedureReviews.length > 0) {
+            review.extendedProcedureReviews.forEach(extReview => {
+              totalRatingSum += extReview.overallRating;
+              totalRatingCount++;
+              if (extReview.wouldRecommend) {
+                totalRecommendations++;
+              }
+              totalRecommendationCount++;
+            });
+          }
+        } else if (entityType === 'technology') {
+          // For technology, map procedure reviews to their technology
+          if (review.procedureReview?.procedureId) {
+            const tech = procedureToTechnologyMap.get(review.procedureReview.procedureId);
+            if (tech) {
+              totalRatingSum += review.procedureReview.overallRating;
+              totalRatingCount++;
+              if (review.procedureReview.wouldRecommend) {
+                totalRecommendations++;
+              }
+              totalRecommendationCount++;
+            }
+          }
+          
+          // Include extended procedure reviews mapped to technology
+          if (review.extendedProcedureReviews && review.extendedProcedureReviews.length > 0) {
+            review.extendedProcedureReviews.forEach(extReview => {
+              if (extReview.procedureId) {
+                const tech = procedureToTechnologyMap.get(extReview.procedureId);
+                if (tech) {
+                  totalRatingSum += extReview.overallRating;
+                  totalRatingCount++;
+                  if (extReview.wouldRecommend) {
+                    totalRecommendations++;
+                  }
+                  totalRecommendationCount++;
+                }
+              }
+            });
+          }
+        }
+      });
+
+      const currentAvgRating = totalRatingCount > 0 ? totalRatingSum / totalRatingCount : 0;
+      const currentRecRate = totalRecommendationCount > 0 ? (totalRecommendations / totalRecommendationCount) * 100 : 0;
+
+      // Calculate trend comparison
+      const trendChange = getTrendChange(currentAvgRating, previousAvgRating);
+
+      trends.push({
+        period: periodInfo.period,
+        startDate: periodInfo.startDate,
+        endDate: periodInfo.endDate,
+        averageRating: currentAvgRating,
+        recommendationRate: currentRecRate,
+        totalReviews: totalRatingCount, // Count of reviews for this entity type
+        previousPeriod: previousAvgRating > 0 ? {
+          averageRating: previousAvgRating,
+          recommendationRate: previousRecRate,
+          percentageChange: Math.abs(trendChange.percentageChange),
+          direction: trendChange.direction,
+        } : undefined,
+      });
+
+      previousAvgRating = currentAvgRating;
+      previousRecRate = currentRecRate;
+    });
+
+    return trends;
+  }
+}
+