@blackcode_sa/metaestetics-api 1.15.16 → 1.15.17-staging.1

package/src/admin/requirements/patient-requirements.admin.service.ts

@@ -1,475 +1,475 @@
-import * as admin from "firebase-admin";
-// Import client-side Timestamp for type compatibility with shared types
-import { Timestamp as FirebaseClientTimestamp } from "@firebase/firestore";
-import {
-  PatientRequirementInstance,
-  PatientInstructionStatus,
-  PatientRequirementOverallStatus,
-  PatientRequirementInstruction,
-  PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME,
-} from "../../types/patient/patient-requirements";
-import {
-  NotificationType,
-  RequirementInstructionDueNotification,
-  NOTIFICATIONS_COLLECTION,
-  NotificationStatus,
-} from "../../types/notifications";
-import { PatientProfile, PATIENTS_COLLECTION } from "../../types/patient";
-import { UserRole } from "../../types"; // Assuming UserRole is in the main types index
-import { NotificationsAdmin } from "../notifications/notifications.admin";
-import { TimestampUtils } from "../../utils/TimestampUtils";
-
-/**
- * @class PatientRequirementsAdminService
- * @description Handles administrative tasks for patient requirement instances, primarily managing associated notifications.
- * This service is intended to be used by Cloud Functions triggered by changes to PatientRequirementInstance documents.
- */
-export class PatientRequirementsAdminService {
-  private db: admin.firestore.Firestore;
-  private notificationsAdmin: NotificationsAdmin;
-
-  constructor(firestore?: admin.firestore.Firestore) {
-    this.db = firestore || admin.firestore();
-    this.notificationsAdmin = new NotificationsAdmin(this.db);
-  }
-
-  /**
-   * Processes a newly created or updated PatientRequirementInstance to schedule notifications for its instructions.
-   * It will also cancel pre-existing notifications if due times have changed significantly.
-   *
-   * @param patientId - The ID of the patient.
-   * @param instance - The PatientRequirementInstance data (either new or updated).
-   * @param previousInstanceData - Optional. The previous state of the instance data if it's an update.
-   *                                 Used to determine if notifications need to be cancelled/rescheduled.
-   * @returns {Promise<void>} A promise that resolves when processing is complete.
-   */
-  async processRequirementInstanceAndScheduleNotifications(
-    patientId: string,
-    instance: PatientRequirementInstance,
-    previousInstanceData?: PatientRequirementInstance
-  ): Promise<void> {
-    console.log(
-      `[PRA_Service] Processing requirement instance ${instance.id} for patient ${patientId}. Overall Status: ${instance.overallStatus}`
-    );
-
-    const patientProfileRef = this.db
-      .collection(PATIENTS_COLLECTION)
-      .doc(patientId);
-    let patientExpoTokens: string[] = [];
-
-    try {
-      const patientDoc = await patientProfileRef.get();
-      if (patientDoc.exists) {
-        const patientData = patientDoc.data() as PatientProfile;
-        patientExpoTokens = patientData.expoTokens || [];
-      }
-    } catch (error) {
-      console.error(
-        `[PRA_Service] Error fetching patient ${patientId} for expo tokens:`,
-        error
-      );
-    }
-
-    if (patientExpoTokens.length === 0) {
-      console.log(
-        `[PRA_Service] Patient ${patientId} has no expo tokens. Skipping notification creation for instance ${instance.id}.`
-      );
-    }
-    // Create a new array of instruction objects to avoid mutating the original
-    // Keep original Timestamp objects by reference
-    const updatedInstructions: PatientRequirementInstruction[] =
-      instance.instructions.map((instr) => ({ ...instr }));
-    let instructionUpdatesMade = false;
-
-    for (let i = 0; i < updatedInstructions.length; i++) {
-      let currentInstruction = updatedInstructions[i];
-      const previousInstruction = previousInstanceData?.instructions.find(
-        (pi) => pi.instructionId === currentInstruction.instructionId
-      );
-      const adminTsNow = admin.firestore.Timestamp.now();
-
-      if (
-        instance.overallStatus ===
-          PatientRequirementOverallStatus.CANCELLED_APPOINTMENT ||
-        instance.overallStatus ===
-          PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE ||
-        currentInstruction.status === PatientInstructionStatus.CANCELLED
-      ) {
-        if (currentInstruction.notificationId) {
-          console.log(
-            `[PRA_Service] Cancelling notification ${currentInstruction.notificationId} for instruction ${currentInstruction.instructionId} of instance ${instance.id}.`
-          );
-          await this.notificationsAdmin.updateNotificationStatus(
-            currentInstruction.notificationId,
-            NotificationStatus.CANCELLED
-          );
-          currentInstruction = {
-            ...currentInstruction,
-            notificationId: undefined,
-            status: PatientInstructionStatus.CANCELLED,
-            updatedAt: TimestampUtils.adminToClient(
-              adminTsNow
-            ) as FirebaseClientTimestamp,
-          };
-          updatedInstructions[i] = currentInstruction;
-          instructionUpdatesMade = true;
-        }
-        continue;
-      }
-
-      const dueTimeChanged =
-        previousInstruction &&
-        currentInstruction.dueTime && // Ensure dueTime exists
-        previousInstruction.dueTime.toMillis() !==
-          currentInstruction.dueTime.toMillis();
-
-      // Simplified: if previous was CANCELLED, and we are in this part of the code,
-      // it means currentInstruction.status is NOT CANCELLED (i.e., it's active).
-      const wasPreviouslyCancelledAndNowActive =
-        previousInstruction &&
-        previousInstruction.status === PatientInstructionStatus.CANCELLED;
-
-      if (
-        previousInstruction &&
-        (dueTimeChanged || wasPreviouslyCancelledAndNowActive) && // Use the simplified variable
-        currentInstruction.notificationId
-      ) {
-        console.log(
-          `[PRA_Service] Due time changed or instruction reactivated for ${currentInstruction.instructionId}. Cancelling old notification ${currentInstruction.notificationId}.`
-        );
-        await this.notificationsAdmin.updateNotificationStatus(
-          currentInstruction.notificationId,
-          NotificationStatus.CANCELLED
-        );
-        currentInstruction = {
-          ...currentInstruction,
-          notificationId: undefined,
-          updatedAt: TimestampUtils.adminToClient(
-            adminTsNow
-          ) as FirebaseClientTimestamp,
-        };
-        updatedInstructions[i] = currentInstruction;
-        instructionUpdatesMade = true;
-      }
-
-      const shouldSchedule =
-        currentInstruction.dueTime && // Ensure dueTime exists
-        currentInstruction.status ===
-          PatientInstructionStatus.PENDING_NOTIFICATION &&
-        !currentInstruction.notificationId &&
-        currentInstruction.dueTime.toMillis() > adminTsNow.toMillis() &&
-        patientExpoTokens.length > 0;
-
-      if (shouldSchedule) {
-        console.log(
-          `[PRA_Service] Scheduling notification for instruction ${
-            currentInstruction.instructionId
-          } of instance ${
-            instance.id
-          } at ${currentInstruction.dueTime.toDate()}.`
-        );
-
-        const notificationPayload: Omit<
-          RequirementInstructionDueNotification,
-          "id" | "createdAt" | "updatedAt" | "status" | "isRead"
-        > = {
-          userId: patientId,
-          userRole: UserRole.PATIENT,
-          notificationType: NotificationType.REQUIREMENT_INSTRUCTION_DUE,
-          notificationTime: currentInstruction.dueTime as any, // dueTime should be an admin.firestore.Timestamp already
-          notificationTokens: patientExpoTokens,
-          title: `Reminder: ${instance.requirementName}`,
-          body: currentInstruction.instructionText,
-          appointmentId: instance.appointmentId,
-          patientRequirementInstanceId: instance.id,
-          instructionId: currentInstruction.instructionId,
-          originalRequirementId: instance.originalRequirementId,
-        };
-
-        try {
-          const createdNotificationId =
-            await this.notificationsAdmin.createNotification(
-              notificationPayload as any
-            );
-          currentInstruction = {
-            ...currentInstruction,
-            notificationId: createdNotificationId,
-            status: PatientInstructionStatus.PENDING_NOTIFICATION,
-            updatedAt: TimestampUtils.adminToClient(
-              adminTsNow
-            ) as FirebaseClientTimestamp,
-          };
-          updatedInstructions[i] = currentInstruction;
-          instructionUpdatesMade = true;
-        } catch (error) {
-          console.error(
-            `[PRA_Service] Failed to create notification for instruction ${currentInstruction.instructionId}:`,
-            error
-          );
-        }
-      }
-    }
-
-    if (instructionUpdatesMade) {
-      console.log(
-        `[PRA_Service] Updating instructions array for instance ${instance.id} on patient ${patientId}.`
-      );
-      const instanceDocRef = this.db
-        .collection(PATIENTS_COLLECTION)
-        .doc(patientId)
-        .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
-        .doc(instance.id);
-
-      const finalAdminTsNow = admin.firestore.Timestamp.now();
-      await instanceDocRef.update({
-        instructions: updatedInstructions, // Array of instructions with actual Timestamps
-        updatedAt: TimestampUtils.adminToClient(
-          finalAdminTsNow
-        ) as FirebaseClientTimestamp,
-      });
-    }
-  }
-
-  /**
-   * Cancels all PENDING notifications associated with a specific PatientRequirementInstance.
-   * Typically called when the instance itself is deleted or its overall status becomes CANCELLED.
-   *
-   * @param instance - The PatientRequirementInstance.
-   * @returns {Promise<void>}
-   */
-  async cancelAllNotificationsForInstance(
-    instance: PatientRequirementInstance
-  ): Promise<void> {
-    console.log(
-      `[PRA_Service] Attempting to cancel all pending notifications for instance ${instance.id}.`
-    );
-    let cancelledCount = 0;
-    for (const instruction of instance.instructions) {
-      if (instruction.notificationId) {
-        try {
-          const notification = await this.notificationsAdmin.getNotification(
-            instruction.notificationId
-          );
-          if (
-            notification &&
-            notification.status === NotificationStatus.PENDING
-          ) {
-            await this.notificationsAdmin.updateNotificationStatus(
-              instruction.notificationId,
-              NotificationStatus.CANCELLED
-            );
-            console.log(
-              `[PRA_Service] Cancelled notification ${instruction.notificationId} for instruction ${instruction.instructionId}.`
-            );
-            cancelledCount++;
-          } else if (notification) {
-            console.log(
-              `[PRA_Service] Notification ${instruction.notificationId} for instruction ${instruction.instructionId} was not pending (status: ${notification.status}). Not cancelling.`
-            );
-          }
-        } catch (error) {
-          console.error(
-            `[PRA_Service] Error cancelling notification ${instruction.notificationId}:`,
-            error
-          );
-        }
-      }
-    }
-    if (cancelledCount > 0) {
-      console.log(
-        `[PRA_Service] Cancelled ${cancelledCount} notifications for instance ${instance.id}.`
-      );
-    }
-  }
-
-  /**
-   * (Optional - For a cron job)
-   * Scans for instructions that are past their due time but not yet actioned, and updates their status to MISSED.
-   * This would typically be called by a scheduled Cloud Function.
-   *
-   * @param patientId - The ID of the patient.
-   * @param instanceId - The ID of the PatientRequirementInstance.
-   * @returns {Promise<void>}
-   */
-  async updateMissedInstructions(
-    patientId: string,
-    instanceId: string
-  ): Promise<void> {
-    const instanceRef = this.db
-      .collection(PATIENTS_COLLECTION)
-      .doc(patientId)
-      .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
-      .doc(instanceId);
-
-    const instanceSnap = await instanceRef.get();
-    if (!instanceSnap.exists) {
-      console.warn(
-        `[PRA_Service] Instance ${instanceId} not found during missed check for patient ${patientId}.`
-      );
-      return;
-    }
-
-    const instance = instanceSnap.data() as PatientRequirementInstance;
-    const adminNowForMissed = admin.firestore.Timestamp.now();
-
-    // Create a new array of instruction objects to avoid mutating the original
-    const updatedInstructions: PatientRequirementInstruction[] =
-      instance.instructions.map((instr) => ({ ...instr }));
-    let changesMade = false;
-
-    for (let i = 0; i < updatedInstructions.length; i++) {
-      let currentInstruction = updatedInstructions[i];
-      if (
-        currentInstruction.dueTime && // Ensure dueTime exists
-        (currentInstruction.status ===
-          PatientInstructionStatus.PENDING_NOTIFICATION ||
-          currentInstruction.status === PatientInstructionStatus.ACTION_DUE) &&
-        currentInstruction.dueTime.toMillis() < adminNowForMissed.toMillis()
-      ) {
-        currentInstruction = {
-          ...currentInstruction,
-          status: PatientInstructionStatus.MISSED,
-          updatedAt: TimestampUtils.adminToClient(
-            adminNowForMissed
-          ) as FirebaseClientTimestamp,
-        };
-        updatedInstructions[i] = currentInstruction;
-        changesMade = true;
-        console.log(
-          `[PRA_Service] Marked instruction ${currentInstruction.instructionId} in instance ${instanceId} as MISSED.`
-        );
-      }
-    }
-
-    if (changesMade) {
-      const finalAdminNowForMissedUpdate = admin.firestore.Timestamp.now();
-      await instanceRef.update({
-        instructions: updatedInstructions, // Array of instructions with actual Timestamps
-        updatedAt: TimestampUtils.adminToClient(
-          finalAdminNowForMissedUpdate
-        ) as FirebaseClientTimestamp,
-      });
-      console.log(
-        `[PRA_Service] Updated missed instructions for instance ${instanceId}.`
-      );
-    }
-  }
-
-  /**
-   * Calculates and updates the overallStatus of a PatientRequirementInstance
-   * based on the statuses of its individual instructions.
-   *
-   * @param patientId - The ID of the patient.
-   * @param instanceId - The ID of the PatientRequirementInstance to update.
-   * @returns {Promise<void>} A promise that resolves when processing is complete.
-   */
-  async updateOverallInstanceStatus(
-    patientId: string,
-    instanceId: string
-  ): Promise<void> {
-    const instanceRef = this.db
-      .collection(PATIENTS_COLLECTION)
-      .doc(patientId)
-      .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
-      .doc(instanceId);
-
-    const instanceSnap = await instanceRef.get();
-    if (!instanceSnap.exists) {
-      console.warn(
-        `[PRA_Service] Instance ${instanceId} not found while trying to update overall status for patient ${patientId}.`
-      );
-      return;
-    }
-
-    const instance = instanceSnap.data() as PatientRequirementInstance;
-
-    // Do not override terminal statuses set by other processes
-    if (
-      instance.overallStatus ===
-        PatientRequirementOverallStatus.CANCELLED_APPOINTMENT ||
-      instance.overallStatus ===
-        PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE ||
-      instance.overallStatus ===
-        PatientRequirementOverallStatus.FAILED_TO_PROCESS // Assuming FAILED_TO_PROCESS is also a terminal state set by other means if it's a hard failure.
-    ) {
-      console.log(
-        `[PRA_Service] Instance ${instanceId} has overallStatus ${instance.overallStatus}, skipping overall status update based on instruction completion logic.`
-      );
-      return;
-    }
-
-    const nonCancelledInstructions = instance.instructions.filter(
-      (instr) => instr.status !== PatientInstructionStatus.CANCELLED
-    );
-
-    if (nonCancelledInstructions.length === 0) {
-      // If all instructions are cancelled or there are no instructions.
-      // If it was previously something like ALL_INSTRUCTIONS_MET, it should revert to ACTIVE or a default.
-      if (instance.overallStatus !== PatientRequirementOverallStatus.ACTIVE) {
-        console.log(
-          `[PRA_Service] Instance ${instanceId} has no active (non-cancelled) instructions. Setting to ACTIVE.`
-        );
-        await instanceRef.update({
-          overallStatus: PatientRequirementOverallStatus.ACTIVE,
-          updatedAt: TimestampUtils.adminToClient(
-            admin.firestore.Timestamp.now()
-          ) as FirebaseClientTimestamp,
-        });
-      }
-      return;
-    }
-
-    // Check if any instruction is still pending action by the patient
-    const hasPendingOrDueInstructions = nonCancelledInstructions.some(
-      (instr) =>
-        instr.status === PatientInstructionStatus.PENDING_NOTIFICATION ||
-        instr.status === PatientInstructionStatus.ACTION_DUE
-    );
-
-    let newOverallStatus: PatientRequirementOverallStatus;
-
-    if (hasPendingOrDueInstructions) {
-      newOverallStatus = PatientRequirementOverallStatus.ACTIVE;
-    } else {
-      // All non-cancelled instructions are in a "resolved" state (ACTION_TAKEN, MISSED, SKIPPED)
-      const effectivelyCompletedCount = nonCancelledInstructions.filter(
-        (instr) =>
-          instr.status === PatientInstructionStatus.ACTION_TAKEN ||
-          instr.status === PatientInstructionStatus.SKIPPED
-      ).length;
-
-      const totalNonCancelled = nonCancelledInstructions.length;
-      const completionPercentage =
-        (effectivelyCompletedCount / totalNonCancelled) * 100;
-
-      if (completionPercentage === 100) {
-        newOverallStatus = PatientRequirementOverallStatus.ALL_INSTRUCTIONS_MET;
-      } else if (completionPercentage >= 60) {
-        // Changed from >60 to >=60 as per common understanding of "more than 60%" often including 60%
-        newOverallStatus = PatientRequirementOverallStatus.PARTIALLY_COMPLETED;
-      } else {
-        // Less than 60% effectively completed (could include some MISSED ones not blocking this calculation directly)
-        // Or if all are MISSED, this would also fall here if FAILED_TO_PROCESS isn't set for other reasons.
-        // Your logic: "if less then 60% of instructions are action taken or skipped, then we move status to failed"
-        newOverallStatus = PatientRequirementOverallStatus.FAILED_TO_PROCESS;
-      }
-    }
-
-    if (newOverallStatus !== instance.overallStatus) {
-      console.log(
-        `[PRA_Service] Updating overallStatus for instance ${instanceId} from ${instance.overallStatus} to ${newOverallStatus}.`
-      );
-      const adminTsNow = admin.firestore.Timestamp.now();
-      await instanceRef.update({
-        overallStatus: newOverallStatus,
-        updatedAt: TimestampUtils.adminToClient(
-          adminTsNow
-        ) as FirebaseClientTimestamp,
-      });
-    } else {
-      console.log(
-        `[PRA_Service] Calculated overallStatus ${newOverallStatus} for instance ${instanceId} is same as current. No update needed.`
-      );
-    }
-  }
-}
+import * as admin from "firebase-admin";
+// Import client-side Timestamp for type compatibility with shared types
+import { Timestamp as FirebaseClientTimestamp } from "@firebase/firestore";
+import {
+  PatientRequirementInstance,
+  PatientInstructionStatus,
+  PatientRequirementOverallStatus,
+  PatientRequirementInstruction,
+  PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME,
+} from "../../types/patient/patient-requirements";
+import {
+  NotificationType,
+  RequirementInstructionDueNotification,
+  NOTIFICATIONS_COLLECTION,
+  NotificationStatus,
+} from "../../types/notifications";
+import { PatientProfile, PATIENTS_COLLECTION } from "../../types/patient";
+import { UserRole } from "../../types"; // Assuming UserRole is in the main types index
+import { NotificationsAdmin } from "../notifications/notifications.admin";
+import { TimestampUtils } from "../../utils/TimestampUtils";
+
+/**
+ * @class PatientRequirementsAdminService
+ * @description Handles administrative tasks for patient requirement instances, primarily managing associated notifications.
+ * This service is intended to be used by Cloud Functions triggered by changes to PatientRequirementInstance documents.
+ */
+export class PatientRequirementsAdminService {
+  private db: admin.firestore.Firestore;
+  private notificationsAdmin: NotificationsAdmin;
+
+  constructor(firestore?: admin.firestore.Firestore) {
+    this.db = firestore || admin.firestore();
+    this.notificationsAdmin = new NotificationsAdmin(this.db);
+  }
+
+  /**
+   * Processes a newly created or updated PatientRequirementInstance to schedule notifications for its instructions.
+   * It will also cancel pre-existing notifications if due times have changed significantly.
+   *
+   * @param patientId - The ID of the patient.
+   * @param instance - The PatientRequirementInstance data (either new or updated).
+   * @param previousInstanceData - Optional. The previous state of the instance data if it's an update.
+   *                                 Used to determine if notifications need to be cancelled/rescheduled.
+   * @returns {Promise<void>} A promise that resolves when processing is complete.
+   */
+  async processRequirementInstanceAndScheduleNotifications(
+    patientId: string,
+    instance: PatientRequirementInstance,
+    previousInstanceData?: PatientRequirementInstance
+  ): Promise<void> {
+    console.log(
+      `[PRA_Service] Processing requirement instance ${instance.id} for patient ${patientId}. Overall Status: ${instance.overallStatus}`
+    );
+
+    const patientProfileRef = this.db
+      .collection(PATIENTS_COLLECTION)
+      .doc(patientId);
+    let patientExpoTokens: string[] = [];
+
+    try {
+      const patientDoc = await patientProfileRef.get();
+      if (patientDoc.exists) {
+        const patientData = patientDoc.data() as PatientProfile;
+        patientExpoTokens = patientData.expoTokens || [];
+      }
+    } catch (error) {
+      console.error(
+        `[PRA_Service] Error fetching patient ${patientId} for expo tokens:`,
+        error
+      );
+    }
+
+    if (patientExpoTokens.length === 0) {
+      console.log(
+        `[PRA_Service] Patient ${patientId} has no expo tokens. Skipping notification creation for instance ${instance.id}.`
+      );
+    }
+    // Create a new array of instruction objects to avoid mutating the original
+    // Keep original Timestamp objects by reference
+    const updatedInstructions: PatientRequirementInstruction[] =
+      instance.instructions.map((instr) => ({ ...instr }));
+    let instructionUpdatesMade = false;
+
+    for (let i = 0; i < updatedInstructions.length; i++) {
+      let currentInstruction = updatedInstructions[i];
+      const previousInstruction = previousInstanceData?.instructions.find(
+        (pi) => pi.instructionId === currentInstruction.instructionId
+      );
+      const adminTsNow = admin.firestore.Timestamp.now();
+
+      if (
+        instance.overallStatus ===
+          PatientRequirementOverallStatus.CANCELLED_APPOINTMENT ||
+        instance.overallStatus ===
+          PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE ||
+        currentInstruction.status === PatientInstructionStatus.CANCELLED
+      ) {
+        if (currentInstruction.notificationId) {
+          console.log(
+            `[PRA_Service] Cancelling notification ${currentInstruction.notificationId} for instruction ${currentInstruction.instructionId} of instance ${instance.id}.`
+          );
+          await this.notificationsAdmin.updateNotificationStatus(
+            currentInstruction.notificationId,
+            NotificationStatus.CANCELLED
+          );
+          currentInstruction = {
+            ...currentInstruction,
+            notificationId: undefined,
+            status: PatientInstructionStatus.CANCELLED,
+            updatedAt: TimestampUtils.adminToClient(
+              adminTsNow
+            ) as FirebaseClientTimestamp,
+          };
+          updatedInstructions[i] = currentInstruction;
+          instructionUpdatesMade = true;
+        }
+        continue;
+      }
+
+      const dueTimeChanged =
+        previousInstruction &&
+        currentInstruction.dueTime && // Ensure dueTime exists
+        previousInstruction.dueTime.toMillis() !==
+          currentInstruction.dueTime.toMillis();
+
+      // Simplified: if previous was CANCELLED, and we are in this part of the code,
+      // it means currentInstruction.status is NOT CANCELLED (i.e., it's active).
+      const wasPreviouslyCancelledAndNowActive =
+        previousInstruction &&
+        previousInstruction.status === PatientInstructionStatus.CANCELLED;
+
+      if (
+        previousInstruction &&
+        (dueTimeChanged || wasPreviouslyCancelledAndNowActive) && // Use the simplified variable
+        currentInstruction.notificationId
+      ) {
+        console.log(
+          `[PRA_Service] Due time changed or instruction reactivated for ${currentInstruction.instructionId}. Cancelling old notification ${currentInstruction.notificationId}.`
+        );
+        await this.notificationsAdmin.updateNotificationStatus(
+          currentInstruction.notificationId,
+          NotificationStatus.CANCELLED
+        );
+        currentInstruction = {
+          ...currentInstruction,
+          notificationId: undefined,
+          updatedAt: TimestampUtils.adminToClient(
+            adminTsNow
+          ) as FirebaseClientTimestamp,
+        };
+        updatedInstructions[i] = currentInstruction;
+        instructionUpdatesMade = true;
+      }
+
+      const shouldSchedule =
+        currentInstruction.dueTime && // Ensure dueTime exists
+        currentInstruction.status ===
+          PatientInstructionStatus.PENDING_NOTIFICATION &&
+        !currentInstruction.notificationId &&
+        currentInstruction.dueTime.toMillis() > adminTsNow.toMillis() &&
+        patientExpoTokens.length > 0;
+
+      if (shouldSchedule) {
+        console.log(
+          `[PRA_Service] Scheduling notification for instruction ${
+            currentInstruction.instructionId
+          } of instance ${
+            instance.id
+          } at ${currentInstruction.dueTime.toDate()}.`
+        );
+
+        const notificationPayload: Omit<
+          RequirementInstructionDueNotification,
+          "id" | "createdAt" | "updatedAt" | "status" | "isRead"
+        > = {
+          userId: patientId,
+          userRole: UserRole.PATIENT,
+          notificationType: NotificationType.REQUIREMENT_INSTRUCTION_DUE,
+          notificationTime: currentInstruction.dueTime as any, // dueTime should be an admin.firestore.Timestamp already
+          notificationTokens: patientExpoTokens,
+          title: `Reminder: ${instance.requirementName}`,
+          body: currentInstruction.instructionText,
+          appointmentId: instance.appointmentId,
+          patientRequirementInstanceId: instance.id,
+          instructionId: currentInstruction.instructionId,
+          originalRequirementId: instance.originalRequirementId,
+        };
+
+        try {
+          const createdNotificationId =
+            await this.notificationsAdmin.createNotification(
+              notificationPayload as any
+            );
+          currentInstruction = {
+            ...currentInstruction,
+            notificationId: createdNotificationId,
+            status: PatientInstructionStatus.PENDING_NOTIFICATION,
+            updatedAt: TimestampUtils.adminToClient(
+              adminTsNow
+            ) as FirebaseClientTimestamp,
+          };
+          updatedInstructions[i] = currentInstruction;
+          instructionUpdatesMade = true;
+        } catch (error) {
+          console.error(
+            `[PRA_Service] Failed to create notification for instruction ${currentInstruction.instructionId}:`,
+            error
+          );
+        }
+      }
+    }
+
+    if (instructionUpdatesMade) {
+      console.log(
+        `[PRA_Service] Updating instructions array for instance ${instance.id} on patient ${patientId}.`
+      );
+      const instanceDocRef = this.db
+        .collection(PATIENTS_COLLECTION)
+        .doc(patientId)
+        .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
+        .doc(instance.id);
+
+      const finalAdminTsNow = admin.firestore.Timestamp.now();
+      await instanceDocRef.update({
+        instructions: updatedInstructions, // Array of instructions with actual Timestamps
+        updatedAt: TimestampUtils.adminToClient(
+          finalAdminTsNow
+        ) as FirebaseClientTimestamp,
+      });
+    }
+  }
+
+  /**
+   * Cancels all PENDING notifications associated with a specific PatientRequirementInstance.
+   * Typically called when the instance itself is deleted or its overall status becomes CANCELLED.
+   *
+   * @param instance - The PatientRequirementInstance.
+   * @returns {Promise<void>}
+   */
+  async cancelAllNotificationsForInstance(
+    instance: PatientRequirementInstance
+  ): Promise<void> {
+    console.log(
+      `[PRA_Service] Attempting to cancel all pending notifications for instance ${instance.id}.`
+    );
+    let cancelledCount = 0;
+    for (const instruction of instance.instructions) {
+      if (instruction.notificationId) {
+        try {
+          const notification = await this.notificationsAdmin.getNotification(
+            instruction.notificationId
+          );
+          if (
+            notification &&
+            notification.status === NotificationStatus.PENDING
+          ) {
+            await this.notificationsAdmin.updateNotificationStatus(
+              instruction.notificationId,
+              NotificationStatus.CANCELLED
+            );
+            console.log(
+              `[PRA_Service] Cancelled notification ${instruction.notificationId} for instruction ${instruction.instructionId}.`
+            );
+            cancelledCount++;
+          } else if (notification) {
+            console.log(
+              `[PRA_Service] Notification ${instruction.notificationId} for instruction ${instruction.instructionId} was not pending (status: ${notification.status}). Not cancelling.`
+            );
+          }
+        } catch (error) {
+          console.error(
+            `[PRA_Service] Error cancelling notification ${instruction.notificationId}:`,
+            error
+          );
+        }
+      }
+    }
+    if (cancelledCount > 0) {
+      console.log(
+        `[PRA_Service] Cancelled ${cancelledCount} notifications for instance ${instance.id}.`
+      );
+    }
+  }
+
+  /**
+   * (Optional - For a cron job)
+   * Scans for instructions that are past their due time but not yet actioned, and updates their status to MISSED.
+   * This would typically be called by a scheduled Cloud Function.
+   *
+   * @param patientId - The ID of the patient.
+   * @param instanceId - The ID of the PatientRequirementInstance.
+   * @returns {Promise<void>}
+   */
+  async updateMissedInstructions(
+    patientId: string,
+    instanceId: string
+  ): Promise<void> {
+    const instanceRef = this.db
+      .collection(PATIENTS_COLLECTION)
+      .doc(patientId)
+      .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
+      .doc(instanceId);
+
+    const instanceSnap = await instanceRef.get();
+    if (!instanceSnap.exists) {
+      console.warn(
+        `[PRA_Service] Instance ${instanceId} not found during missed check for patient ${patientId}.`
+      );
+      return;
+    }
+
+    const instance = instanceSnap.data() as PatientRequirementInstance;
+    const adminNowForMissed = admin.firestore.Timestamp.now();
+
+    // Create a new array of instruction objects to avoid mutating the original
+    const updatedInstructions: PatientRequirementInstruction[] =
+      instance.instructions.map((instr) => ({ ...instr }));
+    let changesMade = false;
+
+    for (let i = 0; i < updatedInstructions.length; i++) {
+      let currentInstruction = updatedInstructions[i];
+      if (
+        currentInstruction.dueTime && // Ensure dueTime exists
+        (currentInstruction.status ===
+          PatientInstructionStatus.PENDING_NOTIFICATION ||
+          currentInstruction.status === PatientInstructionStatus.ACTION_DUE) &&
+        currentInstruction.dueTime.toMillis() < adminNowForMissed.toMillis()
+      ) {
+        currentInstruction = {
+          ...currentInstruction,
+          status: PatientInstructionStatus.MISSED,
+          updatedAt: TimestampUtils.adminToClient(
+            adminNowForMissed
+          ) as FirebaseClientTimestamp,
+        };
+        updatedInstructions[i] = currentInstruction;
+        changesMade = true;
+        console.log(
+          `[PRA_Service] Marked instruction ${currentInstruction.instructionId} in instance ${instanceId} as MISSED.`
+        );
+      }
+    }
+
+    if (changesMade) {
+      const finalAdminNowForMissedUpdate = admin.firestore.Timestamp.now();
+      await instanceRef.update({
+        instructions: updatedInstructions, // Array of instructions with actual Timestamps
+        updatedAt: TimestampUtils.adminToClient(
+          finalAdminNowForMissedUpdate
+        ) as FirebaseClientTimestamp,
+      });
+      console.log(
+        `[PRA_Service] Updated missed instructions for instance ${instanceId}.`
+      );
+    }
+  }
+
+  /**
+   * Calculates and updates the overallStatus of a PatientRequirementInstance
+   * based on the statuses of its individual instructions.
+   *
+   * @param patientId - The ID of the patient.
+   * @param instanceId - The ID of the PatientRequirementInstance to update.
+   * @returns {Promise<void>} A promise that resolves when processing is complete.
+   */
+  async updateOverallInstanceStatus(
+    patientId: string,
+    instanceId: string
+  ): Promise<void> {
+    const instanceRef = this.db
+      .collection(PATIENTS_COLLECTION)
+      .doc(patientId)
+      .collection(PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME)
+      .doc(instanceId);
+
+    const instanceSnap = await instanceRef.get();
+    if (!instanceSnap.exists) {
+      console.warn(
+        `[PRA_Service] Instance ${instanceId} not found while trying to update overall status for patient ${patientId}.`
+      );
+      return;
+    }
+
+    const instance = instanceSnap.data() as PatientRequirementInstance;
+
+    // Do not override terminal statuses set by other processes
+    if (
+      instance.overallStatus ===
+        PatientRequirementOverallStatus.CANCELLED_APPOINTMENT ||
+      instance.overallStatus ===
+        PatientRequirementOverallStatus.SUPERSEDED_RESCHEDULE ||
+      instance.overallStatus ===
+        PatientRequirementOverallStatus.FAILED_TO_PROCESS // Assuming FAILED_TO_PROCESS is also a terminal state set by other means if it's a hard failure.
+    ) {
+      console.log(
+        `[PRA_Service] Instance ${instanceId} has overallStatus ${instance.overallStatus}, skipping overall status update based on instruction completion logic.`
+      );
+      return;
+    }
+
+    const nonCancelledInstructions = instance.instructions.filter(
+      (instr) => instr.status !== PatientInstructionStatus.CANCELLED
+    );
+
+    if (nonCancelledInstructions.length === 0) {
+      // If all instructions are cancelled or there are no instructions.
+      // If it was previously something like ALL_INSTRUCTIONS_MET, it should revert to ACTIVE or a default.
+      if (instance.overallStatus !== PatientRequirementOverallStatus.ACTIVE) {
+        console.log(
+          `[PRA_Service] Instance ${instanceId} has no active (non-cancelled) instructions. Setting to ACTIVE.`
+        );
+        await instanceRef.update({
+          overallStatus: PatientRequirementOverallStatus.ACTIVE,
+          updatedAt: TimestampUtils.adminToClient(
+            admin.firestore.Timestamp.now()
+          ) as FirebaseClientTimestamp,
+        });
+      }
+      return;
+    }
+
+    // Check if any instruction is still pending action by the patient
+    const hasPendingOrDueInstructions = nonCancelledInstructions.some(
+      (instr) =>
+        instr.status === PatientInstructionStatus.PENDING_NOTIFICATION ||
+        instr.status === PatientInstructionStatus.ACTION_DUE
+    );
+
+    let newOverallStatus: PatientRequirementOverallStatus;
+
+    if (hasPendingOrDueInstructions) {
+      newOverallStatus = PatientRequirementOverallStatus.ACTIVE;
+    } else {
+      // All non-cancelled instructions are in a "resolved" state (ACTION_TAKEN, MISSED, SKIPPED)
+      const effectivelyCompletedCount = nonCancelledInstructions.filter(
+        (instr) =>
+          instr.status === PatientInstructionStatus.ACTION_TAKEN ||
+          instr.status === PatientInstructionStatus.SKIPPED
+      ).length;
+
+      const totalNonCancelled = nonCancelledInstructions.length;
+      const completionPercentage =
+        (effectivelyCompletedCount / totalNonCancelled) * 100;
+
+      if (completionPercentage === 100) {
+        newOverallStatus = PatientRequirementOverallStatus.ALL_INSTRUCTIONS_MET;
+      } else if (completionPercentage >= 60) {
+        // Changed from >60 to >=60 as per common understanding of "more than 60%" often including 60%
+        newOverallStatus = PatientRequirementOverallStatus.PARTIALLY_COMPLETED;
+      } else {
+        // Less than 60% effectively completed (could include some MISSED ones not blocking this calculation directly)
+        // Or if all are MISSED, this would also fall here if FAILED_TO_PROCESS isn't set for other reasons.
+        // Your logic: "if less then 60% of instructions are action taken or skipped, then we move status to failed"
+        newOverallStatus = PatientRequirementOverallStatus.FAILED_TO_PROCESS;
+      }
+    }
+
+    if (newOverallStatus !== instance.overallStatus) {
+      console.log(
+        `[PRA_Service] Updating overallStatus for instance ${instanceId} from ${instance.overallStatus} to ${newOverallStatus}.`
+      );
+      const adminTsNow = admin.firestore.Timestamp.now();
+      await instanceRef.update({
+        overallStatus: newOverallStatus,
+        updatedAt: TimestampUtils.adminToClient(
+          adminTsNow
+        ) as FirebaseClientTimestamp,
+      });
+    } else {
+      console.log(
+        `[PRA_Service] Calculated overallStatus ${newOverallStatus} for instance ${instanceId} is same as current. No update needed.`
+      );
+    }
+  }
+}