@blackcode_sa/metaestetics-api 1.15.16 → 1.15.17-staging.0

package/src/types/analytics/analytics.types.ts

@@ -1,597 +1,597 @@
-import { Timestamp } from 'firebase/firestore';
-import { AppointmentStatus, PaymentStatus } from '../appointment';
-
-/**
- * Base metrics interface with common properties
- */
-export interface BaseMetrics {
-  total: number;
-  dateRange?: { start: Date; end: Date };
-}
-
-/**
- * Date range filter for analytics queries
- */
-export interface AnalyticsDateRange {
-  start: Date;
-  end: Date;
-}
-
-/**
- * Common filters for analytics queries
- */
-export interface AnalyticsFilters {
-  clinicBranchId?: string;
-  practitionerId?: string;
-  procedureId?: string;
-  patientId?: string;
-}
-
-/**
- * Grouping period for trend analysis
- */
-export type GroupingPeriod = 'day' | 'week' | 'month';
-
-/**
- * Trend period type (only predefined periods, no custom)
- */
-export type TrendPeriod = 'week' | 'month' | 'quarter' | 'year';
-
-/**
- * Entity type for grouping analytics
- */
-export type EntityType = 'clinic' | 'practitioner' | 'patient' | 'procedure' | 'technology';
-
-/**
- * Practitioner Analytics
- * Comprehensive metrics for a practitioner's performance
- */
-export interface PractitionerAnalytics extends BaseMetrics {
-  practitionerId: string;
-  practitionerName: string;
-  totalAppointments: number;
-  completedAppointments: number;
-  canceledAppointments: number;
-  noShowAppointments: number;
-  pendingAppointments: number;
-  confirmedAppointments: number;
-  cancellationRate: number; // percentage
-  noShowRate: number; // percentage
-  averageBookedTime: number; // minutes
-  averageActualTime: number; // minutes
-  timeEfficiency: number; // percentage
-  totalRevenue: number;
-  averageRevenuePerAppointment: number;
-  currency: string;
-  topProcedures: Array<{
-    procedureId: string;
-    procedureName: string;
-    count: number;
-    revenue: number;
-  }>;
-  patientRetentionRate: number; // percentage
-  uniquePatients: number;
-}
-
-/**
- * Procedure Analytics
- * Comprehensive metrics for procedure performance
- */
-export interface ProcedureAnalytics extends BaseMetrics {
-  procedureId: string;
-  procedureName: string;
-  procedureFamily: string;
-  categoryName: string;
-  subcategoryName: string;
-  technologyName: string;
-  totalAppointments: number;
-  completedAppointments: number;
-  canceledAppointments: number;
-  noShowAppointments: number;
-  cancellationRate: number; // percentage
-  noShowRate: number; // percentage
-  averageCost: number;
-  totalRevenue: number;
-  averageRevenuePerAppointment: number;
-  currency: string;
-  averageBookedDuration: number; // minutes
-  averageActualDuration: number; // minutes
-  productUsage: Array<{
-    productId: string;
-    productName: string;
-    brandName: string;
-    totalQuantity: number;
-    totalRevenue: number;
-    usageCount: number;
-  }>;
-}
-
-/**
- * Time Efficiency Metrics
- * Analysis of booked time vs actual time spent
- */
-export interface TimeEfficiencyMetrics {
-  totalAppointments: number;
-  appointmentsWithActualTime: number;
-  averageBookedDuration: number; // minutes
-  averageActualDuration: number; // minutes
-  averageEfficiency: number; // percentage
-  totalOverrun: number; // minutes
-  totalUnderutilization: number; // minutes
-  averageOverrun: number; // minutes
-  averageUnderutilization: number; // minutes
-  efficiencyDistribution: Array<{
-    range: string; // e.g., "0-50%", "50-75%", "75-100%", "100%+"
-    count: number;
-    percentage: number;
-  }>;
-}
-
-/**
- * Cancellation Metrics
- * Analysis of appointment cancellations
- */
-export interface CancellationMetrics {
-  entityId: string;
-  entityName: string;
-  entityType: EntityType;
-  totalAppointments: number;
-  canceledAppointments: number;
-  cancellationRate: number; // percentage
-  canceledByPatient: number;
-  canceledByClinic: number;
-  canceledByPractitioner: number;
-  canceledRescheduled: number;
-  averageCancellationLeadTime: number; // hours
-  cancellationReasons: Array<{
-    reason: string;
-    count: number;
-    percentage: number;
-  }>;
-  // Practitioner info when grouping by procedure
-  practitionerId?: string;
-  practitionerName?: string;
-}
-
-/**
- * No-Show Metrics
- * Analysis of appointment no-shows
- */
-export interface NoShowMetrics {
-  entityId: string;
-  entityName: string;
-  entityType: EntityType;
-  totalAppointments: number;
-  noShowAppointments: number;
-  noShowRate: number; // percentage
-  // Practitioner info when grouping by procedure
-  practitionerId?: string;
-  practitionerName?: string;
-}
-
-/**
- * Revenue Metrics
- * Financial analysis and revenue tracking
- */
-export interface RevenueMetrics {
-  totalRevenue: number;
-  averageRevenuePerAppointment: number;
-  totalAppointments: number;
-  completedAppointments: number;
-  currency: string;
-  revenueByStatus: Partial<Record<AppointmentStatus, number>>;
-  revenueByPaymentStatus: Partial<Record<PaymentStatus, number>>;
-  unpaidRevenue: number;
-  refundedRevenue: number;
-  totalTax: number;
-  totalSubtotal: number;
-}
-
-/**
- * Revenue Trend
- * Revenue data over time
- */
-export interface RevenueTrend {
-  period: string; // e.g., "2024-W01", "2024-01", "2024-Q1", "2024"
-  startDate: Date;
-  endDate: Date;
-  revenue: number;
-  appointmentCount: number;
-  averageRevenue: number;
-  currency?: string;
-  // Trend comparison (compared to previous period)
-  previousPeriod?: {
-    revenue: number;
-    appointmentCount: number;
-    percentageChange: number;
-    direction: 'up' | 'down' | 'stable';
-  };
-}
-
-/**
- * Duration Trend
- * Appointment duration trends over time
- */
-export interface DurationTrend {
-  period: string;
-  startDate: Date;
-  endDate: Date;
-  averageBookedDuration: number; // minutes
-  averageActualDuration: number; // minutes
-  averageEfficiency: number; // percentage
-  appointmentCount: number;
-  // Trend comparison (compared to previous period)
-  previousPeriod?: {
-    averageBookedDuration: number;
-    averageActualDuration: number;
-    averageEfficiency: number;
-    efficiencyPercentageChange: number;
-    direction: 'up' | 'down' | 'stable';
-  };
-}
-
-/**
- * Appointment Count Trend
- * Appointment count trends over time
- */
-export interface AppointmentTrend {
-  period: string;
-  startDate: Date;
-  endDate: Date;
-  totalAppointments: number;
-  completedAppointments: number;
-  canceledAppointments: number;
-  noShowAppointments: number;
-  pendingAppointments: number;
-  confirmedAppointments: number;
-  // Trend comparison (compared to previous period)
-  previousPeriod?: {
-    totalAppointments: number;
-    completedAppointments: number;
-    percentageChange: number;
-    direction: 'up' | 'down' | 'stable';
-  };
-}
-
-/**
- * Cancellation Rate Trend
- * Cancellation and no-show rate trends over time
- */
-export interface CancellationRateTrend {
-  period: string;
-  startDate: Date;
-  endDate: Date;
-  cancellationRate: number; // percentage
-  noShowRate: number; // percentage
-  totalAppointments: number;
-  canceledAppointments: number;
-  noShowAppointments: number;
-  // Trend comparison (compared to previous period)
-  previousPeriod?: {
-    cancellationRate: number;
-    noShowRate: number;
-    cancellationRateChange: number;
-    noShowRateChange: number;
-    direction: 'up' | 'down' | 'stable';
-  };
-}
-
-/**
- * Review Trend
- * Review rating and recommendation trends over time
- */
-export interface ReviewTrend {
-  period: string; // e.g., "2024-W01", "2024-01", "2024-Q1", "2024"
-  startDate: Date;
-  endDate: Date;
-  averageRating: number; // weighted average rating (0-5)
-  recommendationRate: number; // percentage
-  totalReviews: number;
-  practitionerAverage?: number; // if tracking practitioner reviews
-  procedureAverage?: number; // if tracking procedure reviews
-  // Trend comparison (compared to previous period)
-  previousPeriod?: {
-    averageRating: number;
-    recommendationRate: number;
-    percentageChange: number; // for average rating
-    direction: 'up' | 'down' | 'stable';
-  };
-  entityId?: string; // if grouped by entity
-  entityName?: string;
-}
-
-/**
- * Product Usage Metrics
- * Analysis of product usage in appointments
- */
-export interface ProductUsageMetrics {
-  productId: string;
-  productName: string;
-  brandId: string;
-  brandName: string;
-  totalQuantity: number;
-  totalRevenue: number;
-  averagePrice: number;
-  currency: string;
-  usageCount: number; // number of appointments using this product
-  averageQuantityPerAppointment: number;
-  usageByProcedure: Array<{
-    procedureId: string;
-    procedureName: string;
-    count: number;
-    totalQuantity: number;
-  }>;
-}
-
-/**
- * Product Revenue Metrics
- * Revenue contribution by product
- */
-export interface ProductRevenueMetrics {
-  productId: string;
-  productName: string;
-  brandName: string;
-  totalRevenue: number;
-  currency: string;
-  usageCount: number;
-  averageRevenuePerUsage: number;
-}
-
-/**
- * Product Usage by Procedure
- * Product usage patterns for specific procedures
- */
-export interface ProductUsageByProcedure {
-  procedureId: string;
-  procedureName: string;
-  products: Array<{
-    productId: string;
-    productName: string;
-    brandName: string;
-    totalQuantity: number;
-    totalRevenue: number;
-    usageCount: number;
-  }>;
-}
-
-/**
- * Patient Analytics
- * Comprehensive patient metrics
- */
-export interface PatientAnalytics {
-  patientId: string;
-  patientName: string;
-  totalAppointments: number;
-  completedAppointments: number;
-  canceledAppointments: number;
-  noShowAppointments: number;
-  cancellationRate: number; // percentage
-  noShowRate: number; // percentage
-  totalRevenue: number;
-  averageRevenuePerAppointment: number;
-  currency: string;
-  lifetimeValue: number;
-  firstAppointmentDate: Date | null;
-  lastAppointmentDate: Date | null;
-  averageDaysBetweenAppointments: number | null;
-  uniquePractitioners: number;
-  uniqueClinics: number;
-  favoriteProcedures: Array<{
-    procedureId: string;
-    procedureName: string;
-    count: number;
-  }>;
-}
-
-/**
- * Patient Lifetime Value Metrics
- * Patient value analysis
- */
-export interface PatientLifetimeValueMetrics {
-  totalPatients: number;
-  averageLifetimeValue: number;
-  currency: string;
-  topPatients: Array<{
-    patientId: string;
-    patientName: string;
-    lifetimeValue: number;
-    appointmentCount: number;
-  }>;
-  valueDistribution: Array<{
-    range: string; // e.g., "0-500", "500-1000", "1000+"
-    count: number;
-    percentage: number;
-  }>;
-}
-
-/**
- * Patient Retention Metrics
- * Patient retention and return analysis
- */
-export interface PatientRetentionMetrics {
-  totalPatients: number;
-  newPatients: number;
-  returningPatients: number;
-  retentionRate: number; // percentage
-  averageAppointmentsPerPatient: number;
-  patientsByAppointmentCount: Array<{
-    appointmentCount: number;
-    patientCount: number;
-    percentage: number;
-  }>;
-}
-
-/**
- * Cost Per Patient Metrics
- * Cost analysis per patient
- */
-export interface CostPerPatientMetrics {
-  totalPatients: number;
-  totalRevenue: number;
-  averageCostPerPatient: number;
-  currency: string;
-  costDistribution: Array<{
-    range: string;
-    patientCount: number;
-    percentage: number;
-  }>;
-  patientCosts?: Array<{
-    patientId: string;
-    patientName: string;
-    totalCost: number;
-    appointmentCount: number;
-    averageCost: number;
-  }>;
-}
-
-/**
- * Payment Status Breakdown
- * Analysis of payment statuses
- */
-export interface PaymentStatusBreakdown {
-  totalAppointments: number;
-  byStatus: Partial<Record<PaymentStatus, {
-    count: number;
-    percentage: number;
-    totalRevenue: number;
-  }>>;
-  unpaidCount: number;
-  unpaidRevenue: number;
-  paidCount: number;
-  paidRevenue: number;
-  partiallyPaidCount: number;
-  partiallyPaidRevenue: number;
-  refundedCount: number;
-  refundedRevenue: number;
-}
-
-/**
- * Clinic Analytics
- * Comprehensive clinic performance metrics
- */
-export interface ClinicAnalytics {
-  clinicBranchId: string;
-  clinicName: string;
-  totalAppointments: number;
-  completedAppointments: number;
-  canceledAppointments: number;
-  noShowAppointments: number;
-  cancellationRate: number; // percentage
-  noShowRate: number; // percentage
-  totalRevenue: number;
-  averageRevenuePerAppointment: number;
-  currency: string;
-  practitionerCount: number;
-  patientCount: number;
-  procedureCount: number;
-  topPractitioners: Array<{
-    practitionerId: string;
-    practitionerName: string;
-    appointmentCount: number;
-    revenue: number;
-  }>;
-  topProcedures: Array<{
-    procedureId: string;
-    procedureName: string;
-    appointmentCount: number;
-    revenue: number;
-  }>;
-}
-
-/**
- * Clinic Comparison Metrics
- * Comparison data for multiple clinics
- */
-export interface ClinicComparisonMetrics {
-  clinicBranchId: string;
-  clinicName: string;
-  totalAppointments: number;
-  completedAppointments: number;
-  cancellationRate: number;
-  noShowRate: number;
-  totalRevenue: number;
-  averageRevenuePerAppointment: number;
-  practitionerCount: number;
-  patientCount: number;
-  efficiency: number; // percentage
-}
-
-/**
- * Procedure Popularity
- * Popularity metrics for procedures
- */
-export interface ProcedurePopularity {
-  procedureId: string;
-  procedureName: string;
-  categoryName: string;
-  subcategoryName: string;
-  technologyName: string;
-  appointmentCount: number;
-  completedCount: number;
-  rank: number;
-}
-
-/**
- * Procedure Profitability
- * Profitability metrics for procedures
- */
-export interface ProcedureProfitability {
-  procedureId: string;
-  procedureName: string;
-  categoryName: string;
-  subcategoryName: string;
-  technologyName: string;
-  totalRevenue: number;
-  averageRevenue: number;
-  appointmentCount: number;
-  rank: number;
-}
-
-/**
- * Cancellation Reason Statistics
- * Breakdown of cancellation reasons
- */
-export interface CancellationReasonStats {
-  reason: string;
-  count: number;
-  percentage: number;
-  averageLeadTime: number; // hours
-}
-
-/**
- * Dashboard Analytics
- * Comprehensive dashboard data aggregation
- */
-export interface DashboardAnalytics {
-  overview: {
-    totalAppointments: number;
-    completedAppointments: number;
-    canceledAppointments: number;
-    noShowAppointments: number;
-    pendingAppointments: number;
-    confirmedAppointments: number;
-    totalRevenue: number;
-    averageRevenuePerAppointment: number;
-    currency: string;
-    uniquePatients: number;
-    uniquePractitioners: number;
-    uniqueProcedures: number;
-    cancellationRate: number;
-    noShowRate: number;
-  };
-  practitionerMetrics: PractitionerAnalytics[];
-  procedureMetrics: ProcedureAnalytics[];
-  cancellationMetrics: CancellationMetrics;
-  noShowMetrics: NoShowMetrics;
-  revenueTrends: RevenueTrend[];
-  timeEfficiency: TimeEfficiencyMetrics;
-  topProducts: ProductUsageMetrics[];
-  recentActivity: Array<{
-    type: 'appointment' | 'cancellation' | 'completion' | 'no_show';
-    date: Date;
-    description: string;
-    entityId?: string;
-    entityName?: string;
-  }>;
-}
-
+import { Timestamp } from 'firebase/firestore';
+import { AppointmentStatus, PaymentStatus } from '../appointment';
+
+/**
+ * Base metrics interface with common properties
+ */
+export interface BaseMetrics {
+  total: number;
+  dateRange?: { start: Date; end: Date };
+}
+
+/**
+ * Date range filter for analytics queries
+ */
+export interface AnalyticsDateRange {
+  start: Date;
+  end: Date;
+}
+
+/**
+ * Common filters for analytics queries
+ */
+export interface AnalyticsFilters {
+  clinicBranchId?: string;
+  practitionerId?: string;
+  procedureId?: string;
+  patientId?: string;
+}
+
+/**
+ * Grouping period for trend analysis
+ */
+export type GroupingPeriod = 'day' | 'week' | 'month';
+
+/**
+ * Trend period type (only predefined periods, no custom)
+ */
+export type TrendPeriod = 'week' | 'month' | 'quarter' | 'year';
+
+/**
+ * Entity type for grouping analytics
+ */
+export type EntityType = 'clinic' | 'practitioner' | 'patient' | 'procedure' | 'technology';
+
+/**
+ * Practitioner Analytics
+ * Comprehensive metrics for a practitioner's performance
+ */
+export interface PractitionerAnalytics extends BaseMetrics {
+  practitionerId: string;
+  practitionerName: string;
+  totalAppointments: number;
+  completedAppointments: number;
+  canceledAppointments: number;
+  noShowAppointments: number;
+  pendingAppointments: number;
+  confirmedAppointments: number;
+  cancellationRate: number; // percentage
+  noShowRate: number; // percentage
+  averageBookedTime: number; // minutes
+  averageActualTime: number; // minutes
+  timeEfficiency: number; // percentage
+  totalRevenue: number;
+  averageRevenuePerAppointment: number;
+  currency: string;
+  topProcedures: Array<{
+    procedureId: string;
+    procedureName: string;
+    count: number;
+    revenue: number;
+  }>;
+  patientRetentionRate: number; // percentage
+  uniquePatients: number;
+}
+
+/**
+ * Procedure Analytics
+ * Comprehensive metrics for procedure performance
+ */
+export interface ProcedureAnalytics extends BaseMetrics {
+  procedureId: string;
+  procedureName: string;
+  procedureFamily: string;
+  categoryName: string;
+  subcategoryName: string;
+  technologyName: string;
+  totalAppointments: number;
+  completedAppointments: number;
+  canceledAppointments: number;
+  noShowAppointments: number;
+  cancellationRate: number; // percentage
+  noShowRate: number; // percentage
+  averageCost: number;
+  totalRevenue: number;
+  averageRevenuePerAppointment: number;
+  currency: string;
+  averageBookedDuration: number; // minutes
+  averageActualDuration: number; // minutes
+  productUsage: Array<{
+    productId: string;
+    productName: string;
+    brandName: string;
+    totalQuantity: number;
+    totalRevenue: number;
+    usageCount: number;
+  }>;
+}
+
+/**
+ * Time Efficiency Metrics
+ * Analysis of booked time vs actual time spent
+ */
+export interface TimeEfficiencyMetrics {
+  totalAppointments: number;
+  appointmentsWithActualTime: number;
+  averageBookedDuration: number; // minutes
+  averageActualDuration: number; // minutes
+  averageEfficiency: number; // percentage
+  totalOverrun: number; // minutes
+  totalUnderutilization: number; // minutes
+  averageOverrun: number; // minutes
+  averageUnderutilization: number; // minutes
+  efficiencyDistribution: Array<{
+    range: string; // e.g., "0-50%", "50-75%", "75-100%", "100%+"
+    count: number;
+    percentage: number;
+  }>;
+}
+
+/**
+ * Cancellation Metrics
+ * Analysis of appointment cancellations
+ */
+export interface CancellationMetrics {
+  entityId: string;
+  entityName: string;
+  entityType: EntityType;
+  totalAppointments: number;
+  canceledAppointments: number;
+  cancellationRate: number; // percentage
+  canceledByPatient: number;
+  canceledByClinic: number;
+  canceledByPractitioner: number;
+  canceledRescheduled: number;
+  averageCancellationLeadTime: number; // hours
+  cancellationReasons: Array<{
+    reason: string;
+    count: number;
+    percentage: number;
+  }>;
+  // Practitioner info when grouping by procedure
+  practitionerId?: string;
+  practitionerName?: string;
+}
+
+/**
+ * No-Show Metrics
+ * Analysis of appointment no-shows
+ */
+export interface NoShowMetrics {
+  entityId: string;
+  entityName: string;
+  entityType: EntityType;
+  totalAppointments: number;
+  noShowAppointments: number;
+  noShowRate: number; // percentage
+  // Practitioner info when grouping by procedure
+  practitionerId?: string;
+  practitionerName?: string;
+}
+
+/**
+ * Revenue Metrics
+ * Financial analysis and revenue tracking
+ */
+export interface RevenueMetrics {
+  totalRevenue: number;
+  averageRevenuePerAppointment: number;
+  totalAppointments: number;
+  completedAppointments: number;
+  currency: string;
+  revenueByStatus: Partial<Record<AppointmentStatus, number>>;
+  revenueByPaymentStatus: Partial<Record<PaymentStatus, number>>;
+  unpaidRevenue: number;
+  refundedRevenue: number;
+  totalTax: number;
+  totalSubtotal: number;
+}
+
+/**
+ * Revenue Trend
+ * Revenue data over time
+ */
+export interface RevenueTrend {
+  period: string; // e.g., "2024-W01", "2024-01", "2024-Q1", "2024"
+  startDate: Date;
+  endDate: Date;
+  revenue: number;
+  appointmentCount: number;
+  averageRevenue: number;
+  currency?: string;
+  // Trend comparison (compared to previous period)
+  previousPeriod?: {
+    revenue: number;
+    appointmentCount: number;
+    percentageChange: number;
+    direction: 'up' | 'down' | 'stable';
+  };
+}
+
+/**
+ * Duration Trend
+ * Appointment duration trends over time
+ */
+export interface DurationTrend {
+  period: string;
+  startDate: Date;
+  endDate: Date;
+  averageBookedDuration: number; // minutes
+  averageActualDuration: number; // minutes
+  averageEfficiency: number; // percentage
+  appointmentCount: number;
+  // Trend comparison (compared to previous period)
+  previousPeriod?: {
+    averageBookedDuration: number;
+    averageActualDuration: number;
+    averageEfficiency: number;
+    efficiencyPercentageChange: number;
+    direction: 'up' | 'down' | 'stable';
+  };
+}
+
+/**
+ * Appointment Count Trend
+ * Appointment count trends over time
+ */
+export interface AppointmentTrend {
+  period: string;
+  startDate: Date;
+  endDate: Date;
+  totalAppointments: number;
+  completedAppointments: number;
+  canceledAppointments: number;
+  noShowAppointments: number;
+  pendingAppointments: number;
+  confirmedAppointments: number;
+  // Trend comparison (compared to previous period)
+  previousPeriod?: {
+    totalAppointments: number;
+    completedAppointments: number;
+    percentageChange: number;
+    direction: 'up' | 'down' | 'stable';
+  };
+}
+
+/**
+ * Cancellation Rate Trend
+ * Cancellation and no-show rate trends over time
+ */
+export interface CancellationRateTrend {
+  period: string;
+  startDate: Date;
+  endDate: Date;
+  cancellationRate: number; // percentage
+  noShowRate: number; // percentage
+  totalAppointments: number;
+  canceledAppointments: number;
+  noShowAppointments: number;
+  // Trend comparison (compared to previous period)
+  previousPeriod?: {
+    cancellationRate: number;
+    noShowRate: number;
+    cancellationRateChange: number;
+    noShowRateChange: number;
+    direction: 'up' | 'down' | 'stable';
+  };
+}
+
+/**
+ * Review Trend
+ * Review rating and recommendation trends over time
+ */
+export interface ReviewTrend {
+  period: string; // e.g., "2024-W01", "2024-01", "2024-Q1", "2024"
+  startDate: Date;
+  endDate: Date;
+  averageRating: number; // weighted average rating (0-5)
+  recommendationRate: number; // percentage
+  totalReviews: number;
+  practitionerAverage?: number; // if tracking practitioner reviews
+  procedureAverage?: number; // if tracking procedure reviews
+  // Trend comparison (compared to previous period)
+  previousPeriod?: {
+    averageRating: number;
+    recommendationRate: number;
+    percentageChange: number; // for average rating
+    direction: 'up' | 'down' | 'stable';
+  };
+  entityId?: string; // if grouped by entity
+  entityName?: string;
+}
+
+/**
+ * Product Usage Metrics
+ * Analysis of product usage in appointments
+ */
+export interface ProductUsageMetrics {
+  productId: string;
+  productName: string;
+  brandId: string;
+  brandName: string;
+  totalQuantity: number;
+  totalRevenue: number;
+  averagePrice: number;
+  currency: string;
+  usageCount: number; // number of appointments using this product
+  averageQuantityPerAppointment: number;
+  usageByProcedure: Array<{
+    procedureId: string;
+    procedureName: string;
+    count: number;
+    totalQuantity: number;
+  }>;
+}
+
+/**
+ * Product Revenue Metrics
+ * Revenue contribution by product
+ */
+export interface ProductRevenueMetrics {
+  productId: string;
+  productName: string;
+  brandName: string;
+  totalRevenue: number;
+  currency: string;
+  usageCount: number;
+  averageRevenuePerUsage: number;
+}
+
+/**
+ * Product Usage by Procedure
+ * Product usage patterns for specific procedures
+ */
+export interface ProductUsageByProcedure {
+  procedureId: string;
+  procedureName: string;
+  products: Array<{
+    productId: string;
+    productName: string;
+    brandName: string;
+    totalQuantity: number;
+    totalRevenue: number;
+    usageCount: number;
+  }>;
+}
+
+/**
+ * Patient Analytics
+ * Comprehensive patient metrics
+ */
+export interface PatientAnalytics {
+  patientId: string;
+  patientName: string;
+  totalAppointments: number;
+  completedAppointments: number;
+  canceledAppointments: number;
+  noShowAppointments: number;
+  cancellationRate: number; // percentage
+  noShowRate: number; // percentage
+  totalRevenue: number;
+  averageRevenuePerAppointment: number;
+  currency: string;
+  lifetimeValue: number;
+  firstAppointmentDate: Date | null;
+  lastAppointmentDate: Date | null;
+  averageDaysBetweenAppointments: number | null;
+  uniquePractitioners: number;
+  uniqueClinics: number;
+  favoriteProcedures: Array<{
+    procedureId: string;
+    procedureName: string;
+    count: number;
+  }>;
+}
+
+/**
+ * Patient Lifetime Value Metrics
+ * Patient value analysis
+ */
+export interface PatientLifetimeValueMetrics {
+  totalPatients: number;
+  averageLifetimeValue: number;
+  currency: string;
+  topPatients: Array<{
+    patientId: string;
+    patientName: string;
+    lifetimeValue: number;
+    appointmentCount: number;
+  }>;
+  valueDistribution: Array<{
+    range: string; // e.g., "0-500", "500-1000", "1000+"
+    count: number;
+    percentage: number;
+  }>;
+}
+
+/**
+ * Patient Retention Metrics
+ * Patient retention and return analysis
+ */
+export interface PatientRetentionMetrics {
+  totalPatients: number;
+  newPatients: number;
+  returningPatients: number;
+  retentionRate: number; // percentage
+  averageAppointmentsPerPatient: number;
+  patientsByAppointmentCount: Array<{
+    appointmentCount: number;
+    patientCount: number;
+    percentage: number;
+  }>;
+}
+
+/**
+ * Cost Per Patient Metrics
+ * Cost analysis per patient
+ */
+export interface CostPerPatientMetrics {
+  totalPatients: number;
+  totalRevenue: number;
+  averageCostPerPatient: number;
+  currency: string;
+  costDistribution: Array<{
+    range: string;
+    patientCount: number;
+    percentage: number;
+  }>;
+  patientCosts?: Array<{
+    patientId: string;
+    patientName: string;
+    totalCost: number;
+    appointmentCount: number;
+    averageCost: number;
+  }>;
+}
+
+/**
+ * Payment Status Breakdown
+ * Analysis of payment statuses
+ */
+export interface PaymentStatusBreakdown {
+  totalAppointments: number;
+  byStatus: Partial<Record<PaymentStatus, {
+    count: number;
+    percentage: number;
+    totalRevenue: number;
+  }>>;
+  unpaidCount: number;
+  unpaidRevenue: number;
+  paidCount: number;
+  paidRevenue: number;
+  partiallyPaidCount: number;
+  partiallyPaidRevenue: number;
+  refundedCount: number;
+  refundedRevenue: number;
+}
+
+/**
+ * Clinic Analytics
+ * Comprehensive clinic performance metrics
+ */
+export interface ClinicAnalytics {
+  clinicBranchId: string;
+  clinicName: string;
+  totalAppointments: number;
+  completedAppointments: number;
+  canceledAppointments: number;
+  noShowAppointments: number;
+  cancellationRate: number; // percentage
+  noShowRate: number; // percentage
+  totalRevenue: number;
+  averageRevenuePerAppointment: number;
+  currency: string;
+  practitionerCount: number;
+  patientCount: number;
+  procedureCount: number;
+  topPractitioners: Array<{
+    practitionerId: string;
+    practitionerName: string;
+    appointmentCount: number;
+    revenue: number;
+  }>;
+  topProcedures: Array<{
+    procedureId: string;
+    procedureName: string;
+    appointmentCount: number;
+    revenue: number;
+  }>;
+}
+
+/**
+ * Clinic Comparison Metrics
+ * Comparison data for multiple clinics
+ */
+export interface ClinicComparisonMetrics {
+  clinicBranchId: string;
+  clinicName: string;
+  totalAppointments: number;
+  completedAppointments: number;
+  cancellationRate: number;
+  noShowRate: number;
+  totalRevenue: number;
+  averageRevenuePerAppointment: number;
+  practitionerCount: number;
+  patientCount: number;
+  efficiency: number; // percentage
+}
+
+/**
+ * Procedure Popularity
+ * Popularity metrics for procedures
+ */
+export interface ProcedurePopularity {
+  procedureId: string;
+  procedureName: string;
+  categoryName: string;
+  subcategoryName: string;
+  technologyName: string;
+  appointmentCount: number;
+  completedCount: number;
+  rank: number;
+}
+
+/**
+ * Procedure Profitability
+ * Profitability metrics for procedures
+ */
+export interface ProcedureProfitability {
+  procedureId: string;
+  procedureName: string;
+  categoryName: string;
+  subcategoryName: string;
+  technologyName: string;
+  totalRevenue: number;
+  averageRevenue: number;
+  appointmentCount: number;
+  rank: number;
+}
+
+/**
+ * Cancellation Reason Statistics
+ * Breakdown of cancellation reasons
+ */
+export interface CancellationReasonStats {
+  reason: string;
+  count: number;
+  percentage: number;
+  averageLeadTime: number; // hours
+}
+
+/**
+ * Dashboard Analytics
+ * Comprehensive dashboard data aggregation
+ */
+export interface DashboardAnalytics {
+  overview: {
+    totalAppointments: number;
+    completedAppointments: number;
+    canceledAppointments: number;
+    noShowAppointments: number;
+    pendingAppointments: number;
+    confirmedAppointments: number;
+    totalRevenue: number;
+    averageRevenuePerAppointment: number;
+    currency: string;
+    uniquePatients: number;
+    uniquePractitioners: number;
+    uniqueProcedures: number;
+    cancellationRate: number;
+    noShowRate: number;
+  };
+  practitionerMetrics: PractitionerAnalytics[];
+  procedureMetrics: ProcedureAnalytics[];
+  cancellationMetrics: CancellationMetrics;
+  noShowMetrics: NoShowMetrics;
+  revenueTrends: RevenueTrend[];
+  timeEfficiency: TimeEfficiencyMetrics;
+  topProducts: ProductUsageMetrics[];
+  recentActivity: Array<{
+    type: 'appointment' | 'cancellation' | 'completion' | 'no_show';
+    date: Date;
+    description: string;
+    entityId?: string;
+    entityName?: string;
+  }>;
+}
+