@blackcode_sa/metaestetics-api 1.12.68 → 1.13.0

package/src/services/analytics/QUICK_START.md

@@ -0,0 +1,393 @@
+# Analytics Service - Quick Start Guide
+
+## 🚀 What We Can Do
+
+The Analytics Service provides **comprehensive insights** into your clinic operations:
+
+- **Financial Intelligence**: Revenue, costs, payment tracking
+- **Practitioner Performance**: Doctor efficiency, cancellations, revenue
+- **Procedure Analytics**: Popularity, profitability, product usage
+- **Time Management**: Booked vs actual time, efficiency
+- **Cancellation & No-Show Analysis**: Rates by clinic/doctor/patient/procedure
+- **Patient Insights**: Lifetime value, retention, behavior
+- **Product Usage**: Usage patterns, revenue contribution
+- **Clinic Performance**: Overall metrics and comparisons
+
+---
+
+## 🔄 How It Works: Computed vs On-Demand
+
+### **Pre-Computed Analytics** (Default - Recommended) ⚡
+
+**How:**
+1. Cloud Function runs **every 12 hours**
+2. Computes analytics for all clinics
+3. Stores in Firestore: `clinics/{clinicBranchId}/analytics/`
+4. Client reads cached data (instant!)
+
+**Benefits:**
+- ⚡ **Fast**: 1 document read = instant response
+- 💰 **Cheap**: 1 read vs hundreds/thousands
+- 📈 **Scalable**: Works with large datasets
+
+**Example:**
+```typescript
+// Automatically uses cached data if fresh (< 12 hours)
+const dashboard = await analyticsService.getDashboardData(
+  { clinicBranchId: 'clinic-123' },
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+// Returns instantly! ⚡
+```
+
+### **On-Demand Calculation** (Fallback) 🔄
+
+**When:**
+- No cached data exists
+- Cache is stale (> 12 hours)
+- You set `useCache: false`
+- Custom date ranges
+
+**How:**
+1. Queries all appointments
+2. Calculates metrics in real-time
+3. Returns results
+
+**Example:**
+```typescript
+// Force on-demand calculation
+const dashboard = await analyticsService.getDashboardData(
+  { clinicBranchId: 'clinic-123' },
+  dateRange,
+  { useCache: false } // Force calculation
+);
+```
+
+---
+
+## 📊 Available Analytics
+
+### 1. **Practitioner Analytics** 👨‍⚕️
+```typescript
+const metrics = await analyticsService.getPractitionerAnalytics(
+  'practitioner-id',
+  dateRange
+);
+// Returns: appointments, cancellations, no-shows, revenue, time efficiency, etc.
+```
+
+### 2. **Procedure Analytics** 🏥
+```typescript
+// Single procedure
+const procedure = await analyticsService.getProcedureAnalytics('procedure-id', dateRange);
+
+// All procedures
+const all = await analyticsService.getProcedureAnalytics(undefined, dateRange);
+
+// Most popular
+const popular = await analyticsService.getProcedurePopularity(dateRange, 10);
+
+// Most profitable
+const profitable = await analyticsService.getProcedureProfitability(dateRange, 10);
+```
+
+### 3. **Time Efficiency** ⏱️
+```typescript
+const time = await analyticsService.getTimeEfficiencyMetrics(
+  { clinicBranchId: 'clinic-123' },
+  dateRange
+);
+// Returns: efficiency %, overrun, underutilization, etc.
+```
+
+### 4. **Cancellation Metrics** ❌
+```typescript
+const cancellations = await analyticsService.getCancellationMetrics(
+  'practitioner', // or 'clinic', 'patient', 'procedure'
+  dateRange
+);
+// Returns array with cancellation rates, reasons, lead times
+```
+
+### 5. **No-Show Metrics** 🚫
+```typescript
+const noShows = await analyticsService.getNoShowMetrics(
+  'practitioner', // or 'clinic', 'patient', 'procedure'
+  dateRange
+);
+// Returns array with no-show rates per entity
+```
+
+### 6. **Revenue Metrics** 💰
+```typescript
+const revenue = await analyticsService.getRevenueMetrics(
+  { clinicBranchId: 'clinic-123' },
+  dateRange
+);
+// Returns: total revenue, by status, by payment status, unpaid, etc.
+```
+
+### 7. **Product Usage** 📦
+```typescript
+const products = await analyticsService.getProductUsageMetrics(
+  undefined, // or 'product-id'
+  dateRange
+);
+// Returns: usage counts, revenue, quantities per product
+```
+
+### 8. **Patient Analytics** 👥
+```typescript
+const patient = await analyticsService.getPatientAnalytics(
+  'patient-id', // or undefined for all
+  dateRange
+);
+// Returns: lifetime value, retention, frequency, etc.
+```
+
+### 9. **Dashboard Data** 📊
+```typescript
+const dashboard = await analyticsService.getDashboardData(
+  { clinicBranchId: 'clinic-123' },
+  dateRange
+);
+// Returns: comprehensive dashboard with all metrics
+```
+
+---
+
+## 🎯 Specific Use Case: Patient No-Show Per Doctor
+
+### **Question**: "Which patients have the highest no-show rate for each doctor?"
+
+### **Solution 1: No-Show Rates by Practitioner** ✅
+
+```typescript
+// Get no-show metrics grouped by practitioner (doctor)
+const noShowByPractitioner = await analyticsService.getNoShowMetrics(
+  'practitioner',
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+
+// Returns array:
+// [
+//   {
+//     entityId: 'practitioner-123',
+//     entityName: 'Dr. Smith',
+//     entityType: 'practitioner',
+//     totalAppointments: 100,
+//     noShowAppointments: 15,
+//     noShowRate: 15.0  // 15%
+//   },
+//   ...
+// ]
+
+// Sort by no-show rate (highest first)
+const sorted = noShowByPractitioner
+  .sort((a, b) => b.noShowRate - a.noShowRate);
+
+console.log('Doctors ranked by no-show rate:');
+sorted.forEach((doctor, index) => {
+  console.log(`${index + 1}. ${doctor.entityName}: ${doctor.noShowRate}%`);
+});
+```
+
+### **Solution 2: Patient No-Shows for a Specific Doctor** ✅
+
+```typescript
+// Step 1: Get all appointments for a specific practitioner
+const practitionerId = 'practitioner-123';
+const dateRange = { start: new Date('2024-01-01'), end: new Date('2024-12-31') };
+
+// Get practitioner analytics (includes no-show count)
+const practitionerMetrics = await analyticsService.getPractitionerAnalytics(
+  practitionerId,
+  dateRange
+);
+
+console.log(`Dr. ${practitionerMetrics.practitionerName}:`);
+console.log(`  Total Appointments: ${practitionerMetrics.totalAppointments}`);
+console.log(`  No-Shows: ${practitionerMetrics.noShowAppointments}`);
+console.log(`  No-Show Rate: ${practitionerMetrics.noShowRate}%`);
+
+// Step 2: Get patient-level breakdown for this doctor
+// (You can filter appointments manually or use patient analytics)
+
+// Get patient analytics filtered by practitioner
+const allPatients = await analyticsService.getPatientAnalytics(undefined, dateRange);
+
+// Filter patients who had appointments with this practitioner
+// and calculate their no-show rates
+const patientsWithThisDoctor = allPatients
+  .filter(patient => {
+    // Check if patient had appointments with this practitioner
+    // (You'd need to query appointments or enhance patient analytics)
+    return true; // Placeholder
+  })
+  .sort((a, b) => b.noShowRate - a.noShowRate);
+
+console.log('\nPatients with highest no-show rates for this doctor:');
+patientsWithThisDoctor.slice(0, 10).forEach((patient, index) => {
+  console.log(`${index + 1}. ${patient.patientName}: ${patient.noShowRate}%`);
+});
+```
+
+### **Solution 3: Cross-Analysis (No-Shows by Patient AND Doctor)** ✅
+
+```typescript
+// Get no-shows grouped by patient
+const noShowByPatient = await analyticsService.getNoShowMetrics(
+  'patient',
+  dateRange
+);
+
+// Get no-shows grouped by practitioner
+const noShowByPractitioner = await analyticsService.getNoShowMetrics(
+  'practitioner',
+  dateRange
+);
+
+// For detailed cross-analysis, you can:
+// 1. Get all appointments
+// 2. Filter no-shows
+// 3. Group by practitioner AND patient
+const appointments = await analyticsService['fetchAppointments'](
+  undefined,
+  dateRange
+);
+
+const noShows = appointments.filter(a => a.status === AppointmentStatus.NO_SHOW);
+
+// Create a map: practitioner -> patients -> no-show count
+const practitionerPatientMap = new Map<
+  string,
+  Map<string, { patientName: string; noShowCount: number; totalAppointments: number }>
+>();
+
+appointments.forEach(appointment => {
+  const practitionerId = appointment.practitionerId;
+  const patientId = appointment.patientId;
+  const patientName = appointment.patientInfo?.fullName || 'Unknown';
+
+  if (!practitionerPatientMap.has(practitionerId)) {
+    practitionerPatientMap.set(practitionerId, new Map());
+  }
+
+  const patientMap = practitionerPatientMap.get(practitionerId)!;
+  if (!patientMap.has(patientId)) {
+    patientMap.set(patientId, { patientName, noShowCount: 0, totalAppointments: 0 });
+  }
+
+  const patientData = patientMap.get(patientId)!;
+  patientData.totalAppointments++;
+
+  if (appointment.status === AppointmentStatus.NO_SHOW) {
+    patientData.noShowCount++;
+  }
+});
+
+// Display results
+practitionerPatientMap.forEach((patientMap, practitionerId) => {
+  const practitioner = appointments.find(a => a.practitionerId === practitionerId);
+  const practitionerName = practitioner?.practitionerInfo?.name || 'Unknown';
+
+  console.log(`\n${practitionerName}:`);
+  
+  const patientRates = Array.from(patientMap.entries())
+    .map(([patientId, data]) => ({
+      patientId,
+      patientName: data.patientName,
+      noShowRate: (data.noShowCount / data.totalAppointments) * 100,
+      noShowCount: data.noShowCount,
+      totalAppointments: data.totalAppointments,
+    }))
+    .sort((a, b) => b.noShowRate - a.noShowRate);
+
+  patientRates.forEach(patient => {
+    console.log(`  ${patient.patientName}: ${patient.noShowRate.toFixed(1)}% (${patient.noShowCount}/${patient.totalAppointments})`);
+  });
+});
+```
+
+---
+
+## 📝 Quick Examples
+
+### Example 1: Doctor Performance Dashboard
+```typescript
+const practitionerMetrics = await analyticsService.getPractitionerAnalytics(
+  'practitioner-id',
+  dateRange
+);
+
+console.log(`Doctor: ${practitionerMetrics.practitionerName}`);
+console.log(`Appointments: ${practitionerMetrics.totalAppointments}`);
+console.log(`Cancellation Rate: ${practitionerMetrics.cancellationRate}%`);
+console.log(`No-Show Rate: ${practitionerMetrics.noShowRate}%`);
+console.log(`Time Efficiency: ${practitionerMetrics.timeEfficiency}%`);
+console.log(`Total Revenue: ${practitionerMetrics.totalRevenue} ${practitionerMetrics.currency}`);
+```
+
+### Example 2: Top Procedures by Revenue
+```typescript
+const topProcedures = await analyticsService.getProcedureProfitability(
+  dateRange,
+  10
+);
+
+topProcedures.forEach((procedure, index) => {
+  console.log(`${index + 1}. ${procedure.procedureName}`);
+  console.log(`   Revenue: ${procedure.totalRevenue}`);
+  console.log(`   Appointments: ${procedure.appointmentCount}`);
+});
+```
+
+### Example 3: Clinic Comparison
+```typescript
+const clinic1 = await analyticsService.getClinicAnalytics('clinic-1', dateRange);
+const clinic2 = await analyticsService.getClinicAnalytics('clinic-2', dateRange);
+
+console.log('Clinic Comparison:');
+console.log(`Clinic 1 Revenue: ${clinic1.totalRevenue}`);
+console.log(`Clinic 2 Revenue: ${clinic2.totalRevenue}`);
+console.log(`Clinic 1 Cancellation Rate: ${clinic1.cancellationRate}%`);
+console.log(`Clinic 2 Cancellation Rate: ${clinic2.cancellationRate}%`);
+```
+
+---
+
+## 🎛️ Configuration
+
+### Change Cache Freshness
+```typescript
+// Use cache if data is less than 6 hours old
+const metrics = await analyticsService.getPractitionerAnalytics(
+  practitionerId,
+  dateRange,
+  { maxCacheAgeHours: 6 }
+);
+```
+
+### Force On-Demand Calculation
+```typescript
+const metrics = await analyticsService.getPractitionerAnalytics(
+  practitionerId,
+  dateRange,
+  { useCache: false }
+);
+```
+
+### Change Cloud Function Schedule
+Edit `Cloud/functions/src/analytics/computeAnalytics.ts`:
+```typescript
+schedule: "every 6 hours" // or "every 24 hours"
+```
+
+---
+
+## 📚 Full Documentation
+
+- **Usage Guide**: `USAGE_GUIDE.md` - Complete guide with all use cases
+- **Architecture**: `ARCHITECTURE.md` - How computed vs on-demand works
+- **README**: `README.md` - API reference
+

