@blackcode_sa/metaestetics-api 1.6.4 → 1.6.6

package/src/admin/aggregation/appointment/appointment.aggregation.service.ts

@@ -0,0 +1,1053 @@
+import * as admin from "firebase-admin";
+import {
+  Appointment,
+  AppointmentStatus,
+  // APPOINTMENTS_COLLECTION, // Not directly used in this file after refactor
+} from "../../../types/appointment";
+import {
+  PatientRequirementInstance,
+  PatientRequirementOverallStatus,
+  PatientInstructionStatus,
+  PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME,
+  PatientRequirementInstruction, // Added import
+} from "../../../types/patient/patient-requirements";
+import {
+  Requirement as RequirementTemplate,
+  // REQUIREMENTS_COLLECTION as REQUIREMENTS_TEMPLATES_COLLECTION, // Not used directly after refactor
+  RequirementType,
+  TimeUnit, // Added import
+} from "../../../backoffice/types/requirement.types";
+import {
+  PATIENTS_COLLECTION,
+  PatientProfile,
+  PatientSensitiveInfo,
+  PATIENT_SENSITIVE_INFO_COLLECTION,
+} from "../../../types/patient";
+import {
+  Practitioner,
+  PRACTITIONERS_COLLECTION,
+} from "../../../types/practitioner";
+import { Clinic, CLINICS_COLLECTION } from "../../../types/clinic";
+// import { UserRole } from "../../../types"; // Not directly used
+
+// Dependent Admin Services
+import { PatientRequirementsAdminService } from "../../requirements/patient-requirements.admin.service";
+import { NotificationsAdmin } from "../../notifications/notifications.admin";
+import { CalendarAdminService } from "../../calendar/calendar.admin.service";
+import { AppointmentMailingService } from "../../mailing/appointment/appointment.mailing.service";
+import { Logger } from "../../logger";
+import { UserRole } from "../../../types";
+
+// Mailgun client will be injected via constructor
+
+/**
+ * @class AppointmentAggregationService
+ * @description Handles aggregation tasks and side effects related to appointment lifecycle events.
+ * This service is intended to be used primarily by background functions (e.g., Cloud Functions)
+ * triggered by changes in the appointments collection.
+ */
+export class AppointmentAggregationService {
+  private db: admin.firestore.Firestore;
+  private appointmentMailingService: AppointmentMailingService;
+  private notificationsAdmin: NotificationsAdmin;
+  private calendarAdminService: CalendarAdminService;
+  private patientRequirementsAdminService: PatientRequirementsAdminService;
+
+  /**
+   * Constructor for AppointmentAggregationService.
+   * @param mailgunClient - An initialized Mailgun client instance.
+   * @param firestore Optional Firestore instance. If not provided, it uses the default admin SDK instance.
+   */
+  constructor(
+    mailgunClient: any, // Type as 'any' for now, to be provided by the calling Cloud Function
+    firestore?: admin.firestore.Firestore
+  ) {
+    this.db = firestore || admin.firestore();
+    this.appointmentMailingService = new AppointmentMailingService(
+      this.db,
+      mailgunClient // Pass the injected client
+    );
+    this.notificationsAdmin = new NotificationsAdmin(this.db);
+    this.calendarAdminService = new CalendarAdminService(this.db);
+    this.patientRequirementsAdminService = new PatientRequirementsAdminService(
+      this.db
+    );
+    Logger.info("[AppointmentAggregationService] Initialized.");
+  }
+
+  /**
+   * Handles side effects when an appointment is first created.
+   * This function would typically be called by an Firestore onCreate trigger.
+   * @param {Appointment} appointment - The newly created Appointment object.
+   * @returns {Promise<void>}
+   */
+  async handleAppointmentCreate(appointment: Appointment): Promise<void> {
+    Logger.info(
+      `[AggService] Handling CREATE for appointment: ${appointment.id}, patient: ${appointment.patientId}, status: ${appointment.status}`
+    );
+
+    try {
+      // 1. Manage Patient-Clinic-Practitioner Links (non-critical for core flow, can run in parallel or first)
+      // No need to await if other operations don't depend on its immediate completion, but awaiting for simplicity here.
+      await this.managePatientClinicPractitionerLinks(appointment, "create");
+
+      // 2. Fetch necessary profiles for notifications and context
+      // These can be fetched in parallel
+      const [
+        patientProfile,
+        patientSensitiveInfo,
+        practitionerProfile,
+        clinicInfo,
+      ] = await Promise.all([
+        this.fetchPatientProfile(appointment.patientId),
+        this.fetchPatientSensitiveInfo(appointment.patientId),
+        this.fetchPractitionerProfile(appointment.practitionerId), // Needed for practitioner notifications
+        this.fetchClinicInfo(appointment.clinicBranchId), // Needed for clinic admin notifications
+      ]);
+
+      // 3. Initial State Handling based on appointment status
+      if (appointment.status === AppointmentStatus.CONFIRMED) {
+        Logger.info(
+          `[AggService] Appt ${appointment.id} created as CONFIRMED.`
+        );
+        // Create pre-appointment requirements for confirmed appointments
+        await this.createPreAppointmentRequirementInstances(appointment);
+
+        // Send confirmation notifications
+        if (patientSensitiveInfo?.email && patientProfile) {
+          Logger.info(
+            `[AggService] Sending appointment confirmed email to patient ${patientSensitiveInfo.email}`
+          );
+          // Construct the data object for the mailing service
+          const emailData = {
+            appointment: appointment,
+            recipientProfile: appointment.patientInfo,
+            recipientRole: "patient" as const, // Use 'as const' for literal type
+          };
+          // The type cast here might still be an issue if PatientProfileInfo is not imported.
+          // However, the structure should be compatible enough for the call.
+          await this.appointmentMailingService.sendAppointmentConfirmedEmail(
+            emailData as any // Using 'as any' temporarily to bypass strict type checking if PatientProfileInfo is not imported
+            // TODO: Properly import PatientProfileInfo and ensure type compatibility
+          );
+        } else {
+          Logger.warn(
+            `[AggService] Cannot send confirmation email to patient ${appointment.patientId}: email missing.`
+          );
+        }
+
+        if (
+          patientProfile?.expoTokens &&
+          patientProfile.expoTokens.length > 0
+        ) {
+          Logger.info(
+            `[AggService] TODO: Send appointment confirmed push to patient ${appointment.patientId}`
+          );
+          await this.notificationsAdmin.sendAppointmentConfirmedPush(
+            appointment,
+            appointment.patientId,
+            patientProfile.expoTokens,
+            UserRole.PATIENT
+          );
+        }
+
+        if (practitionerProfile?.basicInfo?.email) {
+          Logger.info(
+            `[AggService] Sending appointment confirmation email to practitioner ${practitionerProfile.basicInfo.email}`
+          );
+          const practitionerEmailData = {
+            appointment: appointment,
+            recipientProfile: appointment.practitionerInfo,
+            recipientRole: "practitioner" as const,
+          };
+          await this.appointmentMailingService.sendAppointmentConfirmedEmail(
+            practitionerEmailData // TODO: Properly import PractitionerProfileInfo and ensure type compatibility
+          );
+        }
+        // TODO: Add push notification for practitioner if they have expoTokens
+      } else if (appointment.status === AppointmentStatus.PENDING) {
+        Logger.info(`[AggService] Appt ${appointment.id} created as PENDING.`);
+        // Notify clinic admin about the pending appointment
+        if (clinicInfo?.contactInfo?.email) {
+          Logger.info(
+            `[AggService] TODO: Send pending appointment notification email to clinic admin ${clinicInfo.contactInfo.email}`
+          );
+          const clinicEmailData = {
+            appointment: appointment,
+            clinicProfile: appointment.clinicInfo, // clinicInfo should be compatible with ClinicInfo type
+          };
+          await this.appointmentMailingService.sendAppointmentRequestedEmailToClinic(
+            clinicEmailData // TODO: Properly import ClinicInfo if stricter typing is needed here and ensure compatibility
+          );
+        } else {
+          Logger.warn(
+            `[AggService] Cannot send pending appointment email to clinic ${appointment.clinicBranchId}: email missing.`
+          );
+        }
+        // TODO: Push notification for clinic admin if applicable (they usually don't have tokens)
+      }
+
+      // Calendar events are noted as being handled by BookingAdmin.orchestrateAppointmentCreation during the booking process itself.
+      Logger.info(
+        `[AggService] Successfully processed CREATE for appointment: ${appointment.id}`
+      );
+    } catch (error) {
+      Logger.error(
+        `[AggService] Critical error in handleAppointmentCreate for appointment ${appointment.id}:`,
+        error
+      );
+      // Depending on the error, you might want to re-throw or handle specific cases
+      // (e.g., update appointment status to an error state if a critical part failed)
+    }
+  }
+
+  /**
+   * Handles side effects when an appointment is updated.
+   * This function would typically be called by an Firestore onUpdate trigger.
+   * @param {Appointment} before - The Appointment object before the update.
+   * @param {Appointment} after - The Appointment object after the update.
+   * @returns {Promise<void>}
+   */
+  async handleAppointmentUpdate(
+    before: Appointment,
+    after: Appointment
+  ): Promise<void> {
+    Logger.info(
+      `[AggService] Handling UPDATE for appointment: ${after.id}. Status ${before.status} -> ${after.status}`
+    );
+
+    try {
+      const statusChanged = before.status !== after.status;
+      const timeChanged =
+        before.appointmentStartTime.toMillis() !==
+          after.appointmentStartTime.toMillis() ||
+        before.appointmentEndTime.toMillis() !==
+          after.appointmentEndTime.toMillis();
+      // const paymentStatusChanged = before.paymentStatus !== after.paymentStatus; // TODO: Handle later
+      // const reviewAdded = !before.reviewInfo && after.reviewInfo; // TODO: Handle later
+
+      // Fetch profiles for notifications - could be conditional based on changes
+      // For simplicity, fetching upfront, but optimize if performance is an issue.
+      const [
+        patientProfile,
+        patientSensitiveInfo,
+        practitionerProfile,
+        clinicInfo,
+      ] = await Promise.all([
+        this.fetchPatientProfile(after.patientId),
+        this.fetchPatientSensitiveInfo(after.patientId),
+        this.fetchPractitionerProfile(after.practitionerId),
+        this.fetchClinicInfo(after.clinicBranchId),
+      ]);
+
+      if (statusChanged) {
+        Logger.info(
+          `[AggService] Status changed for ${after.id}: ${before.status} -> ${after.status}`
+        );
+
+        // --- PENDING -> CONFIRMED ---
+        if (
+          before.status === AppointmentStatus.PENDING &&
+          after.status === AppointmentStatus.CONFIRMED
+        ) {
+          Logger.info(`[AggService] Appt ${after.id} PENDING -> CONFIRMED.`);
+          await this.createPreAppointmentRequirementInstances(after);
+          // Send confirmation notifications
+          if (patientSensitiveInfo?.email && patientProfile) {
+            Logger.info(
+              `[AggService] Sending appointment confirmed email to patient ${patientSensitiveInfo.email}`
+            );
+            const emailData = {
+              appointment: after,
+              recipientProfile: after.patientInfo,
+              recipientRole: "patient" as const,
+            };
+            await this.appointmentMailingService.sendAppointmentConfirmedEmail(
+              emailData as any
+            );
+          } else {
+            Logger.warn(
+              `[AggService] Cannot send confirmation email to patient ${after.patientId}: email missing.`
+            );
+          }
+
+          if (
+            patientProfile?.expoTokens &&
+            patientProfile.expoTokens.length > 0
+          ) {
+            Logger.info(
+              `[AggService] TODO: Send appointment confirmed push to patient ${after.patientId}`
+            );
+            await this.notificationsAdmin.sendAppointmentConfirmedPush(
+              after,
+              after.patientId,
+              patientProfile.expoTokens,
+              UserRole.PATIENT
+            );
+          }
+
+          if (practitionerProfile?.basicInfo?.email) {
+            Logger.info(
+              `[AggService] Sending appointment confirmation email to practitioner ${practitionerProfile.basicInfo.email}`
+            );
+            const practitionerEmailData = {
+              appointment: after,
+              recipientProfile: after.practitionerInfo,
+              recipientRole: "practitioner" as const,
+            };
+            await this.appointmentMailingService.sendAppointmentConfirmedEmail(
+              practitionerEmailData as any // TODO: Properly import PractitionerProfileInfo and ensure type compatibility
+            );
+          }
+          // TODO: Add push notification for practitioner if they have expoTokens
+        }
+        // --- Any -> CANCELLED_* ---
+        else if (
+          after.status === AppointmentStatus.CANCELED_CLINIC ||
+          after.status === AppointmentStatus.CANCELED_PATIENT ||
+          after.status === AppointmentStatus.CANCELED_PATIENT_RESCHEDULED ||
+          after.status === AppointmentStatus.NO_SHOW
+        ) {
+          Logger.info(
+            `[AggService] Appt ${after.id} status -> ${after.status}. Processing as cancellation.`
+          );
+          await this.updateRelatedPatientRequirementInstances(
+            after,
+            PatientRequirementOverallStatus.CANCELLED_APPOINTMENT
+          );
+          await this.managePatientClinicPractitionerLinks(after, "cancel");
+
+          // Send cancellation email to Patient
+          if (patientSensitiveInfo?.email && patientProfile) {
+            Logger.info(
+              `[AggService] Sending appointment cancellation email to patient ${patientSensitiveInfo.email}`
+            );
+            const patientCancellationData = {
+              appointment: after,
+              recipientProfile: after.patientInfo,
+              recipientRole: "patient" as const,
+              // cancellationReason: after.cancellationReason, // TODO: Add if cancellationReason is available on 'after' Appointment
+            };
+            await this.appointmentMailingService.sendAppointmentCancelledEmail(
+              patientCancellationData as any // TODO: Properly import types
+            );
+          }
+
+          // Send cancellation email to Practitioner
+          if (practitionerProfile?.basicInfo?.email) {
+            Logger.info(
+              `[AggService] Sending appointment cancellation email to practitioner ${practitionerProfile.basicInfo.email}`
+            );
+            const practitionerCancellationData = {
+              appointment: after,
+              recipientProfile: after.practitionerInfo,
+              recipientRole: "practitioner" as const,
+              // cancellationReason: after.cancellationReason, // TODO: Add if cancellationReason is available on 'after' Appointment
+            };
+            await this.appointmentMailingService.sendAppointmentCancelledEmail(
+              practitionerCancellationData as any // TODO: Properly import types
+            );
+          }
+
+          // TODO: Send cancellation push notifications (patient, practitioner) via notificationsAdmin
+          // TODO: Update/cancel calendar event via calendarAdminService.updateAppointmentCalendarEventStatus(after, CalendarEventStatus.CANCELED)
+        }
+        // --- Any -> COMPLETED ---
+        else if (after.status === AppointmentStatus.COMPLETED) {
+          Logger.info(`[AggService] Appt ${after.id} status -> COMPLETED.`);
+          await this.createPostAppointmentRequirementInstances(after);
+
+          // Send review request email to patient
+          if (patientSensitiveInfo?.email && patientProfile) {
+            Logger.info(
+              `[AggService] Sending review request email to patient ${patientSensitiveInfo.email}`
+            );
+            const reviewRequestData = {
+              appointment: after,
+              patientProfile: after.patientInfo,
+              reviewLink: "TODO: Generate actual review link", // Placeholder
+            };
+            await this.appointmentMailingService.sendReviewRequestEmail(
+              reviewRequestData as any // TODO: Properly import PatientProfileInfo and define reviewLink generation
+            );
+          }
+          // TODO: Send review request push notification to patient
+        }
+        // --- RESCHEDULE Scenarios (e.g., PENDING/CONFIRMED -> RESCHEDULED_BY_CLINIC) ---
+        else if (after.status === AppointmentStatus.RESCHEDULED_BY_CLINIC) {
+          Logger.info(
+            `[AggService] Appt ${after.id} status -> RESCHEDULED_BY_CLINIC.`
+          );
+          await this.updateRelatedPatientRequirementInstances(
+            before, // Pass the 'before' state for old requirements
+            PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE
+          );
+          Logger.info(
+            `[AggService] TODO: Handle RESCHEDULE logic for requirements carefully based on confirmation flow.`
+          );
+
+          // Send reschedule proposal email to patient
+          if (patientSensitiveInfo?.email && patientProfile) {
+            Logger.info(
+              `[AggService] Sending reschedule proposal email to patient ${patientSensitiveInfo.email}`
+            );
+            const rescheduleEmailData = {
+              appointment: after, // The new state of the appointment
+              patientProfile: after.patientInfo,
+              previousStartTime: before.appointmentStartTime,
+              previousEndTime: before.appointmentEndTime,
+            };
+            await this.appointmentMailingService.sendAppointmentRescheduledProposalEmail(
+              rescheduleEmailData as any // TODO: Properly import PatientProfileInfo and types
+            );
+          }
+
+          Logger.info(
+            `[AggService] TODO: Send reschedule proposal notifications to practitioner as well.`
+          );
+          // TODO: Update calendar event to reflect proposed new time via calendarAdminService.
+        }
+        // TODO: Add more specific status change handlers as needed
+      }
+
+      // --- Independent Time Change (if not tied to a status that already handled it) ---
+      if (timeChanged && !statusChanged) {
+        // Or if status change didn't fully cover reschedule implications
+        Logger.info(`[AggService] Appointment ${after.id} time changed.`);
+        // This scenario is tricky. If time changes, pre-requirements might need to be re-evaluated.
+        // Typically, a time change would also involve a status change to some form of "rescheduled".
+        // If it can happen independently while, e.g., staying CONFIRMED, then:
+        // await this.updateRelatedPatientRequirementInstances(before, PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE);
+        // await this.createPreAppointmentRequirementInstances(after);
+        // TODO: Send reschedule notifications
+        // TODO: Update calendar event via calendarAdminService
+        Logger.warn(
+          `[AggService] Independent time change detected for ${after.id}. Review implications for requirements and calendar.`
+        );
+      }
+
+      // TODO: Handle Payment Status Change
+      // const paymentStatusChanged = before.paymentStatus !== after.paymentStatus;
+      // if (paymentStatusChanged && after.paymentStatus === PaymentStatus.PAID) { ... }
+
+      // TODO: Handle Review Added
+      // const reviewAdded = !before.reviewInfo && after.reviewInfo;
+      // if (reviewAdded) { ... }
+
+      Logger.info(
+        `[AggService] Successfully processed UPDATE for appointment: ${after.id}`
+      );
+    } catch (error) {
+      Logger.error(
+        `[AggService] Critical error in handleAppointmentUpdate for appointment ${after.id}:`,
+        error
+      );
+    }
+  }
+
+  /**
+   * Handles side effects when an appointment is deleted.
+   * @param deletedAppointment - The Appointment object that was deleted.
+   * @returns {Promise<void>}
+   */
+  async handleAppointmentDelete(
+    deletedAppointment: Appointment
+  ): Promise<void> {
+    Logger.info(
+      `[AggService] Handling DELETE for appointment: ${deletedAppointment.id}`
+    );
+    // Similar to cancellation
+    await this.updateRelatedPatientRequirementInstances(
+      deletedAppointment,
+      PatientRequirementOverallStatus.CANCELLED_APPOINTMENT
+    );
+    // await this.calendarAdminService.deleteAppointmentCalendarEvents(deletedAppointment);
+    await this.managePatientClinicPractitionerLinks(
+      deletedAppointment,
+      "cancel"
+    );
+    // TODO: Send cancellation/deletion notifications if appropriate (though data is gone)
+  }
+
+  // --- Helper Methods for Aggregation Logic ---
+
+  /**
+   * Creates PRE_APPOINTMENT PatientRequirementInstance documents for a given appointment.
+   * Uses the `appointment.preProcedureRequirements` array, which should contain relevant Requirement templates.
+   * For each active PRE requirement template, it constructs a new PatientRequirementInstance document
+   * with derived instructions and batch writes them to Firestore under the patient's `patient_requirements` subcollection.
+   *
+   * @param {Appointment} appointment - The appointment for which to create pre-requirement instances.
+   * @returns {Promise<void>} A promise that resolves when the operation is complete.
+   */
+  private async createPreAppointmentRequirementInstances(
+    appointment: Appointment
+  ): Promise<void> {
+    Logger.info(
+      `[AggService] Creating PRE-appointment requirement instances for appt: ${appointment.id}, patient: ${appointment.patientId}`
+    );
+
+    if (!appointment.procedureId) {
+      Logger.warn(
+        `[AggService] Appointment ${appointment.id} has no procedureId. Cannot create pre-requirement instances.`
+      );
+      return;
+    }
+
+    if (
+      !appointment.preProcedureRequirements ||
+      appointment.preProcedureRequirements.length === 0
+    ) {
+      Logger.info(
+        `[AggService] No preProcedureRequirements found on appointment ${appointment.id}. Nothing to create.`
+      );
+      return;
+    }
+
+    try {
+      const batch = this.db.batch();
+      let instancesCreatedCount = 0;
+
+      for (const template of appointment.preProcedureRequirements) {
+        if (!template) continue; // Skip if template is null or undefined in the array
+
+        // Ensure it's an active, PRE-type requirement
+        if (template.type !== RequirementType.PRE || !template.isActive) {
+          Logger.debug(
+            `[AggService] Skipping template ${template.id} (${template.name}): not an active PRE requirement.`
+          );
+          continue;
+        }
+
+        Logger.debug(
+          `[AggService] Processing template ${template.id} (${template.name}) for appt ${appointment.id}`
+        );
+
+        const newInstanceRef = this.db
+          .collection(PATIENTS_COLLECTION)
+          .doc(appointment.patientId)
+          .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
+          .doc(); // Auto-generate ID for the new instance
+
+        const instructions: PatientRequirementInstruction[] = (
+          template.timeframe?.notifyAt || []
+        ).map((notifyAtValue) => {
+          let dueTime: any = appointment.appointmentStartTime;
+          if (template.timeframe && typeof notifyAtValue === "number") {
+            const dueDateTime = new Date(
+              appointment.appointmentStartTime.toMillis()
+            );
+            if (template.timeframe.unit === TimeUnit.DAYS) {
+              dueDateTime.setDate(dueDateTime.getDate() - notifyAtValue);
+            } else if (template.timeframe.unit === TimeUnit.HOURS) {
+              dueDateTime.setHours(dueDateTime.getHours() - notifyAtValue);
+            }
+            dueTime = admin.firestore.Timestamp.fromDate(dueDateTime);
+          }
+
+          // TODO: Determine source or default for 'actionableWindow' - consult requirements for PatientRequirementInstruction
+          const actionableWindowHours =
+            template.importance === "high"
+              ? 1
+              : template.importance === "medium"
+              ? 4
+              : 15; // Default to 15 hours for low importance; // Placeholder default, TODO: Define source
+
+          const instructionObject: PatientRequirementInstruction = {
+            instructionId:
+              `${template.id}_${notifyAtValue}_${newInstanceRef.id}`.replace(
+                /[^a-zA-Z0-9_]/g,
+                "_"
+              ),
+            instructionText: template.description || template.name,
+            dueTime: dueTime as any,
+            actionableWindow: actionableWindowHours, // Directly assigning the placeholder default value
+            status: PatientInstructionStatus.PENDING_NOTIFICATION,
+            originalNotifyAtValue: notifyAtValue,
+            originalTimeframeUnit: template.timeframe.unit,
+            updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+            notificationId: undefined,
+            actionTakenAt: undefined,
+          };
+          return instructionObject;
+        });
+
+        const newInstanceData: Omit<PatientRequirementInstance, "id"> = {
+          patientId: appointment.patientId,
+          appointmentId: appointment.id,
+          originalRequirementId: template.id,
+          requirementName: template.name,
+          requirementDescription: template.description,
+          requirementType: template.type, // Should be RequirementType.PRE
+          requirementImportance: template.importance,
+          overallStatus: PatientRequirementOverallStatus.ACTIVE,
+          instructions: instructions,
+          // Timestamps - cast to any to satisfy client-side Timestamp type for now
+          createdAt: admin.firestore.FieldValue.serverTimestamp() as any,
+          updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+        };
+
+        batch.set(newInstanceRef, newInstanceData);
+        instancesCreatedCount++;
+        Logger.debug(
+          `[AggService] Added PatientRequirementInstance ${newInstanceRef.id} to batch for template ${template.id}.`
+        );
+      }
+
+      if (instancesCreatedCount > 0) {
+        await batch.commit();
+        Logger.info(
+          `[AggService] Successfully created ${instancesCreatedCount} PRE_APPOINTMENT requirement instances for appointment ${appointment.id}.`
+        );
+      } else {
+        Logger.info(
+          `[AggService] No new PRE_APPOINTMENT requirement instances were prepared for batch commit for appointment ${appointment.id}.`
+        );
+      }
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error creating PRE_APPOINTMENT requirement instances for appointment ${appointment.id}:`,
+        error
+      );
+      // Rethrow or handle as per error policy, e.g., if this failure should halt further processing.
+      // For now, just logging.
+    }
+  }
+
+  /**
+   * Creates POST_APPOINTMENT PatientRequirementInstance documents for a given appointment.
+   * Uses the `appointment.postProcedureRequirements` array.
+   * For each active POST requirement template, it constructs a new PatientRequirementInstance document
+   * with derived instructions and batch writes them to Firestore under the patient's `patient_requirements` subcollection.
+   *
+   * @param {Appointment} appointment - The appointment for which to create post-requirement instances.
+   * @returns {Promise<void>} A promise that resolves when the operation is complete.
+   */
+  private async createPostAppointmentRequirementInstances(
+    appointment: Appointment
+  ): Promise<void> {
+    Logger.info(
+      `[AggService] Creating POST-appointment requirement instances for appt: ${appointment.id}, patient: ${appointment.patientId}`
+    );
+
+    if (!appointment.procedureId) {
+      Logger.warn(
+        `[AggService] Appointment ${appointment.id} has no procedureId. Cannot create post-requirement instances.`
+      );
+      return;
+    }
+
+    if (
+      !appointment.postProcedureRequirements ||
+      appointment.postProcedureRequirements.length === 0
+    ) {
+      Logger.info(
+        `[AggService] No postProcedureRequirements found on appointment ${appointment.id}. Nothing to create.`
+      );
+      return;
+    }
+
+    try {
+      const batch = this.db.batch();
+      let instancesCreatedCount = 0;
+
+      for (const template of appointment.postProcedureRequirements) {
+        if (!template) continue;
+
+        if (template.type !== RequirementType.POST || !template.isActive) {
+          Logger.debug(
+            `[AggService] Skipping template ${template.id} (${template.name}): not an active POST requirement.`
+          );
+          continue;
+        }
+
+        Logger.debug(
+          `[AggService] Processing POST template ${template.id} (${template.name}) for appt ${appointment.id}`
+        );
+
+        const newInstanceRef = this.db
+          .collection(PATIENTS_COLLECTION)
+          .doc(appointment.patientId)
+          .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
+          .doc();
+
+        const instructions: PatientRequirementInstruction[] = (
+          template.timeframe?.notifyAt || []
+        ).map((notifyAtValue) => {
+          let dueTime: any = appointment.appointmentEndTime; // Default to appointment end time
+          if (template.timeframe && typeof notifyAtValue === "number") {
+            const dueDateTime = new Date(
+              appointment.appointmentEndTime.toMillis()
+            );
+            // For POST requirements, notifyAtValue usually means AFTER the event
+            if (template.timeframe.unit === TimeUnit.DAYS) {
+              dueDateTime.setDate(dueDateTime.getDate() + notifyAtValue);
+            } else if (template.timeframe.unit === TimeUnit.HOURS) {
+              dueDateTime.setHours(dueDateTime.getHours() + notifyAtValue);
+            }
+            dueTime = admin.firestore.Timestamp.fromDate(dueDateTime);
+          }
+
+          const actionableWindowHours =
+            template.importance === "high"
+              ? 1
+              : template.importance === "medium"
+              ? 4
+              : 15; // Default to 15 hours for low importance; // Placeholder default, TODO: Define source
+
+          return {
+            instructionId:
+              `${template.id}_${notifyAtValue}_${newInstanceRef.id}`.replace(
+                /[^a-zA-Z0-9_]/g,
+                "_"
+              ),
+            instructionText: template.description || template.name,
+            dueTime: dueTime as any,
+            actionableWindow: actionableWindowHours,
+            status: PatientInstructionStatus.PENDING_NOTIFICATION,
+            originalNotifyAtValue: notifyAtValue,
+            originalTimeframeUnit: template.timeframe.unit,
+            updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+            notificationId: undefined,
+            actionTakenAt: undefined,
+          } as PatientRequirementInstruction;
+        });
+
+        const newInstanceData: Omit<PatientRequirementInstance, "id"> = {
+          patientId: appointment.patientId,
+          appointmentId: appointment.id,
+          originalRequirementId: template.id,
+          requirementName: template.name,
+          requirementDescription: template.description,
+          requirementType: template.type, // Should be RequirementType.POST
+          requirementImportance: template.importance,
+          overallStatus: PatientRequirementOverallStatus.ACTIVE,
+          instructions: instructions,
+          createdAt: admin.firestore.FieldValue.serverTimestamp() as any,
+          updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+        };
+
+        batch.set(newInstanceRef, newInstanceData);
+        instancesCreatedCount++;
+        Logger.debug(
+          `[AggService] Added POST PatientRequirementInstance ${newInstanceRef.id} to batch for template ${template.id}.`
+        );
+      }
+
+      if (instancesCreatedCount > 0) {
+        await batch.commit();
+        Logger.info(
+          `[AggService] Successfully created ${instancesCreatedCount} POST_APPOINTMENT requirement instances for appointment ${appointment.id}.`
+        );
+      } else {
+        Logger.info(
+          `[AggService] No new POST_APPOINTMENT requirement instances were prepared for batch commit for appointment ${appointment.id}.`
+        );
+      }
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error creating POST_APPOINTMENT requirement instances for appointment ${appointment.id}:`,
+        error
+      );
+    }
+  }
+
+  /**
+   * Updates the overallStatus of all PatientRequirementInstance documents associated with a given appointment.
+   * This is typically used when an appointment is cancelled or rescheduled, making existing requirements void.
+   *
+   * @param {Appointment} appointment - The appointment whose requirement instances need updating.
+   * @param {PatientRequirementOverallStatus} newOverallStatus - The new status to set (e.g., CANCELLED_APPOINTMENT).
+   * @returns {Promise<void>} A promise that resolves when the operation is complete.
+   */
+  private async updateRelatedPatientRequirementInstances(
+    appointment: Appointment,
+    newOverallStatus: PatientRequirementOverallStatus,
+    _previousAppointmentData?: Appointment // Not used in this basic implementation, but kept for signature consistency
+  ): Promise<void> {
+    Logger.info(
+      `[AggService] Updating related patient req instances for appt ${appointment.id} (patient: ${appointment.patientId}) to ${newOverallStatus}`
+    );
+
+    if (!appointment.id || !appointment.patientId) {
+      Logger.error(
+        "[AggService] updateRelatedPatientRequirementInstances called with missing appointmentId or patientId.",
+        { appointmentId: appointment.id, patientId: appointment.patientId }
+      );
+      return;
+    }
+
+    try {
+      const instancesSnapshot = await this.db
+        .collection(PATIENTS_COLLECTION)
+        .doc(appointment.patientId)
+        .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
+        .where("appointmentId", "==", appointment.id)
+        .get();
+
+      if (instancesSnapshot.empty) {
+        Logger.info(
+          `[AggService] No patient requirement instances found for appointment ${appointment.id} to update.`
+        );
+        return;
+      }
+
+      const batch = this.db.batch();
+      let instancesUpdatedCount = 0;
+
+      instancesSnapshot.docs.forEach((doc) => {
+        const instance = doc.data() as PatientRequirementInstance;
+        // Update only if the status is actually different and not already in a terminal state like FAILED_TO_PROCESS
+        if (
+          instance.overallStatus !== newOverallStatus &&
+          instance.overallStatus !==
+            PatientRequirementOverallStatus.FAILED_TO_PROCESS
+        ) {
+          batch.update(doc.ref, {
+            overallStatus: newOverallStatus,
+            updatedAt: admin.firestore.FieldValue.serverTimestamp() as any, // Cast for now
+            // Potentially also cancel individual instructions if not handled by another trigger
+            // instructions: instance.instructions.map(instr => ({ ...instr, status: PatientInstructionStatus.CANCELLED, updatedAt: admin.firestore.FieldValue.serverTimestamp() as any }))
+          });
+          instancesUpdatedCount++;
+          Logger.debug(
+            `[AggService] Added update for PatientRequirementInstance ${doc.id} to batch. New status: ${newOverallStatus}`
+          );
+        }
+      });
+
+      if (instancesUpdatedCount > 0) {
+        await batch.commit();
+        Logger.info(
+          `[AggService] Successfully updated ${instancesUpdatedCount} patient requirement instances for appointment ${appointment.id} to status ${newOverallStatus}.`
+        );
+      } else {
+        Logger.info(
+          `[AggService] No patient requirement instances needed an update for appointment ${appointment.id}.`
+        );
+      }
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error updating patient requirement instances for appointment ${appointment.id}:`,
+        error
+      );
+    }
+  }
+
+  /**
+   * Manages denormalized links between a patient and the clinic/practitioner associated with an appointment.
+   * Adds patientId to arrays on clinic and practitioner documents on appointment creation.
+   * Removes patientId on appointment cancellation (basic removal, can be enhanced).
+   *
+   * @param {Appointment} appointment - The appointment object.
+   * @param {"create" | "cancel"} action - 'create' to add links, 'cancel' to remove them.
+   * @returns {Promise<void>} A promise that resolves when the operation is complete.
+   */
+  private async managePatientClinicPractitionerLinks(
+    appointment: Appointment,
+    action: "create" | "cancel"
+  ): Promise<void> {
+    Logger.info(
+      `[AggService] Managing patient-clinic-practitioner links for appt ${appointment.id} (patient: ${appointment.patientId}), action: ${action}`
+    );
+
+    if (
+      !appointment.patientId ||
+      !appointment.practitionerId ||
+      !appointment.clinicBranchId
+    ) {
+      Logger.error(
+        "[AggService] managePatientClinicPractitionerLinks called with missing IDs.",
+        {
+          patientId: appointment.patientId,
+          practitionerId: appointment.practitionerId,
+          clinicBranchId: appointment.clinicBranchId,
+        }
+      );
+      return;
+    }
+
+    const batch = this.db.batch();
+    const patientId = appointment.patientId;
+
+    // Practitioner link
+    const practitionerRef = this.db
+      .collection(PRACTITIONERS_COLLECTION)
+      .doc(appointment.practitionerId);
+    // Clinic link
+    const clinicRef = this.db
+      .collection(CLINICS_COLLECTION)
+      .doc(appointment.clinicBranchId);
+
+    if (action === "create") {
+      // Add patient to practitioner's list of patients (if field exists, e.g., 'patientIds')
+      // Assuming a field named 'patientIds' on the practitioner document
+      batch.update(practitionerRef, {
+        patientIds: admin.firestore.FieldValue.arrayUnion(patientId),
+        // Optionally, update a count or last interaction timestamp
+        updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+      });
+      Logger.debug(
+        `[AggService] Adding patient ${patientId} to practitioner ${appointment.practitionerId} patientIds.`
+      );
+
+      // Add patient to clinic's list of patients (if field exists, e.g., 'patientIds')
+      // Assuming a field named 'patientIds' on the clinic document
+      batch.update(clinicRef, {
+        patientIds: admin.firestore.FieldValue.arrayUnion(patientId),
+        updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+      });
+      Logger.debug(
+        `[AggService] Adding patient ${patientId} to clinic ${appointment.clinicBranchId} patientIds.`
+      );
+    } else if (action === "cancel") {
+      // Basic removal.
+      // TODO: Implement more robust removal logic: only remove if this was the last active/confirmed appointment
+      //       linking this patient to this practitioner/clinic.
+      batch.update(practitionerRef, {
+        patientIds: admin.firestore.FieldValue.arrayRemove(patientId),
+        updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+      });
+      Logger.debug(
+        `[AggService] Removing patient ${patientId} from practitioner ${appointment.practitionerId} patientIds.`
+      );
+
+      batch.update(clinicRef, {
+        patientIds: admin.firestore.FieldValue.arrayRemove(patientId),
+        updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+      });
+      Logger.debug(
+        `[AggService] Removing patient ${patientId} from clinic ${appointment.clinicBranchId} patientIds.`
+      );
+    }
+
+    try {
+      await batch.commit();
+      Logger.info(
+        `[AggService] Successfully updated patient-clinic-practitioner links for appointment ${appointment.id}, action: ${action}.`
+      );
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error managing patient-clinic-practitioner links for appointment ${appointment.id}:`,
+        error
+      );
+    }
+  }
+
+  // --- Data Fetching Helpers (Consider moving to a data access layer or using existing services if available) ---
+  private async fetchPatientProfile(
+    patientId: string
+  ): Promise<PatientProfile | null> {
+    try {
+      const doc = await this.db
+        .collection(PATIENTS_COLLECTION)
+        .doc(patientId)
+        .get();
+      return doc.exists ? (doc.data() as PatientProfile) : null;
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error fetching patient profile ${patientId}:`,
+        error
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Fetches the sensitive information for a given patient ID.
+   * @param patientId The ID of the patient to fetch sensitive information for.
+   * @returns {Promise<PatientSensitiveInfo | null>} The patient sensitive information or null if not found or an error occurs.
+   */
+  private async fetchPatientSensitiveInfo(
+    patientId: string
+  ): Promise<PatientSensitiveInfo | null> {
+    try {
+      // Assuming sensitive info is in a subcollection PATIENT_SENSITIVE_INFO_COLLECTION
+      // under the patient's document, and the sensitive info document ID is the patientId itself.
+      // If the document ID is fixed (e.g., 'details'), this path should be adjusted.
+      const doc = await this.db
+        .collection(PATIENTS_COLLECTION)
+        .doc(patientId)
+        .collection(PATIENT_SENSITIVE_INFO_COLLECTION)
+        .doc(patientId) // CONFIRM THIS DOCUMENT ID PATTERN
+        .get();
+      if (!doc.exists) {
+        Logger.warn(
+          `[AggService] No sensitive info found for patient ${patientId}`
+        );
+        return null;
+      }
+      return doc.data() as PatientSensitiveInfo;
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error fetching patient sensitive info ${patientId}:`,
+        error
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Fetches the profile for a given practitioner ID.
+   * @param practitionerId The ID of the practitioner to fetch.
+   * @returns {Promise<Practitioner | null>} The practitioner profile or null if not found or an error occurs.
+   */
+  private async fetchPractitionerProfile(
+    practitionerId: string
+  ): Promise<Practitioner | null> {
+    if (!practitionerId) {
+      Logger.warn(
+        "[AggService] fetchPractitionerProfile called with no practitionerId."
+      );
+      return null;
+    }
+    try {
+      const doc = await this.db
+        .collection(PRACTITIONERS_COLLECTION)
+        .doc(practitionerId)
+        .get();
+      if (!doc.exists) {
+        Logger.warn(
+          `[AggService] No practitioner profile found for ID ${practitionerId}`
+        );
+        return null;
+      }
+      return doc.data() as Practitioner;
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error fetching practitioner profile ${practitionerId}:`,
+        error
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Fetches the information for a given clinic ID.
+   * @param clinicId The ID of the clinic to fetch.
+   * @returns {Promise<Clinic | null>} The clinic information or null if not found or an error occurs.
+   */
+  private async fetchClinicInfo(clinicId: string): Promise<Clinic | null> {
+    if (!clinicId) {
+      Logger.warn("[AggService] fetchClinicInfo called with no clinicId.");
+      return null;
+    }
+    try {
+      const doc = await this.db
+        .collection(CLINICS_COLLECTION)
+        .doc(clinicId)
+        .get();
+      if (!doc.exists) {
+        Logger.warn(`[AggService] No clinic info found for ID ${clinicId}`);
+        return null;
+      }
+      return doc.data() as Clinic;
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error fetching clinic info ${clinicId}:`,
+        error
+      );
+      return null;
+    }
+  }
+}