@blackcode_sa/metaestetics-api 1.12.68 → 1.13.0

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

@@ -0,0 +1,500 @@
+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';
+
+/**
+ * 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;
+  }>;
+}
+
+/**
+ * No-Show Metrics
+ * Analysis of appointment no-shows
+ */
+export interface NoShowMetrics {
+  entityId: string;
+  entityName: string;
+  entityType: EntityType;
+  totalAppointments: number;
+  noShowAppointments: number;
+  noShowRate: number; // percentage
+}
+
+/**
+ * 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-01-01", "2024-W01", "2024-01"
+  startDate: Date;
+  endDate: Date;
+  revenue: number;
+  appointmentCount: number;
+  averageRevenue: number;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+  }>;
+}
+

package/src/types/analytics/grouped-analytics.types.ts

@@ -0,0 +1,148 @@
+import { EntityType } from './analytics.types';
+
+/**
+ * Base interface for grouped analytics results
+ * All grouped analytics share common entity identification
+ */
+export interface GroupedAnalyticsBase {
+  entityId: string;
+  entityName: string;
+  entityType: EntityType;
+}
+
+/**
+ * Grouped Revenue Metrics
+ * Revenue analytics grouped by clinic, practitioner, procedure, or patient
+ */
+export interface GroupedRevenueMetrics extends GroupedAnalyticsBase {
+  totalRevenue: number;
+  averageRevenuePerAppointment: number;
+  totalAppointments: number;
+  completedAppointments: number;
+  currency: string;
+  unpaidRevenue: number;
+  refundedRevenue: number;
+  totalTax: number;
+  totalSubtotal: number;
+}
+
+/**
+ * Grouped Product Usage Metrics
+ * Product usage analytics grouped by clinic, practitioner, procedure, or patient
+ */
+export interface GroupedProductUsageMetrics extends GroupedAnalyticsBase {
+  totalProductsUsed: number;
+  uniqueProducts: number;
+  totalProductRevenue: number;
+  totalProductQuantity: number;
+  averageProductsPerAppointment: number;
+  topProducts: Array<{
+    productId: string;
+    productName: string;
+    brandName: string;
+    totalQuantity: number;
+    totalRevenue: number;
+    usageCount: number;
+  }>;
+}
+
+/**
+ * Grouped Patient Retention Metrics
+ * Patient retention analytics grouped by clinic, practitioner, or procedure
+ */
+export interface GroupedPatientRetentionMetrics extends GroupedAnalyticsBase {
+  totalPatients: number;
+  newPatients: number;
+  returningPatients: number;
+  retentionRate: number; // percentage
+  averageAppointmentsPerPatient: number;
+  patientsByAppointmentCount: Array<{
+    appointmentCount: number;
+    patientCount: number;
+    percentage: number;
+  }>;
+}
+
+/**
+ * Grouped Time Efficiency Metrics
+ * Time efficiency analytics grouped by clinic, practitioner, procedure, or patient
+ */
+export interface GroupedTimeEfficiencyMetrics extends GroupedAnalyticsBase {
+  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
+}
+
+/**
+ * Grouped Patient Behavior Metrics
+ * Patient behavior (no-show, cancellation) grouped by clinic, practitioner, or procedure
+ */
+export interface GroupedPatientBehaviorMetrics extends GroupedAnalyticsBase {
+  totalPatients: number;
+  patientsWithNoShows: number;
+  patientsWithCancellations: number;
+  averageNoShowRate: number; // percentage (average across patients)
+  averageCancellationRate: number; // percentage (average across patients)
+  topNoShowPatients: Array<{
+    patientId: string;
+    patientName: string;
+    noShowCount: number;
+    totalAppointments: number;
+    noShowRate: number;
+  }>;
+  topCancellationPatients: Array<{
+    patientId: string;
+    patientName: string;
+    cancellationCount: number;
+    totalAppointments: number;
+    cancellationRate: number;
+  }>;
+}
+
+/**
+ * Grouped Procedure Performance Metrics
+ * Procedure performance grouped by clinic or practitioner
+ */
+export interface GroupedProcedurePerformanceMetrics extends GroupedAnalyticsBase {
+  totalProcedures: number;
+  totalAppointments: number;
+  completedAppointments: number;
+  totalRevenue: number;
+  averageRevenuePerProcedure: number;
+  topProcedures: Array<{
+    procedureId: string;
+    procedureName: string;
+    appointmentCount: number;
+    revenue: number;
+    cancellationRate: number;
+    noShowRate: number;
+  }>;
+}
+
+/**
+ * Grouped Practitioner Performance Metrics
+ * Practitioner performance grouped by clinic
+ */
+export interface GroupedPractitionerPerformanceMetrics extends GroupedAnalyticsBase {
+  totalPractitioners: number;
+  totalAppointments: number;
+  completedAppointments: number;
+  totalRevenue: number;
+  averageRevenuePerPractitioner: number;
+  topPractitioners: Array<{
+    practitionerId: string;
+    practitionerName: string;
+    appointmentCount: number;
+    revenue: number;
+    cancellationRate: number;
+    noShowRate: number;
+    timeEfficiency: number;
+  }>;
+}
+

package/src/types/analytics/index.ts

@@ -0,0 +1,4 @@
+export * from './analytics.types';
+export * from './stored-analytics.types';
+export * from './grouped-analytics.types';
+