@blackcode_sa/metaestetics-api 1.6.3 → 1.6.5

package/src/services/patient/patientRequirements.service.ts

@@ -0,0 +1,285 @@
+import {
+  collection,
+  getDocs,
+  query,
+  where,
+  doc,
+  updateDoc,
+  Timestamp,
+  DocumentReference,
+  serverTimestamp,
+  orderBy,
+  limit,
+  startAfter,
+  getDoc,
+  FieldPath,
+  WhereFilterOp,
+  Firestore,
+  DocumentSnapshot,
+} from "firebase/firestore";
+import { FirebaseApp } from "firebase/app";
+import { Auth } from "firebase/auth";
+import { BaseService } from "../base.service";
+import {
+  PatientRequirementInstance,
+  PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME,
+  PatientInstructionStatus,
+  PatientRequirementOverallStatus,
+  PatientRequirementInstruction,
+} from "../../types/patient/patient-requirements";
+import { UserRole } from "../../types"; // Assuming UserRole is in the root types
+
+/**
+ * Interface for filtering active patient requirements.
+ */
+export interface PatientRequirementsFilters {
+  appointmentId?: string | "all"; // Specific appointment, or 'all' for any appointment
+  statuses?: PatientRequirementOverallStatus[];
+  instructionStatuses?: PatientInstructionStatus[]; // Filter by status of individual instructions
+  dueBefore?: Timestamp; // Filter for instructions due before this time
+  dueAfter?: Timestamp; // Filter for instructions due after this time
+}
+
+export class PatientRequirementsService extends BaseService {
+  constructor(db: Firestore, auth: Auth, app: FirebaseApp) {
+    super(db, auth, app);
+  }
+
+  private getPatientRequirementsCollectionRef(patientId: string) {
+    return collection(
+      this.db,
+      `patients/${patientId}/${PATIENT_REQUIREMENTS_SUBCOLLECTION_NAME}`
+    );
+  }
+
+  private getPatientRequirementDocRef(
+    patientId: string,
+    instanceId: string
+  ): DocumentReference<PatientRequirementInstance> {
+    return doc(
+      this.getPatientRequirementsCollectionRef(patientId),
+      instanceId
+    ) as DocumentReference<PatientRequirementInstance>;
+  }
+
+  /**
+   * Gets a specific patient requirement instance by its ID.
+   * @param patientId - The ID of the patient.
+   * @param instanceId - The ID of the requirement instance.
+   * @returns The patient requirement instance or null if not found.
+   */
+  async getPatientRequirementInstance(
+    patientId: string,
+    instanceId: string
+  ): Promise<PatientRequirementInstance | null> {
+    const docRef = this.getPatientRequirementDocRef(patientId, instanceId);
+    const docSnap = await getDoc(docRef);
+    if (!docSnap.exists()) {
+      return null;
+    }
+    // Explicitly type data to exclude 'id' before spreading
+    const data = docSnap.data() as Omit<PatientRequirementInstance, "id">;
+    return { id: docSnap.id, ...data } as PatientRequirementInstance;
+  }
+
+  /**
+   * Retrieves patient requirement instances based on specified filters.
+   * This is a flexible query method.
+   *
+   * @param patientId - The ID of the patient.
+   * @param filters - Optional filters for appointmentId, overall statuses, instruction statuses, and due timeframes.
+   * @param pageLimit - Optional limit for pagination.
+   * @param lastVisible - Optional last document snapshot for pagination.
+   * @returns A promise resolving to an array of matching patient requirement instances and the last document snapshot.
+   */
+  async getAllPatientRequirementInstances(
+    patientId: string,
+    filters?: PatientRequirementsFilters,
+    pageLimit: number = 20,
+    lastVisible?: DocumentSnapshot
+  ): Promise<{
+    requirements: PatientRequirementInstance[];
+    lastDoc: DocumentSnapshot | null;
+  }> {
+    const collRef = this.getPatientRequirementsCollectionRef(patientId);
+    let q = query(collRef, orderBy("createdAt", "desc")); // Default sort
+
+    const queryConstraints = [];
+
+    if (filters?.appointmentId && filters.appointmentId !== "all") {
+      queryConstraints.push(
+        where("appointmentId", "==", filters.appointmentId)
+      );
+    }
+
+    if (filters?.statuses && filters.statuses.length > 0) {
+      queryConstraints.push(where("overallStatus", "in", filters.statuses));
+    }
+
+    // Filtering by instruction statuses or due times requires iterating post-fetch
+    // or more complex data modeling if direct querying is essential at scale.
+    // For a "light" service, post-fetch filtering for these is acceptable for now.
+
+    if (lastVisible) {
+      queryConstraints.push(startAfter(lastVisible));
+    }
+    queryConstraints.push(limit(pageLimit));
+
+    q = query(collRef, ...queryConstraints);
+
+    const snapshot = await getDocs(q);
+    let requirements = snapshot.docs.map((docSnap: DocumentSnapshot) => {
+      // Explicitly cast data after ensuring it's not undefined (though .data() on QueryDocumentSnapshot is not undefined)
+      const data = docSnap.data() as Omit<PatientRequirementInstance, "id">;
+      return { id: docSnap.id, ...data } as PatientRequirementInstance;
+    });
+
+    // Post-fetch filtering for instruction statuses and due times
+    if (
+      filters?.instructionStatuses &&
+      filters.instructionStatuses.length > 0
+    ) {
+      requirements = requirements.filter((req) =>
+        req.instructions.some((instr) =>
+          filters.instructionStatuses!.includes(instr.status)
+        )
+      );
+    }
+
+    if (filters?.dueBefore) {
+      const dueBeforeMillis = filters.dueBefore.toMillis();
+      requirements = requirements.filter((req) =>
+        req.instructions.some(
+          (instr) => instr.dueTime.toMillis() < dueBeforeMillis
+        )
+      );
+    }
+
+    if (filters?.dueAfter) {
+      const dueAfterMillis = filters.dueAfter.toMillis();
+      requirements = requirements.filter((req) =>
+        req.instructions.some(
+          (instr) => instr.dueTime.toMillis() > dueAfterMillis
+        )
+      );
+    }
+
+    const newLastVisible = snapshot.docs[snapshot.docs.length - 1] || null;
+
+    return { requirements, lastDoc: newLastVisible };
+  }
+
+  /**
+   * Marks a specific instruction within a PatientRequirementInstance as ACTION_TAKEN.
+   * If all instructions are actioned, updates the overallStatus of the instance.
+   *
+   * @param patientId - The ID of the patient.
+   * @param instanceId - The ID of the PatientRequirementInstance.
+   * @param instructionId - The ID of the instruction to complete.
+   * @returns The updated PatientRequirementInstance.
+   * @throws Error if the instance or instruction is not found, or if the instruction is not in a completable state.
+   */
+  async completeInstruction(
+    patientId: string,
+    instanceId: string,
+    instructionId: string
+  ): Promise<PatientRequirementInstance> {
+    const instanceRef = this.getPatientRequirementDocRef(patientId, instanceId);
+    const instanceSnap = await getDoc(instanceRef); // Simplified: getDoc without explicit generic here
+
+    if (!instanceSnap.exists()) {
+      throw new Error(
+        `PatientRequirementInstance ${instanceId} not found for patient ${patientId}.`
+      );
+    }
+
+    // Explicitly cast data after exists check
+    const instanceData = instanceSnap.data() as Omit<
+      PatientRequirementInstance,
+      "id"
+    >;
+    const instance = { id: instanceSnap.id, ...instanceData };
+
+    const instructionIndex = instance.instructions.findIndex(
+      (instr) => instr.instructionId === instructionId
+    );
+
+    if (instructionIndex === -1) {
+      throw new Error(
+        `Instruction ${instructionId} not found in instance ${instanceId}.`
+      );
+    }
+
+    const instructionToUpdate = instance.instructions[instructionIndex];
+
+    // Allow completion if it's PENDING_NOTIFICATION, ACTION_DUE, or even MISSED (if policy allows late completion)
+    if (
+      instructionToUpdate.status !==
+        PatientInstructionStatus.PENDING_NOTIFICATION &&
+      instructionToUpdate.status !== PatientInstructionStatus.ACTION_DUE &&
+      instructionToUpdate.status !== PatientInstructionStatus.MISSED
+    ) {
+      // If already ACTION_TAKEN or CANCELLED, do nothing or throw specific error
+      if (
+        instructionToUpdate.status === PatientInstructionStatus.ACTION_TAKEN
+      ) {
+        console.warn(
+          `Instruction ${instructionId} is already marked as ACTION_TAKEN.`
+        );
+        return instance as PatientRequirementInstance; // Ensure return type matches
+      }
+      throw new Error(
+        `Instruction ${instructionId} is in status ${instructionToUpdate.status} and cannot be marked as completed.`
+      );
+    }
+
+    const now = Timestamp.now();
+    const updatedInstructions = [...instance.instructions];
+    updatedInstructions[instructionIndex] = {
+      ...instructionToUpdate,
+      status: PatientInstructionStatus.ACTION_TAKEN,
+      actionTakenAt: now,
+      updatedAt: now,
+    };
+
+    // Check if all instructions are now ACTION_TAKEN
+    const allActionTaken = updatedInstructions.every(
+      (instr) => instr.status === PatientInstructionStatus.ACTION_TAKEN
+    );
+
+    let newOverallStatus = instance.overallStatus;
+    if (allActionTaken) {
+      newOverallStatus = PatientRequirementOverallStatus.ALL_INSTRUCTIONS_MET;
+    } else if (
+      updatedInstructions.some(
+        (instr) => instr.status === PatientInstructionStatus.ACTION_TAKEN
+      )
+    ) {
+      // If some are taken, but not all, and it was previously just ACTIVE
+      newOverallStatus = PatientRequirementOverallStatus.PARTIALLY_COMPLETED;
+    }
+
+    const updatePayload: { [key: string]: any } = {
+      // Using a general type for updateDoc payload
+      instructions: updatedInstructions,
+      updatedAt: now,
+    };
+
+    if (newOverallStatus !== instance.overallStatus) {
+      updatePayload.overallStatus = newOverallStatus;
+    }
+
+    await updateDoc(instanceRef, updatePayload);
+
+    // Construct the returned object accurately
+    return {
+      ...instance,
+      instructions: updatedInstructions,
+      updatedAt: now,
+      overallStatus: newOverallStatus,
+    } as PatientRequirementInstance;
+  }
+
+  // Note: As per the request, full CRUD (create, direct update of instance, delete) is not part of this light service,
+  // as those will be handled by Cloud Functions reacting to appointment lifecycle events.
+}

