@blackcode_sa/metaestetics-api 1.12.72 → 1.13.1

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

@@ -0,0 +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;
+  }>;
+}
+