@blackcode_sa/metaestetics-api 1.12.21 → 1.12.23

package/src/services/reviews/README.md

@@ -0,0 +1,129 @@
+# Reviews Service - Enhanced with Entity Names
+
+## Overview
+
+The Reviews Service has been enhanced to automatically include entity names (clinic, practitioner, procedure, and patient names) in all review responses. This eliminates the need for frontend applications to make additional API calls to fetch entity details.
+
+## Enhanced Methods
+
+All review retrieval methods now include entity names from associated appointments:
+
+### 1. `getReview(reviewId: string)`
+- **Enhanced**: ✅ Returns single review with entity names
+- **Entity Names**: Clinic name, practitioner name, procedure name, patient name
+- **Source**: Fetched from associated appointment data
+
+### 2. `getReviewsByPatient(patientId: string)`
+- **Enhanced**: ✅ Returns patient reviews with entity names
+- **Entity Names**: Clinic name, practitioner name, procedure name, patient name
+- **Use Case**: Patient app - "My Reviews" screen
+
+### 3. `getReviewsByPractitioner(practitionerId: string)`
+- **Enhanced**: ✅ Returns practitioner reviews with entity names
+- **Entity Names**: Clinic name, practitioner name, procedure name, patient name
+- **Use Case**: Doctor app - "Reviews" screen
+
+### 4. `getReviewsByClinic(clinicId: string)`
+- **Enhanced**: ✅ Returns clinic reviews with entity names
+- **Entity Names**: Clinic name, practitioner name, procedure name, patient name
+- **Use Case**: Clinic dashboard - "Reviews" section
+
+### 5. `getReviewsByProcedure(procedureId: string)`
+- **Enhanced**: ✅ Returns procedure reviews with entity names
+- **Entity Names**: Clinic name, practitioner name, procedure name, patient name
+- **Use Case**: Procedure analytics and reporting
+
+## Enhanced Review Structure
+
+```typescript
+interface Review {
+  id: string;
+  appointmentId: string;
+  patientId: string;
+  patientName?: string; // 🆕 Enhanced field
+  createdAt: Date;
+  updatedAt: Date;
+  clinicReview?: {
+    // ... existing fields
+    clinicName?: string; // 🆕 Enhanced field
+  };
+  practitionerReview?: {
+    // ... existing fields
+    practitionerName?: string; // 🆕 Enhanced field
+  };
+  procedureReview?: {
+    // ... existing fields
+    procedureName?: string; // 🆕 Enhanced field
+  };
+  overallComment: string;
+  overallRating: number;
+}
+```
+
+## Data Sources
+
+Entity names are fetched from the associated appointment's aggregated information:
+
+- **Clinic Name**: `appointment.clinicInfo.name`
+- **Practitioner Name**: `appointment.practitionerInfo.name`
+- **Procedure Name**: `appointment.procedureInfo.name`
+- **Patient Name**: `appointment.patientInfo.fullName`
+
+## Error Handling
+
+- If appointment is not found, review is returned without enhancement
+- Individual enhancement failures are logged but don't break the entire operation
+- Graceful fallback ensures API reliability
+
+## Logging
+
+Enhanced logging provides detailed information about:
+- Query parameters
+- Number of reviews found
+- Enhancement success/failure
+- Entity names availability
+
+## Performance Considerations
+
+- Each review requires one additional Firestore read for appointment data
+- Enhancement is performed in parallel for multiple reviews
+- Consider caching strategies for high-volume applications
+
+## Migration Notes
+
+- **Backward Compatible**: Existing code continues to work
+- **Optional Fields**: All enhanced fields are optional
+- **No Breaking Changes**: API signature remains the same
+
+## Usage Examples
+
+### Doctor App - Reviews Screen
+```typescript
+const reviews = await reviewService.getReviewsByPractitioner(practitionerId);
+// Now includes practitioner names, clinic names, procedure names, and patient names
+```
+
+### Patient App - My Reviews
+```typescript
+const reviews = await reviewService.getReviewsByPatient(patientId);
+// Now includes all entity names for better UX
+```
+
+### Clinic Dashboard
+```typescript
+const reviews = await reviewService.getReviewsByClinic(clinicId);
+// Now includes practitioner and procedure names for each review
+```
+
+## Testing
+
+All enhanced methods include comprehensive logging for debugging:
+- Input parameters
+- Query results
+- Enhancement status
+- Entity name availability
+
+Monitor logs with:
+```bash
+firebase functions:log --only reviewService
+```

