@blackcode_sa/metaestetics-api 1.6.3 → 1.6.5

package/src/admin/booking/booking.admin.ts

@@ -1,4 +1,5 @@
 import * as admin from "firebase-admin";
+import { Timestamp as FirebaseClientTimestamp } from "@firebase/firestore";
 import {
   BookingAvailabilityCalculator,
   BookingAvailabilityRequest,
@@ -6,9 +7,57 @@ import {
   AvailableSlot,
 } from "./";
 import { CalendarEventStatus, CalendarEventType } from "../../types/calendar";
-import { Clinic } from "../../types/clinic";
-import { Practitioner } from "../../types/practitioner";
-import { Procedure } from "../../types/procedure";
+import {
+  Clinic,
+  CLINICS_COLLECTION,
+  ClinicGroup,
+  CLINIC_GROUPS_COLLECTION,
+} from "../../types/clinic";
+import {
+  Practitioner,
+  PRACTITIONERS_COLLECTION,
+} from "../../types/practitioner";
+import {
+  Procedure,
+  PROCEDURES_COLLECTION,
+  ProcedureSummaryInfo,
+} from "../../types/procedure";
+import {
+  PatientProfile,
+  PATIENTS_COLLECTION,
+  PatientSensitiveInfo,
+  PATIENT_SENSITIVE_INFO_COLLECTION,
+  Gender,
+} from "../../types/patient";
+import {
+  Appointment,
+  AppointmentStatus,
+  PaymentStatus,
+  APPOINTMENTS_COLLECTION,
+  ProcedureExtendedInfo,
+} from "../../types/appointment";
+import { Currency } from "../../backoffice/types/static/pricing.types";
+import { DocumentTemplate } from "../../types/documentation-templates";
+import {
+  ClinicInfo,
+  PractitionerProfileInfo,
+  PatientProfileInfo,
+} from "../../types/profile";
+import { Category } from "../../backoffice/types/category.types";
+import { Subcategory } from "../../backoffice/types/subcategory.types";
+import { Technology } from "../../backoffice/types/technology.types";
+import { Product } from "../../backoffice/types/product.types";
+
+/**
+ * Interface for the data required by orchestrateAppointmentCreation
+ */
+export interface OrchestrateAppointmentCreationData {
+  patientId: string;
+  procedureId: string;
+  appointmentStartTime: admin.firestore.Timestamp;
+  appointmentEndTime: admin.firestore.Timestamp;
+  patientNotes?: string | null;
+}
 
 /**
  * Admin service for handling booking-related operations.
@@ -231,4 +280,328 @@ export class BookingAdmin {
       return [];
     }
   }
+
+  /**
+   * Orchestrates the creation of a new appointment, including data aggregation.
+   * This method is intended to be called from a trusted backend environment (e.g., an Express route handler in a Cloud Function).
+   *
+   * @param data - Data required to create the appointment.
+   * @param authenticatedUserId - The ID of the user making the request (for auditing, and usually is the patientId).
+   * @returns Promise resolving to an object indicating success, and appointmentId or an error message.
+   */
+  async orchestrateAppointmentCreation(
+    data: OrchestrateAppointmentCreationData,
+    authenticatedUserId: string
+  ): Promise<{
+    success: boolean;
+    appointmentId?: string;
+    appointmentData?: Appointment;
+    error?: string;
+  }> {
+    console.log(
+      `[BookingAdmin] Orchestrating appointment creation for patient ${data.patientId} by user ${authenticatedUserId}`
+    );
+
+    try {
+      // --- 1. Input Validation ---
+      if (
+        !data.patientId ||
+        !data.procedureId ||
+        !data.appointmentStartTime ||
+        !data.appointmentEndTime
+      ) {
+        return {
+          success: false,
+          error:
+            "Missing required fields: patientId, procedureId, appointmentStartTime, or appointmentEndTime.",
+        };
+      }
+      if (
+        data.appointmentEndTime.toMillis() <=
+        data.appointmentStartTime.toMillis()
+      ) {
+        return {
+          success: false,
+          error: "Appointment end time must be after start time.",
+        };
+      }
+      if (authenticatedUserId !== data.patientId) {
+        console.warn(
+          `[BookingAdmin] Authenticated user ${authenticatedUserId} is booking for a different patient ${data.patientId}. Review authorization if this is not intended.`
+        );
+      }
+
+      // --- 2. Fetch Core Procedure Data ---
+      const procedureRef = this.db
+        .collection(PROCEDURES_COLLECTION)
+        .doc(data.procedureId);
+      const procedureDoc = await procedureRef.get();
+      if (!procedureDoc.exists) {
+        return {
+          success: false,
+          error: `Procedure ${data.procedureId} not found.`,
+        };
+      }
+      const procedure = procedureDoc.data() as Procedure;
+
+      // --- 3. Fetch Clinic and then other Primary Documents ---
+      // Fetch clinic first to get its clinicGroupId
+      const clinicRef = this.db
+        .collection(CLINICS_COLLECTION)
+        .doc(procedure.clinicBranchId);
+      const clinicSnap = await clinicRef.get(); // Await here directly
+      if (!clinicSnap.exists) {
+        return {
+          success: false,
+          error: `Clinic ${procedure.clinicBranchId} not found.`,
+        };
+      }
+      const clinicData = clinicSnap.data() as Clinic; // Now clinicData is available
+
+      // Define other refs using clinicData for clinicGroupRef
+      const practitionerRef = this.db
+        .collection(PRACTITIONERS_COLLECTION)
+        .doc(procedure.practitionerId);
+      const patientProfileRef = this.db
+        .collection(PATIENTS_COLLECTION)
+        .doc(data.patientId);
+      const patientSensitiveRef = this.db
+        .collection(PATIENTS_COLLECTION)
+        .doc(data.patientId)
+        .collection(PATIENT_SENSITIVE_INFO_COLLECTION)
+        .doc(data.patientId);
+      const clinicGroupRef = this.db
+        .collection(CLINIC_GROUPS_COLLECTION)
+        .doc(clinicData.clinicGroupId); // Use clinicData here
+
+      const [
+        practitionerSnap,
+        patientProfileSnap,
+        patientSensitiveSnap,
+        clinicGroupSnap,
+      ] = await Promise.all([
+        // clinicRef.get() is already done via clinicSnap
+        practitionerRef.get(),
+        patientProfileRef.get(),
+        patientSensitiveRef.get(),
+        clinicGroupRef.get(), // Fetch the defined clinicGroupRef
+      ]);
+
+      if (!practitionerSnap.exists)
+        return {
+          success: false,
+          error: `Practitioner ${procedure.practitionerId} not found.`,
+        };
+      if (!patientProfileSnap.exists)
+        return {
+          success: false,
+          error: `PatientProfile ${data.patientId} not found.`,
+        };
+      if (!clinicGroupSnap.exists)
+        return {
+          success: false,
+          error: `ClinicGroup for clinic ${procedure.clinicBranchId} not found.`,
+        };
+
+      const practitionerData = practitionerSnap.data() as Practitioner;
+      const patientProfileData = patientProfileSnap.data() as PatientProfile;
+      const patientSensitiveData = patientSensitiveSnap.exists
+        ? (patientSensitiveSnap.data() as PatientSensitiveInfo)
+        : undefined;
+      const clinicGroupData = clinicGroupSnap.data() as ClinicGroup;
+
+      // --- 4. Determine initialStatus (based on clinic settings) ---
+      const autoConfirm = clinicGroupData.autoConfirmAppointments || false;
+      const initialStatus = autoConfirm
+        ? AppointmentStatus.CONFIRMED
+        : AppointmentStatus.PENDING;
+
+      // --- 5. Aggregate Information (Snapshots) ---
+      const clinicInfo: ClinicInfo = {
+        id: clinicSnap.id,
+        name: clinicData.name,
+        featuredPhoto: clinicData.coverPhoto || clinicData.logo || "",
+        description: clinicData.description,
+        location: clinicData.location,
+        contactInfo: clinicData.contactInfo,
+      };
+      const practitionerInfo: PractitionerProfileInfo = {
+        id: practitionerSnap.id,
+        practitionerPhoto: practitionerData.basicInfo.profileImageUrl || null,
+        name: `${practitionerData.basicInfo.firstName} ${practitionerData.basicInfo.lastName}`,
+        email: practitionerData.basicInfo.email,
+        phone: practitionerData.basicInfo.phoneNumber || null,
+        certification: practitionerData.certification,
+      };
+      const patientInfo: PatientProfileInfo = {
+        id: patientProfileSnap.id,
+        fullName:
+          `${patientSensitiveData?.firstName || ""} ${
+            patientSensitiveData?.lastName || ""
+          }`.trim() || patientProfileData.displayName,
+        email: patientSensitiveData?.email || "",
+        phone:
+          patientSensitiveData?.phoneNumber ||
+          patientProfileData.phoneNumber ||
+          null,
+        dateOfBirth:
+          patientSensitiveData?.dateOfBirth ||
+          patientProfileData.dateOfBirth ||
+          admin.firestore.Timestamp.now(),
+        gender: patientSensitiveData?.gender || Gender.OTHER,
+      };
+      const procedureCategory = procedure.category as Category;
+      const procedureSubCategory = procedure.subcategory as Subcategory;
+      const procedureTechnology = procedure.technology as Technology;
+      const procedureProduct = procedure.product as Product;
+
+      const procedureInfo: ProcedureSummaryInfo = {
+        id: procedure.id,
+        name: procedure.name,
+        description: procedure.description,
+        family: procedure.family,
+        categoryName: procedureCategory?.name || "",
+        subcategoryName: procedureSubCategory?.name || "",
+        technologyName: procedureTechnology?.name || "",
+        price: procedure.price,
+        pricingMeasure: procedure.pricingMeasure,
+        currency: procedure.currency,
+        duration: procedure.duration,
+        clinicId: procedure.clinicBranchId,
+        clinicName: clinicData.name,
+        practitionerId: procedure.practitionerId,
+        practitionerName: `${practitionerData.basicInfo.firstName} ${practitionerData.basicInfo.lastName}`,
+        photo: procedure.photos?.[0] || "",
+        brandName: procedureProduct?.brandName || "",
+        productName: procedureProduct?.name || "",
+      };
+      const procedureExtendedInfo: ProcedureExtendedInfo = {
+        id: procedure.id,
+        name: procedure.name,
+        description: procedure.description,
+        cost: procedure.price,
+        duration: procedure.duration,
+        procedureFamily: procedure.family,
+        procedureCategoryId: procedureCategory?.id || "",
+        procedureCategoryName: procedureCategory?.name || "",
+        procedureSubCategoryId: procedureSubCategory?.id || "",
+        procedureSubCategoryName: procedureSubCategory?.name || "",
+        procedureTechnologyId: procedureTechnology?.id || "",
+        procedureTechnologyName: procedureTechnology?.name || "",
+        procedureProductBrandId: procedureProduct.brandId || "",
+        procedureProductBrandName: procedureProduct.brandName || "",
+        procedureProductId: procedureProduct.id || "",
+        procedureProductName: procedureProduct.name || "",
+      };
+
+      // --- 6. Determine pendingUserFormsIds and linkedFormIds ---
+      let pendingUserFormsIds: string[] = [];
+      let linkedFormIds: string[] = [];
+      if (
+        procedure.documentationTemplates &&
+        Array.isArray(procedure.documentationTemplates)
+      ) {
+        pendingUserFormsIds = procedure.documentationTemplates
+          .filter(
+            (template: DocumentTemplate) =>
+              template.isUserForm && template.isRequired
+          )
+          .map((template: DocumentTemplate) => template.id);
+        linkedFormIds = procedure.documentationTemplates.map(
+          (template: DocumentTemplate) => template.id
+        );
+      }
+
+      // --- 7. Construct New Appointment Object ---
+      const newAppointmentId = this.db
+        .collection(APPOINTMENTS_COLLECTION)
+        .doc().id;
+      const serverTimestampValue = admin.firestore.FieldValue.serverTimestamp();
+      const adminTsNow = admin.firestore.Timestamp.now();
+
+      const newAppointmentData: Appointment = {
+        id: newAppointmentId,
+        calendarEventId: "",
+        clinicBranchId: procedure.clinicBranchId,
+        clinicInfo,
+        practitionerId: procedure.practitionerId,
+        practitionerInfo,
+        patientId: data.patientId,
+        patientInfo,
+        procedureId: data.procedureId,
+        procedureInfo,
+        procedureExtendedInfo,
+        status: initialStatus,
+        bookingTime: serverTimestampValue as any,
+        confirmationTime:
+          initialStatus === AppointmentStatus.CONFIRMED
+            ? (serverTimestampValue as any)
+            : null,
+        appointmentStartTime: new FirebaseClientTimestamp(
+          data.appointmentStartTime.seconds,
+          data.appointmentStartTime.nanoseconds
+        ),
+        appointmentEndTime: new FirebaseClientTimestamp(
+          data.appointmentEndTime.seconds,
+          data.appointmentEndTime.nanoseconds
+        ),
+        cost: procedure.price,
+        currency: procedure.currency,
+        paymentStatus:
+          procedure.price > 0
+            ? PaymentStatus.UNPAID
+            : PaymentStatus.NOT_APPLICABLE,
+        patientNotes: data.patientNotes || null,
+        blockingConditions: procedure.blockingConditions || [],
+        contraindications: procedure.contraindications || [],
+        preProcedureRequirements: procedure.preRequirements || [],
+        postProcedureRequirements: procedure.postRequirements || [],
+        pendingUserFormsIds: pendingUserFormsIds,
+        completedPreRequirements: [],
+        completedPostRequirements: [],
+        linkedFormIds: linkedFormIds,
+        linkedForms: [],
+        media: [],
+        reviewInfo: null,
+        finalizedDetails: undefined,
+        internalNotes: null,
+        cancellationReason: null,
+        cancellationTime: null,
+        canceledBy: undefined,
+        rescheduleTime: null,
+        procedureActualStartTime: null,
+        actualDurationMinutes: undefined,
+        isRecurring: false,
+        recurringAppointmentId: null,
+        isArchived: false,
+        createdAt: serverTimestampValue as any,
+        updatedAt: serverTimestampValue as any,
+      };
+
+      // --- 8. Save New Appointment ---
+      await this.db
+        .collection(APPOINTMENTS_COLLECTION)
+        .doc(newAppointmentId)
+        .set(newAppointmentData);
+
+      console.log(
+        `[BookingAdmin] Appointment ${newAppointmentId} created successfully with status ${initialStatus}.`
+      );
+      return {
+        success: true,
+        appointmentId: newAppointmentId,
+        appointmentData: newAppointmentData,
+      };
+    } catch (error) {
+      console.error(
+        "[BookingAdmin] Critical error in orchestrateAppointmentCreation:",
+        error
+      );
+      const errorMessage =
+        error instanceof Error
+          ? error.message
+          : "Unknown server error during appointment creation.";
+      return { success: false, error: errorMessage };
+    }
+  }
 }

