@blackcode_sa/metaestetics-api 1.12.72 → 1.13.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blackcode_sa/metaestetics-api",
   "private": false,
-  "version": "1.12.72",
+  "version": "1.13.1",
   "description": "Firebase authentication service with anonymous upgrade support",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/admin/analytics/analytics.admin.service.ts

@@ -0,0 +1,278 @@
+import * as admin from 'firebase-admin';
+import { AnalyticsService } from '../../services/analytics/analytics.service';
+import {
+  AnalyticsDateRange,
+  AnalyticsFilters,
+  EntityType,
+} from '../../types/analytics';
+import {
+  PractitionerAnalytics,
+  ProcedureAnalytics,
+  TimeEfficiencyMetrics,
+  CancellationMetrics,
+  NoShowMetrics,
+  RevenueMetrics,
+  ProductUsageMetrics,
+  PatientAnalytics,
+  ClinicAnalytics,
+  DashboardAnalytics,
+  GroupedRevenueMetrics,
+  GroupedProductUsageMetrics,
+  GroupedTimeEfficiencyMetrics,
+  GroupedPatientBehaviorMetrics,
+} from '../../types/analytics';
+import { Appointment } from '../../types/appointment';
+import { APPOINTMENTS_COLLECTION } from '../../types/appointment';
+
+/**
+ * Admin version of AnalyticsService that uses Firebase Admin SDK
+ * This is intended for use in Cloud Functions and server-side code
+ */
+export class AnalyticsAdminService {
+  private analyticsService: AnalyticsService;
+  private db: admin.firestore.Firestore;
+
+  /**
+   * Creates a new AnalyticsAdminService instance
+   *
+   * @param firestore - Admin Firestore instance (optional, defaults to admin.firestore())
+   */
+  constructor(firestore?: admin.firestore.Firestore) {
+    this.db = firestore || admin.firestore();
+    
+    // Create a mock Firebase App for client SDK compatibility
+    const mockApp = {
+      name: '[DEFAULT]',
+      options: {},
+      automaticDataCollectionEnabled: false,
+    } as any;
+
+    // Create mock Auth (not used by AnalyticsService)
+    const mockAuth = {} as any;
+
+    // Create AppointmentService adapter that uses admin SDK
+    const appointmentService = this.createAppointmentServiceAdapter();
+
+    // Initialize AnalyticsService with adapted dependencies
+    this.analyticsService = new AnalyticsService(
+      this.db as any, // Cast admin Firestore to client Firestore type
+      mockAuth,
+      mockApp,
+      appointmentService,
+    );
+  }
+
+  /**
+   * Creates an adapter for AppointmentService to work with admin SDK
+   */
+  private createAppointmentServiceAdapter(): any {
+    return {
+      searchAppointments: async (params: any) => {
+        // Build query using admin SDK
+        let query: admin.firestore.Query = this.db.collection(APPOINTMENTS_COLLECTION);
+
+        if (params.clinicBranchId) {
+          query = query.where('clinicBranchId', '==', params.clinicBranchId);
+        }
+        if (params.practitionerId) {
+          query = query.where('practitionerId', '==', params.practitionerId);
+        }
+        if (params.procedureId) {
+          query = query.where('procedureId', '==', params.procedureId);
+        }
+        if (params.patientId) {
+          query = query.where('patientId', '==', params.patientId);
+        }
+        if (params.startDate) {
+          const startDate = params.startDate instanceof Date 
+            ? params.startDate 
+            : params.startDate.toDate();
+          const startTimestamp = admin.firestore.Timestamp.fromDate(startDate);
+          query = query.where('appointmentStartTime', '>=', startTimestamp);
+        }
+        if (params.endDate) {
+          const endDate = params.endDate instanceof Date 
+            ? params.endDate 
+            : params.endDate.toDate();
+          const endTimestamp = admin.firestore.Timestamp.fromDate(endDate);
+          query = query.where('appointmentStartTime', '<=', endTimestamp);
+        }
+
+        const snapshot = await query.get();
+        const appointments = snapshot.docs.map(doc => ({
+          id: doc.id,
+          ...doc.data(),
+        })) as Appointment[];
+
+        return {
+          appointments,
+          total: appointments.length,
+        };
+      },
+    };
+  }
+
+  // Delegate all methods to the underlying AnalyticsService
+  // We expose them here so they can be called with admin SDK context
+
+  async getPractitionerAnalytics(
+    practitionerId: string,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<PractitionerAnalytics> {
+    return this.analyticsService.getPractitionerAnalytics(practitionerId, dateRange, options);
+  }
+
+  async getProcedureAnalytics(
+    procedureId?: string,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<ProcedureAnalytics | ProcedureAnalytics[]> {
+    return this.analyticsService.getProcedureAnalytics(procedureId, dateRange, options);
+  }
+
+  async getTimeEfficiencyMetrics(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<TimeEfficiencyMetrics> {
+    return this.analyticsService.getTimeEfficiencyMetrics(filters, dateRange, options);
+  }
+
+  async getTimeEfficiencyMetricsByEntity(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<GroupedTimeEfficiencyMetrics[]> {
+    return this.analyticsService.getTimeEfficiencyMetricsByEntity(groupBy, dateRange, filters);
+  }
+
+  async getCancellationMetrics(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<CancellationMetrics | CancellationMetrics[]> {
+    return this.analyticsService.getCancellationMetrics(groupBy, dateRange, options);
+  }
+
+  async getNoShowMetrics(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<NoShowMetrics | NoShowMetrics[]> {
+    return this.analyticsService.getNoShowMetrics(groupBy, dateRange, options);
+  }
+
+  async getRevenueMetrics(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<RevenueMetrics> {
+    return this.analyticsService.getRevenueMetrics(filters, dateRange, options);
+  }
+
+  async getRevenueMetricsByEntity(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<GroupedRevenueMetrics[]> {
+    return this.analyticsService.getRevenueMetricsByEntity(groupBy, dateRange, filters);
+  }
+
+  async getProductUsageMetrics(
+    productId?: string,
+    dateRange?: AnalyticsDateRange,
+  ): Promise<ProductUsageMetrics | ProductUsageMetrics[]> {
+    return this.analyticsService.getProductUsageMetrics(productId, dateRange);
+  }
+
+  async getProductUsageMetricsByEntity(
+    groupBy: EntityType,
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<GroupedProductUsageMetrics[]> {
+    return this.analyticsService.getProductUsageMetricsByEntity(groupBy, dateRange, filters);
+  }
+
+  async getPatientAnalytics(
+    patientId?: string,
+    dateRange?: AnalyticsDateRange,
+  ): Promise<PatientAnalytics | PatientAnalytics[]> {
+    return this.analyticsService.getPatientAnalytics(patientId, dateRange);
+  }
+
+  async getPatientBehaviorMetricsByEntity(
+    groupBy: 'clinic' | 'practitioner' | 'procedure' | 'technology',
+    dateRange?: AnalyticsDateRange,
+    filters?: AnalyticsFilters,
+  ): Promise<GroupedPatientBehaviorMetrics[]> {
+    return this.analyticsService.getPatientBehaviorMetricsByEntity(groupBy, dateRange, filters);
+  }
+
+  async getClinicAnalytics(
+    clinicBranchId: string,
+    dateRange?: AnalyticsDateRange,
+  ): Promise<ClinicAnalytics | ClinicAnalytics[]> {
+    // Use getDashboardData to get clinic-level analytics
+    const dashboard = await this.analyticsService.getDashboardData(
+      { clinicBranchId },
+      dateRange,
+    );
+    
+    // Get clinic info
+    const clinicDoc = await this.db.collection('clinics').doc(clinicBranchId).get();
+    const clinicData = clinicDoc.data();
+    const clinicName = clinicData?.name || 'Unknown';
+    
+    // Convert DashboardAnalytics to ClinicAnalytics format
+    return {
+      clinicBranchId,
+      clinicName,
+      totalAppointments: dashboard.overview.totalAppointments,
+      completedAppointments: dashboard.overview.completedAppointments,
+      canceledAppointments: dashboard.overview.canceledAppointments,
+      noShowAppointments: dashboard.overview.noShowAppointments,
+      cancellationRate: dashboard.overview.cancellationRate,
+      noShowRate: dashboard.overview.noShowRate,
+      totalRevenue: dashboard.overview.totalRevenue,
+      averageRevenuePerAppointment: dashboard.overview.averageRevenuePerAppointment,
+      currency: dashboard.overview.currency,
+      practitionerCount: dashboard.overview.uniquePractitioners,
+      patientCount: dashboard.overview.uniquePatients,
+      procedureCount: dashboard.overview.uniqueProcedures,
+      topPractitioners: dashboard.practitionerMetrics.slice(0, 5).map(p => ({
+        practitionerId: p.practitionerId,
+        practitionerName: p.practitionerName,
+        appointmentCount: p.totalAppointments,
+        revenue: p.totalRevenue,
+      })),
+      topProcedures: dashboard.procedureMetrics.slice(0, 5).map(p => ({
+        procedureId: p.procedureId,
+        procedureName: p.procedureName,
+        appointmentCount: p.totalAppointments,
+        revenue: p.totalRevenue,
+      })),
+    };
+  }
+
+  async getDashboardData(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+    options?: any,
+  ): Promise<DashboardAnalytics> {
+    return this.analyticsService.getDashboardData(filters, dateRange, options);
+  }
+
+  /**
+   * Expose fetchAppointments for direct access if needed
+   * This method is used internally by AnalyticsService
+   */
+  async fetchAppointments(
+    filters?: AnalyticsFilters,
+    dateRange?: AnalyticsDateRange,
+  ): Promise<any[]> {
+    // Access the private method via the service
+    return (this.analyticsService as any).fetchAppointments(filters, dateRange);
+  }
+}
+

package/src/admin/analytics/index.ts

@@ -0,0 +1,2 @@
+export * from './analytics.admin.service';
+

package/src/admin/index.ts

@@ -64,6 +64,7 @@ TimestampUtils.enableServerMode();
 
 // Export all services and utilities from the admin sub-modules.
 export * from './aggregation';
+export * from './analytics';
 export * from './booking';
 export * from './calendar';
 export * from './documentation-templates';
@@ -73,3 +74,8 @@ export * from './mailing';
 export * from './notifications';
 export * from './requirements';
 export * from './users';
+
+// Export analytics types for Cloud Functions
+export type * from '../types/analytics';
+export * from '../types/analytics';
+export { CLINICS_COLLECTION } from '../types/clinic';

package/src/backoffice/services/analytics.service.proposal.md

@@ -1,9 +1,13 @@
 # Analytics Service Proposal
 
+> **Note**: This proposal has been implemented. The service is located in `src/services/analytics/` and types in `src/types/analytics/`. See the [README](../../services/analytics/README.md) for usage documentation.
+
 ## Overview
 
 This document proposes the design and implementation of an `analytics.service.ts` service for the Clinic Admin app. This service will provide comprehensive financial and analytical intelligence about doctors, procedures, appointments, patients, products, and clinic operations.
 
+**Status**: ✅ **IMPLEMENTED** - See `src/services/analytics/analytics.service.ts`
+
 ## Data Sources & Connections
 
 ### Primary Data Sources

package/src/services/analytics/ARCHITECTURE.md

@@ -0,0 +1,199 @@
+# Analytics Service Architecture
+
+## Overview
+
+The Analytics Service uses a **hybrid approach** combining **pre-computed analytics** (stored in Firestore) with **on-demand calculation** (fallback). This architecture optimizes for:
+
+- **Performance**: Fast reads from pre-computed data
+- **Cost**: Reduced Firestore reads and compute time
+- **Flexibility**: Can still calculate on-demand when needed
+
+## Architecture Components
+
+### 1. Cloud Functions (Pre-computation)
+
+**Location**: `Cloud/functions/src/analytics/computeAnalytics.ts`
+
+**Schedule**: Runs every 12 hours via Cloud Scheduler
+
+**What it does**:
+- Queries all appointments for each clinic
+- Computes analytics for multiple periods (daily, weekly, monthly, yearly, all_time)
+- Stores computed analytics in Firestore subcollections
+
+**Storage Structure**:
+```
+clinics/{clinicBranchId}/
+  └── analytics/
+      ├── dashboard/
+      │   └── {period}/
+      │       └── current
+      ├── clinic/
+      │   └── {period}/
+      │       └── current
+      ├── practitioners/
+      │   └── {period}/
+      │       └── {practitionerId}
+      ├── procedures/
+      │   └── {period}/
+      │       └── {procedureId}
+      ├── time_efficiency/
+      │   └── {period}/
+      │       └── current
+      ├── revenue/
+      │   └── {period}/
+      │       └── current
+      ├── cancellations/
+      │   └── {period}/
+      │       └── clinic
+      └── no_shows/
+          └── {period}/
+              └── clinic
+```
+
+### 2. Analytics Service (Client-side)
+
+**Location**: `Api/src/services/analytics/analytics.service.ts`
+
+**Behavior**:
+1. **First**: Tries to read from stored analytics
+2. **Checks**: If data is fresh (within maxCacheAgeHours, default 12 hours)
+3. **Falls back**: Calculates on-demand if:
+   - No stored data exists
+   - Data is stale (older than maxCacheAgeHours)
+   - `useCache: false` is specified
+
+### 3. Storage Types
+
+**Location**: `Api/src/types/analytics/stored-analytics.types.ts`
+
+Defines types for stored analytics documents, including metadata about when and how they were computed.
+
+## Data Flow
+
+### Pre-computation Flow (Cloud Function)
+
+```
+Cloud Scheduler (every 12 hours)
+  ↓
+computeAnalyticsForAllClinics()
+  ↓
+For each clinic:
+  ├── Compute dashboard analytics
+  ├── Compute clinic analytics
+  ├── Compute practitioner analytics (for each practitioner)
+  ├── Compute procedure analytics (for each procedure)
+  ├── Compute time efficiency metrics
+  ├── Compute revenue metrics
+  ├── Compute cancellation metrics
+  └── Compute no-show metrics
+  ↓
+Store in Firestore subcollections
+```
+
+### Client Read Flow
+
+```
+Client requests analytics
+  ↓
+AnalyticsService.getDashboardData()
+  ↓
+Check stored analytics?
+  ├── Yes → Read from Firestore
+  │   ├── Fresh? → Return cached data ✅
+  │   └── Stale? → Calculate on-demand
+  └── No → Calculate on-demand
+```
+
+## Benefits
+
+### Performance
+- **Fast reads**: Single document read vs. querying hundreds/thousands of appointments
+- **Reduced latency**: Pre-computed data returns instantly
+- **Scalable**: Works efficiently even with large datasets
+
+### Cost Optimization
+- **Fewer reads**: 1 read vs. potentially hundreds/thousands
+- **Reduced compute**: Calculations run server-side, not on every client request
+- **Predictable costs**: Fixed cost per clinic per period
+
+### Flexibility
+- **On-demand fallback**: Can still calculate when needed
+- **Custom date ranges**: Can override cached data for specific queries
+- **Real-time option**: Can disable caching for live data
+
+## Usage Examples
+
+### Using Pre-computed Analytics (Default)
+
+```typescript
+// Automatically uses cached data if available and fresh
+const dashboard = await analyticsService.getDashboardData(
+  { clinicBranchId: 'clinic-123' },
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') }
+);
+```
+
+### Forcing On-demand Calculation
+
+```typescript
+// Bypass cache and calculate on-demand
+const dashboard = await analyticsService.getDashboardData(
+  { clinicBranchId: 'clinic-123' },
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') },
+  { useCache: false }
+);
+```
+
+### Custom Cache Age
+
+```typescript
+// Use cache if data is less than 6 hours old (instead of default 12)
+const dashboard = await analyticsService.getDashboardData(
+  { clinicBranchId: 'clinic-123' },
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') },
+  { maxCacheAgeHours: 6 }
+);
+```
+
+## Configuration
+
+### Cloud Function Schedule
+
+Edit `Cloud/functions/src/analytics/computeAnalytics.ts`:
+
+```typescript
+schedule: "every 12 hours" // Change to "every 6 hours", "every 24 hours", etc.
+```
+
+### Default Cache Age
+
+Edit `Api/src/services/analytics/utils/stored-analytics.utils.ts`:
+
+```typescript
+maxCacheAgeHours = 12 // Change default cache age
+```
+
+## Monitoring
+
+### Cloud Function Logs
+
+Check Cloud Function logs for:
+- Computation success/failure
+- Processing time per clinic
+- Errors during computation
+
+### Firestore Usage
+
+Monitor Firestore reads:
+- Pre-computed reads: 1 per analytics request
+- On-demand reads: Variable (depends on appointment count)
+
+## Future Enhancements
+
+1. **Incremental Updates**: Only recompute changed periods
+2. **Real-time Triggers**: Update analytics when appointments change
+3. **Aggregated Views**: Pre-compute common dashboard views
+4. **Historical Snapshots**: Keep historical analytics for trend analysis
+5. **Multi-clinic Aggregation**: Aggregate analytics across clinic groups
+