@blackcode_sa/metaestetics-api 1.12.68 → 1.12.69

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/appointment/appointment.service.ts

@@ -1833,6 +1833,12 @@ export class AppointmentService extends BaseService {
         finalizationNotes: null,
       };
 
+      // Update payment status if billing data exists but status is NOT_APPLICABLE
+      // This handles cases where appointment was created with price 0 but billing was added later
+      const shouldUpdatePaymentStatus =
+        finalbilling.finalPrice > 0 &&
+        appointment.paymentStatus === PaymentStatus.NOT_APPLICABLE;
+
       const updateData: UpdateAppointmentData = {
         metadata: {
           selectedZones: currentMetadata.selectedZones,
@@ -1848,6 +1854,9 @@ export class AppointmentService extends BaseService {
           finalbilling,
           finalizationNotes: currentMetadata.finalizationNotes,
         },
+        ...(shouldUpdatePaymentStatus && {
+          paymentStatus: PaymentStatus.UNPAID,
+        }),
         updatedAt: serverTimestamp(),
       };
 
@@ -2123,10 +2132,58 @@ export class AppointmentService extends BaseService {
         showNoShow: false,
       });
 
+      // Also get appointments that have recommendations but might not be COMPLETED yet
+      // (e.g., doctor finalized but appointment status is still CONFIRMED/CHECKED_IN)
+      // Get all patient appointments that are past their end time
+      const now = new Date();
+      const allPastAppointments = await this.getPatientAppointments(patientId, {
+        endDate: now,
+        status: [
+          AppointmentStatus.COMPLETED,
+          AppointmentStatus.CONFIRMED,
+          AppointmentStatus.CHECKED_IN,
+          AppointmentStatus.IN_PROGRESS,
+        ],
+      });
+
+      // Filter to only include appointments that are past their end time AND have recommendations
+      const appointmentsWithRecommendations = allPastAppointments.appointments.filter(
+        appointment => {
+          const endTime = appointment.appointmentEndTime?.toMillis
+            ? appointment.appointmentEndTime.toMillis()
+            : appointment.appointmentEndTime?.seconds
+            ? appointment.appointmentEndTime.seconds * 1000
+            : null;
+
+          if (!endTime) return false;
+
+          const isPastEndTime = endTime < now.getTime();
+          const hasRecommendations =
+            (appointment.metadata?.recommendedProcedures?.length || 0) > 0;
+
+          return isPastEndTime && hasRecommendations;
+        },
+      );
+
+      // Combine and deduplicate by appointment ID
+      const allAppointmentsMap = new Map<string, Appointment>();
+      
+      // Add completed appointments
+      pastAppointments.appointments.forEach(apt => {
+        allAppointmentsMap.set(apt.id, apt);
+      });
+
+      // Add appointments with recommendations (will overwrite if duplicate)
+      appointmentsWithRecommendations.forEach(apt => {
+        allAppointmentsMap.set(apt.id, apt);
+      });
+
+      const allAppointments = Array.from(allAppointmentsMap.values());
+
       const recommendations: NextStepsRecommendation[] = [];
 