package/src/services/procedure/procedure.service.ts

@@ -179,6 +179,7 @@ export class ProcedureService extends BaseService {
       technology,
       product,
       blockingConditions: technology.blockingConditions,
+      contraindications: technology.contraindications || [],
       treatmentBenefits: technology.benefits,
       preRequirements: technology.requirements.pre,
       postRequirements: technology.requirements.post,

package/src/types/appointment/index.ts

@@ -6,24 +6,26 @@ import {
 } from "../profile";
 import { ProcedureSummaryInfo } from "../procedure";
 import { Currency } from "../../backoffice/types/static/pricing.types";
-import { CalendarEventStatus } from "../calendar";
 import { BlockingCondition } from "../../backoffice/types/static/blocking-condition.types";
 import { Contraindication } from "../../backoffice/types/static/contraindication.types";
 import { Requirement } from "../../backoffice/types/requirement.types";
+import { FilledDocumentStatus } from "../documentation-templates";
+import type { ProcedureFamily } from "../../backoffice";
 
 /**
  * Enum defining the possible statuses of an appointment.
  */
 export enum AppointmentStatus {
-  SCHEDULED = "scheduled", // Initial state after booking, before confirmation (if applicable)
+  PENDING = "pending", // Initial state after booking, before confirmation (if applicable)
   CONFIRMED = "confirmed", // Confirmed by clinic/practitioner
   CHECKED_IN = "checked_in", // Patient has arrived
   IN_PROGRESS = "in_progress", // Procedure has started
   COMPLETED = "completed", // Procedure finished successfully
   CANCELED_PATIENT = "canceled_patient", // Canceled by the patient
+  CANCELED_PATIENT_RESCHEDULED = "canceled_patient_rescheduled", // Canceled by the patient and rescheduled by the clinic
   CANCELED_CLINIC = "canceled_clinic", // Canceled by the clinic/practitioner
   NO_SHOW = "no_show", // Patient did not attend
-  RESCHEDULED = "rescheduled", // Original appointment replaced by a new one
+  RESCHEDULED_BY_CLINIC = "rescheduled_by_clinic", // When appointment is rescheduled by the clinic, waiting for patient confirmation or cancellation (when reschedule is accepted, status goes to confirmed, if not accepted, then status goes to canceled_patient_rescheduled)
 }
 
 /**
@@ -37,6 +39,76 @@ export enum PaymentStatus {
   NOT_APPLICABLE = "not_applicable", // For free services or other scenarios
 }
 
+/**
+ * Enum for different types of media that can be attached to an appointment.
+ */
+export enum MediaType {
+  BEFORE_PHOTO = "before_photo",
+  AFTER_PHOTO = "after_photo",
+  CONSENT_SCAN = "consent_scan",
+  OTHER_DOCUMENT = "other_document",
+}
+
+/**
+ * Interface to describe a media file linked to an appointment.
+ */
+export interface AppointmentMediaItem {
+  id: string; // Auto-generated unique ID for the media item
+  type: MediaType;
+  url: string; // Cloud Storage URL
+  fileName?: string;
+  uploadedAt: Timestamp;
+  uploadedBy: string; // User ID (patient, practitioner, or clinic_admin)
+  description?: string;
+}
+
+/**
+ * Interface for procedure-specific information
+ */
+export interface ProcedureExtendedInfo {
+  id: string;
+  name: string;
+  description: string;
+  cost: number;
+  duration: number;
+  procedureFamily: ProcedureFamily;
+  procedureCategoryId: string;
+  procedureCategoryName: string;
+  procedureSubCategoryId: string;
+  procedureSubCategoryName: string;
+  procedureTechnologyId: string;
+  procedureTechnologyName: string;
+  procedureProductBrandId: string;
+  procedureProductBrandName: string;
+  procedureProductId: string;
+  procedureProductName: string;
+}
+
+/**
+ * Interface to describe a filled form linked to an appointment.
+ */
+export interface LinkedFormInfo {
+  formId: string; // ID of the FilledDocument
+  templateId: string;
+  templateVersion: number;
+  title: string; // For display, usually from DocumentTemplate.title
+  isUserForm: boolean;
+  status: FilledDocumentStatus; // Status of the filled form (e.g., draft, completed, signed)
+  path: string; // Full Firestore path to the filled document (e.g., appointments/{aid}/user-forms/{fid})
+  submittedAt?: Timestamp;
+  completedAt?: Timestamp; // When the form reached a final state like 'completed' or 'signed'
+}
+
+/**
+ * Interface for summarized patient review information linked to an appointment.
+ */
+export interface PatientReviewInfo {
+  reviewId: string; // ID of the full review document/record if stored elsewhere
+  rating: number; // e.g., 1-5 stars
+  comment?: string; // A short snippet or the full comment
+  reviewedAt: Timestamp;
+}
+
 /**
  * Represents a booked appointment, aggregating key information and relevant procedure rules.
  */
@@ -64,7 +136,9 @@ export interface Appointment {
   /** ID of the procedure */
   procedureId: string;
   /** Aggregated procedure information including product/brand (snapshot) */
-  procedureInfo: ProcedureSummaryInfo;
+  procedureInfo: ProcedureSummaryInfo; // Aggregated procedure information
+  /** Extended procedure information */
+  procedureExtendedInfo: ProcedureExtendedInfo; // Aggregated extended procedure information
 
   /** Status of the appointment */
   status: AppointmentStatus;
@@ -72,8 +146,11 @@ export interface Appointment {
   /** Timestamps */
   bookingTime: Timestamp;
   confirmationTime?: Timestamp | null;
+  cancellationTime?: Timestamp | null;
+  rescheduleTime?: Timestamp | null;
   appointmentStartTime: Timestamp;
   appointmentEndTime: Timestamp;
+  procedureActualStartTime?: Timestamp | null; // NEW: Actual start time of the procedure
   actualDurationMinutes?: number;
 
   /** Cancellation Details */
@@ -100,20 +177,40 @@ export interface Appointment {
   completedPreRequirements?: string[]; // IDs of completed pre-requirements
   completedPostRequirements?: string[]; // IDs of completed post-requirements
 
-  /** Timestamps */
+  /** NEW: Linked forms (consent, procedure-specific forms, etc.) */
+  linkedFormIds?: string[];
+  linkedForms?: LinkedFormInfo[];
+  pendingUserFormsIds?: string[]; // Determines if there are any user forms that are pending for this appointment, blocks the appointment from being checked in (only for user forms with isRequired = true)
+
+  /** NEW: Media items (before/after photos, scanned documents, etc.) */
+  media?: AppointmentMediaItem[];
+
+  /** NEW: Information about the patient's review for this appointment */
+  reviewInfo?: PatientReviewInfo | null;
+
+  /** NEW: Details about the finalization of the appointment by the practitioner */
+  finalizedDetails?: {
+    by: string; // Practitioner User ID
+    at: Timestamp;
+    notes?: string;
+  };
+
+  /** Timestamps for record creation and updates */
   createdAt: Timestamp;
   updatedAt: Timestamp;
 
   /** Recurring appointment information */
   isRecurring?: boolean;
   recurringAppointmentId?: string | null;
+
+  /** NEW: Flag for soft deletion or archiving */
+  isArchived?: boolean;
 }
 
 /**
  * Data needed to create a new Appointment
  */
 export interface CreateAppointmentData {
-  calendarEventId: string;
   clinicBranchId: string;
   practitionerId: string;
   patientId: string;
@@ -124,7 +221,7 @@ export interface CreateAppointmentData {
   currency: Currency;
   patientNotes?: string | null;
   initialStatus: AppointmentStatus;
-  initialPaymentStatus?: PaymentStatus;
+  initialPaymentStatus?: PaymentStatus; // Defaults to UNPAID if not provided
 }
 
 /**
@@ -132,15 +229,43 @@ export interface CreateAppointmentData {
  */
 export interface UpdateAppointmentData {
   status?: AppointmentStatus;
-  confirmationTime?: Timestamp | null;
+  confirmationTime?: Timestamp | FieldValue | null;
+  cancellationTime?: Timestamp | FieldValue | null;
+  rescheduleTime?: Timestamp | FieldValue | null;
+  procedureActualStartTime?: Timestamp | FieldValue | null; // NEW
   actualDurationMinutes?: number;
   cancellationReason?: string | null;
   canceledBy?: "patient" | "clinic" | "practitioner" | "system";
   internalNotes?: string | null;
+  patientNotes?: string | FieldValue | null; // Allow FieldValue for deleting
   paymentStatus?: PaymentStatus;
-  paymentTransactionId?: string | null;
-  completedPreRequirements?: string[]; // IDs of pre-requirements to mark as completed
-  completedPostRequirements?: string[]; // IDs of post-requirements to mark as completed
+  paymentTransactionId?: string | FieldValue | null;
+  completedPreRequirements?: string[] | FieldValue; // Allow FieldValue for arrayUnion/arrayRemove
+  completedPostRequirements?: string[] | FieldValue;
+  appointmentStartTime?: Timestamp; // For rescheduling
+  appointmentEndTime?: Timestamp; // For rescheduling
+  calendarEventId?: string; // If calendar event needs to be re-linked
+  cost?: number; // If cost is adjusted
+  clinicBranchId?: string; // If appointment is moved to another branch (complex scenario)
+  practitionerId?: string; // If practitioner is changed
+
+  /** NEW: For updating linked forms - typically managed by dedicated methods */
+  linkedFormIds?: string[] | FieldValue;
+  linkedForms?: LinkedFormInfo[] | FieldValue;
+
+  /** NEW: For updating media items - typically managed by dedicated methods */
+  media?: AppointmentMediaItem[] | FieldValue;
+
+  /** NEW: For adding/updating review information */
+  reviewInfo?: PatientReviewInfo | FieldValue | null;
+
+  /** NEW: For setting practitioner finalization details */
+  finalizedDetails?: { by: string; at: Timestamp; notes?: string } | FieldValue;
+
+  /** NEW: For archiving/unarchiving */
+  isArchived?: boolean;
+
+  updatedAt?: FieldValue; // To set server timestamp
 }
 
 /**

package/src/types/documentation-templates/index.ts

@@ -7,6 +7,8 @@
  */
 export const DOCUMENTATION_TEMPLATES_COLLECTION = "documentation-templates";
 export const FILLED_DOCUMENTS_COLLECTION = "filled-documents";
+export const USER_FORMS_SUBCOLLECTION = "user-forms";
+export const DOCTOR_FORMS_SUBCOLLECTION = "doctor-forms";
 /**
  * Enum for element types in documentation templates
  */
@@ -27,6 +29,7 @@ export enum DocumentElementType {
   TEXT_INPUT = "text_input",
   DATE_PICKER = "date_picker",
   SIGNATURE = "signature",
+  DITIGAL_SIGNATURE = "digital_signature",
   FILE_UPLOAD = "file_upload",
 }
 
@@ -60,6 +63,11 @@ export enum DynamicVariable {
   PATIENT_BIRTHDAY = "[PATIENT_BIRTHDAY]",
   APPOINTMENT_DATE = "[APPOINTMENT_DATE]",
   CURRENT_DATE = "[CURRENT_DATE]",
+  PROCEDURE_NAME = "[PROCEDURE_NAME]",
+  PROCEDURE_DESCRIPTION = "[PROCEDURE_DESCRIPTION]",
+  PROCEDURE_COST = "[PROCEDURE_COST]",
+  PROCEDURE_DURATION = "[PROCEDURE_DURATION]",
+  PROCEDURE_RISK = "[PROCEDURE_RISK]",
 }
 
 /**
@@ -174,6 +182,14 @@ export interface SignatureElement extends BaseDocumentElement {
   label: string;
 }
 
+/**
+ * Interface for digital signature element
+ */
+export interface DigitalSignatureElement extends BaseDocumentElement {
+  type: DocumentElementType.DITIGAL_SIGNATURE;
+  label: string;
+}
+
 /**
  * Interface for file upload element
  */
@@ -213,6 +229,9 @@ export interface DocumentTemplate {
   createdBy: string; // User ID
   elements: DocumentElement[];
   tags?: string[]; // For categorization
+  isUserForm?: boolean; // Default is false, and that means it's a doctor form
+  isRequired?: boolean; // Default is false, and that means it's an optional form, this is mostly used for user forms
+  sortingOrder?: number; // For sorting the forms in the UI, default is 0
   version: number; // For versioning
   isActive: boolean; // Whether the template is active
 }
@@ -225,6 +244,9 @@ export interface CreateDocumentTemplateData {
   description?: string;
   elements: Omit<DocumentElement, "id">[];
   tags?: string[];
+  isUserForm?: boolean; // Default is false, and that means it's a doctor form
+  isRequired?: boolean; // Default is false, and that means it's an optional form, this is mostly used for user forms
+  sortingOrder?: number; // For sorting the forms in the UI, default is 0
 }
 
 /**
@@ -236,6 +258,9 @@ export interface UpdateDocumentTemplateData {
   elements?: Omit<DocumentElement, "id">[];
   tags?: string[];
   isActive?: boolean;
+  isUserForm?: boolean; // Default is false, and that means it's a doctor form
+  isRequired?: boolean; // Default is false, and that means it's an optional form, this is mostly used for user forms
+  sortingOrder?: number; // For sorting the forms in the UI, default is 0
 }
 
 /**
@@ -245,6 +270,10 @@ export interface FilledDocument {
   id: string;
   templateId: string;
   templateVersion: number;
+  isUserForm: boolean;
+  isRequired: boolean;
+  procedureId: string;
+  appointmentId: string;
   patientId: string;
   practitionerId: string;
   clinicId: string;
@@ -259,6 +288,9 @@ export interface FilledDocument {
  */
 export enum FilledDocumentStatus {
   DRAFT = "draft",
-  COMPLETED = "completed",
-  SIGNED = "signed",
+  SKIPPED = "skipped",
+  PENDING = "pending",
+  COMPLETED = "completed", // When doctor or patient completes the form
+  SIGNED = "signed", // Only used for user forms
+  REJECTED = "rejected", // Only used for user forms
 }