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

package/src/services/documentation-templates/filled-document.service.ts

@@ -1,597 +1,597 @@
-import {
-  collection,
-  doc,
-  getDoc,
-  getDocs,
-  setDoc,
-  updateDoc,
-  query,
-  where,
-  orderBy,
-  limit,
-  startAfter,
-  QueryDocumentSnapshot,
-} from "firebase/firestore";
-import { BaseService } from "../base.service";
-import {
-  // DocumentTemplate, // Not directly used in this file if relying on templateService
-  // DOCUMENTATION_TEMPLATES_COLLECTION, // No longer needed directly here if using templateService
-  // FILLED_DOCUMENTS_COLLECTION, // This will be replaced by subcollection paths
-  FilledDocument,
-  FilledDocumentStatus,
-  FilledDocumentFileValue,
-  USER_FORMS_SUBCOLLECTION,
-  DOCTOR_FORMS_SUBCOLLECTION,
-} from "../../types"; // General types
-import { APPOINTMENTS_COLLECTION } from "../../types/appointment"; // Specific import for the constant
-import { DocumentationTemplateService } from "./documentation-template.service";
-import {
-  MediaService,
-  MediaAccessLevel,
-  MediaMetadata,
-} from "../media/media.service";
-// Import the new validation schemas if you plan to use them for input validation here
-// import { createFilledDocumentDataSchema, updateFilledDocumentDataSchema } from '../../validations/documentation-templates.schema';
-
-/**
- * Service for managing filled documents within appointment subcollections
- */
-export class FilledDocumentService extends BaseService {
-  // No single collectionRef anymore, paths will be dynamic
-  private readonly templateService: DocumentationTemplateService;
-  private readonly mediaService: MediaService;
-
-  constructor(...args: ConstructorParameters<typeof BaseService>) {
-    super(...args);
-    this.templateService = new DocumentationTemplateService(...args); // Pass db and other args
-    this.mediaService = new MediaService(...args); // Initialize media service with the same args
-  }
-
-  private getFormSubcollectionPath(
-    isUserForm: boolean
-  ): typeof USER_FORMS_SUBCOLLECTION | typeof DOCTOR_FORMS_SUBCOLLECTION {
-    return isUserForm ? USER_FORMS_SUBCOLLECTION : DOCTOR_FORMS_SUBCOLLECTION;
-  }
-
-  /**
-   * Create a new filled document within an appointment's subcollection.
-   * @param templateId - ID of the template to use.
-   * @param templateVersion - Version of the template to use.
-   * @param appointmentId - ID of the appointment this form belongs to.
-   * @param procedureId - ID of the procedure associated with this form.
-   * @param patientId - ID of the patient.
-   * @param practitionerId - ID of the practitioner (can be system/generic if patient is filling).
-   * @param clinicId - ID of the clinic.
-   * @param initialValues - Optional initial values for the form elements.
-   * @param initialStatus - Optional initial status for the form.
-   * @returns The created filled document.
-   */
-  async createFilledDocumentForAppointment(
-    templateId: string,
-    templateVersion: number,
-    appointmentId: string,
-    procedureId: string,
-    patientId: string,
-    practitionerId: string, // Consider if this is always available or if a placeholder is needed
-    clinicId: string, // Same consideration as practitionerId
-    initialValues: { [elementId: string]: any } = {},
-    initialStatus: FilledDocumentStatus = FilledDocumentStatus.DRAFT
-  ): Promise<FilledDocument> {
-    const template = await this.templateService.getTemplateById(
-      templateId,
-      templateVersion
-    );
-    if (!template) {
-      throw new Error(`Template with ID ${templateId} not found`);
-    }
-
-    const documentId = this.generateId();
-    const now = Date.now();
-    const isUserForm = template.isUserForm || false;
-    const formSubcollection = this.getFormSubcollectionPath(isUserForm);
-
-    const filledDocument: FilledDocument = {
-      id: documentId,
-      templateId,
-      templateVersion: template.version,
-      isUserForm: isUserForm, // Set based on template
-      isRequired: template.isRequired || false, // Inherit isRequired from the template
-      appointmentId: appointmentId, // NEW
-      procedureId: procedureId, // NEW
-      patientId,
-      practitionerId,
-      clinicId,
-      createdAt: now,
-      updatedAt: now,
-      values: initialValues,
-      status: initialStatus,
-    };
-
-    const docRef = doc(
-      this.db,
-      APPOINTMENTS_COLLECTION, // Replaced "appointments"
-      appointmentId,
-      formSubcollection,
-      documentId
-    );
-    await setDoc(docRef, filledDocument);
-
-    return filledDocument;
-  }
-
-  /**
-   * Get a specific filled document from an appointment's subcollection.
-   * @param appointmentId - ID of the appointment.
-   * @param formId - ID of the filled document.
-   * @param isUserForm - Boolean indicating if it's a user form or doctor form.
-   * @returns The filled document or null if not found.
-   */
-  async getFilledDocumentFromAppointmentById(
-    appointmentId: string,
-    formId: string,
-    isUserForm: boolean
-  ): Promise<FilledDocument | null> {
-    const formSubcollection = this.getFormSubcollectionPath(isUserForm);
-    const docRef = doc(
-      this.db,
-      APPOINTMENTS_COLLECTION, // Replaced "appointments"
-      appointmentId,
-      formSubcollection,
-      formId
-    );
-    const docSnap = await getDoc(docRef);
-
-    if (!docSnap.exists()) {
-      return null;
-    }
-    const data = docSnap.data() as FilledDocument;
-    // Ensure id is populated from Firestore document ID if not in data
-    if (!data.id) {
-      data.id = docSnap.id;
-    }
-    return data;
-  }
-
-  /**
-   * Update values or status in a filled document within an appointment's subcollection.
-   * @param appointmentId - ID of the appointment.
-   * @param formId - ID of the filled document to update.
-   * @param isUserForm - Boolean indicating if it's a user form or doctor form.
-   * @param values - Updated values for elements.
-   * @param status - Optional new status for the document.
-   * @returns The updated filled document.
-   */
-  async updateFilledDocumentInAppointment(
-    appointmentId: string,
-    formId: string,
-    isUserForm: boolean,
-    values?: { [elementId: string]: any },
-    status?: FilledDocumentStatus
-  ): Promise<FilledDocument> {
-    const formSubcollection = this.getFormSubcollectionPath(isUserForm);
-    const docRef = doc(
-      this.db,
-      APPOINTMENTS_COLLECTION, // Replaced "appointments"
-      appointmentId,
-      formSubcollection,
-      formId
-    );
-
-    const existingDoc = await this.getFilledDocumentFromAppointmentById(
-      appointmentId,
-      formId,
-      isUserForm
-    );
-
-    if (!existingDoc) {
-      throw new Error(
-        `Filled document with ID ${formId} not found in appointment ${appointmentId} ${formSubcollection}`
-      );
-    }
-
-    const updatePayload: Partial<FilledDocument> = {
-      updatedAt: Date.now(),
-    };
-
-    if (values) {
-      updatePayload.values = {
-        ...existingDoc.values,
-        ...values,
-      };
-    }
-    if (status) {
-      updatePayload.status = status;
-    }
-
-    if (
-      Object.keys(updatePayload).length === 1 &&
-      "updatedAt" in updatePayload
-    ) {
-      // Only updatedAt, no actual data change, so we can skip the update
-      // or just update timestamp if that is the desired behavior.
-      // For now, we proceed to update the timestamp at least.
-    }
-
-    await updateDoc(docRef, updatePayload);
-
-    return { ...existingDoc, ...updatePayload } as FilledDocument;
-  }
-
-  /**
-   * Get all filled user forms for a specific appointment.
-   * @param appointmentId ID of the appointment.
-   * @param pageSize Number of documents to retrieve.
-   * @param lastDoc Last document from previous page for pagination.
-   */
-  async getFilledUserFormsForAppointment(
-    appointmentId: string,
-    pageSize = 20,
-    lastDoc?: QueryDocumentSnapshot<FilledDocument>
-  ): Promise<{
-    documents: FilledDocument[];
-    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
-  }> {
-    const subcollectionRef = collection(
-      this.db,
-      APPOINTMENTS_COLLECTION, // Replaced "appointments"
-      appointmentId,
-      USER_FORMS_SUBCOLLECTION
-    );
-    let q = query(
-      subcollectionRef,
-      orderBy("updatedAt", "desc"),
-      limit(pageSize)
-    );
-
-    if (lastDoc) {
-      q = query(q, startAfter(lastDoc));
-    }
-    return this.executeQuery(q);
-  }
-
-  /**
-   * Get all filled doctor forms for a specific appointment.
-   * @param appointmentId ID of the appointment.
-   * @param pageSize Number of documents to retrieve.
-   * @param lastDoc Last document from previous page for pagination.
-   */
-  async getFilledDoctorFormsForAppointment(
-    appointmentId: string,
-    pageSize = 20,
-    lastDoc?: QueryDocumentSnapshot<FilledDocument>
-  ): Promise<{
-    documents: FilledDocument[];
-    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
-  }> {
-    const subcollectionRef = collection(
-      this.db,
-      APPOINTMENTS_COLLECTION, // Replaced "appointments"
-      appointmentId,
-      DOCTOR_FORMS_SUBCOLLECTION
-    );
-    let q = query(
-      subcollectionRef,
-      orderBy("updatedAt", "desc"),
-      limit(pageSize)
-    );
-
-    if (lastDoc) {
-      q = query(q, startAfter(lastDoc));
-    }
-    return this.executeQuery(q);
-  }
-
-  // Helper to execute query and return documents + lastDoc
-  private async executeQuery(
-    q: any // Firestore Query type
-  ): Promise<{
-    documents: FilledDocument[];
-    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
-  }> {
-    const querySnapshot = await getDocs(q);
-    const documents: FilledDocument[] = [];
-    let lastVisible: QueryDocumentSnapshot<FilledDocument> | null = null;
-
-    querySnapshot.forEach((docSnapshot) => {
-      const data = docSnapshot.data() as FilledDocument;
-      // Ensure id is populated from Firestore document ID if not in data
-      if (!data.id) {
-        data.id = docSnapshot.id;
-      }
-      documents.push(data);
-      lastVisible = docSnapshot as QueryDocumentSnapshot<FilledDocument>;
-    });
-
-    return {
-      documents,
-      lastDoc: lastVisible,
-    };
-  }
-
-  // IMPORTANT: The following methods that query across all patients/practitioners/clinics
-  // (e.g., getFilledDocumentsByPatient, getFilledDocumentsByPractitioner)
-  // will NOT work correctly if FILLED_DOCUMENTS_COLLECTION is no longer a top-level collection
-  // and data is only in appointment subcollections. You would need to use
-  // Firestore Collection Group Queries for that, which require an index and a different query approach.
-  // These methods are left here for now but would need significant rework or removal.
-
-  /**
-   * Get filled documents for a patient (NEEDS REWORK for subcollections or Collection Group Query)
-   * @param patientId - ID of the patient
-   * @param pageSize - Number of documents to retrieve
-   * @param lastDoc - Last document from previous page for pagination
-   * @returns Array of filled documents and the last document for pagination
-   */
-  async getFilledDocumentsByPatient(
-    patientId: string,
-    pageSize = 20,
-    lastDoc?: QueryDocumentSnapshot<FilledDocument>
-  ): Promise<{
-    documents: FilledDocument[];
-    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
-  }> {
-    console.warn(
-      "getFilledDocumentsByPatient needs rework for subcollection model or Collection Group Queries."
-    );
-    // Original logic commented out as this.collectionRef is no longer valid for this model
-    /*
-    let q = query(
-      this.collectionRef, // LINTER ERROR: this.collectionRef no longer exists
-      where("patientId", "==", patientId),
-      orderBy("updatedAt", "desc"),
-      limit(pageSize)
-    );
-
-    if (lastDoc) {
-      q = query(q, startAfter(lastDoc));
-    }
-
-    const querySnapshot = await getDocs(q);
-    const documents: FilledDocument[] = [];
-    let lastVisible: QueryDocumentSnapshot<FilledDocument> | null = null;
-
-    querySnapshot.forEach((doc) => {
-      documents.push(doc.data() as FilledDocument);
-      lastVisible = doc as QueryDocumentSnapshot<FilledDocument>;
-    });
-
-    return {
-      documents,
-      lastDoc: lastVisible,
-    };
-    */
-    return { documents: [], lastDoc: null }; // Placeholder return
-  }
-
-  /**
-   * Get filled documents for a practitioner (NEEDS REWORK for subcollections or Collection Group Query)
-   * @param practitionerId - ID of the practitioner
-   * @param pageSize - Number of documents to retrieve
-   * @param lastDoc - Last document from previous page for pagination
-   * @returns Array of filled documents and the last document for pagination
-   */
-  async getFilledDocumentsByPractitioner(
-    practitionerId: string,
-    pageSize = 20,
-    lastDoc?: QueryDocumentSnapshot<FilledDocument>
-  ): Promise<{
-    documents: FilledDocument[];
-    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
-  }> {
-    console.warn(
-      "getFilledDocumentsByPractitioner needs rework for subcollection model or Collection Group Queries."
-    );
-    // Original logic commented out
-    /*
-    let q = query(
-      this.collectionRef, // LINTER ERROR
-      where("practitionerId", "==", practitionerId),
-      orderBy("updatedAt", "desc"),
-      limit(pageSize)
-    );
-    // ... rest of original logic ...
-    */
-    return { documents: [], lastDoc: null }; // Placeholder return
-  }
-
-  /**
-   * Get filled documents for a clinic (NEEDS REWORK for subcollections or Collection Group Query)
-   * @param clinicId - ID of the clinic
-   * @param pageSize - Number of documents to retrieve
-   * @param lastDoc - Last document from previous page for pagination
-   * @returns Array of filled documents and the last document for pagination
-   */
-  async getFilledDocumentsByClinic(
-    clinicId: string,
-    pageSize = 20,
-    lastDoc?: QueryDocumentSnapshot<FilledDocument>
-  ): Promise<{
-    documents: FilledDocument[];
-    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
-  }> {
-    console.warn(
-      "getFilledDocumentsByClinic needs rework for subcollection model or Collection Group Queries."
-    );
-    // Original logic commented out
-    /*
-    let q = query(
-      this.collectionRef, // LINTER ERROR
-      where("clinicId", "==", clinicId),
-      orderBy("updatedAt", "desc"),
-      limit(pageSize)
-    );
-    // ... rest of original logic ...
-    */
-    return { documents: [], lastDoc: null }; // Placeholder return
-  }
-
-  /**
-   * Get filled documents by template (NEEDS REWORK for subcollections or Collection Group Query)
-   * @param templateId - ID of the template
-   * @param pageSize - Number of documents to retrieve
-   * @param lastDoc - Last document from previous page for pagination
-   * @returns Array of filled documents and the last document for pagination
-   */
-  async getFilledDocumentsByTemplate(
-    templateId: string,
-    pageSize = 20,
-    lastDoc?: QueryDocumentSnapshot<FilledDocument>
-  ): Promise<{
-    documents: FilledDocument[];
-    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
-  }> {
-    console.warn(
-      "getFilledDocumentsByTemplate needs rework for subcollection model or Collection Group Queries."
-    );
-    // Original logic commented out
-    /*
-    let q = query(
-      this.collectionRef, // LINTER ERROR
-      where("templateId", "==", templateId),
-      orderBy("updatedAt", "desc"),
-      limit(pageSize)
-    );
-    // ... rest of original logic ...
-    */
-    return { documents: [], lastDoc: null }; // Placeholder return
-  }
-
-  /**
-   * Get filled documents by status (NEEDS REWORK for subcollections or Collection Group Query)
-   * @param status - Status to filter by
-   * @param pageSize - Number of documents to retrieve
-   * @param lastDoc - Last document from previous page for pagination
-   * @returns Array of filled documents and the last document for pagination
-   */
-  async getFilledDocumentsByStatus(
-    status: FilledDocumentStatus,
-    pageSize = 20,
-    lastDoc?: QueryDocumentSnapshot<FilledDocument>
-  ): Promise<{
-    documents: FilledDocument[];
-    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
-  }> {
-    console.warn(
-      "getFilledDocumentsByStatus needs rework for subcollection model or Collection Group Queries."
-    );
-    // Original logic commented out
-    /*
-    let q = query(
-      this.collectionRef, // LINTER ERROR
-      where("status", "==", status),
-      orderBy("updatedAt", "desc"),
-      limit(pageSize)
-    );
-    // ... rest of original logic ...
-    */
-    return { documents: [], lastDoc: null }; // Placeholder return
-  }
-
-  /**
-   * Upload a file for a filled document field without updating the document.
-   * This method only handles the upload and returns the file value to be used by the UI.
-   *
-   * @param appointmentId - ID of the appointment
-   * @param formId - ID of the filled document
-   * @param isUserForm - Boolean indicating if it's a user form or doctor form
-   * @param file - The file to upload
-   * @returns The file value object to be stored in the document
-   */
-  async uploadFileForFilledDocument(
-    appointmentId: string,
-    formId: string,
-    isUserForm: boolean,
-    file: File | Blob
-  ): Promise<FilledDocumentFileValue> {
-    console.log(
-      `[FilledDocumentService] Uploading file for form ${formId} in appointment ${appointmentId}`
-    );
-
-    // Generate a unique file ID
-    const fileId = this.generateId();
-
-    // Set the path according to the specified structure
-    const formType = isUserForm ? "user-form" : "doctor-form";
-    const collectionName = `${formType}/${formId}`;
-
-    // Always use CONFIDENTIAL access level
-    const accessLevel = MediaAccessLevel.CONFIDENTIAL;
-
-    // Upload the file using MediaService
-    const mediaMetadata = await this.mediaService.uploadMedia(
-      file,
-      appointmentId, // Using appointmentId as ownerId
-      accessLevel,
-      collectionName,
-      file instanceof File ? file.name : `file_${fileId}`
-    );
-
-    // Create and return a file value object
-    const fileValue: FilledDocumentFileValue = {
-      mediaId: mediaMetadata.id,
-      url: mediaMetadata.url,
-      name: mediaMetadata.name,
-      contentType: mediaMetadata.contentType,
-      size: mediaMetadata.size,
-      uploadedAt: Date.now(),
-    };
-
-    return fileValue;
-  }
-
-  /**
-   * Upload a signature image for a filled document.
-   * This is a specialized version of uploadFileForFilledDocument specifically for signatures.
-   *
-   * @param appointmentId - ID of the appointment
-   * @param formId - ID of the filled document
-   * @param isUserForm - Boolean indicating if it's a user form or doctor form
-   * @param signatureBlob - The signature image as a Blob
-   * @returns The file value object to be stored in the document
-   */
-  async uploadSignatureForFilledDocument(
-    appointmentId: string,
-    formId: string,
-    isUserForm: boolean,
-    signatureBlob: Blob
-  ): Promise<FilledDocumentFileValue> {
-    console.log(
-      `[FilledDocumentService] Uploading signature for form ${formId}`
-    );
-
-    // Generate a filename for the signature
-    const signatureId = this.generateId();
-    const signatureFile = new File(
-      [signatureBlob],
-      `signature_${signatureId}.png`,
-      { type: "image/png" }
-    );
-
-    // Use the general file upload method
-    return this.uploadFileForFilledDocument(
-      appointmentId,
-      formId,
-      isUserForm,
-      signatureFile
-    );
-  }
-
-  /**
-   * Delete a file using its mediaId.
-   *
-   * @param mediaId - ID of the media to delete
-   * @returns Promise resolving when the deletion is complete
-   */
-  async deleteFile(mediaId: string): Promise<void> {
-    console.log(
-      `[FilledDocumentService] Deleting file with mediaId ${mediaId}`
-    );
-
-    if (!mediaId) {
-      throw new Error("MediaId is required to delete a file");
-    }
-
-    // Delete the file using MediaService
-    await this.mediaService.deleteMedia(mediaId);
-  }
-}
+import {
+  collection,
+  doc,
+  getDoc,
+  getDocs,
+  setDoc,
+  updateDoc,
+  query,
+  where,
+  orderBy,
+  limit,
+  startAfter,
+  QueryDocumentSnapshot,
+} from "firebase/firestore";
+import { BaseService } from "../base.service";
+import {
+  // DocumentTemplate, // Not directly used in this file if relying on templateService
+  // DOCUMENTATION_TEMPLATES_COLLECTION, // No longer needed directly here if using templateService
+  // FILLED_DOCUMENTS_COLLECTION, // This will be replaced by subcollection paths
+  FilledDocument,
+  FilledDocumentStatus,
+  FilledDocumentFileValue,
+  USER_FORMS_SUBCOLLECTION,
+  DOCTOR_FORMS_SUBCOLLECTION,
+} from "../../types"; // General types
+import { APPOINTMENTS_COLLECTION } from "../../types/appointment"; // Specific import for the constant
+import { DocumentationTemplateService } from "./documentation-template.service";
+import {
+  MediaService,
+  MediaAccessLevel,
+  MediaMetadata,
+} from "../media/media.service";
+// Import the new validation schemas if you plan to use them for input validation here
+// import { createFilledDocumentDataSchema, updateFilledDocumentDataSchema } from '../../validations/documentation-templates.schema';
+
+/**
+ * Service for managing filled documents within appointment subcollections
+ */
+export class FilledDocumentService extends BaseService {
+  // No single collectionRef anymore, paths will be dynamic
+  private readonly templateService: DocumentationTemplateService;
+  private readonly mediaService: MediaService;
+
+  constructor(...args: ConstructorParameters<typeof BaseService>) {
+    super(...args);
+    this.templateService = new DocumentationTemplateService(...args); // Pass db and other args
+    this.mediaService = new MediaService(...args); // Initialize media service with the same args
+  }
+
+  private getFormSubcollectionPath(
+    isUserForm: boolean
+  ): typeof USER_FORMS_SUBCOLLECTION | typeof DOCTOR_FORMS_SUBCOLLECTION {
+    return isUserForm ? USER_FORMS_SUBCOLLECTION : DOCTOR_FORMS_SUBCOLLECTION;
+  }
+
+  /**
+   * Create a new filled document within an appointment's subcollection.
+   * @param templateId - ID of the template to use.
+   * @param templateVersion - Version of the template to use.
+   * @param appointmentId - ID of the appointment this form belongs to.
+   * @param procedureId - ID of the procedure associated with this form.
+   * @param patientId - ID of the patient.
+   * @param practitionerId - ID of the practitioner (can be system/generic if patient is filling).
+   * @param clinicId - ID of the clinic.
+   * @param initialValues - Optional initial values for the form elements.
+   * @param initialStatus - Optional initial status for the form.
+   * @returns The created filled document.
+   */
+  async createFilledDocumentForAppointment(
+    templateId: string,
+    templateVersion: number,
+    appointmentId: string,
+    procedureId: string,
+    patientId: string,
+    practitionerId: string, // Consider if this is always available or if a placeholder is needed
+    clinicId: string, // Same consideration as practitionerId
+    initialValues: { [elementId: string]: any } = {},
+    initialStatus: FilledDocumentStatus = FilledDocumentStatus.DRAFT
+  ): Promise<FilledDocument> {
+    const template = await this.templateService.getTemplateById(
+      templateId,
+      templateVersion
+    );
+    if (!template) {
+      throw new Error(`Template with ID ${templateId} not found`);
+    }
+
+    const documentId = this.generateId();
+    const now = Date.now();
+    const isUserForm = template.isUserForm || false;
+    const formSubcollection = this.getFormSubcollectionPath(isUserForm);
+
+    const filledDocument: FilledDocument = {
+      id: documentId,
+      templateId,
+      templateVersion: template.version,
+      isUserForm: isUserForm, // Set based on template
+      isRequired: template.isRequired || false, // Inherit isRequired from the template
+      appointmentId: appointmentId, // NEW
+      procedureId: procedureId, // NEW
+      patientId,
+      practitionerId,
+      clinicId,
+      createdAt: now,
+      updatedAt: now,
+      values: initialValues,
+      status: initialStatus,
+    };
+
+    const docRef = doc(
+      this.db,
+      APPOINTMENTS_COLLECTION, // Replaced "appointments"
+      appointmentId,
+      formSubcollection,
+      documentId
+    );
+    await setDoc(docRef, filledDocument);
+
+    return filledDocument;
+  }
+
+  /**
+   * Get a specific filled document from an appointment's subcollection.
+   * @param appointmentId - ID of the appointment.
+   * @param formId - ID of the filled document.
+   * @param isUserForm - Boolean indicating if it's a user form or doctor form.
+   * @returns The filled document or null if not found.
+   */
+  async getFilledDocumentFromAppointmentById(
+    appointmentId: string,
+    formId: string,
+    isUserForm: boolean
+  ): Promise<FilledDocument | null> {
+    const formSubcollection = this.getFormSubcollectionPath(isUserForm);
+    const docRef = doc(
+      this.db,
+      APPOINTMENTS_COLLECTION, // Replaced "appointments"
+      appointmentId,
+      formSubcollection,
+      formId
+    );
+    const docSnap = await getDoc(docRef);
+
+    if (!docSnap.exists()) {
+      return null;
+    }
+    const data = docSnap.data() as FilledDocument;
+    // Ensure id is populated from Firestore document ID if not in data
+    if (!data.id) {
+      data.id = docSnap.id;
+    }
+    return data;
+  }
+
+  /**
+   * Update values or status in a filled document within an appointment's subcollection.
+   * @param appointmentId - ID of the appointment.
+   * @param formId - ID of the filled document to update.
+   * @param isUserForm - Boolean indicating if it's a user form or doctor form.
+   * @param values - Updated values for elements.
+   * @param status - Optional new status for the document.
+   * @returns The updated filled document.
+   */
+  async updateFilledDocumentInAppointment(
+    appointmentId: string,
+    formId: string,
+    isUserForm: boolean,
+    values?: { [elementId: string]: any },
+    status?: FilledDocumentStatus
+  ): Promise<FilledDocument> {
+    const formSubcollection = this.getFormSubcollectionPath(isUserForm);
+    const docRef = doc(
+      this.db,
+      APPOINTMENTS_COLLECTION, // Replaced "appointments"
+      appointmentId,
+      formSubcollection,
+      formId
+    );
+
+    const existingDoc = await this.getFilledDocumentFromAppointmentById(
+      appointmentId,
+      formId,
+      isUserForm
+    );
+
+    if (!existingDoc) {
+      throw new Error(
+        `Filled document with ID ${formId} not found in appointment ${appointmentId} ${formSubcollection}`
+      );
+    }
+
+    const updatePayload: Partial<FilledDocument> = {
+      updatedAt: Date.now(),
+    };
+
+    if (values) {
+      updatePayload.values = {
+        ...existingDoc.values,
+        ...values,
+      };
+    }
+    if (status) {
+      updatePayload.status = status;
+    }
+
+    if (
+      Object.keys(updatePayload).length === 1 &&
+      "updatedAt" in updatePayload
+    ) {
+      // Only updatedAt, no actual data change, so we can skip the update
+      // or just update timestamp if that is the desired behavior.
+      // For now, we proceed to update the timestamp at least.
+    }
+
+    await updateDoc(docRef, updatePayload);
+
+    return { ...existingDoc, ...updatePayload } as FilledDocument;
+  }
+
+  /**
+   * Get all filled user forms for a specific appointment.
+   * @param appointmentId ID of the appointment.
+   * @param pageSize Number of documents to retrieve.
+   * @param lastDoc Last document from previous page for pagination.
+   */
+  async getFilledUserFormsForAppointment(
+    appointmentId: string,
+    pageSize = 20,
+    lastDoc?: QueryDocumentSnapshot<FilledDocument>
+  ): Promise<{
+    documents: FilledDocument[];
+    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
+  }> {
+    const subcollectionRef = collection(
+      this.db,
+      APPOINTMENTS_COLLECTION, // Replaced "appointments"
+      appointmentId,
+      USER_FORMS_SUBCOLLECTION
+    );
+    let q = query(
+      subcollectionRef,
+      orderBy("updatedAt", "desc"),
+      limit(pageSize)
+    );
+
+    if (lastDoc) {
+      q = query(q, startAfter(lastDoc));
+    }
+    return this.executeQuery(q);
+  }
+
+  /**
+   * Get all filled doctor forms for a specific appointment.
+   * @param appointmentId ID of the appointment.
+   * @param pageSize Number of documents to retrieve.
+   * @param lastDoc Last document from previous page for pagination.
+   */
+  async getFilledDoctorFormsForAppointment(
+    appointmentId: string,
+    pageSize = 20,
+    lastDoc?: QueryDocumentSnapshot<FilledDocument>
+  ): Promise<{
+    documents: FilledDocument[];
+    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
+  }> {
+    const subcollectionRef = collection(
+      this.db,
+      APPOINTMENTS_COLLECTION, // Replaced "appointments"
+      appointmentId,
+      DOCTOR_FORMS_SUBCOLLECTION
+    );
+    let q = query(
+      subcollectionRef,
+      orderBy("updatedAt", "desc"),
+      limit(pageSize)
+    );
+
+    if (lastDoc) {
+      q = query(q, startAfter(lastDoc));
+    }
+    return this.executeQuery(q);
+  }
+
+  // Helper to execute query and return documents + lastDoc
+  private async executeQuery(
+    q: any // Firestore Query type
+  ): Promise<{
+    documents: FilledDocument[];
+    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
+  }> {
+    const querySnapshot = await getDocs(q);
+    const documents: FilledDocument[] = [];
+    let lastVisible: QueryDocumentSnapshot<FilledDocument> | null = null;
+
+    querySnapshot.forEach((docSnapshot) => {
+      const data = docSnapshot.data() as FilledDocument;
+      // Ensure id is populated from Firestore document ID if not in data
+      if (!data.id) {
+        data.id = docSnapshot.id;
+      }
+      documents.push(data);
+      lastVisible = docSnapshot as QueryDocumentSnapshot<FilledDocument>;
+    });
+
+    return {
+      documents,
+      lastDoc: lastVisible,
+    };
+  }
+
+  // IMPORTANT: The following methods that query across all patients/practitioners/clinics
+  // (e.g., getFilledDocumentsByPatient, getFilledDocumentsByPractitioner)
+  // will NOT work correctly if FILLED_DOCUMENTS_COLLECTION is no longer a top-level collection
+  // and data is only in appointment subcollections. You would need to use
+  // Firestore Collection Group Queries for that, which require an index and a different query approach.
+  // These methods are left here for now but would need significant rework or removal.
+
+  /**
+   * Get filled documents for a patient (NEEDS REWORK for subcollections or Collection Group Query)
+   * @param patientId - ID of the patient
+   * @param pageSize - Number of documents to retrieve
+   * @param lastDoc - Last document from previous page for pagination
+   * @returns Array of filled documents and the last document for pagination
+   */
+  async getFilledDocumentsByPatient(
+    patientId: string,
+    pageSize = 20,
+    lastDoc?: QueryDocumentSnapshot<FilledDocument>
+  ): Promise<{
+    documents: FilledDocument[];
+    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
+  }> {
+    console.warn(
+      "getFilledDocumentsByPatient needs rework for subcollection model or Collection Group Queries."
+    );
+    // Original logic commented out as this.collectionRef is no longer valid for this model
+    /*
+    let q = query(
+      this.collectionRef, // LINTER ERROR: this.collectionRef no longer exists
+      where("patientId", "==", patientId),
+      orderBy("updatedAt", "desc"),
+      limit(pageSize)
+    );
+
+    if (lastDoc) {
+      q = query(q, startAfter(lastDoc));
+    }
+
+    const querySnapshot = await getDocs(q);
+    const documents: FilledDocument[] = [];
+    let lastVisible: QueryDocumentSnapshot<FilledDocument> | null = null;
+
+    querySnapshot.forEach((doc) => {
+      documents.push(doc.data() as FilledDocument);
+      lastVisible = doc as QueryDocumentSnapshot<FilledDocument>;
+    });
+
+    return {
+      documents,
+      lastDoc: lastVisible,
+    };
+    */
+    return { documents: [], lastDoc: null }; // Placeholder return
+  }
+
+  /**
+   * Get filled documents for a practitioner (NEEDS REWORK for subcollections or Collection Group Query)
+   * @param practitionerId - ID of the practitioner
+   * @param pageSize - Number of documents to retrieve
+   * @param lastDoc - Last document from previous page for pagination
+   * @returns Array of filled documents and the last document for pagination
+   */
+  async getFilledDocumentsByPractitioner(
+    practitionerId: string,
+    pageSize = 20,
+    lastDoc?: QueryDocumentSnapshot<FilledDocument>
+  ): Promise<{
+    documents: FilledDocument[];
+    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
+  }> {
+    console.warn(
+      "getFilledDocumentsByPractitioner needs rework for subcollection model or Collection Group Queries."
+    );
+    // Original logic commented out
+    /*
+    let q = query(
+      this.collectionRef, // LINTER ERROR
+      where("practitionerId", "==", practitionerId),
+      orderBy("updatedAt", "desc"),
+      limit(pageSize)
+    );
+    // ... rest of original logic ...
+    */
+    return { documents: [], lastDoc: null }; // Placeholder return
+  }
+
+  /**
+   * Get filled documents for a clinic (NEEDS REWORK for subcollections or Collection Group Query)
+   * @param clinicId - ID of the clinic
+   * @param pageSize - Number of documents to retrieve
+   * @param lastDoc - Last document from previous page for pagination
+   * @returns Array of filled documents and the last document for pagination
+   */
+  async getFilledDocumentsByClinic(
+    clinicId: string,
+    pageSize = 20,
+    lastDoc?: QueryDocumentSnapshot<FilledDocument>
+  ): Promise<{
+    documents: FilledDocument[];
+    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
+  }> {
+    console.warn(
+      "getFilledDocumentsByClinic needs rework for subcollection model or Collection Group Queries."
+    );
+    // Original logic commented out
+    /*
+    let q = query(
+      this.collectionRef, // LINTER ERROR
+      where("clinicId", "==", clinicId),
+      orderBy("updatedAt", "desc"),
+      limit(pageSize)
+    );
+    // ... rest of original logic ...
+    */
+    return { documents: [], lastDoc: null }; // Placeholder return
+  }
+
+  /**
+   * Get filled documents by template (NEEDS REWORK for subcollections or Collection Group Query)
+   * @param templateId - ID of the template
+   * @param pageSize - Number of documents to retrieve
+   * @param lastDoc - Last document from previous page for pagination
+   * @returns Array of filled documents and the last document for pagination
+   */
+  async getFilledDocumentsByTemplate(
+    templateId: string,
+    pageSize = 20,
+    lastDoc?: QueryDocumentSnapshot<FilledDocument>
+  ): Promise<{
+    documents: FilledDocument[];
+    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
+  }> {
+    console.warn(
+      "getFilledDocumentsByTemplate needs rework for subcollection model or Collection Group Queries."
+    );
+    // Original logic commented out
+    /*
+    let q = query(
+      this.collectionRef, // LINTER ERROR
+      where("templateId", "==", templateId),
+      orderBy("updatedAt", "desc"),
+      limit(pageSize)
+    );
+    // ... rest of original logic ...
+    */
+    return { documents: [], lastDoc: null }; // Placeholder return
+  }
+
+  /**
+   * Get filled documents by status (NEEDS REWORK for subcollections or Collection Group Query)
+   * @param status - Status to filter by
+   * @param pageSize - Number of documents to retrieve
+   * @param lastDoc - Last document from previous page for pagination
+   * @returns Array of filled documents and the last document for pagination
+   */
+  async getFilledDocumentsByStatus(
+    status: FilledDocumentStatus,
+    pageSize = 20,
+    lastDoc?: QueryDocumentSnapshot<FilledDocument>
+  ): Promise<{
+    documents: FilledDocument[];
+    lastDoc: QueryDocumentSnapshot<FilledDocument> | null;
+  }> {
+    console.warn(
+      "getFilledDocumentsByStatus needs rework for subcollection model or Collection Group Queries."
+    );
+    // Original logic commented out
+    /*
+    let q = query(
+      this.collectionRef, // LINTER ERROR
+      where("status", "==", status),
+      orderBy("updatedAt", "desc"),
+      limit(pageSize)
+    );
+    // ... rest of original logic ...
+    */
+    return { documents: [], lastDoc: null }; // Placeholder return
+  }
+
+  /**
+   * Upload a file for a filled document field without updating the document.
+   * This method only handles the upload and returns the file value to be used by the UI.
+   *
+   * @param appointmentId - ID of the appointment
+   * @param formId - ID of the filled document
+   * @param isUserForm - Boolean indicating if it's a user form or doctor form
+   * @param file - The file to upload
+   * @returns The file value object to be stored in the document
+   */
+  async uploadFileForFilledDocument(
+    appointmentId: string,
+    formId: string,
+    isUserForm: boolean,
+    file: File | Blob
+  ): Promise<FilledDocumentFileValue> {
+    console.log(
+      `[FilledDocumentService] Uploading file for form ${formId} in appointment ${appointmentId}`
+    );
+
+    // Generate a unique file ID
+    const fileId = this.generateId();
+
+    // Set the path according to the specified structure
+    const formType = isUserForm ? "user-form" : "doctor-form";
+    const collectionName = `${formType}/${formId}`;
+
+    // Always use CONFIDENTIAL access level
+    const accessLevel = MediaAccessLevel.CONFIDENTIAL;
+
+    // Upload the file using MediaService
+    const mediaMetadata = await this.mediaService.uploadMedia(
+      file,
+      appointmentId, // Using appointmentId as ownerId
+      accessLevel,
+      collectionName,
+      file instanceof File ? file.name : `file_${fileId}`
+    );
+
+    // Create and return a file value object
+    const fileValue: FilledDocumentFileValue = {
+      mediaId: mediaMetadata.id,
+      url: mediaMetadata.url,
+      name: mediaMetadata.name,
+      contentType: mediaMetadata.contentType,
+      size: mediaMetadata.size,
+      uploadedAt: Date.now(),
+    };
+
+    return fileValue;
+  }
+
+  /**
+   * Upload a signature image for a filled document.
+   * This is a specialized version of uploadFileForFilledDocument specifically for signatures.
+   *
+   * @param appointmentId - ID of the appointment
+   * @param formId - ID of the filled document
+   * @param isUserForm - Boolean indicating if it's a user form or doctor form
+   * @param signatureBlob - The signature image as a Blob
+   * @returns The file value object to be stored in the document
+   */
+  async uploadSignatureForFilledDocument(
+    appointmentId: string,
+    formId: string,
+    isUserForm: boolean,
+    signatureBlob: Blob
+  ): Promise<FilledDocumentFileValue> {
+    console.log(
+      `[FilledDocumentService] Uploading signature for form ${formId}`
+    );
+
+    // Generate a filename for the signature
+    const signatureId = this.generateId();
+    const signatureFile = new File(
+      [signatureBlob],
+      `signature_${signatureId}.png`,
+      { type: "image/png" }
+    );
+
+    // Use the general file upload method
+    return this.uploadFileForFilledDocument(
+      appointmentId,
+      formId,
+      isUserForm,
+      signatureFile
+    );
+  }
+
+  /**
+   * Delete a file using its mediaId.
+   *
+   * @param mediaId - ID of the media to delete
+   * @returns Promise resolving when the deletion is complete
+   */
+  async deleteFile(mediaId: string): Promise<void> {
+    console.log(
+      `[FilledDocumentService] Deleting file with mediaId ${mediaId}`
+    );
+
+    if (!mediaId) {
+      throw new Error("MediaId is required to delete a file");
+    }
+
+    // Delete the file using MediaService
+    await this.mediaService.deleteMedia(mediaId);
+  }
+}