-      // Iterate through past appointments and extract recommendations
-      for (const appointment of pastAppointments.appointments) {
+      // Iterate through all appointments and extract recommendations
+      for (const appointment of allAppointments) {
         // Filter by clinic if specified
         if (options?.clinicBranchId && appointment.clinicBranchId !== options.clinicBranchId) {
           continue;
@@ -2181,10 +2238,6 @@ export class AppointmentService extends BaseService {
         ? recommendations.slice(0, options.limit)
         : recommendations;
 
-      console.log(
-        `[APPOINTMENT_SERVICE] Found ${limitedRecommendations.length} next steps recommendations for patient ${patientId}`,
-      );
-
       return limitedRecommendations;
     } catch (error) {
       console.error(

package/src/services/procedure/procedure.service.ts

@@ -1088,6 +1088,14 @@ export class ProcedureService extends BaseService {
           console.log('[PROCEDURE_SERVICE] Strategy 1: Trying nameLower search');
           const searchTerm = filters.nameSearch.trim().toLowerCase();
           const constraints = getBaseConstraints();
+          
+          // Check if we have nested field filters that might conflict with orderBy
+          const hasNestedFilters = !!(filters.procedureTechnology || filters.procedureCategory || filters.procedureSubcategory);
+          
+          if (hasNestedFilters) {
+            console.log('[PROCEDURE_SERVICE] Strategy 1: Has nested filters, will apply client-side after query');
+          }
+          
           constraints.push(where('nameLower', '>=', searchTerm));
           constraints.push(where('nameLower', '<=', searchTerm + '\uf8ff'));
           constraints.push(orderBy('nameLower'));
@@ -1105,9 +1113,15 @@ export class ProcedureService extends BaseService {
 
           const q = query(collection(this.db, PROCEDURES_COLLECTION), ...constraints);
           const querySnapshot = await getDocs(q);
-          const procedures = querySnapshot.docs.map(
+          let procedures = querySnapshot.docs.map(
             doc => ({ ...doc.data(), id: doc.id } as Procedure),
           );
+          
+          // Apply client-side filters for nested fields if needed
+          if (hasNestedFilters) {
+            procedures = this.applyInMemoryFilters(procedures, filters);
+          }
+          
           const lastDoc =
             querySnapshot.docs.length > 0
               ? querySnapshot.docs[querySnapshot.docs.length - 1]
@@ -1131,6 +1145,14 @@ export class ProcedureService extends BaseService {
           console.log('[PROCEDURE_SERVICE] Strategy 2: Trying name field search');
           const searchTerm = filters.nameSearch.trim().toLowerCase();
           const constraints = getBaseConstraints();
+          
+          // Check if we have nested field filters that might conflict with orderBy
+          const hasNestedFilters = !!(filters.procedureTechnology || filters.procedureCategory || filters.procedureSubcategory);
+          
+          if (hasNestedFilters) {
+            console.log('[PROCEDURE_SERVICE] Strategy 2: Has nested filters, will apply client-side after query');
+          }
+          
           constraints.push(where('name', '>=', searchTerm));
           constraints.push(where('name', '<=', searchTerm + '\uf8ff'));
           constraints.push(orderBy('name'));
@@ -1148,9 +1170,15 @@ export class ProcedureService extends BaseService {
 
           const q = query(collection(this.db, PROCEDURES_COLLECTION), ...constraints);
           const querySnapshot = await getDocs(q);
-          const procedures = querySnapshot.docs.map(
+          let procedures = querySnapshot.docs.map(
             doc => ({ ...doc.data(), id: doc.id } as Procedure),
           );
+          
+          // Apply client-side filters for nested fields if needed
+          if (hasNestedFilters) {
+            procedures = this.applyInMemoryFilters(procedures, filters);
+          }
+          
           const lastDoc =
             querySnapshot.docs.length > 0
               ? querySnapshot.docs[querySnapshot.docs.length - 1]
@@ -1169,11 +1197,66 @@ export class ProcedureService extends BaseService {
       }
 
       // Strategy 3: orderBy createdAt with client-side filtering
+      // NOTE: This strategy excludes nested field filters (technology.id, category.id, subcategory.id)
+      // from Firestore query because Firestore doesn't support orderBy on different field
+      // when using where on nested fields without a composite index.
+      // These filters are applied client-side instead.
       try {
         console.log(
           '[PROCEDURE_SERVICE] Strategy 3: Using createdAt orderBy with client-side filtering',
+          {
+            procedureTechnology: filters.procedureTechnology,
+            hasTechnologyFilter: !!filters.procedureTechnology,
+          },
+        );
+        
+        // Build constraints WITHOUT nested field filters (these will be applied client-side)
+        const constraints: QueryConstraint[] = [];
+        
+        // Active status filter
+        if (filters.isActive !== undefined) {
+          constraints.push(where('isActive', '==', filters.isActive));
+        } else {
+          constraints.push(where('isActive', '==', true));
+        }
+        
+        // Only include non-nested field filters in Firestore query
+        if (filters.procedureFamily) {
+          constraints.push(where('family', '==', filters.procedureFamily));
+        }
+        if (filters.practitionerId) {
+          constraints.push(where('practitionerId', '==', filters.practitionerId));
+        }
+        if (filters.clinicId) {
+          constraints.push(where('clinicBranchId', '==', filters.clinicId));
+        }
+        if (filters.minPrice !== undefined) {
+          constraints.push(where('price', '>=', filters.minPrice));
+        }
+        if (filters.maxPrice !== undefined) {
+          constraints.push(where('price', '<=', filters.maxPrice));
+        }
+        if (filters.minRating !== undefined) {
+          constraints.push(where('reviewInfo.averageRating', '>=', filters.minRating));
+        }
+        if (filters.maxRating !== undefined) {
+          constraints.push(where('reviewInfo.averageRating', '<=', filters.maxRating));
+        }
+        if (filters.treatmentBenefits && filters.treatmentBenefits.length > 0) {
+          const benefitIdsToMatch = filters.treatmentBenefits;
+          constraints.push(where('treatmentBenefitIds', 'array-contains-any', benefitIdsToMatch));
+        }
+        
+        // NOTE: We intentionally EXCLUDE these nested field filters from Firestore query:
+        // - filters.procedureTechnology (technology.id)
+        // - filters.procedureCategory (category.id)
+        // - filters.procedureSubcategory (subcategory.id)
+        // These will be applied client-side in applyInMemoryFilters
+        
+        console.log(
+          '[PROCEDURE_SERVICE] Strategy 3 Firestore constraints (nested filters excluded):',
+          constraints.map(c => (c as any).fieldPath || 'unknown'),
         );
-        const constraints = getBaseConstraints();
         constraints.push(orderBy('createdAt', 'desc'));
 
         if (filters.lastDoc) {
@@ -1194,7 +1277,20 @@ export class ProcedureService extends BaseService {
         );
 
         // Apply all client-side filters using centralized function
+        console.log('[PROCEDURE_SERVICE] Before applyInMemoryFilters (Strategy 3):', {
+          procedureCount: procedures.length,
+          procedureTechnology: filters.procedureTechnology,
+          filtersObject: {
+            procedureTechnology: filters.procedureTechnology,
+            procedureFamily: filters.procedureFamily,
+            procedureCategory: filters.procedureCategory,
+            procedureSubcategory: filters.procedureSubcategory,
+          },
+        });
         procedures = this.applyInMemoryFilters(procedures, filters);
+        console.log('[PROCEDURE_SERVICE] After applyInMemoryFilters (Strategy 3):', {
+          procedureCount: procedures.length,
+        });
 
         const lastDoc =
           querySnapshot.docs.length > 0 ? querySnapshot.docs[querySnapshot.docs.length - 1] : null;
@@ -1265,6 +1361,14 @@ export class ProcedureService extends BaseService {
   ): (Procedure & { distance?: number })[] {
     let filteredProcedures = [...procedures]; // Create copy to avoid mutating original
 
+    // Debug: Log what filters we received
+    console.log('[PROCEDURE_SERVICE] applyInMemoryFilters called:', {
+      procedureCount: procedures.length,
+      procedureTechnology: filters.procedureTechnology,
+      hasTechnologyFilter: !!filters.procedureTechnology,
+      allFilterKeys: Object.keys(filters).filter(k => filters[k] !== undefined && filters[k] !== null),
+    });
+
     // Name search filter
     if (filters.nameSearch && filters.nameSearch.trim()) {
       const searchTerm = filters.nameSearch.trim().toLowerCase();
@@ -1348,12 +1452,21 @@ export class ProcedureService extends BaseService {
 
     // Technology filtering
     if (filters.procedureTechnology) {
+      const beforeCount = filteredProcedures.length;
       filteredProcedures = filteredProcedures.filter(
         procedure => procedure.technology?.id === filters.procedureTechnology,
       );
       console.log(
-        `[PROCEDURE_SERVICE] Applied technology filter, results: ${filteredProcedures.length}`,
+        `[PROCEDURE_SERVICE] Applied technology filter (${filters.procedureTechnology}), before: ${beforeCount}, after: ${filteredProcedures.length}`,
       );
+      // Log sample technology IDs for debugging
+      if (beforeCount > filteredProcedures.length) {
+        const filteredOut = procedures
+          .filter(p => p.technology?.id !== filters.procedureTechnology)
+          .slice(0, 3)
+          .map(p => ({ id: p.id, techId: p.technology?.id, name: p.name }));
+        console.log('[PROCEDURE_SERVICE] Filtered out sample procedures:', filteredOut);
+      }
     }
 
     // Practitioner filtering

package/src/types/notifications/index.ts

@@ -21,6 +21,7 @@ export enum NotificationType {
 
   // --- Patient Engagement ---
   REVIEW_REQUEST = "reviewRequest", // Request for patient review post-appointment
+  PROCEDURE_RECOMMENDATION = "procedureRecommendation", // Doctor recommended a procedure for follow-up
 
   // --- Payment Related (Examples) ---
   PAYMENT_DUE = "paymentDue",
@@ -231,6 +232,25 @@ export interface ReviewRequestNotification extends BaseNotification {
   procedureName?: string;
 }
 
+/**
+ * Notification for when a doctor recommends a procedure for follow-up.
+ * Example: "Dr. Smith recommended [Procedure Name] for you. Suggested timeframe: in 2 weeks"
+ */
+export interface ProcedureRecommendationNotification extends BaseNotification {
+  notificationType: NotificationType.PROCEDURE_RECOMMENDATION;
+  appointmentId: string; // The appointment where recommendation was made
+  recommendationId: string; // Format: `${appointmentId}:${index}`
+  procedureId: string;
+  procedureName: string;
+  practitionerName: string;
+  clinicName: string;
+  note?: string; // Doctor's note about the recommendation
+  timeframe: {
+    value: number;
+    unit: 'day' | 'week' | 'month' | 'year';
+  };
+}
+
 /**
  * Generic notification for direct messages or announcements.
  */
@@ -261,5 +281,6 @@ export type Notification =
   | FormReminderNotification
   | FormSubmissionConfirmationNotification
   | ReviewRequestNotification
+  | ProcedureRecommendationNotification
   | GeneralMessageNotification
   | PaymentConfirmationNotification;