@blackcode_sa/metaestetics-api 1.12.61 → 1.12.62

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

@@ -1,1844 +1,1844 @@
-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 { Procedure, PROCEDURES_COLLECTION } from '../../../types/procedure';
-import { RequirementSourceProcedure } from '../../../types/patient/patient-requirements';
-// 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';
-import { CalendarEventStatus } from '../../../types/calendar';
-
-// Mailgun client will be injected via constructor
-
-/**
- * Type for requirement with source procedure tracking
- */
-type RequirementWithSource = {
-  requirement: RequirementTemplate;
-  sourceProcedures: RequirementSourceProcedure[];
-};
-
-/**
- * @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. 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
-        ]);
-
-      // 2. Manage Patient-Clinic-Practitioner Links (moved from beginning to here)
-      // Now we can pass the already fetched patient profile
-      if (patientProfile) {
-        await this.managePatientClinicPractitionerLinks(
-          patientProfile,
-          appointment.practitionerId,
-          appointment.clinicBranchId,
-          'create',
-        );
-      }
-
-      // 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 zonePhotosChanged = this.hasZonePhotosChanged(before, after);
-      // 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);
-
-          // Update calendar events to CONFIRMED status
-          await this.calendarAdminService.updateAppointmentCalendarEventsStatus(
-            after,
-            CalendarEventStatus.CONFIRMED,
-          );
-
-          // 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,
-            );
-          }
-        }
-        // --- RESCHEDULED_BY_CLINIC -> CONFIRMED (Reschedule Acceptance) ---
-        else if (
-          before.status === AppointmentStatus.RESCHEDULED_BY_CLINIC &&
-          after.status === AppointmentStatus.CONFIRMED
-        ) {
-          Logger.info(`[AggService] Appt ${after.id} RESCHEDULED_BY_CLINIC -> CONFIRMED.`);
-
-          // Update existing requirements as superseded and create new ones
-          await this.updateRelatedPatientRequirementInstances(
-            before,
-            PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE,
-          );
-          await this.createPreAppointmentRequirementInstances(after);
-
-          // Update calendar events to CONFIRMED status and update times
-          await this.calendarAdminService.updateAppointmentCalendarEventsStatus(
-            after,
-            CalendarEventStatus.CONFIRMED,
-          );
-
-          // Send confirmation notifications (similar to PENDING -> CONFIRMED)
-          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);
-          }
-
-          if (patientProfile?.expoTokens && patientProfile.expoTokens.length > 0) {
-            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,
-            );
-          }
-        }
-        // --- 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,
-          );
-
-          // Update patient-clinic-practitioner links if patient profile exists
-          if (patientProfile) {
-            await this.managePatientClinicPractitionerLinks(
-              patientProfile,
-              after.practitionerId,
-              after.clinicBranchId,
-              'cancel',
-              after.status,
-            );
-          }
-
-          const calendarStatus = (status: AppointmentStatus) => {
-            switch (status) {
-              case AppointmentStatus.NO_SHOW:
-                return CalendarEventStatus.NO_SHOW;
-              case AppointmentStatus.CANCELED_CLINIC:
-                return CalendarEventStatus.REJECTED;
-              case AppointmentStatus.CANCELED_PATIENT:
-                return CalendarEventStatus.CANCELED;
-              case AppointmentStatus.CANCELED_PATIENT_RESCHEDULED:
-                return CalendarEventStatus.REJECTED;
-              default:
-                return CalendarEventStatus.CANCELED;
-            }
-          };
-
-          await this.calendarAdminService.updateAppointmentCalendarEventsStatus(
-            after,
-            calendarStatus(after.status),
-          );
-
-          // 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);
-
-          // Update calendar events to COMPLETED status
-          await this.calendarAdminService.updateAppointmentCalendarEventsStatus(
-            after,
-            CalendarEventStatus.COMPLETED,
-          );
-
-          // 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,
-          );
-
-          // First update the calendar event times with new proposed times
-          await this.calendarAdminService.updateAppointmentCalendarEventsTime(after, {
-            start: after.appointmentStartTime,
-            end: after.appointmentEndTime,
-          });
-
-          // Then update calendar events to PENDING status (waiting for patient confirmation)
-          await this.calendarAdminService.updateAppointmentCalendarEventsStatus(
-            after,
-            CalendarEventStatus.PENDING,
-          );
-
-          // 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.`);
-
-        // If confirmed appointment has time change, we need to update requirements
-        if (after.status === AppointmentStatus.CONFIRMED) {
-          // Update existing requirements as superseded and create new ones
-          await this.updateRelatedPatientRequirementInstances(
-            before,
-            PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE,
-          );
-          await this.createPreAppointmentRequirementInstances(after);
-
-          // Update calendar event times with new times
-          await this.calendarAdminService.updateAppointmentCalendarEventsTime(after, {
-            start: after.appointmentStartTime,
-            end: after.appointmentEndTime,
-          });
-        } else {
-          Logger.warn(
-            `[AggService] Independent time change detected for ${after.id} with status ${after.status}. Review implications for requirements and calendar.`,
-          );
-        }
-      }
-
-      // TODO: Handle Payment Status Change
-      // const paymentStatusChanged = before.paymentStatus !== after.paymentStatus;
-      // if (paymentStatusChanged && after.paymentStatus === PaymentStatus.PAID) { ... }
-
-      // Handle Zone Photos Changes
-      if (zonePhotosChanged) {
-        Logger.info(`[AggService] Zone photos changed for appointment ${after.id}`);
-        await this.handleZonePhotosUpdate(before, after);
-      }
-
-      // 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,
-    );
-
-    // Fetch patient profile first
-    const patientProfile = await this.fetchPatientProfile(deletedAppointment.patientId);
-
-    // Update relationship links if patient profile exists
-    if (patientProfile) {
-      await this.managePatientClinicPractitionerLinks(
-        patientProfile,
-        deletedAppointment.practitionerId,
-        deletedAppointment.clinicBranchId,
-        'cancel',
-      );
-    }
-
-    // Delete all associated calendar events
-    await this.calendarAdminService.deleteAppointmentCalendarEvents(deletedAppointment);
-
-    // 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;
-      // Store created instances for fallback direct creation if needed
-      let createdInstances = [];
-
-      // Log more details about the pre-requirements
-      Logger.info(
-        `[AggService] Found ${
-          appointment.preProcedureRequirements.length
-        } pre-requirements to process: ${JSON.stringify(
-          appointment.preProcedureRequirements.map(r => ({
-            id: r.id,
-            name: r.name,
-            type: r.type,
-            isActive: r.isActive,
-            hasTimeframe: !!r.timeframe,
-            notifyAtLength: r.timeframe?.notifyAt?.length || 0,
-          })),
-        )}`,
-      );
-
-      for (const template of appointment.preProcedureRequirements) {
-        if (!template) {
-          Logger.warn(
-            `[AggService] Found null/undefined template in preProcedureRequirements array`,
-          );
-          continue;
-        }
-
-        // 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;
-        }
-
-        if (
-          !template.timeframe ||
-          !template.timeframe.notifyAt ||
-          template.timeframe.notifyAt.length === 0
-        ) {
-          Logger.warn(
-            `[AggService] Template ${template.id} (${template.name}) has no timeframe.notifyAt values. Creating with empty instructions.`,
-          );
-        }
-
-        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
-
-        // Log the path for debugging
-        Logger.debug(`[AggService] Created doc reference: ${newInstanceRef.path}`);
-
-        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.Timestamp.now() as any, // Use current server timestamp
-          };
-          return instructionObject;
-        });
-
-        const newInstanceData: PatientRequirementInstance = {
-          id: newInstanceRef.id, // Add the ID to the document data
-          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,
-        };
-
-        // Log the data being set
-        Logger.debug(
-          `[AggService] Setting data for requirement: ${JSON.stringify({
-            id: newInstanceRef.id,
-            patientId: newInstanceData.patientId,
-            appointmentId: newInstanceData.appointmentId,
-            requirementName: newInstanceData.requirementName,
-            instructionsCount: newInstanceData.instructions.length,
-          })}`,
-        );
-
-        batch.set(newInstanceRef, newInstanceData);
-        // Store for potential fallback
-        createdInstances.push({
-          ref: newInstanceRef,
-          data: newInstanceData,
-        });
-
-        instancesCreatedCount++;
-        Logger.debug(
-          `[AggService] Added PatientRequirementInstance ${newInstanceRef.id} to batch for template ${template.id}.`,
-        );
-      }
-
-      if (instancesCreatedCount > 0) {
-        try {
-          await batch.commit();
-          Logger.info(
-            `[AggService] Successfully created ${instancesCreatedCount} PRE_APPOINTMENT requirement instances for appointment ${appointment.id}.`,
-          );
-
-          // Verify creation success
-          try {
-            const verifySnapshot = await this.db
-              .collection(PATIENTS_COLLECTION)
-              .doc(appointment.patientId)
-              .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
-              .where('appointmentId', '==', appointment.id)
-              .get();
-
-            if (verifySnapshot.empty) {
-              Logger.warn(
-                `[AggService] Batch commit reported success but documents not found! Attempting direct creation as fallback...`,
-              );
-
-              // Fallback to direct creation if batch worked but docs aren't there
-              const fallbackPromises = createdInstances.map(async ({ ref, data }) => {
-                try {
-                  await ref.set(data);
-                  Logger.info(`[AggService] Fallback direct creation success for ${ref.id}`);
-                  return true;
-                } catch (fallbackError) {
-                  Logger.error(
-                    `[AggService] Fallback direct creation failed for ${ref.id}:`,
-                    fallbackError,
-                  );
-                  return false;
-                }
-              });
-
-              const fallbackResults = await Promise.allSettled(fallbackPromises);
-              const successCount = fallbackResults.filter(
-                r => r.status === 'fulfilled' && r.value === true,
-              ).length;
-
-              if (successCount > 0) {
-                Logger.info(
-                  `[AggService] Fallback mechanism created ${successCount} out of ${createdInstances.length} requirements`,
-                );
-              } else {
-                Logger.error(
-                  `[AggService] Both batch and fallback mechanisms failed to create requirements`,
-                );
-                throw new Error(
-                  'Failed to create patient requirements through both batch and direct methods',
-                );
-              }
-            } else {
-              Logger.info(
-                `[AggService] Verification confirmed ${verifySnapshot.size} requirement documents created`,
-              );
-            }
-          } catch (verifyError) {
-            Logger.error(
-              `[AggService] Error during verification of created requirements:`,
-              verifyError,
-            );
-          }
-        } catch (commitError) {
-          Logger.error(
-            `[AggService] Error committing batch for PRE_APPOINTMENT requirement instances for appointment ${appointment.id}:`,
-            commitError,
-          );
-
-          // Try direct creation as fallback
-          Logger.info(`[AggService] Attempting direct creation as fallback...`);
-          const fallbackPromises = createdInstances.map(async ({ ref, data }) => {
-            try {
-              await ref.set(data);
-              Logger.info(`[AggService] Fallback direct creation success for ${ref.id}`);
-              return true;
-            } catch (fallbackError) {
-              Logger.error(
-                `[AggService] Fallback direct creation failed for ${ref.id}:`,
-                fallbackError,
-              );
-              return false;
-            }
-          });
-
-          const fallbackResults = await Promise.allSettled(fallbackPromises);
-          const successCount = fallbackResults.filter(
-            r => r.status === 'fulfilled' && r.value === true,
-          ).length;
-
-          if (successCount > 0) {
-            Logger.info(
-              `[AggService] Fallback mechanism created ${successCount} out of ${createdInstances.length} requirements`,
-            );
-          } else {
-            Logger.error(
-              `[AggService] Both batch and fallback mechanisms failed to create requirements`,
-            );
-            throw new Error(
-              'Failed to create patient requirements through both batch and direct methods',
-            );
-          }
-        }
-      } 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,
-      );
-      throw error; // Re-throw to ensure the caller knows there was a problem
-    }
-  }
-
-  /**
-   * Fetches post-requirements from a procedure document
-   * @param procedureId - The procedure ID to fetch requirements from
-   * @returns Promise resolving to array of post-requirements with source procedure info
-   */
-  private async fetchPostRequirementsFromProcedure(
-    procedureId: string,
-  ): Promise<RequirementWithSource[]> {
-    try {
-      const procedureDoc = await this.db.collection(PROCEDURES_COLLECTION).doc(procedureId).get();
-      if (!procedureDoc.exists) {
-        Logger.warn(`[AggService] Procedure ${procedureId} not found when fetching requirements`);
-        return [];
-      }
-
-      const procedure = procedureDoc.data() as Procedure;
-      const postRequirements = procedure.postRequirements || [];
-
-      if (postRequirements.length === 0) {
-        return [];
-      }
-
-      return postRequirements.map(req => ({
-        requirement: req,
-        sourceProcedures: [
-          {
-            procedureId: procedure.id,
-            procedureName: procedure.name,
-          },
-        ],
-      }));
-    } catch (error) {
-      Logger.error(
-        `[AggService] Error fetching post-requirements from procedure ${procedureId}:`,
-        error,
-      );
-      return [];
-    }
-  }
-
-  /**
-   * Collects all post-requirements from primary and extended procedures
-   * @param appointment - The appointment to collect requirements for
-   * @returns Promise resolving to array of requirements with source procedures
-   */
-  private async collectAllPostRequirements(
-    appointment: Appointment,
-  ): Promise<RequirementWithSource[]> {
-    const allRequirements: RequirementWithSource[] = [];
-
-    // Fetch from primary procedure
-    if (appointment.procedureId) {
-      const primaryRequirements = await this.fetchPostRequirementsFromProcedure(
-        appointment.procedureId,
-      );
-      allRequirements.push(...primaryRequirements);
-    }
-
-    // Fetch from extended procedures
-    const extendedProcedures = appointment.metadata?.extendedProcedures || [];
-    if (extendedProcedures.length > 0) {
-      Logger.info(
-        `[AggService] Fetching post-requirements from ${extendedProcedures.length} extended procedures`,
-      );
-
-      const extendedRequirementsPromises = extendedProcedures.map(extProc =>
-        this.fetchPostRequirementsFromProcedure(extProc.procedureId),
-      );
-
-      const extendedRequirementsArrays = await Promise.all(extendedRequirementsPromises);
-      extendedRequirementsArrays.forEach(reqs => {
-        allRequirements.push(...reqs);
-      });
-    }
-
-    return allRequirements;
-  }
-
-  /**
-   * Generates a unique key for a requirement based on ID and timeframe
-   * @param requirement - The requirement to generate a key for
-   * @returns Unique key string
-   */
-  private getRequirementKey(requirement: RequirementTemplate): string {
-    const timeframeSig = JSON.stringify({
-      duration: requirement.timeframe?.duration || 0,
-      unit: requirement.timeframe?.unit || '',
-      notifyAt: (requirement.timeframe?.notifyAt || []).slice().sort((a, b) => a - b),
-    });
-    return `${requirement.id}:${timeframeSig}`;
-  }
-
-  /**
-   * Deduplicates requirements based on requirement ID and timeframe
-   * Merges source procedures when requirements match
-   * @param requirements - Array of requirements with sources
-   * @returns Deduplicated array of requirements
-   */
-  private deduplicateRequirements(
-    requirements: RequirementWithSource[],
-  ): RequirementWithSource[] {
-    const requirementMap = new Map<string, RequirementWithSource>();
-
-    for (const reqWithSource of requirements) {
-      const key = this.getRequirementKey(reqWithSource.requirement);
-
-      if (requirementMap.has(key)) {
-        // Merge source procedures
-        const existing = requirementMap.get(key)!;
-        const existingProcedureIds = new Set(
-          existing.sourceProcedures.map(sp => sp.procedureId),
-        );
-
-        // Add new source procedures that don't already exist
-        reqWithSource.sourceProcedures.forEach(sp => {
-          if (!existingProcedureIds.has(sp.procedureId)) {
-            existing.sourceProcedures.push(sp);
-          }
-        });
-      } else {
-        // New requirement, add it
-        requirementMap.set(key, {
-          requirement: reqWithSource.requirement,
-          sourceProcedures: [...reqWithSource.sourceProcedures],
-        });
-      }
-    }
-
-    return Array.from(requirementMap.values());
-  }
-
-  /**
-   * Creates POST_APPOINTMENT PatientRequirementInstance documents for a given appointment.
-   * Fetches requirements from primary and extended procedures, deduplicates them,
-   * and creates requirement instances with source procedure tracking.
-   *
-   * @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;
-    }
-
-    try {
-      // Collect all post-requirements from primary and extended procedures
-      const allRequirements = await this.collectAllPostRequirements(appointment);
-
-      if (allRequirements.length === 0) {
-        Logger.info(
-          `[AggService] No post-requirements found from any procedures for appointment ${appointment.id}. Nothing to create.`,
-        );
-        return;
-      }
-
-      // Deduplicate requirements based on ID + timeframe
-      const deduplicatedRequirements = this.deduplicateRequirements(allRequirements);
-
-      Logger.info(
-        `[AggService] Found ${allRequirements.length} total post-requirements, ${deduplicatedRequirements.length} after deduplication`,
-      );
-
-      // Log details about the deduplicated requirements
-      Logger.info(
-        `[AggService] Processing deduplicated post-requirements: ${JSON.stringify(
-          deduplicatedRequirements.map(r => ({
-            id: r.requirement.id,
-            name: r.requirement.name,
-            type: r.requirement.type,
-            isActive: r.requirement.isActive,
-            hasTimeframe: !!r.requirement.timeframe,
-            notifyAtLength: r.requirement.timeframe?.notifyAt?.length || 0,
-            sourceProcedures: r.sourceProcedures.map(sp => ({
-              procedureId: sp.procedureId,
-              procedureName: sp.procedureName,
-            })),
-          })),
-        )}`,
-      );
-
-      const batch = this.db.batch();
-      let instancesCreatedCount = 0;
-      // Store created instances for fallback direct creation if needed
-      let createdInstances = [];
-
-      for (const reqWithSource of deduplicatedRequirements) {
-        const template = reqWithSource.requirement;
-        if (!template) {
-          Logger.warn(
-            `[AggService] Found null/undefined template in postProcedureRequirements array`,
-          );
-          continue;
-        }
-
-        // Ensure it's an active, POST-type requirement
-        if (template.type !== RequirementType.POST || !template.isActive) {
-          Logger.debug(
-            `[AggService] Skipping template ${template.id} (${template.name}): not an active POST requirement.`,
-          );
-          continue;
-        }
-
-        if (
-          !template.timeframe ||
-          !template.timeframe.notifyAt ||
-          template.timeframe.notifyAt.length === 0
-        ) {
-          Logger.warn(
-            `[AggService] Template ${template.id} (${template.name}) has no timeframe.notifyAt values. Creating with empty instructions.`,
-          );
-        }
-
-        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
-
-        // Log the path for debugging
-        Logger.debug(`[AggService] Created doc reference: ${newInstanceRef.path}`);
-
-        const instructions: PatientRequirementInstruction[] = (
-          template.timeframe?.notifyAt || []
-        ).map(notifyAtValue => {
-          let dueTime: any = appointment.appointmentEndTime;
-          if (template.timeframe && typeof notifyAtValue === 'number') {
-            const dueDateTime = new Date(appointment.appointmentEndTime.toMillis());
-            // For POST requirements, notifyAtValue 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
-
-          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,
-            status: PatientInstructionStatus.PENDING_NOTIFICATION,
-            originalNotifyAtValue: notifyAtValue,
-            originalTimeframeUnit: template.timeframe.unit,
-            updatedAt: admin.firestore.Timestamp.now() as any,
-            notificationId: undefined,
-            actionTakenAt: undefined,
-          };
-          return instructionObject;
-        });
-
-        const newInstanceData: PatientRequirementInstance = {
-          id: newInstanceRef.id,
-          patientId: appointment.patientId,
-          appointmentId: appointment.id,
-          originalRequirementId: template.id,
-          requirementName: template.name,
-          requirementDescription: template.description,
-          requirementType: template.type,
-          requirementImportance: template.importance,
-          overallStatus: PatientRequirementOverallStatus.ACTIVE,
-          instructions: instructions,
-          sourceProcedures: reqWithSource.sourceProcedures, // Track which procedures this requirement comes from
-          createdAt: admin.firestore.FieldValue.serverTimestamp() as any,
-          updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
-        };
-
-        // Log the data being set
-        Logger.debug(
-          `[AggService] Setting data for requirement: ${JSON.stringify({
-            id: newInstanceRef.id,
-            patientId: newInstanceData.patientId,
-            appointmentId: newInstanceData.appointmentId,
-            requirementName: newInstanceData.requirementName,
-            instructionsCount: newInstanceData.instructions.length,
-            sourceProcedures: newInstanceData.sourceProcedures?.map(sp => ({
-              procedureId: sp.procedureId,
-              procedureName: sp.procedureName,
-            })) || [],
-          })}`,
-        );
-
-        batch.set(newInstanceRef, newInstanceData);
-        // Store for potential fallback
-        createdInstances.push({
-          ref: newInstanceRef,
-          data: newInstanceData,
-        });
-
-        instancesCreatedCount++;
-        Logger.debug(
-          `[AggService] Added PatientRequirementInstance ${newInstanceRef.id} to batch for template ${template.id}.`,
-        );
-      }
-
-      if (instancesCreatedCount > 0) {
-        try {
-          await batch.commit();
-          Logger.info(
-            `[AggService] Successfully created ${instancesCreatedCount} POST_APPOINTMENT requirement instances for appointment ${appointment.id}.`,
-          );
-
-          // Verify creation success
-          try {
-            const verifySnapshot = await this.db
-              .collection(PATIENTS_COLLECTION)
-              .doc(appointment.patientId)
-              .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
-              .where('appointmentId', '==', appointment.id)
-              .get();
-
-            if (verifySnapshot.empty) {
-              Logger.warn(
-                `[AggService] Batch commit reported success but documents not found! Attempting direct creation as fallback...`,
-              );
-
-              // Fallback to direct creation if batch worked but docs aren't there
-              const fallbackPromises = createdInstances.map(async ({ ref, data }) => {
-                try {
-                  await ref.set(data);
-                  Logger.info(`[AggService] Fallback direct creation success for ${ref.id}`);
-                  return true;
-                } catch (fallbackError) {
-                  Logger.error(
-                    `[AggService] Fallback direct creation failed for ${ref.id}:`,
-                    fallbackError,
-                  );
-                  return false;
-                }
-              });
-
-              const fallbackResults = await Promise.allSettled(fallbackPromises);
-              const successCount = fallbackResults.filter(
-                r => r.status === 'fulfilled' && r.value === true,
-              ).length;
-
-              if (successCount > 0) {
-                Logger.info(
-                  `[AggService] Fallback mechanism created ${successCount} out of ${createdInstances.length} requirements`,
-                );
-              } else {
-                Logger.error(
-                  `[AggService] Both batch and fallback mechanisms failed to create requirements`,
-                );
-                throw new Error(
-                  'Failed to create patient requirements through both batch and direct methods',
-                );
-              }
-            } else {
-              Logger.info(
-                `[AggService] Verification confirmed ${verifySnapshot.size} requirement documents created`,
-              );
-            }
-          } catch (verifyError) {
-            Logger.error(
-              `[AggService] Error during verification of created requirements:`,
-              verifyError,
-            );
-          }
-        } catch (commitError) {
-          Logger.error(
-            `[AggService] Error committing batch for POST_APPOINTMENT requirement instances for appointment ${appointment.id}:`,
-            commitError,
-          );
-
-          // Try direct creation as fallback
-          Logger.info(`[AggService] Attempting direct creation as fallback...`);
-          const fallbackPromises = createdInstances.map(async ({ ref, data }) => {
-            try {
-              await ref.set(data);
-              Logger.info(`[AggService] Fallback direct creation success for ${ref.id}`);
-              return true;
-            } catch (fallbackError) {
-              Logger.error(
-                `[AggService] Fallback direct creation failed for ${ref.id}:`,
-                fallbackError,
-              );
-              return false;
-            }
-          });
-
-          const fallbackResults = await Promise.allSettled(fallbackPromises);
-          const successCount = fallbackResults.filter(
-            r => r.status === 'fulfilled' && r.value === true,
-          ).length;
-
-          if (successCount > 0) {
-            Logger.info(
-              `[AggService] Fallback mechanism created ${successCount} out of ${createdInstances.length} requirements`,
-            );
-          } else {
-            Logger.error(
-              `[AggService] Both batch and fallback mechanisms failed to create requirements`,
-            );
-            throw new Error(
-              'Failed to create patient requirements through both batch and direct methods',
-            );
-          }
-        }
-      } 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,
-      );
-      throw error; // Re-throw to ensure the caller knows there was a problem
-    }
-  }
-
-  /**
-   * 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 relationships between a patient and clinics/practitioners.
-   * Only updates the patient profile with doctorIds and clinicIds.
-   *
-   * @param {PatientProfile} patientProfile - The patient profile to update
-   * @param {string} practitionerId - The practitioner ID
-   * @param {string} clinicId - The clinic ID
-   * @param {"create" | "cancel"} action - 'create' to add IDs, 'cancel' to potentially remove them
-   * @param {AppointmentStatus} [cancelStatus] - The appointment status if action is 'cancel'
-   * @returns {Promise<void>} A promise that resolves when the operation is complete.
-   */
-  private async managePatientClinicPractitionerLinks(
-    patientProfile: PatientProfile,
-    practitionerId: string,
-    clinicId: string,
-    action: 'create' | 'cancel',
-    cancelStatus?: AppointmentStatus,
-  ): Promise<void> {
-    Logger.info(
-      `[AggService] Managing patient-clinic-practitioner links for patient ${patientProfile.id}, action: ${action}`,
-    );
-
-    try {
-      if (action === 'create') {
-        await this.addPatientLinks(patientProfile, practitionerId, clinicId);
-      } else if (action === 'cancel') {
-        await this.removePatientLinksIfNoActiveAppointments(
-          patientProfile,
-          practitionerId,
-          clinicId,
-        );
-      }
-    } catch (error) {
-      Logger.error(
-        `[AggService] Error managing patient-clinic-practitioner links for patient ${patientProfile.id}:`,
-        error,
-      );
-    }
-  }
-
-  /**
-   * Adds practitioner and clinic IDs to the patient profile.
-   *
-   * @param {PatientProfile} patientProfile - The patient profile to update
-   * @param {string} practitionerId - The practitioner ID to add
-   * @param {string} clinicId - The clinic ID to add
-   * @returns {Promise<void>} A promise that resolves when the operation is complete.
-   */
-  private async addPatientLinks(
-    patientProfile: PatientProfile,
-    practitionerId: string,
-    clinicId: string,
-  ): Promise<void> {
-    try {
-      // Check if the IDs already exist in the arrays
-      const hasDoctor = patientProfile.doctorIds?.includes(practitionerId) || false;
-      const hasClinic = patientProfile.clinicIds?.includes(clinicId) || false;
-
-      // Only update if necessary
-      if (!hasDoctor || !hasClinic) {
-        const patientRef = this.db.collection(PATIENTS_COLLECTION).doc(patientProfile.id);
-        const updateData: Record<string, any> = {
-          updatedAt: admin.firestore.FieldValue.serverTimestamp(),
-        };
-
-        if (!hasDoctor) {
-          Logger.debug(
-            `[AggService] Adding practitioner ${practitionerId} to patient ${patientProfile.id}`,
-          );
-          updateData.doctorIds = admin.firestore.FieldValue.arrayUnion(practitionerId);
-        }
-
-        if (!hasClinic) {
-          Logger.debug(`[AggService] Adding clinic ${clinicId} to patient ${patientProfile.id}`);
-          updateData.clinicIds = admin.firestore.FieldValue.arrayUnion(clinicId);
-        }
-
-        await patientRef.update(updateData);
-        Logger.info(
-          `[AggService] Successfully updated patient ${patientProfile.id} with new links.`,
-        );
-      } else {
-        Logger.info(
-          `[AggService] Patient ${patientProfile.id} already has links to both practitioner ${practitionerId} and clinic ${clinicId}.`,
-        );
-      }
-    } catch (error) {
-      Logger.error(
-        `[AggService] Error updating patient ${patientProfile.id} with new links:`,
-        error,
-      );
-      throw error;
-    }
-  }
-
-  /**
-   * Removes practitioner and clinic IDs from the patient profile if there are no more active appointments.
-   *
-   * @param {PatientProfile} patientProfile - The patient profile to update
-   * @param {string} practitionerId - The practitioner ID to remove
-   * @param {string} clinicId - The clinic ID to remove
-   * @returns {Promise<void>} A promise that resolves when the operation is complete.
-   */
-  private async removePatientLinksIfNoActiveAppointments(
-    patientProfile: PatientProfile,
-    practitionerId: string,
-    clinicId: string,
-  ): Promise<void> {
-    try {
-      // Check for active appointments with this practitioner and clinic
-      const activePractitionerAppointments = await this.checkActiveAppointments(
-        patientProfile.id,
-        'practitionerId',
-        practitionerId,
-      );
-
-      const activeClinicAppointments = await this.checkActiveAppointments(
-        patientProfile.id,
-        'clinicBranchId',
-        clinicId,
-      );
-
-      Logger.info(
-        `[AggService] Active appointment count for patient ${patientProfile.id}: With practitioner ${practitionerId}: ${activePractitionerAppointments}, With clinic ${clinicId}: ${activeClinicAppointments}`,
-      );
-
-      // Only update if there are no active appointments
-      const patientRef = this.db.collection(PATIENTS_COLLECTION).doc(patientProfile.id);
-      const updateData: Record<string, any> = {};
-      let updateNeeded = false;
-
-      if (
-        activePractitionerAppointments === 0 &&
-        patientProfile.doctorIds?.includes(practitionerId)
-      ) {
-        Logger.debug(
-          `[AggService] Removing practitioner ${practitionerId} from patient ${patientProfile.id}`,
-        );
-        updateData.doctorIds = admin.firestore.FieldValue.arrayRemove(practitionerId);
-        updateNeeded = true;
-      }
-
-      if (activeClinicAppointments === 0 && patientProfile.clinicIds?.includes(clinicId)) {
-        Logger.debug(`[AggService] Removing clinic ${clinicId} from patient ${patientProfile.id}`);
-        updateData.clinicIds = admin.firestore.FieldValue.arrayRemove(clinicId);
-        updateNeeded = true;
-      }
-
-      if (updateNeeded) {
-        updateData.updatedAt = admin.firestore.FieldValue.serverTimestamp();
-        await patientRef.update(updateData);
-        Logger.info(`[AggService] Successfully removed links from patient ${patientProfile.id}`);
-      } else {
-        Logger.info(`[AggService] No links need to be removed from patient ${patientProfile.id}`);
-      }
-    } catch (error) {
-      Logger.error(`[AggService] Error removing links from patient profile:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Checks if there are active appointments between a patient and another entity (practitioner or clinic).
-   *
-   * @param {string} patientId - The patient ID.
-   * @param {"practitionerId" | "clinicBranchId"} entityField - The field to check for the entity ID.
-   * @param {string} entityId - The entity ID (practitioner or clinic).
-   * @returns {Promise<number>} The number of active appointments found.
-   */
-  private async checkActiveAppointments(
-    patientId: string,
-    entityField: 'practitionerId' | 'clinicBranchId',
-    entityId: string,
-  ): Promise<number> {
-    try {
-      // Define all cancelled/inactive appointment statuses
-      const inactiveStatuses = [
-        AppointmentStatus.CANCELED_CLINIC,
-        AppointmentStatus.CANCELED_PATIENT,
-        AppointmentStatus.CANCELED_PATIENT_RESCHEDULED,
-        AppointmentStatus.NO_SHOW,
-      ];
-
-      const snapshot = await this.db
-        .collection('appointments')
-        .where('patientId', '==', patientId)
-        .where(entityField, '==', entityId)
-        .where('status', 'not-in', inactiveStatuses)
-        .get();
-
-      return snapshot.size;
-    } catch (error) {
-      Logger.error(`[AggService] Error checking active appointments:`, error);
-      throw 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;
-    }
-  }
-
-  /**
-   * Checks if zone photos have changed between two appointment states
-   * @param before - The appointment state before update
-   * @param after - The appointment state after update
-   * @returns True if zone photos have changed, false otherwise
-   */
-  private hasZonePhotosChanged(before: Appointment, after: Appointment): boolean {
-    const beforePhotos = before.metadata?.zonePhotos;
-    const afterPhotos = after.metadata?.zonePhotos;
-
-    // If both are null/undefined, no change
-    if (!beforePhotos && !afterPhotos) {
-      return false;
-    }
-
-    // If one is null and the other isn't, there's a change
-    if (!beforePhotos || !afterPhotos) {
-      return true;
-    }
-
-    // Compare the number of zones
-    const beforeZones = Object.keys(beforePhotos);
-    const afterZones = Object.keys(afterPhotos);
-
-    if (beforeZones.length !== afterZones.length) {
-      return true;
-    }
-
-    // Compare each zone's photos
-    for (const zoneId of afterZones) {
-      const beforeZonePhotos = beforePhotos[zoneId];
-      const afterZonePhotos = afterPhotos[zoneId];
-
-      if (!beforeZonePhotos && !afterZonePhotos) {
-        continue;
-      }
-
-      if (!beforeZonePhotos || !afterZonePhotos) {
-        return true;
-      }
-
-      // Compare before and after photos arrays
-      // If array lengths differ or any entry differs, consider it changed
-      if (beforeZonePhotos.length !== afterZonePhotos.length) {
-        return true;
-      }
-      
-      // Compare each entry in the arrays
-      for (let i = 0; i < beforeZonePhotos.length; i++) {
-        const beforeEntry = beforeZonePhotos[i];
-        const afterEntry = afterZonePhotos[i];
-        if (
-          beforeEntry.before !== afterEntry.before ||
-          beforeEntry.after !== afterEntry.after ||
-          beforeEntry.beforeNote !== afterEntry.beforeNote ||
-          beforeEntry.afterNote !== afterEntry.afterNote
-        ) {
-          return true;
-        }
-      }
-    }
-
-    return false;
-  }
-
-  /**
-   * Handles zone photos update notifications and logging
-   * @param before - The appointment state before update
-   * @param after - The appointment state after update
-   */
-  private async handleZonePhotosUpdate(before: Appointment, after: Appointment): Promise<void> {
-    try {
-      Logger.info(`[AggService] Processing zone photos update for appointment ${after.id}`);
-
-      const beforePhotos = before.metadata?.zonePhotos || {};
-      const afterPhotos = after.metadata?.zonePhotos || {};
-
-      // Find zones with new or updated photos
-      const updatedZones: string[] = [];
-      const newPhotoTypes: { zoneId: string; photoType: 'before' | 'after' }[] = [];
-
-      for (const zoneId of Object.keys(afterPhotos)) {
-        const beforeZonePhotos = beforePhotos[zoneId] || [];
-        const afterZonePhotos = afterPhotos[zoneId] || [];
-
-        if (beforeZonePhotos.length === 0 && afterZonePhotos.length > 0) {
-          // New zone with photos
-          updatedZones.push(zoneId);
-          afterZonePhotos.forEach(entry => {
-            if (entry.before) {
-              newPhotoTypes.push({ zoneId, photoType: 'before' });
-            }
-            if (entry.after) {
-              newPhotoTypes.push({ zoneId, photoType: 'after' });
-            }
-          });
-        } else if (afterZonePhotos.length > beforeZonePhotos.length) {
-          // New photos added to existing zone
-          updatedZones.push(zoneId);
-          const newEntries = afterZonePhotos.slice(beforeZonePhotos.length);
-          newEntries.forEach(entry => {
-            if (entry.before) {
-              newPhotoTypes.push({ zoneId, photoType: 'before' });
-            }
-            if (entry.after) {
-              newPhotoTypes.push({ zoneId, photoType: 'after' });
-            }
-          });
-        } else {
-          // Check for updated photos in existing entries
-          for (let i = 0; i < afterZonePhotos.length; i++) {
-            const beforeEntry = beforeZonePhotos[i];
-            const afterEntry = afterZonePhotos[i];
-            
-            if (beforeEntry && afterEntry) {
-              if (beforeEntry.before !== afterEntry.before && afterEntry.before) {
-                updatedZones.push(zoneId);
-                newPhotoTypes.push({ zoneId, photoType: 'before' });
-              }
-              if (beforeEntry.after !== afterEntry.after && afterEntry.after) {
-                updatedZones.push(zoneId);
-                newPhotoTypes.push({ zoneId, photoType: 'after' });
-              }
-            }
-          }
-        }
-      }
-
-      if (updatedZones.length > 0) {
-        Logger.info(
-          `[AggService] Zone photos updated for appointment ${after.id}: ${updatedZones.join(
-            ', ',
-          )}`,
-        );
-
-        // Log specific photo types that were added
-        for (const { zoneId, photoType } of newPhotoTypes) {
-          Logger.info(
-            `[AggService] New ${photoType} photo added for zone ${zoneId} in appointment ${after.id}`,
-          );
-        }
-
-        // TODO: Add notifications to practitioners/clinic admins about photo updates
-        // TODO: Add audit logging for photo uploads
-        // TODO: Trigger any business logic related to photo completion (e.g., appointment progress tracking)
-      }
-
-      // Check if all required photos are now complete
-      const selectedZones = after.metadata?.selectedZones || [];
-      if (selectedZones.length > 0) {
-        const completedZones = selectedZones.filter(zoneId => {
-          const zonePhotos = afterPhotos[zoneId];
-          return zonePhotos && zonePhotos.length > 0 && zonePhotos.some(entry => entry.before || entry.after);
-        });
-
-        const completionPercentage = (completedZones.length / selectedZones.length) * 100;
-        Logger.info(
-          `[AggService] Photo completion for appointment ${
-            after.id
-          }: ${completionPercentage.toFixed(1)}% (${completedZones.length}/${
-            selectedZones.length
-          } zones)`,
-        );
-
-        // TODO: Trigger notifications when all photos are complete
-        if (completionPercentage === 100) {
-          Logger.info(`[AggService] All zone photos completed for appointment ${after.id}`);
-          // TODO: Send notification to relevant parties
-        }
-      }
-    } catch (error) {
-      Logger.error(
-        `[AggService] Error handling zone photos update for appointment ${after.id}:`,
-        error,
-      );
-      // Don't throw - this is a side effect and shouldn't break the main update flow
-    }
-  }
-}
+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 { Procedure, PROCEDURES_COLLECTION } from '../../../types/procedure';
+import { RequirementSourceProcedure } from '../../../types/patient/patient-requirements';
+// 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';
+import { CalendarEventStatus } from '../../../types/calendar';
+
+// Mailgun client will be injected via constructor
+
+/**
+ * Type for requirement with source procedure tracking
+ */
+type RequirementWithSource = {
+  requirement: RequirementTemplate;
+  sourceProcedures: RequirementSourceProcedure[];
+};
+
+/**
+ * @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. 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
+        ]);
+
+      // 2. Manage Patient-Clinic-Practitioner Links (moved from beginning to here)
+      // Now we can pass the already fetched patient profile
+      if (patientProfile) {
+        await this.managePatientClinicPractitionerLinks(
+          patientProfile,
+          appointment.practitionerId,
+          appointment.clinicBranchId,
+          'create',
+        );
+      }
+
+      // 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 zonePhotosChanged = this.hasZonePhotosChanged(before, after);
+      // 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);
+
+          // Update calendar events to CONFIRMED status
+          await this.calendarAdminService.updateAppointmentCalendarEventsStatus(
+            after,
+            CalendarEventStatus.CONFIRMED,
+          );
+
+          // 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,
+            );
+          }
+        }
+        // --- RESCHEDULED_BY_CLINIC -> CONFIRMED (Reschedule Acceptance) ---
+        else if (
+          before.status === AppointmentStatus.RESCHEDULED_BY_CLINIC &&
+          after.status === AppointmentStatus.CONFIRMED
+        ) {
+          Logger.info(`[AggService] Appt ${after.id} RESCHEDULED_BY_CLINIC -> CONFIRMED.`);
+
+          // Update existing requirements as superseded and create new ones
+          await this.updateRelatedPatientRequirementInstances(
+            before,
+            PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE,
+          );
+          await this.createPreAppointmentRequirementInstances(after);
+
+          // Update calendar events to CONFIRMED status and update times
+          await this.calendarAdminService.updateAppointmentCalendarEventsStatus(
+            after,
+            CalendarEventStatus.CONFIRMED,
+          );
+
+          // Send confirmation notifications (similar to PENDING -> CONFIRMED)
+          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);
+          }
+
+          if (patientProfile?.expoTokens && patientProfile.expoTokens.length > 0) {
+            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,
+            );
+          }
+        }
+        // --- 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,
+          );
+
+          // Update patient-clinic-practitioner links if patient profile exists
+          if (patientProfile) {
+            await this.managePatientClinicPractitionerLinks(
+              patientProfile,
+              after.practitionerId,
+              after.clinicBranchId,
+              'cancel',
+              after.status,
+            );
+          }
+
+          const calendarStatus = (status: AppointmentStatus) => {
+            switch (status) {
+              case AppointmentStatus.NO_SHOW:
+                return CalendarEventStatus.NO_SHOW;
+              case AppointmentStatus.CANCELED_CLINIC:
+                return CalendarEventStatus.REJECTED;
+              case AppointmentStatus.CANCELED_PATIENT:
+                return CalendarEventStatus.CANCELED;
+              case AppointmentStatus.CANCELED_PATIENT_RESCHEDULED:
+                return CalendarEventStatus.REJECTED;
+              default:
+                return CalendarEventStatus.CANCELED;
+            }
+          };
+
+          await this.calendarAdminService.updateAppointmentCalendarEventsStatus(
+            after,
+            calendarStatus(after.status),
+          );
+
+          // 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);
+
+          // Update calendar events to COMPLETED status
+          await this.calendarAdminService.updateAppointmentCalendarEventsStatus(
+            after,
+            CalendarEventStatus.COMPLETED,
+          );
+
+          // 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,
+          );
+
+          // First update the calendar event times with new proposed times
+          await this.calendarAdminService.updateAppointmentCalendarEventsTime(after, {
+            start: after.appointmentStartTime,
+            end: after.appointmentEndTime,
+          });
+
+          // Then update calendar events to PENDING status (waiting for patient confirmation)
+          await this.calendarAdminService.updateAppointmentCalendarEventsStatus(
+            after,
+            CalendarEventStatus.PENDING,
+          );
+
+          // 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.`);
+
+        // If confirmed appointment has time change, we need to update requirements
+        if (after.status === AppointmentStatus.CONFIRMED) {
+          // Update existing requirements as superseded and create new ones
+          await this.updateRelatedPatientRequirementInstances(
+            before,
+            PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE,
+          );
+          await this.createPreAppointmentRequirementInstances(after);
+
+          // Update calendar event times with new times
+          await this.calendarAdminService.updateAppointmentCalendarEventsTime(after, {
+            start: after.appointmentStartTime,
+            end: after.appointmentEndTime,
+          });
+        } else {
+          Logger.warn(
+            `[AggService] Independent time change detected for ${after.id} with status ${after.status}. Review implications for requirements and calendar.`,
+          );
+        }
+      }
+
+      // TODO: Handle Payment Status Change
+      // const paymentStatusChanged = before.paymentStatus !== after.paymentStatus;
+      // if (paymentStatusChanged && after.paymentStatus === PaymentStatus.PAID) { ... }
+
+      // Handle Zone Photos Changes
+      if (zonePhotosChanged) {
+        Logger.info(`[AggService] Zone photos changed for appointment ${after.id}`);
+        await this.handleZonePhotosUpdate(before, after);
+      }
+
+      // 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,
+    );
+
+    // Fetch patient profile first
+    const patientProfile = await this.fetchPatientProfile(deletedAppointment.patientId);
+
+    // Update relationship links if patient profile exists
+    if (patientProfile) {
+      await this.managePatientClinicPractitionerLinks(
+        patientProfile,
+        deletedAppointment.practitionerId,
+        deletedAppointment.clinicBranchId,
+        'cancel',
+      );
+    }
+
+    // Delete all associated calendar events
+    await this.calendarAdminService.deleteAppointmentCalendarEvents(deletedAppointment);
+
+    // 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;
+      // Store created instances for fallback direct creation if needed
+      let createdInstances = [];
+
+      // Log more details about the pre-requirements
+      Logger.info(
+        `[AggService] Found ${
+          appointment.preProcedureRequirements.length
+        } pre-requirements to process: ${JSON.stringify(
+          appointment.preProcedureRequirements.map(r => ({
+            id: r.id,
+            name: r.name,
+            type: r.type,
+            isActive: r.isActive,
+            hasTimeframe: !!r.timeframe,
+            notifyAtLength: r.timeframe?.notifyAt?.length || 0,
+          })),
+        )}`,
+      );
+
+      for (const template of appointment.preProcedureRequirements) {
+        if (!template) {
+          Logger.warn(
+            `[AggService] Found null/undefined template in preProcedureRequirements array`,
+          );
+          continue;
+        }
+
+        // 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;
+        }
+
+        if (
+          !template.timeframe ||
+          !template.timeframe.notifyAt ||
+          template.timeframe.notifyAt.length === 0
+        ) {
+          Logger.warn(
+            `[AggService] Template ${template.id} (${template.name}) has no timeframe.notifyAt values. Creating with empty instructions.`,
+          );
+        }
+
+        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
+
+        // Log the path for debugging
+        Logger.debug(`[AggService] Created doc reference: ${newInstanceRef.path}`);
+
+        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.Timestamp.now() as any, // Use current server timestamp
+          };
+          return instructionObject;
+        });
+
+        const newInstanceData: PatientRequirementInstance = {
+          id: newInstanceRef.id, // Add the ID to the document data
+          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,
+        };
+
+        // Log the data being set
+        Logger.debug(
+          `[AggService] Setting data for requirement: ${JSON.stringify({
+            id: newInstanceRef.id,
+            patientId: newInstanceData.patientId,
+            appointmentId: newInstanceData.appointmentId,
+            requirementName: newInstanceData.requirementName,
+            instructionsCount: newInstanceData.instructions.length,
+          })}`,
+        );
+
+        batch.set(newInstanceRef, newInstanceData);
+        // Store for potential fallback
+        createdInstances.push({
+          ref: newInstanceRef,
+          data: newInstanceData,
+        });
+
+        instancesCreatedCount++;
+        Logger.debug(
+          `[AggService] Added PatientRequirementInstance ${newInstanceRef.id} to batch for template ${template.id}.`,
+        );
+      }
+
+      if (instancesCreatedCount > 0) {
+        try {
+          await batch.commit();
+          Logger.info(
+            `[AggService] Successfully created ${instancesCreatedCount} PRE_APPOINTMENT requirement instances for appointment ${appointment.id}.`,
+          );
+
+          // Verify creation success
+          try {
+            const verifySnapshot = await this.db
+              .collection(PATIENTS_COLLECTION)
+              .doc(appointment.patientId)
+              .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
+              .where('appointmentId', '==', appointment.id)
+              .get();
+
+            if (verifySnapshot.empty) {
+              Logger.warn(
+                `[AggService] Batch commit reported success but documents not found! Attempting direct creation as fallback...`,
+              );
+
+              // Fallback to direct creation if batch worked but docs aren't there
+              const fallbackPromises = createdInstances.map(async ({ ref, data }) => {
+                try {
+                  await ref.set(data);
+                  Logger.info(`[AggService] Fallback direct creation success for ${ref.id}`);
+                  return true;
+                } catch (fallbackError) {
+                  Logger.error(
+                    `[AggService] Fallback direct creation failed for ${ref.id}:`,
+                    fallbackError,
+                  );
+                  return false;
+                }
+              });
+
+              const fallbackResults = await Promise.allSettled(fallbackPromises);
+              const successCount = fallbackResults.filter(
+                r => r.status === 'fulfilled' && r.value === true,
+              ).length;
+
+              if (successCount > 0) {
+                Logger.info(
+                  `[AggService] Fallback mechanism created ${successCount} out of ${createdInstances.length} requirements`,
+                );
+              } else {
+                Logger.error(
+                  `[AggService] Both batch and fallback mechanisms failed to create requirements`,
+                );
+                throw new Error(
+                  'Failed to create patient requirements through both batch and direct methods',
+                );
+              }
+            } else {
+              Logger.info(
+                `[AggService] Verification confirmed ${verifySnapshot.size} requirement documents created`,
+              );
+            }
+          } catch (verifyError) {
+            Logger.error(
+              `[AggService] Error during verification of created requirements:`,
+              verifyError,
+            );
+          }
+        } catch (commitError) {
+          Logger.error(
+            `[AggService] Error committing batch for PRE_APPOINTMENT requirement instances for appointment ${appointment.id}:`,
+            commitError,
+          );
+
+          // Try direct creation as fallback
+          Logger.info(`[AggService] Attempting direct creation as fallback...`);
+          const fallbackPromises = createdInstances.map(async ({ ref, data }) => {
+            try {
+              await ref.set(data);
+              Logger.info(`[AggService] Fallback direct creation success for ${ref.id}`);
+              return true;
+            } catch (fallbackError) {
+              Logger.error(
+                `[AggService] Fallback direct creation failed for ${ref.id}:`,
+                fallbackError,
+              );
+              return false;
+            }
+          });
+
+          const fallbackResults = await Promise.allSettled(fallbackPromises);
+          const successCount = fallbackResults.filter(
+            r => r.status === 'fulfilled' && r.value === true,
+          ).length;
+
+          if (successCount > 0) {
+            Logger.info(
+              `[AggService] Fallback mechanism created ${successCount} out of ${createdInstances.length} requirements`,
+            );
+          } else {
+            Logger.error(
+              `[AggService] Both batch and fallback mechanisms failed to create requirements`,
+            );
+            throw new Error(
+              'Failed to create patient requirements through both batch and direct methods',
+            );
+          }
+        }
+      } 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,
+      );
+      throw error; // Re-throw to ensure the caller knows there was a problem
+    }
+  }
+
+  /**
+   * Fetches post-requirements from a procedure document
+   * @param procedureId - The procedure ID to fetch requirements from
+   * @returns Promise resolving to array of post-requirements with source procedure info
+   */
+  private async fetchPostRequirementsFromProcedure(
+    procedureId: string,
+  ): Promise<RequirementWithSource[]> {
+    try {
+      const procedureDoc = await this.db.collection(PROCEDURES_COLLECTION).doc(procedureId).get();
+      if (!procedureDoc.exists) {
+        Logger.warn(`[AggService] Procedure ${procedureId} not found when fetching requirements`);
+        return [];
+      }
+
+      const procedure = procedureDoc.data() as Procedure;
+      const postRequirements = procedure.postRequirements || [];
+
+      if (postRequirements.length === 0) {
+        return [];
+      }
+
+      return postRequirements.map(req => ({
+        requirement: req,
+        sourceProcedures: [
+          {
+            procedureId: procedure.id,
+            procedureName: procedure.name,
+          },
+        ],
+      }));
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error fetching post-requirements from procedure ${procedureId}:`,
+        error,
+      );
+      return [];
+    }
+  }
+
+  /**
+   * Collects all post-requirements from primary and extended procedures
+   * @param appointment - The appointment to collect requirements for
+   * @returns Promise resolving to array of requirements with source procedures
+   */
+  private async collectAllPostRequirements(
+    appointment: Appointment,
+  ): Promise<RequirementWithSource[]> {
+    const allRequirements: RequirementWithSource[] = [];
+
+    // Fetch from primary procedure
+    if (appointment.procedureId) {
+      const primaryRequirements = await this.fetchPostRequirementsFromProcedure(
+        appointment.procedureId,
+      );
+      allRequirements.push(...primaryRequirements);
+    }
+
+    // Fetch from extended procedures
+    const extendedProcedures = appointment.metadata?.extendedProcedures || [];
+    if (extendedProcedures.length > 0) {
+      Logger.info(
+        `[AggService] Fetching post-requirements from ${extendedProcedures.length} extended procedures`,
+      );
+
+      const extendedRequirementsPromises = extendedProcedures.map(extProc =>
+        this.fetchPostRequirementsFromProcedure(extProc.procedureId),
+      );
+
+      const extendedRequirementsArrays = await Promise.all(extendedRequirementsPromises);
+      extendedRequirementsArrays.forEach(reqs => {
+        allRequirements.push(...reqs);
+      });
+    }
+
+    return allRequirements;
+  }
+
+  /**
+   * Generates a unique key for a requirement based on ID and timeframe
+   * @param requirement - The requirement to generate a key for
+   * @returns Unique key string
+   */
+  private getRequirementKey(requirement: RequirementTemplate): string {
+    const timeframeSig = JSON.stringify({
+      duration: requirement.timeframe?.duration || 0,
+      unit: requirement.timeframe?.unit || '',
+      notifyAt: (requirement.timeframe?.notifyAt || []).slice().sort((a, b) => a - b),
+    });
+    return `${requirement.id}:${timeframeSig}`;
+  }
+
+  /**
+   * Deduplicates requirements based on requirement ID and timeframe
+   * Merges source procedures when requirements match
+   * @param requirements - Array of requirements with sources
+   * @returns Deduplicated array of requirements
+   */
+  private deduplicateRequirements(
+    requirements: RequirementWithSource[],
+  ): RequirementWithSource[] {
+    const requirementMap = new Map<string, RequirementWithSource>();
+
+    for (const reqWithSource of requirements) {
+      const key = this.getRequirementKey(reqWithSource.requirement);
+
+      if (requirementMap.has(key)) {
+        // Merge source procedures
+        const existing = requirementMap.get(key)!;
+        const existingProcedureIds = new Set(
+          existing.sourceProcedures.map(sp => sp.procedureId),
+        );
+
+        // Add new source procedures that don't already exist
+        reqWithSource.sourceProcedures.forEach(sp => {
+          if (!existingProcedureIds.has(sp.procedureId)) {
+            existing.sourceProcedures.push(sp);
+          }
+        });
+      } else {
+        // New requirement, add it
+        requirementMap.set(key, {
+          requirement: reqWithSource.requirement,
+          sourceProcedures: [...reqWithSource.sourceProcedures],
+        });
+      }
+    }
+
+    return Array.from(requirementMap.values());
+  }
+
+  /**
+   * Creates POST_APPOINTMENT PatientRequirementInstance documents for a given appointment.
+   * Fetches requirements from primary and extended procedures, deduplicates them,
+   * and creates requirement instances with source procedure tracking.
+   *
+   * @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;
+    }
+
+    try {
+      // Collect all post-requirements from primary and extended procedures
+      const allRequirements = await this.collectAllPostRequirements(appointment);
+
+      if (allRequirements.length === 0) {
+        Logger.info(
+          `[AggService] No post-requirements found from any procedures for appointment ${appointment.id}. Nothing to create.`,
+        );
+        return;
+      }
+
+      // Deduplicate requirements based on ID + timeframe
+      const deduplicatedRequirements = this.deduplicateRequirements(allRequirements);
+
+      Logger.info(
+        `[AggService] Found ${allRequirements.length} total post-requirements, ${deduplicatedRequirements.length} after deduplication`,
+      );
+
+      // Log details about the deduplicated requirements
+      Logger.info(
+        `[AggService] Processing deduplicated post-requirements: ${JSON.stringify(
+          deduplicatedRequirements.map(r => ({
+            id: r.requirement.id,
+            name: r.requirement.name,
+            type: r.requirement.type,
+            isActive: r.requirement.isActive,
+            hasTimeframe: !!r.requirement.timeframe,
+            notifyAtLength: r.requirement.timeframe?.notifyAt?.length || 0,
+            sourceProcedures: r.sourceProcedures.map(sp => ({
+              procedureId: sp.procedureId,
+              procedureName: sp.procedureName,
+            })),
+          })),
+        )}`,
+      );
+
+      const batch = this.db.batch();
+      let instancesCreatedCount = 0;
+      // Store created instances for fallback direct creation if needed
+      let createdInstances = [];
+
+      for (const reqWithSource of deduplicatedRequirements) {
+        const template = reqWithSource.requirement;
+        if (!template) {
+          Logger.warn(
+            `[AggService] Found null/undefined template in postProcedureRequirements array`,
+          );
+          continue;
+        }
+
+        // Ensure it's an active, POST-type requirement
+        if (template.type !== RequirementType.POST || !template.isActive) {
+          Logger.debug(
+            `[AggService] Skipping template ${template.id} (${template.name}): not an active POST requirement.`,
+          );
+          continue;
+        }
+
+        if (
+          !template.timeframe ||
+          !template.timeframe.notifyAt ||
+          template.timeframe.notifyAt.length === 0
+        ) {
+          Logger.warn(
+            `[AggService] Template ${template.id} (${template.name}) has no timeframe.notifyAt values. Creating with empty instructions.`,
+          );
+        }
+
+        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
+
+        // Log the path for debugging
+        Logger.debug(`[AggService] Created doc reference: ${newInstanceRef.path}`);
+
+        const instructions: PatientRequirementInstruction[] = (
+          template.timeframe?.notifyAt || []
+        ).map(notifyAtValue => {
+          let dueTime: any = appointment.appointmentEndTime;
+          if (template.timeframe && typeof notifyAtValue === 'number') {
+            const dueDateTime = new Date(appointment.appointmentEndTime.toMillis());
+            // For POST requirements, notifyAtValue 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
+
+          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,
+            status: PatientInstructionStatus.PENDING_NOTIFICATION,
+            originalNotifyAtValue: notifyAtValue,
+            originalTimeframeUnit: template.timeframe.unit,
+            updatedAt: admin.firestore.Timestamp.now() as any,
+            notificationId: undefined,
+            actionTakenAt: undefined,
+          };
+          return instructionObject;
+        });
+
+        const newInstanceData: PatientRequirementInstance = {
+          id: newInstanceRef.id,
+          patientId: appointment.patientId,
+          appointmentId: appointment.id,
+          originalRequirementId: template.id,
+          requirementName: template.name,
+          requirementDescription: template.description,
+          requirementType: template.type,
+          requirementImportance: template.importance,
+          overallStatus: PatientRequirementOverallStatus.ACTIVE,
+          instructions: instructions,
+          sourceProcedures: reqWithSource.sourceProcedures, // Track which procedures this requirement comes from
+          createdAt: admin.firestore.FieldValue.serverTimestamp() as any,
+          updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+        };
+
+        // Log the data being set
+        Logger.debug(
+          `[AggService] Setting data for requirement: ${JSON.stringify({
+            id: newInstanceRef.id,
+            patientId: newInstanceData.patientId,
+            appointmentId: newInstanceData.appointmentId,
+            requirementName: newInstanceData.requirementName,
+            instructionsCount: newInstanceData.instructions.length,
+            sourceProcedures: newInstanceData.sourceProcedures?.map(sp => ({
+              procedureId: sp.procedureId,
+              procedureName: sp.procedureName,
+            })) || [],
+          })}`,
+        );
+
+        batch.set(newInstanceRef, newInstanceData);
+        // Store for potential fallback
+        createdInstances.push({
+          ref: newInstanceRef,
+          data: newInstanceData,
+        });
+
+        instancesCreatedCount++;
+        Logger.debug(
+          `[AggService] Added PatientRequirementInstance ${newInstanceRef.id} to batch for template ${template.id}.`,
+        );
+      }
+
+      if (instancesCreatedCount > 0) {
+        try {
+          await batch.commit();
+          Logger.info(
+            `[AggService] Successfully created ${instancesCreatedCount} POST_APPOINTMENT requirement instances for appointment ${appointment.id}.`,
+          );
+
+          // Verify creation success
+          try {
+            const verifySnapshot = await this.db
+              .collection(PATIENTS_COLLECTION)
+              .doc(appointment.patientId)
+              .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
+              .where('appointmentId', '==', appointment.id)
+              .get();
+
+            if (verifySnapshot.empty) {
+              Logger.warn(
+                `[AggService] Batch commit reported success but documents not found! Attempting direct creation as fallback...`,
+              );
+
+              // Fallback to direct creation if batch worked but docs aren't there
+              const fallbackPromises = createdInstances.map(async ({ ref, data }) => {
+                try {
+                  await ref.set(data);
+                  Logger.info(`[AggService] Fallback direct creation success for ${ref.id}`);
+                  return true;
+                } catch (fallbackError) {
+                  Logger.error(
+                    `[AggService] Fallback direct creation failed for ${ref.id}:`,
+                    fallbackError,
+                  );
+                  return false;
+                }
+              });
+
+              const fallbackResults = await Promise.allSettled(fallbackPromises);
+              const successCount = fallbackResults.filter(
+                r => r.status === 'fulfilled' && r.value === true,
+              ).length;
+
+              if (successCount > 0) {
+                Logger.info(
+                  `[AggService] Fallback mechanism created ${successCount} out of ${createdInstances.length} requirements`,
+                );
+              } else {
+                Logger.error(
+                  `[AggService] Both batch and fallback mechanisms failed to create requirements`,
+                );
+                throw new Error(
+                  'Failed to create patient requirements through both batch and direct methods',
+                );
+              }
+            } else {
+              Logger.info(
+                `[AggService] Verification confirmed ${verifySnapshot.size} requirement documents created`,
+              );
+            }
+          } catch (verifyError) {
+            Logger.error(
+              `[AggService] Error during verification of created requirements:`,
+              verifyError,
+            );
+          }
+        } catch (commitError) {
+          Logger.error(
+            `[AggService] Error committing batch for POST_APPOINTMENT requirement instances for appointment ${appointment.id}:`,
+            commitError,
+          );
+
+          // Try direct creation as fallback
+          Logger.info(`[AggService] Attempting direct creation as fallback...`);
+          const fallbackPromises = createdInstances.map(async ({ ref, data }) => {
+            try {
+              await ref.set(data);
+              Logger.info(`[AggService] Fallback direct creation success for ${ref.id}`);
+              return true;
+            } catch (fallbackError) {
+              Logger.error(
+                `[AggService] Fallback direct creation failed for ${ref.id}:`,
+                fallbackError,
+              );
+              return false;
+            }
+          });
+
+          const fallbackResults = await Promise.allSettled(fallbackPromises);
+          const successCount = fallbackResults.filter(
+            r => r.status === 'fulfilled' && r.value === true,
+          ).length;
+
+          if (successCount > 0) {
+            Logger.info(
+              `[AggService] Fallback mechanism created ${successCount} out of ${createdInstances.length} requirements`,
+            );
+          } else {
+            Logger.error(
+              `[AggService] Both batch and fallback mechanisms failed to create requirements`,
+            );
+            throw new Error(
+              'Failed to create patient requirements through both batch and direct methods',
+            );
+          }
+        }
+      } 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,
+      );
+      throw error; // Re-throw to ensure the caller knows there was a problem
+    }
+  }
+
+  /**
+   * 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 relationships between a patient and clinics/practitioners.
+   * Only updates the patient profile with doctorIds and clinicIds.
+   *
+   * @param {PatientProfile} patientProfile - The patient profile to update
+   * @param {string} practitionerId - The practitioner ID
+   * @param {string} clinicId - The clinic ID
+   * @param {"create" | "cancel"} action - 'create' to add IDs, 'cancel' to potentially remove them
+   * @param {AppointmentStatus} [cancelStatus] - The appointment status if action is 'cancel'
+   * @returns {Promise<void>} A promise that resolves when the operation is complete.
+   */
+  private async managePatientClinicPractitionerLinks(
+    patientProfile: PatientProfile,
+    practitionerId: string,
+    clinicId: string,
+    action: 'create' | 'cancel',
+    cancelStatus?: AppointmentStatus,
+  ): Promise<void> {
+    Logger.info(
+      `[AggService] Managing patient-clinic-practitioner links for patient ${patientProfile.id}, action: ${action}`,
+    );
+
+    try {
+      if (action === 'create') {
+        await this.addPatientLinks(patientProfile, practitionerId, clinicId);
+      } else if (action === 'cancel') {
+        await this.removePatientLinksIfNoActiveAppointments(
+          patientProfile,
+          practitionerId,
+          clinicId,
+        );
+      }
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error managing patient-clinic-practitioner links for patient ${patientProfile.id}:`,
+        error,
+      );
+    }
+  }
+
+  /**
+   * Adds practitioner and clinic IDs to the patient profile.
+   *
+   * @param {PatientProfile} patientProfile - The patient profile to update
+   * @param {string} practitionerId - The practitioner ID to add
+   * @param {string} clinicId - The clinic ID to add
+   * @returns {Promise<void>} A promise that resolves when the operation is complete.
+   */
+  private async addPatientLinks(
+    patientProfile: PatientProfile,
+    practitionerId: string,
+    clinicId: string,
+  ): Promise<void> {
+    try {
+      // Check if the IDs already exist in the arrays
+      const hasDoctor = patientProfile.doctorIds?.includes(practitionerId) || false;
+      const hasClinic = patientProfile.clinicIds?.includes(clinicId) || false;
+
+      // Only update if necessary
+      if (!hasDoctor || !hasClinic) {
+        const patientRef = this.db.collection(PATIENTS_COLLECTION).doc(patientProfile.id);
+        const updateData: Record<string, any> = {
+          updatedAt: admin.firestore.FieldValue.serverTimestamp(),
+        };
+
+        if (!hasDoctor) {
+          Logger.debug(
+            `[AggService] Adding practitioner ${practitionerId} to patient ${patientProfile.id}`,
+          );
+          updateData.doctorIds = admin.firestore.FieldValue.arrayUnion(practitionerId);
+        }
+
+        if (!hasClinic) {
+          Logger.debug(`[AggService] Adding clinic ${clinicId} to patient ${patientProfile.id}`);
+          updateData.clinicIds = admin.firestore.FieldValue.arrayUnion(clinicId);
+        }
+
+        await patientRef.update(updateData);
+        Logger.info(
+          `[AggService] Successfully updated patient ${patientProfile.id} with new links.`,
+        );
+      } else {
+        Logger.info(
+          `[AggService] Patient ${patientProfile.id} already has links to both practitioner ${practitionerId} and clinic ${clinicId}.`,
+        );
+      }
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error updating patient ${patientProfile.id} with new links:`,
+        error,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Removes practitioner and clinic IDs from the patient profile if there are no more active appointments.
+   *
+   * @param {PatientProfile} patientProfile - The patient profile to update
+   * @param {string} practitionerId - The practitioner ID to remove
+   * @param {string} clinicId - The clinic ID to remove
+   * @returns {Promise<void>} A promise that resolves when the operation is complete.
+   */
+  private async removePatientLinksIfNoActiveAppointments(
+    patientProfile: PatientProfile,
+    practitionerId: string,
+    clinicId: string,
+  ): Promise<void> {
+    try {
+      // Check for active appointments with this practitioner and clinic
+      const activePractitionerAppointments = await this.checkActiveAppointments(
+        patientProfile.id,
+        'practitionerId',
+        practitionerId,
+      );
+
+      const activeClinicAppointments = await this.checkActiveAppointments(
+        patientProfile.id,
+        'clinicBranchId',
+        clinicId,
+      );
+
+      Logger.info(
+        `[AggService] Active appointment count for patient ${patientProfile.id}: With practitioner ${practitionerId}: ${activePractitionerAppointments}, With clinic ${clinicId}: ${activeClinicAppointments}`,
+      );
+
+      // Only update if there are no active appointments
+      const patientRef = this.db.collection(PATIENTS_COLLECTION).doc(patientProfile.id);
+      const updateData: Record<string, any> = {};
+      let updateNeeded = false;
+
+      if (
+        activePractitionerAppointments === 0 &&
+        patientProfile.doctorIds?.includes(practitionerId)
+      ) {
+        Logger.debug(
+          `[AggService] Removing practitioner ${practitionerId} from patient ${patientProfile.id}`,
+        );
+        updateData.doctorIds = admin.firestore.FieldValue.arrayRemove(practitionerId);
+        updateNeeded = true;
+      }
+
+      if (activeClinicAppointments === 0 && patientProfile.clinicIds?.includes(clinicId)) {
+        Logger.debug(`[AggService] Removing clinic ${clinicId} from patient ${patientProfile.id}`);
+        updateData.clinicIds = admin.firestore.FieldValue.arrayRemove(clinicId);
+        updateNeeded = true;
+      }
+
+      if (updateNeeded) {
+        updateData.updatedAt = admin.firestore.FieldValue.serverTimestamp();
+        await patientRef.update(updateData);
+        Logger.info(`[AggService] Successfully removed links from patient ${patientProfile.id}`);
+      } else {
+        Logger.info(`[AggService] No links need to be removed from patient ${patientProfile.id}`);
+      }
+    } catch (error) {
+      Logger.error(`[AggService] Error removing links from patient profile:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Checks if there are active appointments between a patient and another entity (practitioner or clinic).
+   *
+   * @param {string} patientId - The patient ID.
+   * @param {"practitionerId" | "clinicBranchId"} entityField - The field to check for the entity ID.
+   * @param {string} entityId - The entity ID (practitioner or clinic).
+   * @returns {Promise<number>} The number of active appointments found.
+   */
+  private async checkActiveAppointments(
+    patientId: string,
+    entityField: 'practitionerId' | 'clinicBranchId',
+    entityId: string,
+  ): Promise<number> {
+    try {
+      // Define all cancelled/inactive appointment statuses
+      const inactiveStatuses = [
+        AppointmentStatus.CANCELED_CLINIC,
+        AppointmentStatus.CANCELED_PATIENT,
+        AppointmentStatus.CANCELED_PATIENT_RESCHEDULED,
+        AppointmentStatus.NO_SHOW,
+      ];
+
+      const snapshot = await this.db
+        .collection('appointments')
+        .where('patientId', '==', patientId)
+        .where(entityField, '==', entityId)
+        .where('status', 'not-in', inactiveStatuses)
+        .get();
+
+      return snapshot.size;
+    } catch (error) {
+      Logger.error(`[AggService] Error checking active appointments:`, error);
+      throw 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;
+    }
+  }
+
+  /**
+   * Checks if zone photos have changed between two appointment states
+   * @param before - The appointment state before update
+   * @param after - The appointment state after update
+   * @returns True if zone photos have changed, false otherwise
+   */
+  private hasZonePhotosChanged(before: Appointment, after: Appointment): boolean {
+    const beforePhotos = before.metadata?.zonePhotos;
+    const afterPhotos = after.metadata?.zonePhotos;
+
+    // If both are null/undefined, no change
+    if (!beforePhotos && !afterPhotos) {
+      return false;
+    }
+
+    // If one is null and the other isn't, there's a change
+    if (!beforePhotos || !afterPhotos) {
+      return true;
+    }
+
+    // Compare the number of zones
+    const beforeZones = Object.keys(beforePhotos);
+    const afterZones = Object.keys(afterPhotos);
+
+    if (beforeZones.length !== afterZones.length) {
+      return true;
+    }
+
+    // Compare each zone's photos
+    for (const zoneId of afterZones) {
+      const beforeZonePhotos = beforePhotos[zoneId];
+      const afterZonePhotos = afterPhotos[zoneId];
+
+      if (!beforeZonePhotos && !afterZonePhotos) {
+        continue;
+      }
+
+      if (!beforeZonePhotos || !afterZonePhotos) {
+        return true;
+      }
+
+      // Compare before and after photos arrays
+      // If array lengths differ or any entry differs, consider it changed
+      if (beforeZonePhotos.length !== afterZonePhotos.length) {
+        return true;
+      }
+      
+      // Compare each entry in the arrays
+      for (let i = 0; i < beforeZonePhotos.length; i++) {
+        const beforeEntry = beforeZonePhotos[i];
+        const afterEntry = afterZonePhotos[i];
+        if (
+          beforeEntry.before !== afterEntry.before ||
+          beforeEntry.after !== afterEntry.after ||
+          beforeEntry.beforeNote !== afterEntry.beforeNote ||
+          beforeEntry.afterNote !== afterEntry.afterNote
+        ) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Handles zone photos update notifications and logging
+   * @param before - The appointment state before update
+   * @param after - The appointment state after update
+   */
+  private async handleZonePhotosUpdate(before: Appointment, after: Appointment): Promise<void> {
+    try {
+      Logger.info(`[AggService] Processing zone photos update for appointment ${after.id}`);
+
+      const beforePhotos = before.metadata?.zonePhotos || {};
+      const afterPhotos = after.metadata?.zonePhotos || {};
+
+      // Find zones with new or updated photos
+      const updatedZones: string[] = [];
+      const newPhotoTypes: { zoneId: string; photoType: 'before' | 'after' }[] = [];
+
+      for (const zoneId of Object.keys(afterPhotos)) {
+        const beforeZonePhotos = beforePhotos[zoneId] || [];
+        const afterZonePhotos = afterPhotos[zoneId] || [];
+
+        if (beforeZonePhotos.length === 0 && afterZonePhotos.length > 0) {
+          // New zone with photos
+          updatedZones.push(zoneId);
+          afterZonePhotos.forEach(entry => {
+            if (entry.before) {
+              newPhotoTypes.push({ zoneId, photoType: 'before' });
+            }
+            if (entry.after) {
+              newPhotoTypes.push({ zoneId, photoType: 'after' });
+            }
+          });
+        } else if (afterZonePhotos.length > beforeZonePhotos.length) {
+          // New photos added to existing zone
+          updatedZones.push(zoneId);
+          const newEntries = afterZonePhotos.slice(beforeZonePhotos.length);
+          newEntries.forEach(entry => {
+            if (entry.before) {
+              newPhotoTypes.push({ zoneId, photoType: 'before' });
+            }
+            if (entry.after) {
+              newPhotoTypes.push({ zoneId, photoType: 'after' });
+            }
+          });
+        } else {
+          // Check for updated photos in existing entries
+          for (let i = 0; i < afterZonePhotos.length; i++) {
+            const beforeEntry = beforeZonePhotos[i];
+            const afterEntry = afterZonePhotos[i];
+            
+            if (beforeEntry && afterEntry) {
+              if (beforeEntry.before !== afterEntry.before && afterEntry.before) {
+                updatedZones.push(zoneId);
+                newPhotoTypes.push({ zoneId, photoType: 'before' });
+              }
+              if (beforeEntry.after !== afterEntry.after && afterEntry.after) {
+                updatedZones.push(zoneId);
+                newPhotoTypes.push({ zoneId, photoType: 'after' });
+              }
+            }
+          }
+        }
+      }
+
+      if (updatedZones.length > 0) {
+        Logger.info(
+          `[AggService] Zone photos updated for appointment ${after.id}: ${updatedZones.join(
+            ', ',
+          )}`,
+        );
+
+        // Log specific photo types that were added
+        for (const { zoneId, photoType } of newPhotoTypes) {
+          Logger.info(
+            `[AggService] New ${photoType} photo added for zone ${zoneId} in appointment ${after.id}`,
+          );
+        }
+
+        // TODO: Add notifications to practitioners/clinic admins about photo updates
+        // TODO: Add audit logging for photo uploads
+        // TODO: Trigger any business logic related to photo completion (e.g., appointment progress tracking)
+      }
+
+      // Check if all required photos are now complete
+      const selectedZones = after.metadata?.selectedZones || [];
+      if (selectedZones.length > 0) {
+        const completedZones = selectedZones.filter(zoneId => {
+          const zonePhotos = afterPhotos[zoneId];
+          return zonePhotos && zonePhotos.length > 0 && zonePhotos.some(entry => entry.before || entry.after);
+        });
+
+        const completionPercentage = (completedZones.length / selectedZones.length) * 100;
+        Logger.info(
+          `[AggService] Photo completion for appointment ${
+            after.id
+          }: ${completionPercentage.toFixed(1)}% (${completedZones.length}/${
+            selectedZones.length
+          } zones)`,
+        );
+
+        // TODO: Trigger notifications when all photos are complete
+        if (completionPercentage === 100) {
+          Logger.info(`[AggService] All zone photos completed for appointment ${after.id}`);
+          // TODO: Send notification to relevant parties
+        }
+      }
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error handling zone photos update for appointment ${after.id}:`,
+        error,
+      );
+      // Don't throw - this is a side effect and shouldn't break the main update flow
+    }
+  }
+}