@blackcode_sa/metaestetics-api 1.6.5 → 1.6.6

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

@@ -2,29 +2,43 @@ import * as admin from "firebase-admin";
 import {
   Appointment,
   AppointmentStatus,
-  APPOINTMENTS_COLLECTION,
-} from "../../../types/appointment"; // Assuming APPOINTMENTS_COLLECTION is exported here
+  // 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,
-  RequirementType as RequirementTemplateType,
+  // REQUIREMENTS_COLLECTION as REQUIREMENTS_TEMPLATES_COLLECTION, // Not used directly after refactor
+  RequirementType,
+  TimeUnit, // Added import
 } from "../../../backoffice/types/requirement.types";
-import { PATIENTS_COLLECTION } from "../../../types/patient";
+import {
+  PATIENTS_COLLECTION,
+  PatientProfile,
+  PatientSensitiveInfo,
+  PATIENT_SENSITIVE_INFO_COLLECTION,
+} from "../../../types/patient";
+import {
+  Practitioner,
+  PRACTITIONERS_COLLECTION,
+} from "../../../types/practitioner";
+import { Clinic, CLINICS_COLLECTION } from "../../../types/clinic";
+// import { UserRole } from "../../../types"; // Not directly used
 
 // Dependent Admin Services
 import { PatientRequirementsAdminService } from "../../requirements/patient-requirements.admin.service";
 import { NotificationsAdmin } from "../../notifications/notifications.admin";
-// import { CalendarAdminService } from "../../calendar/calendar.admin.service"; // Placeholder - To be created
-// import { AppointmentMailingService } from "../mailing/appointment/appointment.mailing.service"; // Placeholder - To be created
-// import { PatientAdminService } from "../patient/patient.admin.service"; // Placeholder for specific patient admin actions
-// import { PractitionerAdminService } from "../practitioner/practitioner.admin.service"; // Placeholder for specific practitioner admin actions
-// import { ClinicAdminService } from "../clinic/clinic.admin.service"; // Placeholder for specific clinic admin actions
+import { CalendarAdminService } from "../../calendar/calendar.admin.service";
+import { AppointmentMailingService } from "../../mailing/appointment/appointment.mailing.service";
+import { Logger } from "../../logger";
+import { UserRole } from "../../../types";
+
+// Mailgun client will be injected via constructor
 
 /**
  * @class AppointmentAggregationService
@@ -34,288 +48,1006 @@ import { NotificationsAdmin } from "../../notifications/notifications.admin";
  */
 export class AppointmentAggregationService {
   private db: admin.firestore.Firestore;
-  private patientRequirementsAdminService: PatientRequirementsAdminService;
+  private appointmentMailingService: AppointmentMailingService;
   private notificationsAdmin: NotificationsAdmin;
-  // private calendarAdminService: CalendarAdminService; // Placeholder
-  // private appointmentMailingService: AppointmentMailingService; // Placeholder
-  // private patientAdminService: PatientAdminService; // Placeholder
-  // private practitionerAdminService: PractitionerAdminService; // Placeholder
-  // private clinicAdminService: ClinicAdminService; // Placeholder
+  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(firestore?: admin.firestore.Firestore) {
+  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
     );
-    this.notificationsAdmin = new NotificationsAdmin(this.db);
-    // this.calendarAdminService = new CalendarAdminService(this.db); // Placeholder
-    // this.appointmentMailingService = new AppointmentMailingService(this.db /*, mailgunClient */); // Placeholder
-    // this.patientAdminService = new PatientAdminService(this.db); // Placeholder
-    // this.practitionerAdminService = new PractitionerAdminService(this.db); // Placeholder
-    // this.clinicAdminService = new ClinicAdminService(this.db); // Placeholder
+    Logger.info("[AppointmentAggregationService] Initialized.");
   }
 
   /**
-   * Handles side effects when an appointment is confirmed.
-   * - Creates PRE-appointment PatientRequirementInstances.
-   * - Triggers calendar event creation.
-   * - Triggers email/push notifications.
-   * - Manages patient-clinic-practitioner links.
-   * @param appointment - The confirmed Appointment object.
+   * 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 handleAppointmentConfirmed(appointment: Appointment): Promise<void> {
-    console.log(
-      `[AppointmentAggregationService] Handling confirmed appointment: ${appointment.id}`
+  async handleAppointmentCreate(appointment: Appointment): Promise<void> {
+    Logger.info(
+      `[AggService] Handling CREATE for appointment: ${appointment.id}, patient: ${appointment.patientId}, status: ${appointment.status}`
     );
-    // 1. Create PRE-appointment PatientRequirementInstances
-    //    - Fetch RequirementTemplates for procedureId
-    //    - Construct and save PatientRequirementInstance documents
-    //    - Rely on PatientRequirementInstance triggers for notification scheduling
 
-    // 2. Trigger calendar event creation (e.g., this.calendarAdminService.createEventForAppointment(appointment))
+    try {
+      // 1. Manage Patient-Clinic-Practitioner Links (non-critical for core flow, can run in parallel or first)
+      // No need to await if other operations don't depend on its immediate completion, but awaiting for simplicity here.
+      await this.managePatientClinicPractitionerLinks(appointment, "create");
 
-    // 3. Trigger email/push notifications (e.g., this.appointmentMailingService.sendAppointmentConfirmedEmail(appointment))
+      // 2. Fetch necessary profiles for notifications and context
+      // These can be fetched in parallel
+      const [
+        patientProfile,
+        patientSensitiveInfo,
+        practitionerProfile,
+        clinicInfo,
+      ] = await Promise.all([
+        this.fetchPatientProfile(appointment.patientId),
+        this.fetchPatientSensitiveInfo(appointment.patientId),
+        this.fetchPractitionerProfile(appointment.practitionerId), // Needed for practitioner notifications
+        this.fetchClinicInfo(appointment.clinicBranchId), // Needed for clinic admin notifications
+      ]);
 
-    // 4. Manage patient-clinic-practitioner links (e.g., this.managePatientClinicPractitionerLinks(appointment, '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);
 
-    // Example: Placeholder for creating pre-requirements
-    // const requirementTemplates = await this.fetchRequirementTemplates(appointment.procedureId, 'PRE');
-    // for (const template of requirementTemplates) {
-    //   await this.createPatientRequirementInstance(appointment, template, 'PRE');
-    // }
-  }
+        // 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.`
+          );
+        }
 
-  /**
-   * Handles side effects when an appointment is completed.
-   * - Creates POST-appointment PatientRequirementInstances.
-   * - Triggers review request notifications.
-   * @param appointment - The completed Appointment object.
-   * @returns {Promise<void>}
-   */
-  async handleAppointmentCompleted(appointment: Appointment): Promise<void> {
-    console.log(
-      `[AppointmentAggregationService] Handling completed appointment: ${appointment.id}`
-    );
-    // 1. Create POST-appointment PatientRequirementInstances
-    //    - Fetch RequirementTemplates for procedureId
-    //    - Construct and save PatientRequirementInstance documents
+        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)
+      }
 
