@blackcode_sa/metaestetics-api 1.12.68 → 1.13.0

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

@@ -0,0 +1,143 @@
+# Analytics Service - Executive Summary
+
+## Overview
+
+This document provides a high-level summary of the proposed Analytics Service for the Clinic Admin app. The full detailed proposal can be found in [analytics.service.proposal.md](./analytics.service.proposal.md).
+
+## Purpose
+
+The Analytics Service will provide comprehensive financial and operational intelligence to clinic administrators, enabling data-driven decision making across:
+
+- **Practitioner Performance**: Track doctor efficiency, revenue generation, and patient satisfaction
+- **Procedure Analytics**: Understand procedure popularity, profitability, and product usage
+- **Financial Intelligence**: Monitor revenue, costs, payment status, and trends
+- **Operational Efficiency**: Analyze time utilization, cancellations, and no-shows
+- **Patient Insights**: Track patient lifetime value, retention, and behavior patterns
+
+## Key Data Sources
+
+The service will aggregate data from:
+
+1. **Appointments Collection**: Primary source for all appointment-related metrics
+2. **Procedures Collection**: Procedure metadata and categorization
+3. **Practitioners Collection**: Doctor information and associations
+4. **Patients Collection**: Patient profiles and history
+5. **Clinics Collection**: Clinic and branch information
+6. **Products Collection**: Product usage and pricing data
+
+## Core Analytics Categories
+
+### 1. Practitioner Analytics
+- Total and completed appointments
+- Cancellation and no-show rates
+- Time efficiency (booked vs actual)
+- Revenue generation
+- Patient retention
+
+### 2. Procedure Analytics
+- Appointment counts and popularity
+- Revenue and profitability
+- Cancellation rates
+- Product usage patterns
+- Performance by category/technology
+
+### 3. Time Analytics
+- Booked vs actual time comparison
+- Efficiency percentages
+- Overrun/underutilization analysis
+- Peak hours and trends
+
+### 4. Cancellation & No-Show Analytics
+- Rates by clinic, practitioner, patient, procedure
+- Cancellation reasons breakdown
+- Patterns and trends
+- Lead time analysis
+
+### 5. Financial Analytics
+- Total and average revenue
+- Cost per patient/appointment
+- Payment status breakdown
+- Revenue trends
+- Product cost analysis
+
+### 6. Product Usage Analytics
+- Products used per appointment
+- Revenue contribution
+- Usage by procedure/zone
+- Quantity and pricing trends
+
+### 7. Patient Analytics
+- Lifetime value
+- Retention rates
+- Appointment frequency
+- Cancellation patterns
+
+### 8. Clinic Analytics
+- Overall performance metrics
+- Practitioner comparisons
+- Procedure popularity
+- Efficiency metrics
+
+## Proposed Service Structure
+
+The `AnalyticsService` will extend `BaseService` and provide methods organized by analytics category:
+
+- `getPractitionerAnalytics()` - Comprehensive practitioner metrics
+- `getProcedureAnalytics()` - Procedure performance data
+- `getTimeEfficiencyMetrics()` - Time utilization analysis
+- `getCancellationMetrics()` - Cancellation insights
+- `getRevenueMetrics()` - Financial intelligence
+- `getProductUsageMetrics()` - Product analytics
+- `getPatientAnalytics()` - Patient insights
+- `getClinicAnalytics()` - Clinic performance
+- `getDashboardData()` - Comprehensive dashboard aggregation
+
+## Key Calculations
+
+### Cost Calculation Priority
+1. `metadata.finalbilling.finalPrice` (if available)
+2. Sum of `metadata.zonesData` subtotals
+3. `appointment.cost` (fallback)
+
+### Time Efficiency
+```
+efficiency = (actualDuration / bookedDuration) * 100
+overrun = actualDuration > bookedDuration ? difference : 0
+```
+
+### Cancellation Rate
+```
+cancellationRate = (canceledCount / totalAppointments) * 100
+```
+
+## Implementation Phases
+
+1. **Phase 1**: Core infrastructure and utilities
+2. **Phase 2**: Basic metrics (practitioner, procedure, financial)
+3. **Phase 3**: Advanced analytics (time, products, patients)
+4. **Phase 4**: Dashboard and trend analysis
+
+## Performance Considerations
+
+- Firestore composite indexes for query optimization
+- Pagination for large datasets
+- Caching strategy for frequently accessed metrics
+- Batch processing for complex aggregations
+- Server-side calculations via Cloud Functions
+
+## Next Steps
+
+1. Review and approve the detailed proposal
+2. Create TypeScript type definitions
+3. Implement core service structure
+4. Build utility functions for calculations
+5. Implement metrics methods incrementally
+6. Add comprehensive tests
+7. Create API documentation
+8. Integrate with Clinic Admin app
+
+## Documentation
+
+- **Full Proposal**: [analytics.service.proposal.md](./analytics.service.proposal.md)
+- **Service README**: [README.md](./README.md)
+

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
+