package/src/services/reviews/reviews.service.ts

@@ -8,23 +8,21 @@ import {
   setDoc,
   deleteDoc,
   serverTimestamp,
-} from "firebase/firestore";
-import { BaseService } from "../base.service";
+} from 'firebase/firestore';
+import { BaseService } from '../base.service';
 import {
   Review,
   ClinicReview,
   PractitionerReview,
   ProcedureReview,
   REVIEWS_COLLECTION,
-} from "../../types/reviews";
-import {
-  createReviewSchema,
-  reviewSchema,
-} from "../../validations/reviews.schema";
-import { z } from "zod";
-import { Auth } from "firebase/auth";
-import { Firestore } from "firebase/firestore";
-import { FirebaseApp } from "firebase/app";
+} from '../../types/reviews';
+import { createReviewSchema, reviewSchema } from '../../validations/reviews.schema';
+import { z } from 'zod';
+import { Auth } from 'firebase/auth';
+import { Firestore } from 'firebase/firestore';
+import { FirebaseApp } from 'firebase/app';
+import { Appointment, APPOINTMENTS_COLLECTION } from '../../types/appointment';
 
 export class ReviewService extends BaseService {
   constructor(db: Firestore, auth: Auth, app: FirebaseApp) {
@@ -38,13 +36,20 @@ export class ReviewService extends BaseService {
    * @returns The created review
    */
   async createReview(
-    data: Omit<
-      Review,
-      "id" | "createdAt" | "updatedAt" | "appointmentId" | "overallRating"
-    >,
-    appointmentId: string
+    data: Omit<Review, 'id' | 'createdAt' | 'updatedAt' | 'appointmentId' | 'overallRating'>,
+    appointmentId: string,
   ): Promise<Review> {
     try {
+      console.log('🔍 ReviewService.createReview - Input data:', {
+        appointmentId,
+        hasClinicReview: !!data.clinicReview,
+        hasPractitionerReview: !!data.practitionerReview,
+        hasProcedureReview: !!data.procedureReview,
+        practitionerId: data.practitionerReview?.practitionerId,
+        clinicId: data.clinicReview?.clinicId,
+        procedureId: data.procedureReview?.procedureId,
+      });
+
       // Validate input data
       const validatedData = createReviewSchema.parse(data);
 
@@ -137,6 +142,13 @@ export class ReviewService extends BaseService {
         updatedAt: serverTimestamp(),
       });
 
+      console.log('✅ ReviewService.createReview - Review saved to Firestore:', {
+        reviewId,
+        practitionerId: review.practitionerReview?.practitionerId,
+        clinicId: review.clinicReview?.clinicId,
+        procedureId: review.procedureReview?.procedureId,
+      });
+
       // Note: Related entity updates (clinic, practitioner, procedure) are now handled
       // by cloud functions through the ReviewsAggregationService
 
@@ -150,75 +162,423 @@ export class ReviewService extends BaseService {
   }
 
   /**
-   * Gets a review by ID
+   * Gets a review by ID with enhanced entity names
    * @param reviewId The ID of the review to get
-   * @returns The review if found, null otherwise
+   * @returns The review with entity names if found, null otherwise
    */
   async getReview(reviewId: string): Promise<Review | null> {
+    console.log('🔍 ReviewService.getReview - Getting review:', reviewId);
+
     const docRef = doc(this.db, REVIEWS_COLLECTION, reviewId);
     const docSnap = await getDoc(docRef);
 
     if (!docSnap.exists()) {
+      console.log('❌ ReviewService.getReview - Review not found:', reviewId);
       return null;
     }
 
-    return docSnap.data() as Review;
+    const review = { ...docSnap.data(), id: reviewId } as Review;
+
+    try {
+      // Fetch the associated appointment to enhance with entity names
+      const appointmentDoc = await getDoc(
+        doc(this.db, APPOINTMENTS_COLLECTION, review.appointmentId),
+      );
+
+      if (appointmentDoc.exists()) {
+        const appointment = appointmentDoc.data() as Appointment;
+
+        // Create enhanced review with entity names
+        const enhancedReview = { ...review };
+
+        if (enhancedReview.clinicReview && appointment.clinicInfo) {
+          enhancedReview.clinicReview = {
+            ...enhancedReview.clinicReview,
+            clinicName: appointment.clinicInfo.name,
+          };
+        }
+
+        if (enhancedReview.practitionerReview && appointment.practitionerInfo) {
+          enhancedReview.practitionerReview = {
+            ...enhancedReview.practitionerReview,
+            practitionerName: appointment.practitionerInfo.name,
+          };
+        }
+
+        if (enhancedReview.procedureReview && appointment.procedureInfo) {
+          enhancedReview.procedureReview = {
+            ...enhancedReview.procedureReview,
+            procedureName: appointment.procedureInfo.name,
+          };
+        }
+
+        // Add patient name to the main review object
+        if (appointment.patientInfo) {
+          enhancedReview.patientName = appointment.patientInfo.fullName;
+        }
+
+        console.log('✅ ReviewService.getReview - Enhanced review:', {
+          reviewId,
+          hasEntityNames: !!(
+            enhancedReview.clinicReview?.clinicName ||
+            enhancedReview.practitionerReview?.practitionerName ||
+            enhancedReview.procedureReview?.procedureName ||
+            enhancedReview.patientName
+          ),
+        });
+
+        return enhancedReview;
+      }
+
+      console.log('⚠️ ReviewService.getReview - Appointment not found for review:', reviewId);
+      return review;
+    } catch (error) {
+      console.warn(`Failed to enhance review ${reviewId} with entity names:`, error);
+      return review;
+    }
   }
 
   /**
-   * Gets all reviews for a specific patient
+   * Gets all reviews for a specific patient with enhanced entity names
    * @param patientId The ID of the patient
-   * @returns Array of reviews for the patient
+   * @returns Array of reviews for the patient with clinic, practitioner, and procedure names
    */
   async getReviewsByPatient(patientId: string): Promise<Review[]> {
-    const q = query(
-      collection(this.db, REVIEWS_COLLECTION),
-      where("patientId", "==", patientId)
-    );
+    const q = query(collection(this.db, REVIEWS_COLLECTION), where('patientId', '==', patientId));
     const snapshot = await getDocs(q);
-    return snapshot.docs.map((doc) => doc.data() as Review);
+    const reviews = snapshot.docs.map(doc => doc.data() as Review);
+
+    // Enhance reviews with entity names from appointments
+    const enhancedReviews = await Promise.all(
+      reviews.map(async review => {
+        try {
+          // Fetch the associated appointment
+          const appointmentDoc = await getDoc(
+            doc(this.db, APPOINTMENTS_COLLECTION, review.appointmentId),
+          );
+
+          if (appointmentDoc.exists()) {
+            const appointment = appointmentDoc.data() as Appointment;
+
+            // Create enhanced review with entity names
+            const enhancedReview = { ...review };
+
+            if (enhancedReview.clinicReview && appointment.clinicInfo) {
+              enhancedReview.clinicReview = {
+                ...enhancedReview.clinicReview,
+                clinicName: appointment.clinicInfo.name,
+              };
+            }
+
+            if (enhancedReview.practitionerReview && appointment.practitionerInfo) {
+              enhancedReview.practitionerReview = {
+                ...enhancedReview.practitionerReview,
+                practitionerName: appointment.practitionerInfo.name,
+              };
+            }
+
+            if (enhancedReview.procedureReview && appointment.procedureInfo) {
+              enhancedReview.procedureReview = {
+                ...enhancedReview.procedureReview,
+                procedureName: appointment.procedureInfo.name,
+              };
+            }
+
+            // Add patient name to the main review object
+            if (appointment.patientInfo) {
+              enhancedReview.patientName = appointment.patientInfo.fullName;
+            }
+
+            return enhancedReview;
+          }
+
+          return review;
+        } catch (error) {
+          console.warn(`Failed to enhance review ${review.id} with entity names:`, error);
+          return review;
+        }
+      }),
+    );
+
+    return enhancedReviews;
   }
 
   /**
-   * Gets all reviews for a specific clinic
+   * Gets all reviews for a specific clinic with enhanced entity names
    * @param clinicId The ID of the clinic
-   * @returns Array of reviews containing clinic reviews
+   * @returns Array of reviews containing clinic reviews with clinic, practitioner, and procedure names
    */
   async getReviewsByClinic(clinicId: string): Promise<Review[]> {
+    console.log('🔍 ReviewService.getReviewsByClinic - Querying for clinic:', clinicId);
+
     const q = query(
       collection(this.db, REVIEWS_COLLECTION),
-      where("clinicReview.clinicId", "==", clinicId)
+      where('clinicReview.clinicId', '==', clinicId),
     );
     const snapshot = await getDocs(q);
-    return snapshot.docs.map((doc) => doc.data() as Review);
+    const reviews = snapshot.docs.map(doc => {
+      const data = doc.data() as Review;
+      return { ...data, id: doc.id };
+    });
+
+    console.log('🔍 ReviewService.getReviewsByClinic - Found reviews before enhancement:', {
+      clinicId,
+      reviewCount: reviews.length,
+      reviewIds: reviews.map(r => r.id),
+    });
+
+    // Enhance reviews with entity names from appointments
+    const enhancedReviews = await Promise.all(
+      reviews.map(async review => {
+        try {
+          // Fetch the associated appointment
+          const appointmentDoc = await getDoc(
+            doc(this.db, APPOINTMENTS_COLLECTION, review.appointmentId),
+          );
+
+          if (appointmentDoc.exists()) {
+            const appointment = appointmentDoc.data() as Appointment;
+
+            // Create enhanced review with entity names
+            const enhancedReview = { ...review };
+
+            if (enhancedReview.clinicReview && appointment.clinicInfo) {
+              enhancedReview.clinicReview = {
+                ...enhancedReview.clinicReview,
+                clinicName: appointment.clinicInfo.name,
+              };
+            }
+
+            if (enhancedReview.practitionerReview && appointment.practitionerInfo) {
+              enhancedReview.practitionerReview = {
+                ...enhancedReview.practitionerReview,
+                practitionerName: appointment.practitionerInfo.name,
+              };
+            }
+
+            if (enhancedReview.procedureReview && appointment.procedureInfo) {
+              enhancedReview.procedureReview = {
+                ...enhancedReview.procedureReview,
+                procedureName: appointment.procedureInfo.name,
+              };
+            }
+
+            // Add patient name to the main review object
+            if (appointment.patientInfo) {
+              enhancedReview.patientName = appointment.patientInfo.fullName;
+            }
+
+            return enhancedReview;
+          }
+
+          return review;
+        } catch (error) {
+          console.warn(`Failed to enhance review ${review.id} with entity names:`, error);
+          return review;
+        }
+      }),
+    );
+
+    console.log('✅ ReviewService.getReviewsByClinic - Enhanced reviews:', {
+      clinicId,
+      reviewCount: enhancedReviews.length,
+      reviewIds: enhancedReviews.map(r => r.id),
+      hasEntityNames: enhancedReviews.some(
+        r =>
+          r.clinicReview?.clinicName ||
+          r.practitionerReview?.practitionerName ||
+          r.procedureReview?.procedureName ||
+          r.patientName,
+      ),
+    });
+
+    return enhancedReviews;
   }
 
   /**
-   * Gets all reviews for a specific practitioner
+   * Gets all reviews for a specific practitioner with enhanced entity names
    * @param practitionerId The ID of the practitioner
-   * @returns Array of reviews containing practitioner reviews
+   * @returns Array of reviews containing practitioner reviews with clinic, practitioner, and procedure names
    */
   async getReviewsByPractitioner(practitionerId: string): Promise<Review[]> {
+    console.log(
+      '🔍 ReviewService.getReviewsByPractitioner - Querying for practitioner:',
+      practitionerId,
+    );
+
     const q = query(
       collection(this.db, REVIEWS_COLLECTION),
-      where("practitionerReview.practitionerId", "==", practitionerId)
+      where('practitionerReview.practitionerId', '==', practitionerId),
     );
     const snapshot = await getDocs(q);
-    return snapshot.docs.map((doc) => doc.data() as Review);
+    const reviews = snapshot.docs.map(doc => {
+      const data = doc.data() as Review;
+      return { ...data, id: doc.id };
+    });
+
+    console.log('🔍 ReviewService.getReviewsByPractitioner - Found reviews before enhancement:', {
+      practitionerId,
+      reviewCount: reviews.length,
+      reviewIds: reviews.map(r => r.id),
+    });
+
+    // Enhance reviews with entity names from appointments
+    const enhancedReviews = await Promise.all(
+      reviews.map(async review => {
+        try {
+          // Fetch the associated appointment
+          const appointmentDoc = await getDoc(
+            doc(this.db, APPOINTMENTS_COLLECTION, review.appointmentId),
+          );
+
+          if (appointmentDoc.exists()) {
+            const appointment = appointmentDoc.data() as Appointment;
+
+            // Create enhanced review with entity names
+            const enhancedReview = { ...review };
+
+            if (enhancedReview.clinicReview && appointment.clinicInfo) {
+              enhancedReview.clinicReview = {
+                ...enhancedReview.clinicReview,
+                clinicName: appointment.clinicInfo.name,
+              };
+            }
+
+            if (enhancedReview.practitionerReview && appointment.practitionerInfo) {
+              enhancedReview.practitionerReview = {
+                ...enhancedReview.practitionerReview,
+                practitionerName: appointment.practitionerInfo.name,
+              };
+            }
+
+            if (enhancedReview.procedureReview && appointment.procedureInfo) {
+              enhancedReview.procedureReview = {
+                ...enhancedReview.procedureReview,
+                procedureName: appointment.procedureInfo.name,
+              };
+            }
+
+            // Add patient name to the main review object
+            if (appointment.patientInfo) {
+              enhancedReview.patientName = appointment.patientInfo.fullName;
+            }
+
+            return enhancedReview;
+          }
+
+          return review;
+        } catch (error) {
+          console.warn(`Failed to enhance review ${review.id} with entity names:`, error);
+          return review;
+        }
+      }),
+    );
+
+    console.log('✅ ReviewService.getReviewsByPractitioner - Enhanced reviews:', {
+      practitionerId,
+      reviewCount: enhancedReviews.length,
+      reviewIds: enhancedReviews.map(r => r.id),
+      hasEntityNames: enhancedReviews.some(
+        r =>
+          r.clinicReview?.clinicName ||
+          r.practitionerReview?.practitionerName ||
+          r.procedureReview?.procedureName,
+      ),
+    });
+
+    return enhancedReviews;
   }
 
   /**
-   * Gets all reviews for a specific procedure
+   * Gets all reviews for a specific procedure with enhanced entity names
    * @param procedureId The ID of the procedure
-   * @returns Array of reviews containing procedure reviews
+   * @returns Array of reviews containing procedure reviews with clinic, practitioner, and procedure names
    */
   async getReviewsByProcedure(procedureId: string): Promise<Review[]> {
+    console.log('🔍 ReviewService.getReviewsByProcedure - Querying for procedure:', procedureId);
+
     const q = query(
       collection(this.db, REVIEWS_COLLECTION),
-      where("procedureReview.procedureId", "==", procedureId)
+      where('procedureReview.procedureId', '==', procedureId),
     );
     const snapshot = await getDocs(q);
-    return snapshot.docs.map((doc) => doc.data() as Review);
+    const reviews = snapshot.docs.map(doc => {
+      const data = doc.data() as Review;
+      return { ...data, id: doc.id };
+    });
+
+    console.log('🔍 ReviewService.getReviewsByProcedure - Found reviews before enhancement:', {
+      procedureId,
+      reviewCount: reviews.length,
+      reviewIds: reviews.map(r => r.id),
+    });
+
+    // Enhance reviews with entity names from appointments
+    const enhancedReviews = await Promise.all(
+      reviews.map(async review => {
+        try {
+          // Fetch the associated appointment
+          const appointmentDoc = await getDoc(
+            doc(this.db, APPOINTMENTS_COLLECTION, review.appointmentId),
+          );
+
+          if (appointmentDoc.exists()) {
+            const appointment = appointmentDoc.data() as Appointment;
+
+            // Create enhanced review with entity names
+            const enhancedReview = { ...review };
+
+            if (enhancedReview.clinicReview && appointment.clinicInfo) {
+              enhancedReview.clinicReview = {
+                ...enhancedReview.clinicReview,
+                clinicName: appointment.clinicInfo.name,
+              };
+            }
+
+            if (enhancedReview.practitionerReview && appointment.practitionerInfo) {
+              enhancedReview.practitionerReview = {
+                ...enhancedReview.practitionerReview,
+                practitionerName: appointment.practitionerInfo.name,
+              };
+            }
+
+            if (enhancedReview.procedureReview && appointment.procedureInfo) {
+              enhancedReview.procedureReview = {
+                ...enhancedReview.procedureReview,
+                procedureName: appointment.procedureInfo.name,
+              };
+            }
+
+            // Add patient name to the main review object
+            if (appointment.patientInfo) {
+              enhancedReview.patientName = appointment.patientInfo.fullName;
+            }
+
+            return enhancedReview;
+          }
+
+          return review;
+        } catch (error) {
+          console.warn(`Failed to enhance review ${review.id} with entity names:`, error);
+          return review;
+        }
+      }),
+    );
+
+    console.log('✅ ReviewService.getReviewsByProcedure - Enhanced reviews:', {
+      procedureId,
+      reviewCount: enhancedReviews.length,
+      reviewIds: enhancedReviews.map(r => r.id),
+      hasEntityNames: enhancedReviews.some(
+        r =>
+          r.clinicReview?.clinicName ||
+          r.practitionerReview?.practitionerName ||
+          r.procedureReview?.procedureName ||
+          r.patientName,
+      ),
+    });
+
+    return enhancedReviews;
   }
 
   /**
@@ -229,7 +589,7 @@ export class ReviewService extends BaseService {
   async getReviewByAppointment(appointmentId: string): Promise<Review | null> {
     const q = query(
       collection(this.db, REVIEWS_COLLECTION),
-      where("appointmentId", "==", appointmentId)
+      where('appointmentId', '==', appointmentId),
     );
     const snapshot = await getDocs(q);
 

package/src/types/reviews/index.ts

@@ -22,6 +22,7 @@ interface BaseReview {
  */
 export interface ClinicReview extends BaseReview {
   clinicId: string;
+  clinicName?: string; // Enhanced field: clinic name from appointment
   cleanliness: number; // 1-5 stars
   facilities: number; // 1-5 stars
   staffFriendliness: number; // 1-5 stars
@@ -37,6 +38,7 @@ export interface ClinicReview extends BaseReview {
  */
 export interface PractitionerReview extends BaseReview {
   practitionerId: string;
+  practitionerName?: string; // Enhanced field: practitioner name from appointment
   knowledgeAndExpertise: number; // 1-5 stars
   communicationSkills: number; // 1-5 stars
   bedSideManner: number; // 1-5 stars
@@ -52,6 +54,7 @@ export interface PractitionerReview extends BaseReview {
  */
 export interface ProcedureReview extends BaseReview {
   procedureId: string;
+  procedureName?: string; // Enhanced field: procedure name from appointment
   effectivenessOfTreatment: number; // 1-5 stars
   outcomeExplanation: number; // 1-5 stars
   painManagement: number; // 1-5 stars
@@ -114,6 +117,7 @@ export interface Review {
   id: string;
   appointmentId: string;
   patientId: string;
+  patientName?: string; // Enhanced field: patient name from appointment
   createdAt: Date;
   updatedAt: Date;
   clinicReview?: ClinicReview;
@@ -123,4 +127,4 @@ export interface Review {
   overallRating: number; // Average of all available ratings
 }
 
-export const REVIEWS_COLLECTION = "reviews";
+export const REVIEWS_COLLECTION = 'reviews';