-    // 2. Trigger review request (e.g., this.appointmentMailingService.sendReviewRequestEmail(appointment))
+      // 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 cancelled.
-   * - Updates overallStatus of related PatientRequirementInstances to CANCELLED_APPOINTMENT.
-   * - Triggers calendar event cancellation/update.
-   * - Triggers email/push notifications for cancellation.
-   * - Evaluates patient-clinic-practitioner links.
-   * @param appointment - The cancelled Appointment object.
-   * @param previousStatus - The status of the appointment before cancellation.
+   * 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 handleAppointmentCancelled(
-    appointment: Appointment,
-    previousStatus?: AppointmentStatus
+  async handleAppointmentUpdate(
+    before: Appointment,
+    after: Appointment
   ): Promise<void> {
-    console.log(
-      `[AppointmentAggregationService] Handling cancelled appointment: ${appointment.id}, previous status: ${previousStatus}`
+    Logger.info(
+      `[AggService] Handling UPDATE for appointment: ${after.id}. Status ${before.status} -> ${after.status}`
     );
-    // 1. Update related PatientRequirementInstances' overallStatus
-    //    - Query instances by appointment.id
-    //    - Update overallStatus to PatientRequirementOverallStatus.CANCELLED_APPOINTMENT
-    //    - PatientRequirementsAdminService (via trigger) should handle notification cancellations.
 
-    // 2. Trigger calendar event cancellation (e.g., this.calendarAdminService.cancelEventForAppointment(appointment))
+    try {
+      const statusChanged = before.status !== after.status;
+      const timeChanged =
+        before.appointmentStartTime.toMillis() !==
+          after.appointmentStartTime.toMillis() ||
+        before.appointmentEndTime.toMillis() !==
+          after.appointmentEndTime.toMillis();
+      // const paymentStatusChanged = before.paymentStatus !== after.paymentStatus; // TODO: Handle later
+      // const reviewAdded = !before.reviewInfo && after.reviewInfo; // TODO: Handle later
+
+      // Fetch profiles for notifications - could be conditional based on changes
+      // For simplicity, fetching upfront, but optimize if performance is an issue.
+      const [
+        patientProfile,
+        patientSensitiveInfo,
+        practitionerProfile,
+        clinicInfo,
+      ] = await Promise.all([
+        this.fetchPatientProfile(after.patientId),
+        this.fetchPatientSensitiveInfo(after.patientId),
+        this.fetchPractitionerProfile(after.practitionerId),
+        this.fetchClinicInfo(after.clinicBranchId),
+      ]);
+
+      if (statusChanged) {
+        Logger.info(
+          `[AggService] Status changed for ${after.id}: ${before.status} -> ${after.status}`
+        );
+
+        // --- PENDING -> CONFIRMED ---
+        if (
+          before.status === AppointmentStatus.PENDING &&
+          after.status === AppointmentStatus.CONFIRMED
+        ) {
+          Logger.info(`[AggService] Appt ${after.id} PENDING -> CONFIRMED.`);
+          await this.createPreAppointmentRequirementInstances(after);
+          // Send confirmation notifications
+          if (patientSensitiveInfo?.email && patientProfile) {
+            Logger.info(
+              `[AggService] Sending appointment confirmed email to patient ${patientSensitiveInfo.email}`
+            );
+            const emailData = {
+              appointment: after,
+              recipientProfile: after.patientInfo,
+              recipientRole: "patient" as const,
+            };
+            await this.appointmentMailingService.sendAppointmentConfirmedEmail(
+              emailData as any
+            );
+          } else {
+            Logger.warn(
+              `[AggService] Cannot send confirmation email to patient ${after.patientId}: email missing.`
+            );
+          }
+
+          if (
+            patientProfile?.expoTokens &&
+            patientProfile.expoTokens.length > 0
+          ) {
+            Logger.info(
+              `[AggService] TODO: Send appointment confirmed push to patient ${after.patientId}`
+            );
+            await this.notificationsAdmin.sendAppointmentConfirmedPush(
+              after,
+              after.patientId,
+              patientProfile.expoTokens,
+              UserRole.PATIENT
+            );
+          }
+
+          if (practitionerProfile?.basicInfo?.email) {
+            Logger.info(
+              `[AggService] Sending appointment confirmation email to practitioner ${practitionerProfile.basicInfo.email}`
+            );
+            const practitionerEmailData = {
+              appointment: after,
+              recipientProfile: after.practitionerInfo,
+              recipientRole: "practitioner" as const,
+            };
+            await this.appointmentMailingService.sendAppointmentConfirmedEmail(
+              practitionerEmailData as any // TODO: Properly import PractitionerProfileInfo and ensure type compatibility
+            );
+          }
+          // TODO: Add push notification for practitioner if they have expoTokens
+        }
+        // --- Any -> CANCELLED_* ---
+        else if (
+          after.status === AppointmentStatus.CANCELED_CLINIC ||
+          after.status === AppointmentStatus.CANCELED_PATIENT ||
+          after.status === AppointmentStatus.CANCELED_PATIENT_RESCHEDULED ||
+          after.status === AppointmentStatus.NO_SHOW
+        ) {
+          Logger.info(
+            `[AggService] Appt ${after.id} status -> ${after.status}. Processing as cancellation.`
+          );
+          await this.updateRelatedPatientRequirementInstances(
+            after,
+            PatientRequirementOverallStatus.CANCELLED_APPOINTMENT
+          );
+          await this.managePatientClinicPractitionerLinks(after, "cancel");
+
+          // Send cancellation email to Patient
+          if (patientSensitiveInfo?.email && patientProfile) {
+            Logger.info(
+              `[AggService] Sending appointment cancellation email to patient ${patientSensitiveInfo.email}`
+            );
+            const patientCancellationData = {
+              appointment: after,
+              recipientProfile: after.patientInfo,
+              recipientRole: "patient" as const,
+              // cancellationReason: after.cancellationReason, // TODO: Add if cancellationReason is available on 'after' Appointment
+            };
+            await this.appointmentMailingService.sendAppointmentCancelledEmail(
+              patientCancellationData as any // TODO: Properly import types
+            );
+          }
+
+          // Send cancellation email to Practitioner
+          if (practitionerProfile?.basicInfo?.email) {
+            Logger.info(
+              `[AggService] Sending appointment cancellation email to practitioner ${practitionerProfile.basicInfo.email}`
+            );
+            const practitionerCancellationData = {
+              appointment: after,
+              recipientProfile: after.practitionerInfo,
+              recipientRole: "practitioner" as const,
+              // cancellationReason: after.cancellationReason, // TODO: Add if cancellationReason is available on 'after' Appointment
+            };
+            await this.appointmentMailingService.sendAppointmentCancelledEmail(
+              practitionerCancellationData as any // TODO: Properly import types
+            );
+          }
 
-    // 3. Trigger email notifications (e.g., this.appointmentMailingService.sendAppointmentCancelledEmail(appointment))
+          // 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);
 
-    // 4. Evaluate patient-clinic-practitioner links for removal
+          // Send review request email to patient
+          if (patientSensitiveInfo?.email && patientProfile) {
+            Logger.info(
+              `[AggService] Sending review request email to patient ${patientSensitiveInfo.email}`
+            );
+            const reviewRequestData = {
+              appointment: after,
+              patientProfile: after.patientInfo,
+              reviewLink: "TODO: Generate actual review link", // Placeholder
+            };
+            await this.appointmentMailingService.sendReviewRequestEmail(
+              reviewRequestData as any // TODO: Properly import PatientProfileInfo and define reviewLink generation
+            );
+          }
+          // TODO: Send review request push notification to patient
+        }
+        // --- RESCHEDULE Scenarios (e.g., PENDING/CONFIRMED -> RESCHEDULED_BY_CLINIC) ---
+        else if (after.status === AppointmentStatus.RESCHEDULED_BY_CLINIC) {
+          Logger.info(
+            `[AggService] Appt ${after.id} status -> RESCHEDULED_BY_CLINIC.`
+          );
+          await this.updateRelatedPatientRequirementInstances(
+            before, // Pass the 'before' state for old requirements
+            PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE
+          );
+          Logger.info(
+            `[AggService] TODO: Handle RESCHEDULE logic for requirements carefully based on confirmation flow.`
+          );
+
+          // Send reschedule proposal email to patient
+          if (patientSensitiveInfo?.email && patientProfile) {
+            Logger.info(
+              `[AggService] Sending reschedule proposal email to patient ${patientSensitiveInfo.email}`
+            );
+            const rescheduleEmailData = {
+              appointment: after, // The new state of the appointment
+              patientProfile: after.patientInfo,
+              previousStartTime: before.appointmentStartTime,
+              previousEndTime: before.appointmentEndTime,
+            };
+            await this.appointmentMailingService.sendAppointmentRescheduledProposalEmail(
+              rescheduleEmailData as any // TODO: Properly import PatientProfileInfo and types
+            );
+          }
+
+          Logger.info(
+            `[AggService] TODO: Send reschedule proposal notifications to practitioner as well.`
+          );
+          // TODO: Update calendar event to reflect proposed new time via calendarAdminService.
+        }
+        // TODO: Add more specific status change handlers as needed
+      }
+
+      // --- Independent Time Change (if not tied to a status that already handled it) ---
+      if (timeChanged && !statusChanged) {
+        // Or if status change didn't fully cover reschedule implications
+        Logger.info(`[AggService] Appointment ${after.id} time changed.`);
+        // This scenario is tricky. If time changes, pre-requirements might need to be re-evaluated.
+        // Typically, a time change would also involve a status change to some form of "rescheduled".
+        // If it can happen independently while, e.g., staying CONFIRMED, then:
+        // await this.updateRelatedPatientRequirementInstances(before, PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE);
+        // await this.createPreAppointmentRequirementInstances(after);
+        // TODO: Send reschedule notifications
+        // TODO: Update calendar event via calendarAdminService
+        Logger.warn(
+          `[AggService] Independent time change detected for ${after.id}. Review implications for requirements and calendar.`
+        );
+      }
+
+      // TODO: Handle Payment Status Change
+      // const paymentStatusChanged = before.paymentStatus !== after.paymentStatus;
+      // if (paymentStatusChanged && after.paymentStatus === PaymentStatus.PAID) { ... }
+
+      // TODO: Handle Review Added
+      // const reviewAdded = !before.reviewInfo && after.reviewInfo;
+      // if (reviewAdded) { ... }
+
+      Logger.info(
+        `[AggService] Successfully processed UPDATE for appointment: ${after.id}`
+      );
+    } catch (error) {
+      Logger.error(
+        `[AggService] Critical error in handleAppointmentUpdate for appointment ${after.id}:`,
+        error
+      );
+    }
   }
 
   /**
-   * Handles side effects when an appointment is rescheduled.
-   * - Updates/recreates PRE-appointment PatientRequirementInstances based on new times.
-   * - Triggers calendar event updates.
-   * - Triggers email/push notifications for rescheduling.
-   * @param appointment - The rescheduled Appointment object with new times.
-   * @param previousAppointmentData - The appointment data before rescheduling.
+   * Handles side effects when an appointment is deleted.
+   * @param deletedAppointment - The Appointment object that was deleted.
    * @returns {Promise<void>}
    */
-  async handleAppointmentRescheduled(
-    appointment: Appointment,
-    previousAppointmentData: Appointment
+  async handleAppointmentDelete(
+    deletedAppointment: Appointment
   ): Promise<void> {
-    console.log(
-      `[AppointmentAggregationService] Handling rescheduled appointment: ${appointment.id}`
+    Logger.info(
+      `[AggService] Handling DELETE for appointment: ${deletedAppointment.id}`
     );
-    // 1. Manage PatientRequirementInstances for PRE-requirements:
-    //    - Mark old instances as SUPERSEDED_RESCHEDULE.
-    //    - Create new instances for the new time OR update existing ones (more complex).
-    //    - PatientRequirementsAdminService (via trigger) will manage notification updates.
-
-    // 2. Trigger calendar event update (e.g., this.calendarAdminService.updateEventForAppointment(appointment, previousAppointmentData))
-
-    // 3. Trigger email notifications for reschedule (e.g., this.appointmentMailingService.sendAppointmentRescheduledEmail(appointment))
+    // Similar to cancellation
+    await this.updateRelatedPatientRequirementInstances(
+      deletedAppointment,
+      PatientRequirementOverallStatus.CANCELLED_APPOINTMENT
+    );
+    // await this.calendarAdminService.deleteAppointmentCalendarEvents(deletedAppointment);
+    await this.managePatientClinicPractitionerLinks(
+      deletedAppointment,
+      "cancel"
+    );
+    // TODO: Send cancellation/deletion notifications if appropriate (though data is gone)
   }
 
+  // --- Helper Methods for Aggregation Logic ---
+
   /**
-   * Manages the links between a patient and the clinic/practitioner associated with an appointment.
-   * Adds links on creation, potentially removes them on cancellation if it's the only link.
-   * @param appointment - The appointment object.
-   * @param action - 'create' to add links, 'cancel' to evaluate removal.
-   * @returns {Promise<void>}
+   * 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.
    */
-  async managePatientClinicPractitionerLinks(
-    appointment: Appointment,
-    action: "create" | "cancel"
+  private async createPreAppointmentRequirementInstances(
+    appointment: Appointment
   ): Promise<void> {
-    console.log(
-      `[AppointmentAggregationService] Managing patient-clinic-practitioner links for appointment ${appointment.id}, action: ${action}`
+    Logger.info(
+      `[AggService] Creating PRE-appointment requirement instances for appt: ${appointment.id}, patient: ${appointment.patientId}`
     );
-    // Logic to add patientId to clinic.patientIds / practitioner.patientIds if 'create'
-    // Logic to check and potentially remove if 'cancel' and no other appointments link them.
-    // This would likely involve calling methods on a PatientAdminService, ClinicAdminService, PractitionerAdminService
+
+    if (!appointment.procedureId) {
+      Logger.warn(
+        `[AggService] Appointment ${appointment.id} has no procedureId. Cannot create pre-requirement instances.`
+      );
+      return;
+    }
+
+    if (
+      !appointment.preProcedureRequirements ||
+      appointment.preProcedureRequirements.length === 0
+    ) {
+      Logger.info(
+        `[AggService] No preProcedureRequirements found on appointment ${appointment.id}. Nothing to create.`
+      );
+      return;
+    }
+
+    try {
+      const batch = this.db.batch();
+      let instancesCreatedCount = 0;
+
+      for (const template of appointment.preProcedureRequirements) {
+        if (!template) continue; // Skip if template is null or undefined in the array
+
+        // Ensure it's an active, PRE-type requirement
+        if (template.type !== RequirementType.PRE || !template.isActive) {
+          Logger.debug(
+            `[AggService] Skipping template ${template.id} (${template.name}): not an active PRE requirement.`
+          );
+          continue;
+        }
+
+        Logger.debug(
+          `[AggService] Processing template ${template.id} (${template.name}) for appt ${appointment.id}`
+        );
+
+        const newInstanceRef = this.db
+          .collection(PATIENTS_COLLECTION)
+          .doc(appointment.patientId)
+          .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
+          .doc(); // Auto-generate ID for the new instance
+
+        const instructions: PatientRequirementInstruction[] = (
+          template.timeframe?.notifyAt || []
+        ).map((notifyAtValue) => {
+          let dueTime: any = appointment.appointmentStartTime;
+          if (template.timeframe && typeof notifyAtValue === "number") {
+            const dueDateTime = new Date(
+              appointment.appointmentStartTime.toMillis()
+            );
+            if (template.timeframe.unit === TimeUnit.DAYS) {
+              dueDateTime.setDate(dueDateTime.getDate() - notifyAtValue);
+            } else if (template.timeframe.unit === TimeUnit.HOURS) {
+              dueDateTime.setHours(dueDateTime.getHours() - notifyAtValue);
+            }
+            dueTime = admin.firestore.Timestamp.fromDate(dueDateTime);
+          }
+
+          // TODO: Determine source or default for 'actionableWindow' - consult requirements for PatientRequirementInstruction
+          const actionableWindowHours =
+            template.importance === "high"
+              ? 1
+              : template.importance === "medium"
+              ? 4
+              : 15; // Default to 15 hours for low importance; // Placeholder default, TODO: Define source
+
+          const instructionObject: PatientRequirementInstruction = {
+            instructionId:
+              `${template.id}_${notifyAtValue}_${newInstanceRef.id}`.replace(
+                /[^a-zA-Z0-9_]/g,
+                "_"
+              ),
+            instructionText: template.description || template.name,
+            dueTime: dueTime as any,
+            actionableWindow: actionableWindowHours, // Directly assigning the placeholder default value
+            status: PatientInstructionStatus.PENDING_NOTIFICATION,
+            originalNotifyAtValue: notifyAtValue,
+            originalTimeframeUnit: template.timeframe.unit,
+            updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+            notificationId: undefined,
+            actionTakenAt: undefined,
+          };
+          return instructionObject;
+        });
+
+        const newInstanceData: Omit<PatientRequirementInstance, "id"> = {
+          patientId: appointment.patientId,
+          appointmentId: appointment.id,
+          originalRequirementId: template.id,
+          requirementName: template.name,
+          requirementDescription: template.description,
+          requirementType: template.type, // Should be RequirementType.PRE
+          requirementImportance: template.importance,
+          overallStatus: PatientRequirementOverallStatus.ACTIVE,
+          instructions: instructions,
+          // Timestamps - cast to any to satisfy client-side Timestamp type for now
+          createdAt: admin.firestore.FieldValue.serverTimestamp() as any,
+          updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+        };
+
+        batch.set(newInstanceRef, newInstanceData);
+        instancesCreatedCount++;
+        Logger.debug(
+          `[AggService] Added PatientRequirementInstance ${newInstanceRef.id} to batch for template ${template.id}.`
+        );
+      }
+
+      if (instancesCreatedCount > 0) {
+        await batch.commit();
+        Logger.info(
+          `[AggService] Successfully created ${instancesCreatedCount} PRE_APPOINTMENT requirement instances for appointment ${appointment.id}.`
+        );
+      } else {
+        Logger.info(
+          `[AggService] No new PRE_APPOINTMENT requirement instances were prepared for batch commit for appointment ${appointment.id}.`
+        );
+      }
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error creating PRE_APPOINTMENT requirement instances for appointment ${appointment.id}:`,
+        error
+      );
+      // Rethrow or handle as per error policy, e.g., if this failure should halt further processing.
+      // For now, just logging.
+    }
   }
 
   /**
-   * Placeholder for a more generic calendar update trigger.
-   * @param appointment The appointment data.
-   * @param action The type of action ('create', 'update', 'delete').
-   * @param previousAppointmentData Optional, for 'update' actions.
-   * @returns {Promise<void>}
+   * Creates POST_APPOINTMENT PatientRequirementInstance documents for a given appointment.
+   * Uses the `appointment.postProcedureRequirements` array.
+   * For each active POST requirement template, it constructs a new PatientRequirementInstance document
+   * with derived instructions and batch writes them to Firestore under the patient's `patient_requirements` subcollection.
+   *
+   * @param {Appointment} appointment - The appointment for which to create post-requirement instances.
+   * @returns {Promise<void>} A promise that resolves when the operation is complete.
    */
-  async triggerCalendarUpdate(
-    appointment: Appointment,
-    action: "create" | "update" | "delete",
-    previousAppointmentData?: Appointment
+  private async createPostAppointmentRequirementInstances(
+    appointment: Appointment
   ): Promise<void> {
-    console.log(
-      `[AppointmentAggregationService] Triggering calendar update for appointment ${appointment.id}, action: ${action}`
+    Logger.info(
+      `[AggService] Creating POST-appointment requirement instances for appt: ${appointment.id}, patient: ${appointment.patientId}`
     );
-    // Call methods on a dedicated CalendarAdminService
+
+    if (!appointment.procedureId) {
+      Logger.warn(
+        `[AggService] Appointment ${appointment.id} has no procedureId. Cannot create post-requirement instances.`
+      );
+      return;
+    }
+
+    if (
+      !appointment.postProcedureRequirements ||
+      appointment.postProcedureRequirements.length === 0
+    ) {
+      Logger.info(
+        `[AggService] No postProcedureRequirements found on appointment ${appointment.id}. Nothing to create.`
+      );
+      return;
+    }
+
+    try {
+      const batch = this.db.batch();
+      let instancesCreatedCount = 0;
+
+      for (const template of appointment.postProcedureRequirements) {
+        if (!template) continue;
+
+        if (template.type !== RequirementType.POST || !template.isActive) {
+          Logger.debug(
+            `[AggService] Skipping template ${template.id} (${template.name}): not an active POST requirement.`
+          );
+          continue;
+        }
+
+        Logger.debug(
+          `[AggService] Processing POST template ${template.id} (${template.name}) for appt ${appointment.id}`
+        );
+
+        const newInstanceRef = this.db
+          .collection(PATIENTS_COLLECTION)
+          .doc(appointment.patientId)
+          .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
+          .doc();
+
+        const instructions: PatientRequirementInstruction[] = (
+          template.timeframe?.notifyAt || []
+        ).map((notifyAtValue) => {
+          let dueTime: any = appointment.appointmentEndTime; // Default to appointment end time
+          if (template.timeframe && typeof notifyAtValue === "number") {
+            const dueDateTime = new Date(
+              appointment.appointmentEndTime.toMillis()
+            );
+            // For POST requirements, notifyAtValue usually means AFTER the event
+            if (template.timeframe.unit === TimeUnit.DAYS) {
+              dueDateTime.setDate(dueDateTime.getDate() + notifyAtValue);
+            } else if (template.timeframe.unit === TimeUnit.HOURS) {
+              dueDateTime.setHours(dueDateTime.getHours() + notifyAtValue);
+            }
+            dueTime = admin.firestore.Timestamp.fromDate(dueDateTime);
+          }
+
+          const actionableWindowHours =
+            template.importance === "high"
+              ? 1
+              : template.importance === "medium"
+              ? 4
+              : 15; // Default to 15 hours for low importance; // Placeholder default, TODO: Define source
+
+          return {
+            instructionId:
+              `${template.id}_${notifyAtValue}_${newInstanceRef.id}`.replace(
+                /[^a-zA-Z0-9_]/g,
+                "_"
+              ),
+            instructionText: template.description || template.name,
+            dueTime: dueTime as any,
+            actionableWindow: actionableWindowHours,
+            status: PatientInstructionStatus.PENDING_NOTIFICATION,
+            originalNotifyAtValue: notifyAtValue,
+            originalTimeframeUnit: template.timeframe.unit,
+            updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+            notificationId: undefined,
+            actionTakenAt: undefined,
+          } as PatientRequirementInstruction;
+        });
+
+        const newInstanceData: Omit<PatientRequirementInstance, "id"> = {
+          patientId: appointment.patientId,
+          appointmentId: appointment.id,
+          originalRequirementId: template.id,
+          requirementName: template.name,
+          requirementDescription: template.description,
+          requirementType: template.type, // Should be RequirementType.POST
+          requirementImportance: template.importance,
+          overallStatus: PatientRequirementOverallStatus.ACTIVE,
+          instructions: instructions,
+          createdAt: admin.firestore.FieldValue.serverTimestamp() as any,
+          updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+        };
+
+        batch.set(newInstanceRef, newInstanceData);
+        instancesCreatedCount++;
+        Logger.debug(
+          `[AggService] Added POST PatientRequirementInstance ${newInstanceRef.id} to batch for template ${template.id}.`
+        );
+      }
+
+      if (instancesCreatedCount > 0) {
+        await batch.commit();
+        Logger.info(
+          `[AggService] Successfully created ${instancesCreatedCount} POST_APPOINTMENT requirement instances for appointment ${appointment.id}.`
+        );
+      } else {
+        Logger.info(
+          `[AggService] No new POST_APPOINTMENT requirement instances were prepared for batch commit for appointment ${appointment.id}.`
+        );
+      }
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error creating POST_APPOINTMENT requirement instances for appointment ${appointment.id}:`,
+        error
+      );
+    }
   }
 
   /**
-   * Placeholder for a more generic email notification trigger.
-   * @param appointment The appointment data.
-   * @param emailType A string identifying the type of email (e.g., 'APPOINTMENT_CONFIRMED_PATIENT').
-   * @param previousAppointmentData Optional, for context.
-   * @returns {Promise<void>}
+   * 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.
    */
-  async triggerEmailNotification(
+  private async updateRelatedPatientRequirementInstances(
     appointment: Appointment,
-    emailType: string,
-    previousAppointmentData?: Appointment
+    newOverallStatus: PatientRequirementOverallStatus,
+    _previousAppointmentData?: Appointment // Not used in this basic implementation, but kept for signature consistency
   ): Promise<void> {
-    console.log(
-      `[AppointmentAggregationService] Triggering email type '${emailType}' for appointment ${appointment.id}`
+    Logger.info(
+      `[AggService] Updating related patient req instances for appt ${appointment.id} (patient: ${appointment.patientId}) to ${newOverallStatus}`
     );
-    // Call methods on a dedicated AppointmentMailingService
+
+    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
+      );
+    }
   }
 
   /**
-   * Handles logic for sending a review request after appointment completion.
-   * @param appointment - The completed appointment.
-   * @returns {Promise<void>}
+   * Manages denormalized links between a patient and the clinic/practitioner associated with an appointment.
+   * Adds patientId to arrays on clinic and practitioner documents on appointment creation.
+   * Removes patientId on appointment cancellation (basic removal, can be enhanced).
+   *
+   * @param {Appointment} appointment - The appointment object.
+   * @param {"create" | "cancel"} action - 'create' to add links, 'cancel' to remove them.
+   * @returns {Promise<void>} A promise that resolves when the operation is complete.
    */
-  async handleReviewRequest(appointment: Appointment): Promise<void> {
-    console.log(
-      `[AppointmentAggregationService] Handling review request for appointment ${appointment.id}`
+  private async managePatientClinicPractitionerLinks(
+    appointment: Appointment,
+    action: "create" | "cancel"
+  ): Promise<void> {
+    Logger.info(
+      `[AggService] Managing patient-clinic-practitioner links for appt ${appointment.id} (patient: ${appointment.patientId}), action: ${action}`
     );
-    // Logic to schedule or send a review request notification/email.
-    // Might involve checking if a review already exists.
+
+    if (
+      !appointment.patientId ||
+      !appointment.practitionerId ||
+      !appointment.clinicBranchId
+    ) {
+      Logger.error(
+        "[AggService] managePatientClinicPractitionerLinks called with missing IDs.",
+        {
+          patientId: appointment.patientId,
+          practitionerId: appointment.practitionerId,
+          clinicBranchId: appointment.clinicBranchId,
+        }
+      );
+      return;
+    }
+
+    const batch = this.db.batch();
+    const patientId = appointment.patientId;
+
+    // Practitioner link
+    const practitionerRef = this.db
+      .collection(PRACTITIONERS_COLLECTION)
+      .doc(appointment.practitionerId);
+    // Clinic link
+    const clinicRef = this.db
+      .collection(CLINICS_COLLECTION)
+      .doc(appointment.clinicBranchId);
+
+    if (action === "create") {
+      // Add patient to practitioner's list of patients (if field exists, e.g., 'patientIds')
+      // Assuming a field named 'patientIds' on the practitioner document
+      batch.update(practitionerRef, {
+        patientIds: admin.firestore.FieldValue.arrayUnion(patientId),
+        // Optionally, update a count or last interaction timestamp
+        updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+      });
+      Logger.debug(
+        `[AggService] Adding patient ${patientId} to practitioner ${appointment.practitionerId} patientIds.`
+      );
+
+      // Add patient to clinic's list of patients (if field exists, e.g., 'patientIds')
+      // Assuming a field named 'patientIds' on the clinic document
+      batch.update(clinicRef, {
+        patientIds: admin.firestore.FieldValue.arrayUnion(patientId),
+        updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+      });
+      Logger.debug(
+        `[AggService] Adding patient ${patientId} to clinic ${appointment.clinicBranchId} patientIds.`
+      );
+    } else if (action === "cancel") {
+      // Basic removal.
+      // TODO: Implement more robust removal logic: only remove if this was the last active/confirmed appointment
+      //       linking this patient to this practitioner/clinic.
+      batch.update(practitionerRef, {
+        patientIds: admin.firestore.FieldValue.arrayRemove(patientId),
+        updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+      });
+      Logger.debug(
+        `[AggService] Removing patient ${patientId} from practitioner ${appointment.practitionerId} patientIds.`
+      );
+
+      batch.update(clinicRef, {
+        patientIds: admin.firestore.FieldValue.arrayRemove(patientId),
+        updatedAt: admin.firestore.FieldValue.serverTimestamp() as any,
+      });
+      Logger.debug(
+        `[AggService] Removing patient ${patientId} from clinic ${appointment.clinicBranchId} patientIds.`
+      );
+    }
+
+    try {
+      await batch.commit();
+      Logger.info(
+        `[AggService] Successfully updated patient-clinic-practitioner links for appointment ${appointment.id}, action: ${action}.`
+      );
+    } catch (error) {
+      Logger.error(
+        `[AggService] Error managing patient-clinic-practitioner links for appointment ${appointment.id}:`,
+        error
+      );
+    }
   }
 
-  // --- Helper methods --- //
+  // --- 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 requirement templates based on procedure ID and type (PRE/POST).
-   * @param procedureId The ID of the procedure.
-   * @param type 'PRE' or 'POST'.
-   * @returns {Promise<RequirementTemplate[]>}
+   * 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 fetchRequirementTemplates(
-    procedureId: string,
-    type: "PRE" | "POST" // Assuming type is stored on the template
-  ): Promise<RequirementTemplate[]> {
-    console.log(
-      `[AppointmentAggregationService] Fetching '${type}' requirement templates for procedure ${procedureId}`
-    );
-    // const templatesSnapshot = await this.db
-    //   .collection(REQUIREMENTS_TEMPLATES_COLLECTION)
-    //   .where("procedureIds", "array-contains", procedureId)
-    //   .where("type", "==", type) // Assuming a 'type' field on the template
-    //   .where("isActive", "==", true)
-    //   .get();
-    // return templatesSnapshot.docs.map(doc => ({ id: doc.id, ...doc.data() } as RequirementTemplate));
-    return []; // Placeholder
+  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;
+    }
   }
 
   /**
-   * Creates a PatientRequirementInstance document.
-   * @param appointment The parent appointment.
-   * @param template The RequirementTemplate to base the instance on.
-   * @param type 'PRE' or 'POST'.
-   * @returns {Promise<string>} ID of the created instance.
+   * 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 createPatientRequirementInstance(
-    appointment: Appointment,
-    template: RequirementTemplate,
-    type: "PRE" | "POST"
-  ): Promise<string> {
-    console.log(
-      `[AppointmentAggregationService] Creating '${type}' PatientRequirementInstance for appointment ${appointment.id} from template ${template.id}`
-    );
-    const newInstanceRef = this.db
-      .collection(PATIENTS_COLLECTION)
-      .doc(appointment.patientId)
-      .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
-      .doc(); // Auto-generate ID
-
-    // const instructions = template.instructions.map(instrTemplate => ({
-    //   ...instrTemplate, // Spread common fields like instructionText, instructionId (if pre-defined)
-    //   instructionId: instrTemplate.instructionId || this.db.collection('_').doc().id, // Ensure unique ID
-    //   status: PatientInstructionStatus.PENDING_NOTIFICATION,
-    //   dueTime: this.calculateInstructionDueTime(appointment, instrTemplate, type),
-    //   createdAt: admin.firestore.FieldValue.serverTimestamp(),
-    //   updatedAt: admin.firestore.FieldValue.serverTimestamp(),
-    // }));
-
-    // const instanceData: Omit<PatientRequirementInstance, 'id' | 'createdAt' | 'updatedAt'> = {
-    //   patientId: appointment.patientId,
-    //   appointmentId: appointment.id,
-    //   originalRequirementId: template.id,
-    //   requirementName: template.name,
-    //   type: type, // 'PRE' or 'POST'
-    //   overallStatus: PatientRequirementOverallStatus.ACTIVE,
-    //   instructions: instructions,
-    //   // ... other fields like clinicId, practitionerId if needed from appointment
-    // };
-
-    // await newInstanceRef.set({
-    //   ...instanceData,
-    //   createdAt: admin.firestore.FieldValue.serverTimestamp(),
-    //   updatedAt: admin.firestore.FieldValue.serverTimestamp(),
-    // });
-    // return newInstanceRef.id;
-    return newInstanceRef.id; // Placeholder
+  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;
+    }
   }
 
   /**
-   * Calculates the due time for an instruction.
-   * @param appointment The appointment.
-   * @param instructionTemplate The instruction template from RequirementTemplate.
-   * @param type 'PRE' or 'POST'.
-   * @returns {admin.firestore.Timestamp}
+   * 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 calculateInstructionDueTime(appointment: Appointment, instructionTemplate: any, type: 'PRE' | 'POST'): admin.firestore.Timestamp {
-  //   const baseTime = type === 'PRE' ? appointment.appointmentStartTime : appointment.appointmentEndTime;
-  //   // Logic to add/subtract instructionTemplate.offset (e.g., { value: 24, unit: 'hours' }) from baseTime
-  //   return baseTime; // Placeholder
-  // }
+  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;
+    }
+  }
 }