package/src/admin/index.ts

@@ -30,6 +30,9 @@ import { PractitionerInviteMailingService } from "./mailing/practitionerInvite/p
 // Import booking services
 import { BookingAdmin } from "./booking/booking.admin";
 
+// Import patient requirements services
+import { PatientRequirementsAdminService } from "./requirements/patient-requirements.admin.service";
+
 // Re-export types
 export type {
   Notification,
@@ -37,7 +40,6 @@ export type {
   PreRequirementNotification,
   PostRequirementNotification,
   AppointmentReminderNotification,
-  AppointmentNotification,
 } from "../types/notifications";
 
 // Re-export types needed by cloud functions
@@ -64,6 +66,7 @@ export {
   PractitionerAggregationService,
   ProcedureAggregationService,
   PatientAggregationService,
+  PatientRequirementsAdminService,
 };
 
 // Export mailing services
@@ -75,6 +78,17 @@ export { BookingAdmin };
 // Also export booking types
 export * from "./booking/booking.types";
 
+// Re-export types needed by admin services that might not be covered by general type exports
+export type {
+  PatientRequirementInstance,
+  PatientRequirementInstruction,
+} from "../types/patient/patient-requirements";
+export {
+  PatientInstructionStatus,
+  PatientRequirementOverallStatus,
+  PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME,
+} from "../types/patient/patient-requirements";
+
 /**
  * Main entry point for the Admin module.
  * This module contains services and utilities intended for administrative tasks,

package/src/admin/notifications/notifications.admin.ts

@@ -56,7 +56,7 @@ export class NotificationsAdmin {
   /**
    * Ažurira status notifikacije
    */
-  private async updateNotificationStatus(
+  public async updateNotificationStatus(
     notificationId: string,
     status: NotificationStatus,
     error?: string

package/src/admin/requirements/README.md

@@ -0,0 +1,128 @@
+# Patient Requirements Admin Service (`patient-requirements.admin.service.ts`)
+
+## Overview
+
+The `PatientRequirementsAdminService` is a backend service responsible for managing administrative tasks related to `PatientRequirementInstance` documents, primarily focusing on the lifecycle of associated patient notifications. This service is designed to be primarily invoked by Cloud Functions that trigger on Create, Update, and Delete events of `PatientRequirementInstance` documents in Firestore.
+
+It ensures that patients receive timely notifications for instructions they need to follow before an appointment and that these notifications are appropriately updated or cancelled if the appointment or requirement details change.
+
+## Core Dependencies
+
+- **Firebase Admin SDK**: For interacting with Firestore.
+- **`NotificationsAdmin` Service**: For creating, fetching, and updating notification documents.
+- **Shared Types**: Uses types defined in `Api/src/types/` for `PatientRequirementInstance`, `PatientInstruction`, `Notification`, `PatientProfile`, etc., ensuring consistency across the application. This includes using client-side `Timestamp` types (`@firebase/firestore.Timestamp`) for data stored in Firestore documents that are also accessed by the client.
+
+## Methods
+
+### 1. `constructor(firestore?: admin.firestore.Firestore)`
+
+- **Purpose**: Initializes the service.
+- **Parameters**:
+  - `firestore` (optional): An instance of `admin.firestore.Firestore`. If not provided, it initializes a new default instance.
+- **Core Logic**:
+  1.  Sets up the Firestore database connection (`this.db`).
+  2.  Initializes an instance of the `NotificationsAdmin` service (`this.notificationsAdmin`), passing the Firestore instance to it.
+
+### 2. `async processRequirementInstanceAndScheduleNotifications(patientId: string, instance: PatientRequirementInstance, previousInstanceData?: PatientRequirementInstance)`
+
+- **Purpose**: This is the primary method for handling the creation and updates of a `PatientRequirementInstance`. It iterates through the instructions within the instance, schedules new notifications, cancels outdated ones, and updates the instruction statuses and notification IDs within the `PatientRequirementInstance` document.
+- **Parameters**:
+  - `patientId: string`: The ID of the patient to whom the requirement instance belongs.
+  - `instance: PatientRequirementInstance`: The current (new or updated) data of the patient requirement instance.
+  - `previousInstanceData?: PatientRequirementInstance` (optional): The state of the instance _before_ the current change. This is crucial for determining if due times have changed or if instructions were cancelled/reactivated, necessitating changes to existing notifications.
+- **Core Logic Flow**:
+  1.  **Fetch Patient Expo Tokens**: Retrieves the patient's Expo push notification tokens from their `PatientProfile`. If no tokens are found, notification scheduling for that patient is skipped.
+  2.  **Iterate Through Instructions**: Loops through each `PatientRequirementInstruction` in the `instance.instructions` array.
+      - A copy of the instructions array (`updatedInstructions`) is made to track changes without mutating the input directly.
+  3.  **Handle Cancelled/Superseded Instances/Instructions**:
+      - If the overall `instance.overallStatus` indicates a cancelled appointment or a superseded reschedule, or if an individual `currentInstruction.status` is `CANCELLED`:
+        - If the instruction had an existing `notificationId`, calls `this.notificationsAdmin.updateNotificationStatus()` to set the notification's status to `CANCELLED`.
+        - Updates the `currentInstruction`'s `notificationId` to `undefined` and its `status` to `CANCELLED`.
+        - Marks that `instructionUpdatesMade` is `true`.
+  4.  **Handle Reschedules/Reactivations for Existing Notifications**:
+      - Compares `currentInstruction` with `previousInstruction` (if available).
+      - Determines if `dueTimeChanged` or if the instruction `wasPreviouslyCancelledAndNowActive`.
+      - If either is true AND the `currentInstruction` has a `notificationId` (meaning an old notification exists):
+        - Cancels the old notification using `this.notificationsAdmin.updateNotificationStatus()`.
+        - Clears `currentInstruction.notificationId`.
+        - Marks `instructionUpdatesMade` as `true`.
+  5.  **Schedule New Notifications**:
+      - Checks if a notification `shouldSchedule` for the `currentInstruction`:
+        - Instruction status must be `PENDING_NOTIFICATION`.
+        - No existing `notificationId`.
+        - `dueTime` must be in the future.
+        - Patient must have Expo tokens.
+      - If `shouldSchedule` is true:
+        - Constructs a `notificationPayload` for a `RequirementInstructionDueNotification`.
+        - Calls `this.notificationsAdmin.createNotification()` to create the notification document.
+        - Updates `currentInstruction` with the new `notificationId` and ensures its status is `PENDING_NOTIFICATION`.
+        - Marks `instructionUpdatesMade` as `true`.
+  6.  **Update Firestore Document**:
+      - If `instructionUpdatesMade` is `true` (meaning any instruction's notification details or status changed):
+        - Updates the `PatientRequirementInstance` document in Firestore with the `updatedInstructions` array and sets its `updatedAt` timestamp.
+        - Ensures all `updatedAt` (and other Timestamp fields) within `updatedInstructions` and for the main instance are converted to `FirebaseClientTimestamp` for compatibility with shared types.
+- **Usage Context**:
+  - Triggered by a Cloud Function on **create** of a `PatientRequirementInstance`.
+  - Triggered by a Cloud Function on **update** of a `PatientRequirementInstance`. The Cloud Function should provide both the new and previous data of the instance.
+
+### 3. `async cancelAllNotificationsForInstance(instance: PatientRequirementInstance)`
+
+- **Purpose**: To cancel all _pending_ notifications associated with a given `PatientRequirementInstance`. This is typically used when an entire instance is hard-deleted or unequivocally cancelled in a way not covered by status changes processed by `processRequirementInstanceAndScheduleNotifications`.
+- **Parameters**:
+  - `instance: PatientRequirementInstance`: The requirement instance whose notifications need to be cancelled.
+- **Core Logic Flow**:
+  1.  Iterates through each instruction in `instance.instructions`.
+  2.  If an instruction has a `notificationId`:
+      - Fetches the notification using `this.notificationsAdmin.getNotification()`.
+      - If the notification exists and its status is `PENDING`:
+        - Calls `this.notificationsAdmin.updateNotificationStatus()` to set its status to `CANCELLED`.
+- **Usage Context**:
+  - Triggered by a Cloud Function on **delete** of a `PatientRequirementInstance`.
+  - Can also be invoked if an instance's overall status changes to a terminal "cancelled" state that requires immediate cessation of all related pending notifications.
+
+### 4. `async updateMissedInstructions(patientId: string, instanceId: string)`
+
+- **Purpose**: (Optional utility, typically for a cron job) Scans instructions within a specific `PatientRequirementInstance` that are past their `dueTime` but have not yet been actioned (i.e., status is `PENDING_NOTIFICATION` or `ACTION_DUE`). It updates their status to `MISSED`.
+- **Parameters**:
+  - `patientId: string`: The ID of the patient.
+  - `instanceId: string`: The ID of the `PatientRequirementInstance` to check.
+- **Core Logic Flow**:
+  1.  Fetches the specified `PatientRequirementInstance` document.
+  2.  If not found, logs a warning and exits.
+  3.  Iterates through each instruction in the instance.
+  4.  If an instruction's `dueTime` is in the past AND its status is `PENDING_NOTIFICATION` or `ACTION_DUE`:
+      - Updates the instruction's `status` to `MISSED`.
+      - Sets the instruction's `updatedAt` timestamp (converted to `FirebaseClientTimestamp`).
+      - Marks that `changesMade` is `true`.
+  5.  If `changesMade` is `true`:
+      - Updates the `PatientRequirementInstance` document in Firestore with the modified instructions and sets its main `updatedAt` timestamp (converted to `FirebaseClientTimestamp`).
+- **Usage Context**:
+  - Intended to be called by a scheduled Cloud Function (e.g., a daily cron job) to perform cleanup and status updates for instructions that were not completed by their due date.
+
+### 5. `async updateOverallInstanceStatus(patientId: string, instanceId: string)`
+
+- **Purpose**: Calculates and updates the `overallStatus` of a `PatientRequirementInstance` based on the collective statuses of its individual, non-cancelled instructions. This helps reflect the true completion state of the entire requirement set.
+- **Parameters**:
+  - `patientId: string`: The ID of the patient to whom the requirement instance belongs.
+  - `instanceId: string`: The ID of the `PatientRequirementInstance` to update.
+- **Core Logic Flow**:
+  1.  **Fetch Instance**: Retrieves the specified `PatientRequirementInstance`.
+  2.  **Check Terminal States**: If the current `instance.overallStatus` is already `CANCELLED_APPOINTMENT`, `SUPERSEDED_RESCHEDULE`, or `FAILED_TO_PROCESS`, the function logs this and exits, as these are considered final states not to be overridden by this logic.
+  3.  **Handle No Active Instructions**: Filters out any instructions with a status of `CANCELLED`. If no non-cancelled instructions remain:
+      - Sets the `overallStatus` to `ACTIVE` (if not already) and updates Firestore. This acts as a default if an instance becomes empty of actionable items.
+  4.  **Check for Pending/Due Instructions**: Iterates through the non-cancelled instructions. If any instruction has a status of `PENDING_NOTIFICATION` or `ACTION_DUE`:
+      - The `newOverallStatus` is determined to be `ACTIVE`.
+  5.  **All Instructions Resolved**: If no instructions are `PENDING_NOTIFICATION` or `ACTION_DUE` (meaning all non-cancelled instructions are in a "resolved" state: `ACTION_TAKEN`, `MISSED`, or `SKIPPED`):
+      - Counts `effectivelyCompletedCount` (non-cancelled instructions that are `ACTION_TAKEN` or `SKIPPED`).
+      - Calculates `completionPercentage = (effectivelyCompletedCount / totalNonCancelledInstructions) * 100`.
+      - If `completionPercentage === 100%`, `newOverallStatus` is `ALL_INSTRUCTIONS_MET`.
+      - Else if `completionPercentage >= 60%`, `newOverallStatus` is `PARTIALLY_COMPLETED`.
+      - Else (`completionPercentage < 60%`), `newOverallStatus` is `FAILED_TO_PROCESS`.
+  6.  **Update Firestore**: If the calculated `newOverallStatus` is different from the `instance.overallStatus` currently in Firestore, it updates the document with the new status and the current timestamp (converted to `FirebaseClientTimestamp`).
+- **Usage Context**:
+  - Typically called by a Cloud Function triggered on **update** of a `PatientRequirementInstance`, ideally after `processRequirementInstanceAndScheduleNotifications` (or any other logic that might modify individual instruction statuses) has completed. This ensures the `overallStatus` accurately reflects the latest state of the instructions.
+  - It helps maintain data integrity and provides a clear, high-level status for the entire set of requirements.
+
+## Timestamp Handling
+
+A key aspect of this service is the correct handling of Firestore Timestamps. Since the shared type definitions (e.g., for `PatientRequirementInstruction`) expect Timestamps compatible with the client-side Firebase SDK (`@firebase/firestore.Timestamp`), any Timestamps generated by the Admin SDK (e.g., `admin.firestore.Timestamp.now()`) must be converted to `new FirebaseClientTimestamp(adminTimestamp.seconds, adminTimestamp.nanoseconds)` before being written back to Firestore as part of these shared types. This ensures type consistency across the backend (admin) and frontend/shared type definitions.