package/src/services/analytics/README.md

@@ -0,0 +1,287 @@
+# Analytics Service
+
+Comprehensive financial and analytical intelligence service for the Clinic Admin app. Provides insights about doctors, procedures, appointments, patients, products, and clinic operations.
+
+## Overview
+
+The `AnalyticsService` extends `BaseService` and provides methods to analyze appointment data, calculate metrics, and generate reports for clinic administration.
+
+## Usage
+
+### Initialization
+
+```typescript
+import { AnalyticsService } from '@blackcode_sa/metaestetics-api';
+import { AppointmentService } from '@blackcode_sa/metaestetics-api';
+
+// Initialize dependencies
+const appointmentService = new AppointmentService(db, auth, app, ...);
+
+// Initialize analytics service
+const analyticsService = new AnalyticsService(db, auth, app, appointmentService);
+```
+
+## Available Methods
+
+### ⚡ **Grouped Analytics** (NEW!)
+
+All analytics now support **consistent grouping** by clinic, practitioner, procedure, patient, or technology:
+
+- `getRevenueMetricsByEntity(groupBy, dateRange?, filters?)` - Revenue by entity
+- `getProductUsageMetricsByEntity(groupBy, dateRange?, filters?)` - Product usage by entity
+- `getTimeEfficiencyMetricsByEntity(groupBy, dateRange?, filters?)` - Time efficiency by entity
+- `getPatientBehaviorMetricsByEntity(groupBy, dateRange?, filters?)` - Patient behavior by entity
+- `getCancellationMetrics(groupBy, dateRange?)` - Cancellations by entity (existing)
+- `getNoShowMetrics(groupBy, dateRange?)` - No-shows by entity (existing)
+
+**Technology Grouping**: Groups all procedures using the same technology across all doctors (e.g., all Botox treatments regardless of which doctor performed them).
+
+**See [GROUPED_ANALYTICS.md](./GROUPED_ANALYTICS.md) for complete guide and examples.**
+
+### Practitioner Analytics
+
+#### `getPractitionerAnalytics(practitionerId, dateRange?)`
+
+Get comprehensive performance metrics for a practitioner.
+
+**Returns**: `PractitionerAnalytics`
+
+**Example**:
+```typescript
+const metrics = await analyticsService.getPractitionerAnalytics(
+  'practitioner-id-123',
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+
+console.log(`Total appointments: ${metrics.totalAppointments}`);
+console.log(`Cancellation rate: ${metrics.cancellationRate}%`);
+console.log(`Total revenue: ${metrics.totalRevenue} ${metrics.currency}`);
+```
+
+### Procedure Analytics
+
+#### `getProcedureAnalytics(procedureId?, dateRange?)`
+
+Get performance metrics for one or all procedures.
+
+**Returns**: `ProcedureAnalytics | ProcedureAnalytics[]`
+
+**Example**:
+```typescript
+// Get analytics for a specific procedure
+const procedureMetrics = await analyticsService.getProcedureAnalytics(
+  'procedure-id-123',
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+
+// Get analytics for all procedures
+const allProcedures = await analyticsService.getProcedureAnalytics(
+  undefined,
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+```
+
+#### `getProcedurePopularity(dateRange?, limit?)`
+
+Get the most popular procedures by appointment count.
+
+**Returns**: `ProcedurePopularity[]`
+
+**Example**:
+```typescript
+const topProcedures = await analyticsService.getProcedurePopularity(
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') },
+  10 // Top 10 procedures
+);
+```
+
+#### `getProcedureProfitability(dateRange?, limit?)`
+
+Get the most profitable procedures by revenue.
+
+**Returns**: `ProcedureProfitability[]`
+
+**Example**:
+```typescript
+const profitableProcedures = await analyticsService.getProcedureProfitability(
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') },
+  10
+);
+```
+
+### Time Efficiency Analytics
+
+#### `getTimeEfficiencyMetrics(filters?, dateRange?)`
+
+Analyze booked time vs actual time spent on appointments.
+
+**Returns**: `TimeEfficiencyMetrics`
+
+**Example**:
+```typescript
+const timeMetrics = await analyticsService.getTimeEfficiencyMetrics(
+  { clinicBranchId: 'clinic-123' },
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+
+console.log(`Average efficiency: ${timeMetrics.averageEfficiency}%`);
+console.log(`Average overrun: ${timeMetrics.averageOverrun} minutes`);
+```
+
+### Cancellation & No-Show Analytics
+
+#### `getCancellationMetrics(groupBy, dateRange?)`
+
+Get cancellation metrics grouped by clinic, practitioner, patient, or procedure.
+
+**Returns**: `CancellationMetrics | CancellationMetrics[]`
+
+**Example**:
+```typescript
+// Get cancellations by clinic
+const clinicCancellations = await analyticsService.getCancellationMetrics(
+  'clinic',
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+
+// Get cancellations by practitioner
+const practitionerCancellations = await analyticsService.getCancellationMetrics(
+  'practitioner',
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+```
+
+#### `getNoShowMetrics(groupBy, dateRange?)`
+
+Get no-show metrics grouped by clinic, practitioner, patient, or procedure.
+
+**Returns**: `NoShowMetrics | NoShowMetrics[]`
+
+**Example**:
+```typescript
+const noShowMetrics = await analyticsService.getNoShowMetrics(
+  'patient',
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+```
+
+### Financial Analytics
+
+#### `getRevenueMetrics(filters?, dateRange?)`
+
+Get comprehensive revenue metrics.
+
+**Returns**: `RevenueMetrics`
+
+**Example**:
+```typescript
+const revenue = await analyticsService.getRevenueMetrics(
+  { clinicBranchId: 'clinic-123' },
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+
+console.log(`Total revenue: ${revenue.totalRevenue} ${revenue.currency}`);
+console.log(`Unpaid revenue: ${revenue.unpaidRevenue}`);
+```
+
+### Product Usage Analytics
+
+#### `getProductUsageMetrics(productId?, dateRange?)`
+
+Get product usage metrics for one or all products.
+
+**Returns**: `ProductUsageMetrics | ProductUsageMetrics[]`
+
+**Example**:
+```typescript
+// Get usage for a specific product
+const productMetrics = await analyticsService.getProductUsageMetrics(
+  'product-id-123',
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+
+// Get usage for all products
+const allProducts = await analyticsService.getProductUsageMetrics(
+  undefined,
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+```
+
+### Patient Analytics
+
+#### `getPatientAnalytics(patientId?, dateRange?)`
+
+Get analytics for one or all patients.
+
+**Returns**: `PatientAnalytics | PatientAnalytics[]`
+
+**Example**:
+```typescript
+const patientMetrics = await analyticsService.getPatientAnalytics(
+  'patient-id-123',
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+
+console.log(`Lifetime value: ${patientMetrics.lifetimeValue}`);
+console.log(`Average days between appointments: ${patientMetrics.averageDaysBetweenAppointments}`);
+```
+
+### Dashboard Analytics
+
+#### `getDashboardData(filters?, dateRange?)`
+
+Get comprehensive dashboard data aggregation.
+
+**Returns**: `DashboardAnalytics`
+
+**Example**:
+```typescript
+const dashboard = await analyticsService.getDashboardData(
+  { clinicBranchId: 'clinic-123' },
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+
+console.log(`Total appointments: ${dashboard.overview.totalAppointments}`);
+console.log(`Total revenue: ${dashboard.overview.totalRevenue}`);
+console.log(`Top practitioners:`, dashboard.practitionerMetrics);
+```
+
+## Cost Calculation Priority
+
+The service calculates appointment costs using the following priority:
+
+1. **`metadata.finalbilling.finalPrice`** - If available, uses the final billing price
+2. **`metadata.zonesData`** - Calculates from zone item subtotals
+3. **`appointment.cost`** - Falls back to base appointment cost
+
+## Time Efficiency Calculation
+
+Time efficiency is calculated as:
+- **Booked Duration**: `appointmentEndTime - appointmentStartTime` (minutes)
+- **Actual Duration**: `actualDurationMinutes` or booked duration if not available
+- **Efficiency**: `(actualDuration / bookedDuration) * 100` (percentage)
+- **Overrun**: Positive difference if actual > booked
+- **Underutilization**: Positive difference if booked > actual
+
+## Status Filtering
+
+The service filters appointments by status:
+
+- **Completed**: `AppointmentStatus.COMPLETED`
+- **Canceled**: `CANCELED_PATIENT`, `CANCELED_CLINIC`, `CANCELED_PATIENT_RESCHEDULED`
+- **No-Show**: `AppointmentStatus.NO_SHOW`
+- **Active**: All statuses except canceled and no-show
+
+## Performance Considerations
+
+- The service uses the `AppointmentService` to query appointments efficiently
+- Large date ranges may require pagination (to be implemented)
+- Consider caching dashboard data for frequently accessed metrics
+- Use specific filters to reduce query scope when possible
+
+## Related Documentation
+
+- [Analytics Types](../../types/analytics/analytics.types.ts)
+- [Appointment Service](../appointment/README.md)
+- [Full Proposal](../../backoffice/services/analytics.service.proposal.md)
+