package/src/services/analytics/CLOUD_FUNCTIONS.md

@@ -0,0 +1,225 @@
+# Analytics Cloud Functions Guide
+
+## Overview
+
+The Analytics Service supports **on-demand calculation via Cloud Functions**, allowing you to trigger fresh analytics calculations server-side and optionally cache the results.
+
+## Available Cloud Functions
+
+### 1. `calculateAnalyticsOnDemand` (Callable)
+
+A callable Cloud Function that calculates analytics on-demand and optionally stores results in cache.
+
+**Location**: `Cloud/functions/src/analytics/calculateAnalyticsOnDemand.ts`
+
+## Usage
+
+### Using the Client Service Helper
+
+```typescript
+import { AnalyticsCloudService } from '@blackcode_sa/metaestetics-api';
+import { getApp } from 'firebase/app';
+
+const app = getApp();
+const cloudService = new AnalyticsCloudService(app);
+
+// Calculate dashboard analytics on-demand
+const dashboard = await cloudService.calculateDashboard(
+  { clinicBranchId: 'clinic-123' },
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') },
+  { storeInCache: true } // Store result for future use
+);
+```
+
+### Direct Callable Function Usage
+
+```typescript
+import { getFunctions, httpsCallable } from 'firebase/functions';
+import { getApp } from 'firebase/app';
+
+const functions = getFunctions(getApp(), 'europe-west6');
+const calculateAnalytics = httpsCallable(functions, 'calculateAnalyticsOnDemand');
+
+// Calculate revenue metrics grouped by practitioner
+const result = await calculateAnalytics({
+  analyticsType: 'revenueByEntity',
+  groupBy: 'practitioner',
+  filters: { clinicBranchId: 'clinic-123' },
+  dateRange: {
+    start: '2024-01-01T00:00:00Z',
+    end: '2024-12-31T23:59:59Z',
+  },
+  options: {
+    storeInCache: true, // Store in cache after calculation
+    useCache: false,    // Force fresh calculation
+  },
+});
+
+const revenueByPractitioner = result.data.data;
+```
+
+## Supported Analytics Types
+
+### Top-Level Analytics
+
+- `dashboard` - Complete dashboard analytics
+- `practitioner` - Individual practitioner analytics (requires `entityId`)
+- `procedure` - Individual procedure analytics (requires `entityId`)
+- `clinic` - Clinic-level analytics
+- `timeEfficiency` - Time efficiency metrics
+- `revenue` - Revenue metrics
+- `productUsage` - Product usage metrics
+- `patient` - Patient analytics (optional `entityId`)
+
+### Grouped Analytics
+
+- `revenueByEntity` - Revenue grouped by clinic/practitioner/procedure/patient/technology (requires `groupBy`)
+- `productUsageByEntity` - Product usage grouped by entity (requires `groupBy`)
+- `timeEfficiencyByEntity` - Time efficiency grouped by entity (requires `groupBy`)
+- `patientBehaviorByEntity` - Patient behavior grouped by entity (requires `groupBy`)
+- `cancellation` - Cancellation metrics grouped by entity (requires `groupBy`)
+- `noShow` - No-show metrics grouped by entity (requires `groupBy`)
+
+## Request Parameters
+
+```typescript
+interface CalculateAnalyticsRequest {
+  analyticsType: string;        // Required: Type of analytics to calculate
+  filters?: AnalyticsFilters;   // Optional: Filters (clinicBranchId, etc.)
+  dateRange?: {                 // Optional: Date range
+    start: string;              // ISO date string
+    end: string;                // ISO date string
+  };
+  entityId?: string;            // Required for practitioner/procedure/patient
+  groupBy?: EntityType;         // Required for grouped analytics
+  options?: {
+    storeInCache?: boolean;     // Default: true - Store result in cache
+    useCache?: boolean;         // Default: false - Use cache if available
+    maxCacheAgeHours?: number;  // Default: 12 - Max cache age
+  };
+}
+```
+
+## Response Format
+
+```typescript
+interface CalculateAnalyticsResponse {
+  success: boolean;
+  data: any;                    // The calculated analytics data
+  computedAt: string;           // ISO timestamp of when it was computed
+}
+```
+
+## Examples
+
+### Example 1: Calculate Dashboard Analytics
+
+```typescript
+const dashboard = await cloudService.calculateDashboard(
+  { clinicBranchId: 'clinic-123' },
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') },
+  { storeInCache: true }
+);
+```
+
+### Example 2: Calculate Revenue by Technology
+
+```typescript
+const revenueByTechnology = await cloudService.calculateRevenueByEntity(
+  'technology',
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') },
+  { clinicBranchId: 'clinic-123' },
+  { storeInCache: true }
+);
+```
+
+### Example 3: Force Fresh Calculation (Bypass Cache)
+
+```typescript
+const result = await calculateAnalytics({
+  analyticsType: 'dashboard',
+  filters: { clinicBranchId: 'clinic-123' },
+  dateRange: {
+    start: '2024-01-01T00:00:00Z',
+    end: '2024-12-31T23:59:59Z',
+  },
+  options: {
+    useCache: false,      // Don't use cache
+    storeInCache: true,   // But store the result
+  },
+});
+```
+
+### Example 4: Calculate Practitioner Analytics
+
+```typescript
+const practitionerMetrics = await cloudService.calculatePractitioner(
+  'practitioner-123',
+  { start: new Date('2024-01-01'), end: new Date('2024-12-31') },
+  {
+    storeInCache: true,
+    clinicBranchId: 'clinic-123',
+  }
+);
+```
+
+## Benefits
+
+### Performance
+- **Server-side computation**: Faster than client-side for large datasets
+- **Parallel processing**: Cloud Functions can handle multiple requests simultaneously
+- **No client resource usage**: Computation happens in the cloud
+
+### Caching
+- **Automatic caching**: Results can be stored automatically
+- **Future reads**: Cached results can be read instantly by `AnalyticsService`
+- **Configurable**: Control whether to use/store cache
+
+### Cost Optimization
+- **Efficient**: Server-side computation is optimized
+- **Scalable**: Handles large datasets without client limitations
+- **Predictable**: Fixed cost per calculation
+
+## When to Use
+
+### Use Cloud Function When:
+- ✅ Cache is stale and you need fresh data immediately
+- ✅ Calculating analytics for large date ranges
+- ✅ Need to calculate multiple analytics types
+- ✅ Want to store results for future use
+- ✅ Client device has limited resources
+
+### Use Client Service When:
+- ✅ Cache is fresh (< 12 hours old)
+- ✅ Small date ranges
+- ✅ Quick reads from cache
+- ✅ Offline-first scenarios
+
+## Error Handling
+
+```typescript
+try {
+  const result = await cloudService.calculateDashboard(...);
+} catch (error) {
+  if (error.code === 'invalid-argument') {
+    // Invalid parameters provided
+  } else if (error.code === 'internal') {
+    // Server error during calculation
+  }
+}
+```
+
+## Integration with AnalyticsService
+
+The Cloud Function works seamlessly with `AnalyticsService`:
+
+1. **Client checks cache first** (via `AnalyticsService`)
+2. **If cache is stale/missing**, call Cloud Function
+3. **Cloud Function calculates** and optionally stores result
+4. **Future reads** use the cached data
+
+This creates a **hybrid approach**:
+- Fast reads from cache (default)
+- On-demand fresh calculations when needed
+- Automatic caching for future use
+