@blackcode_sa/metaestetics-api 1.6.3 → 1.6.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blackcode_sa/metaestetics-api",
   "private": false,
-  "version": "1.6.3",
+  "version": "1.6.5",
   "description": "Firebase authentication service with anonymous upgrade support",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

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

@@ -0,0 +1,321 @@
+import * as admin from "firebase-admin";
+import {
+  Appointment,
+  AppointmentStatus,
+  APPOINTMENTS_COLLECTION,
+} from "../../../types/appointment"; // Assuming APPOINTMENTS_COLLECTION is exported here
+import {
+  PatientRequirementInstance,
+  PatientRequirementOverallStatus,
+  PatientInstructionStatus,
+  PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME,
+} from "../../../types/patient/patient-requirements";
+import {
+  Requirement as RequirementTemplate,
+  REQUIREMENTS_COLLECTION as REQUIREMENTS_TEMPLATES_COLLECTION,
+  RequirementType as RequirementTemplateType,
+} from "../../../backoffice/types/requirement.types";
+import { PATIENTS_COLLECTION } from "../../../types/patient";
+
+// 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
+
+/**
+ * @class AppointmentAggregationService
+ * @description Handles aggregation tasks and side effects related to appointment lifecycle events.
+ * This service is intended to be used primarily by background functions (e.g., Cloud Functions)
+ * triggered by changes in the appointments collection.
+ */
+export class AppointmentAggregationService {
+  private db: admin.firestore.Firestore;
+  private patientRequirementsAdminService: PatientRequirementsAdminService;
+  private notificationsAdmin: NotificationsAdmin;
+  // private calendarAdminService: CalendarAdminService; // Placeholder
+  // private appointmentMailingService: AppointmentMailingService; // Placeholder
+  // private patientAdminService: PatientAdminService; // Placeholder
+  // private practitionerAdminService: PractitionerAdminService; // Placeholder
+  // private clinicAdminService: ClinicAdminService; // Placeholder
+
+  /**
+   * Constructor for AppointmentAggregationService.
+   * @param firestore Optional Firestore instance. If not provided, it uses the default admin SDK instance.
+   */
+  constructor(firestore?: admin.firestore.Firestore) {
+    this.db = firestore || admin.firestore();
+    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
+  }
+
+  /**
+   * 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.
+   * @returns {Promise<void>}
+   */
+  async handleAppointmentConfirmed(appointment: Appointment): Promise<void> {
+    console.log(
+      `[AppointmentAggregationService] Handling confirmed appointment: ${appointment.id}`
+    );
+    // 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))
+
+    // 3. Trigger email/push notifications (e.g., this.appointmentMailingService.sendAppointmentConfirmedEmail(appointment))
+
+    // 4. Manage patient-clinic-practitioner links (e.g., this.managePatientClinicPractitionerLinks(appointment, 'create'))
+
+    // 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');
+    // }
+  }
+
+  /**
+   * 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
+
+    // 2. Trigger review request (e.g., this.appointmentMailingService.sendReviewRequestEmail(appointment))
+  }
+
+  /**
+   * 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.
+   * @returns {Promise<void>}
+   */
+  async handleAppointmentCancelled(
+    appointment: Appointment,
+    previousStatus?: AppointmentStatus
+  ): Promise<void> {
+    console.log(
+      `[AppointmentAggregationService] Handling cancelled appointment: ${appointment.id}, previous status: ${previousStatus}`
+    );
+    // 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))
+
+    // 3. Trigger email notifications (e.g., this.appointmentMailingService.sendAppointmentCancelledEmail(appointment))
+
+    // 4. Evaluate patient-clinic-practitioner links for removal
+  }
+
+  /**
+   * 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.
+   * @returns {Promise<void>}
+   */
+  async handleAppointmentRescheduled(
+    appointment: Appointment,
+    previousAppointmentData: Appointment
+  ): Promise<void> {
+    console.log(
+      `[AppointmentAggregationService] Handling rescheduled appointment: ${appointment.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))
+  }
+
+  /**
+   * 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>}
+   */
+  async managePatientClinicPractitionerLinks(
+    appointment: Appointment,
+    action: "create" | "cancel"
+  ): Promise<void> {
+    console.log(
+      `[AppointmentAggregationService] Managing patient-clinic-practitioner links for appointment ${appointment.id}, action: ${action}`
+    );
+    // 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
+  }
+
+  /**
+   * 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>}
+   */
+  async triggerCalendarUpdate(
+    appointment: Appointment,
+    action: "create" | "update" | "delete",
+    previousAppointmentData?: Appointment
+  ): Promise<void> {
+    console.log(
+      `[AppointmentAggregationService] Triggering calendar update for appointment ${appointment.id}, action: ${action}`
+    );
+    // Call methods on a dedicated CalendarAdminService
+  }
+
+  /**
+   * 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>}
+   */
+  async triggerEmailNotification(
+    appointment: Appointment,
+    emailType: string,
+    previousAppointmentData?: Appointment
+  ): Promise<void> {
+    console.log(
+      `[AppointmentAggregationService] Triggering email type '${emailType}' for appointment ${appointment.id}`
+    );
+    // Call methods on a dedicated AppointmentMailingService
+  }
+
+  /**
+   * Handles logic for sending a review request after appointment completion.
+   * @param appointment - The completed appointment.
+   * @returns {Promise<void>}
+   */
+  async handleReviewRequest(appointment: Appointment): Promise<void> {
+    console.log(
+      `[AppointmentAggregationService] Handling review request for appointment ${appointment.id}`
+    );
+    // Logic to schedule or send a review request notification/email.
+    // Might involve checking if a review already exists.
+  }
+
+  // --- Helper methods --- //
+
+  /**
+   * 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[]>}
+   */
+  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
+  }
+
+  /**
+   * 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.
+   */
+  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
+  }
+
+  /**
+   * 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}
+   */
+  // 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
+  // }
+}