@blackcode_sa/metaestetics-api 1.12.62 → 1.12.63

package/src/services/appointment/appointment.service.ts

@@ -1,2082 +1,2505 @@
-import {
-  Firestore,
-  Timestamp,
-  DocumentSnapshot,
-  serverTimestamp,
-  arrayUnion,
-  arrayRemove,
-  QueryConstraint,
-  where,
-  orderBy,
-  collection,
-  query,
-  limit,
-  startAfter,
-  getDocs,
-  getCountFromServer,
-} from 'firebase/firestore';
-import { Auth } from 'firebase/auth';
-import { FirebaseApp } from 'firebase/app';
-import { Functions, getFunctions, httpsCallable } from 'firebase/functions';
-import { BaseService } from '../base.service';
-import {
-  Appointment,
-  AppointmentStatus,
-  UpdateAppointmentData,
-  SearchAppointmentsParams,
-  PaymentStatus,
-  AppointmentMediaItem,
-  PatientReviewInfo,
-  type CreateAppointmentHttpData,
-  type ZonePhotoUploadData,
-  BeforeAfterPerZone,
-  ZoneItemData,
-  ExtendedProcedureInfo,
-  AppointmentProductMetadata,
-  RecommendedProcedure,
-  APPOINTMENTS_COLLECTION,
-} from '../../types/appointment';
-import {
-  updateAppointmentSchema,
-  searchAppointmentsSchema,
-  rescheduleAppointmentSchema,
-  zonePhotoUploadSchema,
-} from '../../validations/appointment.schema';
-
-// Import other services needed (dependency injection pattern)
-import { CalendarServiceV2 } from '../calendar/calendar.v2.service';
-import { PatientService } from '../patient/patient.service';
-import { PractitionerService } from '../practitioner/practitioner.service';
-import { ClinicService } from '../clinic/clinic.service';
-import { FilledDocumentService } from '../documentation-templates/filled-document.service';
-import {
-  MediaService,
-  MediaAccessLevel,
-  MediaMetadata,
-  MediaResource,
-} from '../media/media.service';
-
-// Import utility functions
-import {
-  updateAppointmentUtil,
-  getAppointmentByIdUtil,
-  searchAppointmentsUtil,
-} from './utils/appointment.utils';
-import {
-  addItemToZoneUtil,
-  removeItemFromZoneUtil,
-  updateZoneItemUtil,
-  overridePriceForZoneItemUtil,
-  updateSubzonesUtil,
-  calculateFinalBilling,
-} from './utils/zone-management.utils';
-import {
-  addExtendedProcedureUtil,
-  removeExtendedProcedureUtil,
-  getExtendedProceduresUtil,
-  getAppointmentProductsUtil,
-} from './utils/extended-procedure.utils';
-import {
-  addRecommendedProcedureUtil,
-  removeRecommendedProcedureUtil,
-  updateRecommendedProcedureUtil,
-  getRecommendedProceduresUtil,
-} from './utils/recommended-procedure.utils';
-import {
-  updateZonePhotoEntryUtil,
-  addAfterPhotoToEntryUtil,
-  updateZonePhotoNotesUtil,
-  getZonePhotoEntryUtil,
-} from './utils/zone-photo.utils';
-
-/**
- * Interface for available booking slot
- */
-interface AvailableSlot {
-  start: Date;
-}
-
-/**
- * AppointmentService is responsible for managing appointments,
- * including creating, updating, retrieving, and searching appointments.
- * It serves as the main entry point for working with appointment data.
- */
-export class AppointmentService extends BaseService {
-  private calendarService: CalendarServiceV2;
-  private patientService: PatientService;
-  private practitionerService: PractitionerService;
-  private clinicService: ClinicService;
-  private filledDocumentService: FilledDocumentService;
-  private mediaService: MediaService;
-  private functions: Functions;
-
-  /**
-   * Creates a new AppointmentService instance.
-   *
-   * @param db Firestore instance
-   * @param auth Firebase Auth instance
-   * @param app Firebase App instance
-   * @param calendarService Calendar service instance
-   * @param patientService Patient service instance
-   * @param practitionerService Practitioner service instance
-   * @param clinicService Clinic service instance
-   * @param filledDocumentService Filled document service instance
-   */
-  constructor(
-    db: Firestore,
-    auth: Auth,
-    app: FirebaseApp,
-    calendarService: CalendarServiceV2,
-    patientService: PatientService,
-    practitionerService: PractitionerService,
-    clinicService: ClinicService,
-    filledDocumentService: FilledDocumentService,
-  ) {
-    super(db, auth, app);
-    this.calendarService = calendarService;
-    this.patientService = patientService;
-    this.practitionerService = practitionerService;
-    this.clinicService = clinicService;
-    this.filledDocumentService = filledDocumentService;
-    this.mediaService = new MediaService(db, auth, app);
-    this.functions = getFunctions(app, 'europe-west6'); // Initialize Firebase Functions with the correct region
-  }
-
-  /**
-   * Gets available booking slots for a specific clinic, practitioner, and procedure using HTTP request.
-   * This is an alternative implementation using direct HTTP request instead of callable function.
-   *
-   * @param clinicId ID of the clinic
-   * @param practitionerId ID of the practitioner
-   * @param procedureId ID of the procedure
-   * @param startDate Start date of the time range to check
-   * @param endDate End date of the time range to check
-   * @returns Array of available booking slots
-   */
-  async getAvailableBookingSlotsHttp(
-    clinicId: string,
-    practitionerId: string,
-    procedureId: string,
-    startDate: Date,
-    endDate: Date,
-  ): Promise<AvailableSlot[]> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Getting available booking slots via HTTP for clinic: ${clinicId}, practitioner: ${practitionerId}, procedure: ${procedureId}`,
-      );
-
-      // Validate input parameters
-      if (!clinicId || !practitionerId || !procedureId || !startDate || !endDate) {
-        throw new Error('Missing required parameters for booking slots calculation');
-      }
-
-      if (endDate <= startDate) {
-        throw new Error('End date must be after start date');
-      }
-
-      // Check if user is authenticated
-      const currentUser = this.auth.currentUser;
-      if (!currentUser) {
-        throw new Error('User must be authenticated to get available booking slots');
-      }
-
-      // Construct the function URL for the Express app endpoint
-      const functionUrl = `https://europe-west6-metaestetics.cloudfunctions.net/bookingApi/getAvailableBookingSlots`;
-
-      // Get the authenticated user's ID token
-      // By default, getIdToken doesn't allow setting audience for web/mobile clients
-      // So we need to treat this token specially on the server side
-      const idToken = await currentUser.getIdToken();
-
-      // Log that we're getting a token
-      console.log(`[APPOINTMENT_SERVICE] Got user token, user ID: ${currentUser.uid}`);
-
-      // Alternate direct URL (if needed):
-      // const functionUrl = `https://getavailablebookingslotshttp-grqala5m6a-oa.a.run.app`;
-
-      // Request data
-      const requestData = {
-        clinicId,
-        practitionerId,
-        procedureId,
-        timeframe: {
-          start: startDate.getTime(), // Convert to timestamp
-          end: endDate.getTime(),
-        },
-      };
-
-      console.log(`[APPOINTMENT_SERVICE] Making fetch request to ${functionUrl}`);
-
-      // Make the HTTP request with expanded CORS options for browser
-      const response = await fetch(functionUrl, {
-        method: 'POST',
-        mode: 'cors', // Important for cross-origin requests
-        cache: 'no-cache', // Don't cache this request
-        credentials: 'omit', // Don't send cookies since we're using token auth
-        headers: {
-          'Content-Type': 'application/json',
-          Authorization: `Bearer ${idToken}`,
-        },
-        redirect: 'follow',
-        referrerPolicy: 'no-referrer',
-        body: JSON.stringify(requestData),
-      });
-
-      console.log(
-        `[APPOINTMENT_SERVICE] Received response ${response.status}: ${response.statusText}`,
-      );
-
-      // Check if the request was successful
-      if (!response.ok) {
-        const errorText = await response.text();
-        console.error(`[APPOINTMENT_SERVICE] Error response details: ${errorText}`);
-        throw new Error(
-          `Failed to get available booking slots: ${response.status} ${response.statusText} - ${errorText}`,
-        );
-      }
-
-      // Parse the response
-      const result = await response.json();
-      console.log(`[APPOINTMENT_SERVICE] Response parsed successfully`, result);
-
-      if (!result.success) {
-        throw new Error(result.error || 'Failed to get available booking slots');
-      }
-
-      // Convert timestamp numbers to Date objects
-      const slots: AvailableSlot[] = result.availableSlots.map((slot: { start: number }) => ({
-        start: new Date(slot.start),
-      }));
-
-      console.log(`[APPOINTMENT_SERVICE] Found ${slots.length} available booking slots via HTTP`);
-
-      return slots;
-    } catch (error) {
-      console.error('[APPOINTMENT_SERVICE] Error getting available booking slots via HTTP:', error);
-      throw error;
-    }
-  }
-
-  /**
-   * Creates an appointment via the Cloud Function orchestrateAppointmentCreation
-   *
-   * @param data - CreateAppointmentData object
-   * @returns The created appointment
-   */
-  async createAppointmentHttp(data: CreateAppointmentHttpData): Promise<Appointment> {
-    try {
-      console.log('[APPOINTMENT_SERVICE] Creating appointment via cloud function');
-
-      // Get the authenticated user's ID token
-      const currentUser = this.auth.currentUser;
-      if (!currentUser) {
-        throw new Error('User must be authenticated to create an appointment');
-      }
-      const idToken = await currentUser.getIdToken();
-
-      // Construct the function URL for the Express app endpoint
-      const functionUrl = `https://europe-west6-metaestetics.cloudfunctions.net/bookingApi/orchestrateAppointmentCreation`;
-
-      // Prepare request data for the Cloud Function
-      // Map CreateAppointmentData to OrchestrateAppointmentCreationData format
-      const requestData = {
-        patientId: data.patientId,
-        procedureId: data.procedureId,
-        appointmentStartTime: data.appointmentStartTime.toMillis
-          ? data.appointmentStartTime.toMillis()
-          : new Date(data.appointmentStartTime as any).getTime(),
-        appointmentEndTime: data.appointmentEndTime.toMillis
-          ? data.appointmentEndTime.toMillis()
-          : new Date(data.appointmentEndTime as any).getTime(),
-        patientNotes: data?.patientNotes || null,
-      };
-
-      console.log(`[APPOINTMENT_SERVICE] Making fetch request to ${functionUrl}`);
-
-      // Make the HTTP request with expanded CORS options for browser
-      const response = await fetch(functionUrl, {
-        method: 'POST',
-        mode: 'cors',
-        cache: 'no-cache',
-        credentials: 'omit',
-        headers: {
-          'Content-Type': 'application/json',
-          Authorization: `Bearer ${idToken}`,
-        },
-        redirect: 'follow',
-        referrerPolicy: 'no-referrer',
-        body: JSON.stringify(requestData),
-      });
-
-      console.log(
-        `[APPOINTMENT_SERVICE] Received response ${response.status}: ${response.statusText}`,
-      );
-
-      // Check if the request was successful
-      if (!response.ok) {
-        const errorText = await response.text();
-        console.error(`[APPOINTMENT_SERVICE] Error response details: ${errorText}`);
-        throw new Error(
-          `Failed to create appointment: ${response.status} ${response.statusText} - ${errorText}`,
-        );
-      }
-
-      // Parse the response
-      const result = await response.json();
-
-      if (!result.success) {
-        throw new Error(result.error || 'Failed to create appointment');
-      }
-
-      // If the backend returns the full appointment data
-      if (result.appointmentData) {
-        console.log(`[APPOINTMENT_SERVICE] Appointment created with ID: ${result.appointmentId}`);
-        return result.appointmentData;
-      }
-
-      // If only the ID is returned, fetch the complete appointment
-      const createdAppointment = await this.getAppointmentById(result.appointmentId);
-      if (!createdAppointment) {
-        throw new Error(`Failed to retrieve created appointment with ID: ${result.appointmentId}`);
-      }
-
-      return createdAppointment;
-    } catch (error) {
-      console.error('[APPOINTMENT_SERVICE] Error creating appointment via cloud function:', error);
-      throw error;
-    }
-  }
-
-  /**
-   * Gets an appointment by ID.
-   *
-   * @param appointmentId ID of the appointment to retrieve
-   * @returns The appointment or null if not found
-   */
-  async getAppointmentById(appointmentId: string): Promise<Appointment | null> {
-    try {
-      console.log(`[APPOINTMENT_SERVICE] Getting appointment with ID: ${appointmentId}`);
-
-      const appointment = await getAppointmentByIdUtil(this.db, appointmentId);
-
-      console.log(
-        `[APPOINTMENT_SERVICE] Appointment ${appointmentId} ${appointment ? 'found' : 'not found'}`,
-      );
-
-      return appointment;
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error getting appointment ${appointmentId}:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Updates an existing appointment.
-   *
-   * @param appointmentId ID of the appointment to update
-   * @param data Update data for the appointment
-   * @returns The updated appointment
-   */
-  async updateAppointment(
-    appointmentId: string,
-    data: UpdateAppointmentData,
-  ): Promise<Appointment> {
-    try {
-      console.log(`[APPOINTMENT_SERVICE] Updating appointment with ID: ${appointmentId}`);
-
-      // AUTO-MIGRATION: Convert old zonePhotos format to new array format BEFORE validation
-      if (data.metadata?.zonePhotos) {
-        const migratedZonePhotos: Record<string, BeforeAfterPerZone[]> = {};
-
-        for (const [key, value] of Object.entries(data.metadata.zonePhotos)) {
-          if (Array.isArray(value)) {
-            // Already in new format
-            migratedZonePhotos[key] = value as BeforeAfterPerZone[];
-          } else {
-            // Old format - convert to array
-            console.log(`[APPOINTMENT_SERVICE] Auto-migrating ${key} from object to array format`);
-            const oldData = value as any;
-            migratedZonePhotos[key] = [
-              {
-                before: oldData.before || null,
-                after: oldData.after || null,
-                beforeNote: null,
-                afterNote: null,
-              },
-            ];
-          }
-        }
-
-        // Replace with migrated data
-        data.metadata.zonePhotos = migratedZonePhotos;
-      }
-
-      // AUTO-CLEANUP: Remove invalid recommendedProcedures with empty notes BEFORE validation
-      console.log(
-        '[APPOINTMENT_SERVICE] 🔍 BEFORE CLEANUP - recommendedProcedures:',
-        JSON.stringify(data.metadata?.recommendedProcedures, null, 2),
-      );
-
-      if (
-        data.metadata?.recommendedProcedures &&
-        Array.isArray(data.metadata.recommendedProcedures)
-      ) {
-        const validRecommendations = data.metadata.recommendedProcedures.filter((rec: any) => {
-          const isValid = rec.note && typeof rec.note === 'string' && rec.note.trim().length > 0;
-          if (!isValid) {
-            console.log('[APPOINTMENT_SERVICE] ❌ INVALID recommendation found:', rec);
-          }
-          return isValid;
-        });
-
-        if (validRecommendations.length !== data.metadata.recommendedProcedures.length) {
-          console.log(
-            `[APPOINTMENT_SERVICE] 🧹 Removing ${
-              data.metadata.recommendedProcedures.length - validRecommendations.length
-            } invalid recommended procedures with empty notes`,
-          );
-          data.metadata.recommendedProcedures = validRecommendations;
-        } else {
-          console.log('[APPOINTMENT_SERVICE] ✅ All recommendedProcedures are valid');
-        }
-      }
-
-      console.log(
-        '[APPOINTMENT_SERVICE] 🔍 AFTER CLEANUP - recommendedProcedures:',
-        JSON.stringify(data.metadata?.recommendedProcedures, null, 2),
-      );
-
-      // Validate input data
-      console.log('[APPOINTMENT_SERVICE] 🔍 Starting Zod validation...');
-      const validatedData = await updateAppointmentSchema.parseAsync(data);
-      console.log('[APPOINTMENT_SERVICE] ✅ Zod validation passed!');
-
-      // Update the appointment using the utility function
-      const updatedAppointment = await updateAppointmentUtil(this.db, appointmentId, validatedData);
-
-      console.log(`[APPOINTMENT_SERVICE] Appointment ${appointmentId} updated successfully`);
-
-      return updatedAppointment;
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error updating appointment ${appointmentId}:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Searches for appointments based on various criteria.
-   *
-   * @param params Search parameters
-   * @returns Found appointments and the last document for pagination
-   */
-  async searchAppointments(params: SearchAppointmentsParams): Promise<{
-    appointments: Appointment[];
-    lastDoc: DocumentSnapshot | null;
-  }> {
-    try {
-      console.log('[APPOINTMENT_SERVICE] Searching appointments with params:', params);
-
-      // Validate search parameters
-      await searchAppointmentsSchema.parseAsync(params);
-
-      // Search for appointments using the utility function
-      const result = await searchAppointmentsUtil(this.db, params);
-
-      console.log(`[APPOINTMENT_SERVICE] Found ${result.appointments.length} appointments`);
-
-      return result;
-    } catch (error) {
-      console.error('[APPOINTMENT_SERVICE] Error searching appointments:', error);
-      throw error;
-    }
-  }
-
-  /**
-   * Gets appointments for a specific patient.
-   *
-   * @param patientId ID of the patient
-   * @param options Optional parameters for filtering and pagination
-   * @returns Found appointments and the last document for pagination
-   */
-  async getPatientAppointments(
-    patientId: string,
-    options?: {
-      startDate?: Date;
-      endDate?: Date;
-      status?: AppointmentStatus | AppointmentStatus[];
-      limit?: number;
-      startAfter?: DocumentSnapshot;
-    },
-  ): Promise<{
-    appointments: Appointment[];
-    lastDoc: DocumentSnapshot | null;
-  }> {
-    console.log(`[APPOINTMENT_SERVICE] Getting appointments for patient: ${patientId}`);
-
-    const searchParams: SearchAppointmentsParams = {
-      patientId,
-      startDate: options?.startDate,
-      endDate: options?.endDate,
-      status: options?.status,
-      limit: options?.limit,
-      startAfter: options?.startAfter,
-    };
-
-    return this.searchAppointments(searchParams);
-  }
-
-  /**
-   * Gets appointments for a specific practitioner.
-   *
-   * @param practitionerId ID of the practitioner
-   * @param options Optional parameters for filtering and pagination
-   * @returns Found appointments and the last document for pagination
-   */
-  async getPractitionerAppointments(
-    practitionerId: string,
-    options?: {
-      startDate?: Date;
-      endDate?: Date;
-      status?: AppointmentStatus | AppointmentStatus[];
-      limit?: number;
-      startAfter?: DocumentSnapshot;
-    },
-  ): Promise<{
-    appointments: Appointment[];
-    lastDoc: DocumentSnapshot | null;
-  }> {
-    console.log(`[APPOINTMENT_SERVICE] Getting appointments for practitioner: ${practitionerId}`);
-
-    const searchParams: SearchAppointmentsParams = {
-      practitionerId,
-      startDate: options?.startDate,
-      endDate: options?.endDate,
-      status: options?.status,
-      limit: options?.limit,
-      startAfter: options?.startAfter,
-    };
-
-    return this.searchAppointments(searchParams);
-  }
-
-  /**
-   * Gets appointments for a specific clinic.
-   *
-   * @param clinicBranchId ID of the clinic branch
-   * @param options Optional parameters for filtering and pagination
-   * @returns Found appointments and the last document for pagination
-   */
-  async getClinicAppointments(
-    clinicBranchId: string,
-    options?: {
-      practitionerId?: string;
-      startDate?: Date;
-      endDate?: Date;
-      status?: AppointmentStatus | AppointmentStatus[];
-      limit?: number;
-      startAfter?: DocumentSnapshot;
-    },
-  ): Promise<{
-    appointments: Appointment[];
-    lastDoc: DocumentSnapshot | null;
-  }> {
-    console.log(`[APPOINTMENT_SERVICE] Getting appointments for clinic: ${clinicBranchId}`);
-
-    const searchParams: SearchAppointmentsParams = {
-      clinicBranchId,
-      practitionerId: options?.practitionerId,
-      startDate: options?.startDate,
-      endDate: options?.endDate,
-      status: options?.status,
-      limit: options?.limit,
-      startAfter: options?.startAfter,
-    };
-
-    return this.searchAppointments(searchParams);
-  }
-
-  /**
-   * Updates the status of an appointment.
-   *
-   * @param appointmentId ID of the appointment
-   * @param newStatus New status to set
-   * @param details Optional details for the status change
-   * @returns The updated appointment
-   */
-  async updateAppointmentStatus(
-    appointmentId: string,
-    newStatus: AppointmentStatus,
-    details?: {
-      cancellationReason?: string;
-      canceledBy?: 'patient' | 'clinic' | 'practitioner' | 'system';
-    },
-  ): Promise<Appointment> {
-    console.log(
-      `[APPOINTMENT_SERVICE] Updating status of appointment ${appointmentId} to ${newStatus}`,
-    );
-    const updateData: UpdateAppointmentData = {
-      status: newStatus,
-      updatedAt: serverTimestamp(),
-    };
-
-    if (
-      newStatus === AppointmentStatus.CANCELED_CLINIC ||
-      newStatus === AppointmentStatus.CANCELED_PATIENT ||
-      newStatus === AppointmentStatus.CANCELED_PATIENT_RESCHEDULED
-    ) {
-      if (!details?.cancellationReason) {
-        throw new Error('Cancellation reason is required when canceling.');
-      }
-      if (!details?.canceledBy) {
-        throw new Error('Canceled by is required when canceling.');
-      }
-      updateData.cancellationReason = details.cancellationReason;
-      updateData.canceledBy = details.canceledBy;
-      updateData.cancellationTime = Timestamp.now();
-    }
-
-    if (newStatus === AppointmentStatus.CONFIRMED) {
-      updateData.confirmationTime = Timestamp.now();
-    }
-
-    if (newStatus === AppointmentStatus.RESCHEDULED_BY_CLINIC) {
-      updateData.rescheduleTime = Timestamp.now();
-    }
-
-    return this.updateAppointment(appointmentId, updateData);
-  }
-
-  /**
-   * Confirms a PENDING appointment by an Admin/Clinic.
-   */
-  async confirmAppointmentAdmin(appointmentId: string): Promise<Appointment> {
-    console.log(`[APPOINTMENT_SERVICE] Admin confirming appointment: ${appointmentId}`);
-    const appointment = await this.getAppointmentById(appointmentId);
-    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
-    if (appointment.status !== AppointmentStatus.PENDING) {
-      throw new Error(`Appointment ${appointmentId} is not in PENDING state to be confirmed.`);
-    }
-    return this.updateAppointmentStatus(appointmentId, AppointmentStatus.CONFIRMED);
-  }
-
-  /**
-   * Cancels an appointment by the User (Patient).
-   */
-  async cancelAppointmentUser(appointmentId: string, reason: string): Promise<Appointment> {
-    console.log(`[APPOINTMENT_SERVICE] User canceling appointment: ${appointmentId}`);
-    return this.updateAppointmentStatus(appointmentId, AppointmentStatus.CANCELED_PATIENT, {
-      cancellationReason: reason,
-      canceledBy: 'patient',
-    });
-  }
-
-  /**
-   * Cancels an appointment by an Admin/Clinic.
-   */
-  async cancelAppointmentAdmin(appointmentId: string, reason: string): Promise<Appointment> {
-    console.log(`[APPOINTMENT_SERVICE] Admin canceling appointment: ${appointmentId}`);
-    return this.updateAppointmentStatus(appointmentId, AppointmentStatus.CANCELED_CLINIC, {
-      cancellationReason: reason,
-      canceledBy: 'clinic',
-    });
-  }
-
-  /**
-   * Admin proposes to reschedule an appointment.
-   * Sets status to RESCHEDULED_BY_CLINIC and updates times.
-   */
-  async rescheduleAppointmentAdmin(params: {
-    appointmentId: string;
-    newStartTime: any; // Accept any type (number, string, Timestamp, etc.)
-    newEndTime: any; // Accept any type (number, string, Timestamp, etc.)
-  }): Promise<Appointment> {
-    console.log(`[APPOINTMENT_SERVICE] Admin rescheduling appointment: ${params.appointmentId}`);
-
-    // Validate input data
-    const validatedParams = await rescheduleAppointmentSchema.parseAsync(params);
-
-    // Convert input to Timestamp objects
-    const startTimestamp = this.convertToTimestamp(validatedParams.newStartTime);
-    const endTimestamp = this.convertToTimestamp(validatedParams.newEndTime);
-
-    if (endTimestamp.toMillis() <= startTimestamp.toMillis()) {
-      throw new Error('New end time must be after new start time.');
-    }
-
-    const updateData: UpdateAppointmentData = {
-      status: AppointmentStatus.RESCHEDULED_BY_CLINIC,
-      appointmentStartTime: startTimestamp,
-      appointmentEndTime: endTimestamp,
-      rescheduleTime: Timestamp.now(),
-      confirmationTime: null,
-      updatedAt: serverTimestamp(),
-    };
-    return this.updateAppointment(validatedParams.appointmentId, updateData);
-  }
-
-  /**
-   * Helper method to convert various timestamp formats to Firestore Timestamp
-   * @param value - Any timestamp format (Timestamp, number, string, Date, serialized Timestamp)
-   * @returns Firestore Timestamp object
-   */
-  private convertToTimestamp(value: any): Timestamp {
-    console.log(`[APPOINTMENT_SERVICE] Converting timestamp:`, {
-      value,
-      type: typeof value,
-    });
-
-    // If it's already a Timestamp object with methods
-    if (value && typeof value.toMillis === 'function') {
-      return value;
-    }
-
-    // If it's a number (milliseconds since epoch)
-    if (typeof value === 'number') {
-      return Timestamp.fromMillis(value);
-    }
-
-    // If it's a string (ISO date string)
-    if (typeof value === 'string') {
-      return Timestamp.fromDate(new Date(value));
-    }
-
-    // If it's a Date object
-    if (value instanceof Date) {
-      return Timestamp.fromDate(value);
-    }
-
-    // If it has _seconds property (serialized Timestamp) - THIS IS WHAT FRONTEND SENDS
-    if (value && typeof value._seconds === 'number') {
-      return new Timestamp(value._seconds, value._nanoseconds || 0);
-    }
-
-    // If it has seconds property (serialized Timestamp)
-    if (value && typeof value.seconds === 'number') {
-      return new Timestamp(value.seconds, value.nanoseconds || 0);
-    }
-
-    throw new Error(`Invalid timestamp format: ${typeof value}, value: ${JSON.stringify(value)}`);
-  }
-
-  /**
-   * User confirms a reschedule proposed by the clinic.
-   * Status changes from RESCHEDULED_BY_CLINIC to CONFIRMED.
-   */
-  async rescheduleAppointmentConfirmUser(appointmentId: string): Promise<Appointment> {
-    console.log(`[APPOINTMENT_SERVICE] User confirming reschedule for: ${appointmentId}`);
-    const appointment = await this.getAppointmentById(appointmentId);
-    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
-    if (appointment.status !== AppointmentStatus.RESCHEDULED_BY_CLINIC) {
-      throw new Error(`Appointment ${appointmentId} is not in RESCHEDULED_BY_CLINIC state.`);
-    }
-    return this.updateAppointmentStatus(appointmentId, AppointmentStatus.CONFIRMED);
-  }
-
-  /**
-   * User rejects a reschedule proposed by the clinic.
-   * Status changes from RESCHEDULED_BY_CLINIC to CANCELED_PATIENT_RESCHEDULED.
-   */
-  async rescheduleAppointmentRejectUser(
-    appointmentId: string,
-    reason: string,
-  ): Promise<Appointment> {
-    console.log(`[APPOINTMENT_SERVICE] User rejecting reschedule for: ${appointmentId}`);
-    const appointment = await this.getAppointmentById(appointmentId);
-    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
-    if (appointment.status !== AppointmentStatus.RESCHEDULED_BY_CLINIC) {
-      throw new Error(`Appointment ${appointmentId} is not in RESCHEDULED_BY_CLINIC state.`);
-    }
-    return this.updateAppointmentStatus(
-      appointmentId,
-      AppointmentStatus.CANCELED_PATIENT_RESCHEDULED,
-      {
-        cancellationReason: reason,
-        canceledBy: 'patient',
-      },
-    );
-  }
-
-  /**
-   * Admin checks in a patient for their appointment.
-   * Requires all pending user forms to be completed.
-   */
-  async checkInPatientAdmin(appointmentId: string): Promise<Appointment> {
-    console.log(`[APPOINTMENT_SERVICE] Admin checking in patient for: ${appointmentId}`);
-    const appointment = await this.getAppointmentById(appointmentId);
-    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
-
-    if (appointment.pendingUserFormsIds && appointment.pendingUserFormsIds.length > 0) {
-      throw new Error(
-        `Cannot check in: Patient has ${
-          appointment.pendingUserFormsIds.length
-        } pending required form(s). IDs: ${appointment.pendingUserFormsIds.join(', ')}`,
-      );
-    }
-    if (
-      appointment.status !== AppointmentStatus.CONFIRMED &&
-      appointment.status !== AppointmentStatus.RESCHEDULED_BY_CLINIC
-    ) {
-      console.warn(
-        `Checking in appointment ${appointmentId} with status ${appointment.status}. Ensure this is intended.`,
-      );
-    }
-
-    return this.updateAppointmentStatus(appointmentId, AppointmentStatus.CHECKED_IN);
-  }
-
-  /**
-   * Doctor starts the appointment procedure.
-   */
-  async startAppointmentDoctor(appointmentId: string): Promise<Appointment> {
-    console.log(`[APPOINTMENT_SERVICE] Doctor starting appointment: ${appointmentId}`);
-    const appointment = await this.getAppointmentById(appointmentId);
-    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
-    if (appointment.status !== AppointmentStatus.CHECKED_IN) {
-      throw new Error(`Appointment ${appointmentId} must be CHECKED_IN to start.`);
-    }
-    // Update status and set procedureActualStartTime
-    const updateData: UpdateAppointmentData = {
-      status: AppointmentStatus.IN_PROGRESS,
-      procedureActualStartTime: Timestamp.now(), // Set actual start time
-      updatedAt: serverTimestamp(),
-    };
-    return this.updateAppointment(appointmentId, updateData);
-  }
-
-  /**
-   * Doctor completes and finalizes the appointment.
-   */
-  async completeAppointmentDoctor(
-    appointmentId: string,
-    finalizationNotes: string,
-    actualDurationMinutesInput?: number, // Renamed to avoid conflict if we calculate
-  ): Promise<Appointment> {
-    console.log(`[APPOINTMENT_SERVICE] Doctor completing appointment: ${appointmentId}`);
-    const currentUser = this.auth.currentUser;
-    if (!currentUser) throw new Error('Authentication required to complete appointment.');
-
-    const appointment = await this.getAppointmentById(appointmentId);
-    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
-
-    let calculatedDurationMinutes = actualDurationMinutesInput;
-    const procedureCompletionTime = Timestamp.now();
-
-    // Calculate duration if not provided and actual start time is available
-    if (calculatedDurationMinutes === undefined && appointment.procedureActualStartTime) {
-      const startTimeMillis = appointment.procedureActualStartTime.toMillis();
-      const endTimeMillis = procedureCompletionTime.toMillis();
-      if (endTimeMillis > startTimeMillis) {
-        calculatedDurationMinutes = Math.round((endTimeMillis - startTimeMillis) / 60000);
-      }
-    }
-
-    const updateData: UpdateAppointmentData = {
-      status: AppointmentStatus.COMPLETED,
-      actualDurationMinutes: calculatedDurationMinutes, // Use calculated or provided duration
-      finalizedDetails: {
-        by: currentUser.uid, // This is used ID, not practitioner's profile ID (just so we know who completed the appointment)
-        at: procedureCompletionTime, // Use consistent completion timestamp
-        notes: finalizationNotes,
-      },
-      // Optionally update appointmentEndTime to the actual completion time
-      // appointmentEndTime: procedureCompletionTime,
-      updatedAt: serverTimestamp(),
-    };
-    return this.updateAppointment(appointmentId, updateData);
-  }
-
-  /**
-   * Admin marks an appointment as No-Show.
-   */
-  async markNoShowAdmin(appointmentId: string): Promise<Appointment> {
-    console.log(`[APPOINTMENT_SERVICE] Admin marking no-show for: ${appointmentId}`);
-    const appointment = await this.getAppointmentById(appointmentId);
-    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
-    if (Timestamp.now().toMillis() < appointment.appointmentStartTime.toMillis()) {
-      throw new Error('Cannot mark no-show before appointment start time.');
-    }
-    return this.updateAppointmentStatus(appointmentId, AppointmentStatus.NO_SHOW, {
-      cancellationReason: 'Patient did not show up for the appointment.',
-      canceledBy: 'clinic',
-    });
-  }
-
-  /**
-   * Adds a media item to an appointment.
-   */
-  async addMediaToAppointment(
-    appointmentId: string,
-    mediaItemData: Omit<AppointmentMediaItem, 'id' | 'uploadedAt'>,
-  ): Promise<Appointment> {
-    console.log(`[APPOINTMENT_SERVICE] Adding media to appointment ${appointmentId}`);
-    const currentUser = this.auth.currentUser;
-    if (!currentUser) throw new Error('Authentication required.');
-
-    const newMediaItem: AppointmentMediaItem = {
-      ...mediaItemData,
-      id: this.generateId(),
-      uploadedAt: Timestamp.now(),
-      uploadedBy: currentUser.uid,
-    };
-
-    const updateData: UpdateAppointmentData = {
-      media: arrayUnion(newMediaItem) as any,
-      updatedAt: serverTimestamp(),
-    };
-    return this.updateAppointment(appointmentId, updateData);
-  }
-
-  /**
-   * Removes a media item from an appointment.
-   */
-  async removeMediaFromAppointment(
-    appointmentId: string,
-    mediaItemId: string,
-  ): Promise<Appointment> {
-    console.log(
-      `[APPOINTMENT_SERVICE] Removing media ${mediaItemId} from appointment ${appointmentId}`,
-    );
-    const appointment = await this.getAppointmentById(appointmentId);
-    if (!appointment || !appointment.media) {
-      throw new Error('Appointment or media list not found.');
-    }
-    const mediaToRemove = appointment.media.find(m => m.id === mediaItemId);
-    if (!mediaToRemove) {
-      throw new Error(`Media item ${mediaItemId} not found in appointment.`);
-    }
-
-    const updateData: UpdateAppointmentData = {
-      media: arrayRemove(mediaToRemove) as any,
-      updatedAt: serverTimestamp(),
-    };
-    return this.updateAppointment(appointmentId, updateData);
-  }
-
-  /**
-   * Adds or updates review information for an appointment.
-   */
-  async addReviewToAppointment(
-    appointmentId: string,
-    reviewData: Omit<PatientReviewInfo, 'reviewedAt' | 'reviewId'>,
-  ): Promise<Appointment> {
-    console.log(`[APPOINTMENT_SERVICE] Adding review to appointment ${appointmentId}`);
-    const newReviewInfo: PatientReviewInfo = {
-      ...reviewData,
-      reviewId: this.generateId(),
-      reviewedAt: Timestamp.now(),
-    };
-    const updateData: UpdateAppointmentData = {
-      reviewInfo: newReviewInfo,
-      updatedAt: serverTimestamp(),
-    };
-    return this.updateAppointment(appointmentId, updateData);
-  }
-
-  /**
-   * Updates the payment status of an appointment.
-   */
-  async updatePaymentStatus(
-    appointmentId: string,
-    paymentStatus: PaymentStatus,
-    paymentTransactionId?: string,
-  ): Promise<Appointment> {
-    console.log(
-      `[APPOINTMENT_SERVICE] Updating payment status of appointment ${appointmentId} to ${paymentStatus}`,
-    );
-    const updateData: UpdateAppointmentData = {
-      paymentStatus,
-      paymentTransactionId: paymentTransactionId || null,
-      updatedAt: serverTimestamp(),
-    };
-    return this.updateAppointment(appointmentId, updateData);
-  }
-
-  /**
-   * Updates the internal notes of an appointment.
-   *
-   * @param appointmentId ID of the appointment
-   * @param notes Updated internal notes
-   * @returns The updated appointment
-   */
-  async updateInternalNotes(appointmentId: string, notes: string | null): Promise<Appointment> {
-    console.log(`[APPOINTMENT_SERVICE] Updating internal notes for appointment: ${appointmentId}`);
-
-    const updateData: UpdateAppointmentData = {
-      internalNotes: notes,
-    };
-
-    return this.updateAppointment(appointmentId, updateData);
-  }
-
-  /**
-   * Gets upcoming appointments for a specific patient.
-   * These include appointments with statuses: PENDING, CONFIRMED, CHECKED_IN, IN_PROGRESS
-   *
-   * @param patientId ID of the patient
-   * @param options Optional parameters for filtering and pagination
-   * @returns Found appointments and the last document for pagination
-   */
-  async getUpcomingPatientAppointments(
-    patientId: string,
-    options?: {
-      startDate?: Date; // Optional starting date (defaults to now)
-      endDate?: Date;
-      limit?: number;
-      startAfter?: DocumentSnapshot;
-    },
-  ): Promise<{
-    appointments: Appointment[];
-    lastDoc: DocumentSnapshot | null;
-  }> {
-    try {
-      console.log(`[APPOINTMENT_SERVICE] Getting upcoming appointments for patient: ${patientId}`);
-
-      // Default to current date/time if no startDate provided
-      const effectiveStartDate = options?.startDate || new Date();
-
-      // Define the statuses considered as "upcoming"
-      const upcomingStatuses = [
-        AppointmentStatus.PENDING,
-        AppointmentStatus.CONFIRMED,
-        AppointmentStatus.CHECKED_IN,
-        AppointmentStatus.IN_PROGRESS,
-        AppointmentStatus.RESCHEDULED_BY_CLINIC,
-      ];
-
-      // Build query constraints
-      const constraints: QueryConstraint[] = [];
-
-      // Patient ID filter
-      constraints.push(where('patientId', '==', patientId));
-
-      // Status filter - multiple statuses
-      constraints.push(where('status', 'in', upcomingStatuses));
-
-      // Date range filters
-      constraints.push(where('appointmentStartTime', '>=', Timestamp.fromDate(effectiveStartDate)));
-
-      if (options?.endDate) {
-        constraints.push(where('appointmentStartTime', '<=', Timestamp.fromDate(options.endDate)));
-      }
-
-      // Order by appointment start time (ascending for upcoming - closest first)
-      constraints.push(orderBy('appointmentStartTime', 'asc'));
-
-      // Add pagination if specified
-      if (options?.limit) {
-        constraints.push(limit(options.limit));
-      }
-
-      if (options?.startAfter) {
-        constraints.push(startAfter(options.startAfter));
-      }
-
-      // Execute query
-      const q = query(collection(this.db, APPOINTMENTS_COLLECTION), ...constraints);
-      const querySnapshot = await getDocs(q);
-
-      // Extract results
-      const appointments = querySnapshot.docs.map(doc => doc.data() as Appointment);
-
-      // Get last document for pagination
-      const lastDoc =
-        querySnapshot.docs.length > 0 ? querySnapshot.docs[querySnapshot.docs.length - 1] : null;
-
-      console.log(
-        `[APPOINTMENT_SERVICE] Found ${appointments.length} upcoming appointments for patient ${patientId}`,
-      );
-
-      return { appointments, lastDoc };
-    } catch (error) {
-      console.error(
-        `[APPOINTMENT_SERVICE] Error getting upcoming appointments for patient ${patientId}:`,
-        error,
-      );
-      throw error;
-    }
-  }
-
-  /**
-   * Gets past appointments for a specific patient.
-   * These include appointments with statuses: COMPLETED, CANCELED_PATIENT,
-   * CANCELED_PATIENT_RESCHEDULED, CANCELED_CLINIC, NO_SHOW
-   *
-   * @param patientId ID of the patient
-   * @param options Optional parameters for filtering and pagination
-   * @returns Found appointments and the last document for pagination
-   */
-  async getPastPatientAppointments(
-    patientId: string,
-    options?: {
-      startDate?: Date;
-      endDate?: Date; // Optional end date (defaults to now)
-      showCanceled?: boolean; // Whether to include canceled appointments
-      showNoShow?: boolean; // Whether to include no-show appointments
-      limit?: number;
-      startAfter?: DocumentSnapshot;
-    },
-  ): Promise<{
-    appointments: Appointment[];
-    lastDoc: DocumentSnapshot | null;
-  }> {
-    try {
-      console.log(`[APPOINTMENT_SERVICE] Getting past appointments for patient: ${patientId}`);
-
-      // Default to current date/time if no endDate provided
-      const effectiveEndDate = options?.endDate || new Date();
-
-      // Define the base status for past appointments
-      const pastStatuses: AppointmentStatus[] = [AppointmentStatus.COMPLETED];
-
-      // Add canceled statuses if requested
-      if (options?.showCanceled) {
-        pastStatuses.push(
-          AppointmentStatus.CANCELED_PATIENT,
-          AppointmentStatus.CANCELED_PATIENT_RESCHEDULED,
-          AppointmentStatus.CANCELED_CLINIC,
-        );
-      }
-
-      // Add no-show status if requested
-      if (options?.showNoShow) {
-        pastStatuses.push(AppointmentStatus.NO_SHOW);
-      }
-
-      // Build query constraints
-      const constraints: QueryConstraint[] = [];
-
-      // Patient ID filter
-      constraints.push(where('patientId', '==', patientId));
-
-      // Status filter - multiple statuses
-      constraints.push(where('status', 'in', pastStatuses));
-
-      // Date range filters
-      if (options?.startDate) {
-        constraints.push(
-          where('appointmentStartTime', '>=', Timestamp.fromDate(options.startDate)),
-        );
-      }
-
-      constraints.push(where('appointmentStartTime', '<=', Timestamp.fromDate(effectiveEndDate)));
-
-      // Order by appointment start time (descending for past - most recent first)
-      constraints.push(orderBy('appointmentStartTime', 'desc'));
-
-      // Add pagination if specified
-      if (options?.limit) {
-        constraints.push(limit(options.limit));
-      }
-
-      if (options?.startAfter) {
-        constraints.push(startAfter(options.startAfter));
-      }
-
-      // Execute query
-      const q = query(collection(this.db, APPOINTMENTS_COLLECTION), ...constraints);
-      const querySnapshot = await getDocs(q);
-
-      // Extract results
-      const appointments = querySnapshot.docs.map(doc => doc.data() as Appointment);
-
-      // Get last document for pagination
-      const lastDoc =
-        querySnapshot.docs.length > 0 ? querySnapshot.docs[querySnapshot.docs.length - 1] : null;
-
-      console.log(
-        `[APPOINTMENT_SERVICE] Found ${appointments.length} past appointments for patient ${patientId}`,
-      );
-
-      return { appointments, lastDoc };
-    } catch (error) {
-      console.error(
-        `[APPOINTMENT_SERVICE] Error getting past appointments for patient ${patientId}:`,
-        error,
-      );
-      throw error;
-    }
-  }
-
-  /**
-   * Counts completed appointments for a patient with optional clinic filtering.
-   *
-   * @param patientId ID of the patient.
-   * @param clinicBranchId Optional ID of the clinic branch to either include or exclude.
-   * @param excludeClinic Optional boolean. If true (default), excludes the specified clinic. If false, includes only that clinic.
-   * @returns The count of completed appointments.
-   */
-  async countCompletedAppointments(
-    patientId: string,
-    clinicBranchId?: string,
-    excludeClinic = true,
-  ): Promise<number> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Counting completed appointments for patient: ${patientId}`,
-        { clinicBranchId, excludeClinic },
-      );
-
-      // Build query constraints
-      const constraints: QueryConstraint[] = [
-        where('patientId', '==', patientId),
-        where('status', '==', AppointmentStatus.COMPLETED),
-      ];
-
-      if (clinicBranchId) {
-        if (excludeClinic) {
-          // Exclude appointments from the specified clinic
-          constraints.push(where('clinicBranchId', '!=', clinicBranchId));
-        } else {
-          // Include only appointments from the specified clinic
-          constraints.push(where('clinicBranchId', '==', clinicBranchId));
-        }
-      }
-
-      // Execute query to get only the count
-      const q = query(collection(this.db, APPOINTMENTS_COLLECTION), ...constraints);
-      const snapshot = await getCountFromServer(q);
-      const count = snapshot.data().count;
-
-      console.log(
-        `[APPOINTMENT_SERVICE] Found ${count} completed appointments for patient ${patientId}`,
-      );
-
-      return count;
-    } catch (error) {
-      console.error(
-        `[APPOINTMENT_SERVICE] Error counting completed appointments for patient ${patientId}:`,
-        error,
-      );
-      throw error;
-    }
-  }
-
-  /**
-   * Uploads a zone photo and updates appointment metadata
-   *
-   * @param uploadData Zone photo upload data containing appointment ID, zone ID, photo type, file, and optional notes
-   * @returns The uploaded media metadata
-   */
-  async uploadZonePhoto(uploadData: ZonePhotoUploadData): Promise<MediaMetadata> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Uploading ${uploadData.photoType} photo for zone ${uploadData.zoneId} in appointment ${uploadData.appointmentId}`,
-      );
-
-      // Validate input data
-      const validatedData = await zonePhotoUploadSchema.parseAsync(uploadData);
-
-      // Check if user is authenticated
-      const currentUser = this.auth.currentUser;
-      if (!currentUser) {
-        throw new Error('User must be authenticated to upload zone photos');
-      }
-
-      // Get the appointment to verify it exists and user has access
-      const appointment = await this.getAppointmentById(validatedData.appointmentId);
-      if (!appointment) {
-        throw new Error(`Appointment with ID ${validatedData.appointmentId} not found`);
-      }
-
-      // Generate collection name for the media
-      const collectionName = `appointment_${validatedData.appointmentId}_zone_photos`;
-
-      // Generate filename with zone and photo type info
-      const timestamp = Date.now();
-      const fileExtension = validatedData.file.type?.split('/')[1] || 'jpg';
-      const fileName = `${validatedData.photoType}_${validatedData.zoneId}_${timestamp}.${fileExtension}`;
-
-      console.log(
-        `[APPOINTMENT_SERVICE] Uploading file: ${fileName} to collection: ${collectionName}`,
-      );
-
-      // Upload the media file using MediaService
-      const uploadedMedia = await this.mediaService.uploadMedia(
-        validatedData.file,
-        validatedData.appointmentId, // ownerId is the appointment ID
-        MediaAccessLevel.PRIVATE, // Zone photos are private
-        collectionName,
-        fileName,
-      );
-
-      console.log(`[APPOINTMENT_SERVICE] Media uploaded successfully with ID: ${uploadedMedia.id}`);
-
-      // Update appointment metadata with the new photo
-      await this.updateAppointmentZonePhoto(
-        validatedData.appointmentId,
-        validatedData.zoneId,
-        validatedData.photoType,
-        uploadedMedia,
-        validatedData.notes,
-      );
-
-      console.log(
-        `[APPOINTMENT_SERVICE] Successfully uploaded and linked ${validatedData.photoType} photo for zone ${validatedData.zoneId}`,
-      );
-
-      return uploadedMedia;
-    } catch (error) {
-      console.error('[APPOINTMENT_SERVICE] Error uploading zone photo:', error);
-      throw error;
-    }
-  }
-
-  /**
-   * Updates appointment metadata with zone photo information
-   *
-   * @param appointmentId ID of the appointment
-   * @param zoneId ID of the zone
-   * @param photoType Type of photo ('before' or 'after')
-   * @param mediaMetadata Uploaded media metadata
-   * @param notes Optional notes for the photo
-   * @returns The updated appointment
-   */
-  private async updateAppointmentZonePhoto(
-    appointmentId: string,
-    zoneId: string,
-    photoType: 'before' | 'after',
-    mediaMetadata: MediaMetadata,
-    notes?: string,
-  ): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Updating appointment metadata for ${photoType} photo in zone ${zoneId}`,
-      );
-
-      // Get current appointment
-      const appointment = await this.getAppointmentById(appointmentId);
-      if (!appointment) {
-        throw new Error(`Appointment with ID ${appointmentId} not found`);
-      }
-
-      // Initialize metadata if it doesn't exist
-      const currentMetadata = appointment.metadata || {
-        selectedZones: null,
-        zonePhotos: null,
-        zonesData: null,
-        appointmentProducts: [],
-        extendedProcedures: [],
-        recommendedProcedures: [],
-        zoneBilling: null,
-        finalbilling: null,
-        finalizationNotes: null,
-      };
-
-      // Initialize zonePhotos if it doesn't exist (array model per zone)
-      let currentZonePhotos: Record<string, BeforeAfterPerZone[]> = {};
-
-      // AUTO-MIGRATION: Convert old object format to new array format
-      if (currentMetadata.zonePhotos) {
-        for (const [key, value] of Object.entries(currentMetadata.zonePhotos)) {
-          if (Array.isArray(value)) {
-            // Already in new format
-            currentZonePhotos[key] = value as BeforeAfterPerZone[];
-          } else {
-            // Old format - convert to array
-            console.log(`[APPOINTMENT_SERVICE] Auto-migrating ${key} from object to array format`);
-            const oldData = value as any;
-            currentZonePhotos[key] = [
-              {
-                before: oldData.before || null,
-                after: oldData.after || null,
-                beforeNote: null,
-                afterNote: null,
-              },
-            ];
-          }
-        }
-      }
-
-      // Initialize the zone array if it doesn't exist
-      if (!currentZonePhotos[zoneId]) {
-        currentZonePhotos[zoneId] = [];
-      }
-
-      // Create a new entry for this uploaded photo with per-photo notes
-      const newEntry: BeforeAfterPerZone = {
-        before: photoType === 'before' ? mediaMetadata.url : null,
-        after: photoType === 'after' ? mediaMetadata.url : null,
-        beforeNote: photoType === 'before' ? notes || null : null,
-        afterNote: photoType === 'after' ? notes || null : null,
-      };
-
-      // Append to the zone's photo list
-      currentZonePhotos[zoneId] = [...currentZonePhotos[zoneId], newEntry];
-      // Enforce max 10 photos per zone by keeping the most recent 10
-      if (currentZonePhotos[zoneId].length > 10) {
-        currentZonePhotos[zoneId] = currentZonePhotos[zoneId].slice(-10);
-      }
-
-      // Update the appointment with new metadata
-      const updateData: UpdateAppointmentData = {
-        metadata: {
-          selectedZones: currentMetadata.selectedZones,
-          zonePhotos: currentZonePhotos,
-          zonesData: currentMetadata.zonesData || null,
-          appointmentProducts: currentMetadata.appointmentProducts || [],
-          extendedProcedures: currentMetadata.extendedProcedures || [],
-          recommendedProcedures: currentMetadata.recommendedProcedures || [],
-          // Only include zoneBilling if it exists (avoid undefined values in Firestore)
-          ...(currentMetadata.zoneBilling !== undefined && {
-            zoneBilling: currentMetadata.zoneBilling,
-          }),
-          finalbilling: currentMetadata.finalbilling,
-          finalizationNotes: currentMetadata.finalizationNotes,
-        },
-        updatedAt: serverTimestamp(),
-      };
-
-      const updatedAppointment = await this.updateAppointment(appointmentId, updateData);
-
-      console.log(
-        `[APPOINTMENT_SERVICE] Successfully updated appointment metadata for ${photoType} photo in zone ${zoneId}`,
-      );
-
-      return updatedAppointment;
-    } catch (error) {
-      console.error(
-        `[APPOINTMENT_SERVICE] Error updating appointment metadata for zone photo:`,
-        error,
-      );
-      throw error;
-    }
-  }
-
-  /**
-   * Gets zone photos for a specific appointment and zone
-   *
-   * @param appointmentId ID of the appointment
-   * @param zoneId ID of the zone (optional - if not provided, returns all zones)
-   * @returns Zone photos data
-   */
-  async getZonePhotos(
-    appointmentId: string,
-    zoneId?: string,
-  ): Promise<Record<string, BeforeAfterPerZone[]> | BeforeAfterPerZone[] | null> {
-    try {
-      console.log(`[APPOINTMENT_SERVICE] Getting zone photos for appointment ${appointmentId}`);
-
-      const appointment = await this.getAppointmentById(appointmentId);
-      if (!appointment) {
-        throw new Error(`Appointment with ID ${appointmentId} not found`);
-      }
-
-      const zonePhotos = appointment.metadata?.zonePhotos as
-        | Record<string, BeforeAfterPerZone[]>
-        | undefined
-        | null;
-      if (!zonePhotos) {
-        return null;
-      }
-
-      // If specific zone requested, return only that zone's photos
-      if (zoneId) {
-        return zonePhotos[zoneId] || null;
-      }
-
-      // Return all zone photos
-      return zonePhotos;
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error getting zone photos:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Deletes a zone photo entry (by index) and updates appointment metadata
-   *
-   * @param appointmentId ID of the appointment
-   * @param zoneId ID of the zone
-   * @param photoIndex Index of the photo entry to delete in the zone array
-   * @returns The updated appointment
-   */
-  async deleteZonePhoto(
-    appointmentId: string,
-    zoneId: string,
-    photoIndex: number,
-  ): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Deleting zone photo index ${photoIndex} for zone ${zoneId} in appointment ${appointmentId}`,
-      );
-
-      // Get current appointment
-      const appointment = await this.getAppointmentById(appointmentId);
-      if (!appointment) {
-        throw new Error(`Appointment with ID ${appointmentId} not found`);
-      }
-
-      const zonePhotos = appointment.metadata?.zonePhotos as
-        | Record<string, BeforeAfterPerZone[]>
-        | undefined
-        | null;
-      if (!zonePhotos || !zonePhotos[zoneId] || !Array.isArray(zonePhotos[zoneId])) {
-        throw new Error(`No photos found for zone ${zoneId} in appointment ${appointmentId}`);
-      }
-
-      const zoneArray = [...zonePhotos[zoneId]];
-      if (photoIndex < 0 || photoIndex >= zoneArray.length) {
-        throw new Error(`Invalid photo index ${photoIndex} for zone ${zoneId}`);
-      }
-
-      const entry = zoneArray[photoIndex];
-      const photoUrl = (entry.before || entry.after) as MediaResource | null;
-      if (!photoUrl) {
-        throw new Error(`No photo URL found for index ${photoIndex} in zone ${zoneId}`);
-      }
-
-      // Try to find and delete the media from storage
-      try {
-        // Only try to delete if photoUrl is a string (URL)
-        if (typeof photoUrl === 'string') {
-          const mediaMetadata = await this.mediaService.getMediaMetadataByUrl(photoUrl);
-          if (mediaMetadata) {
-            await this.mediaService.deleteMedia(mediaMetadata.id);
-            console.log(`[APPOINTMENT_SERVICE] Deleted media file with ID: ${mediaMetadata.id}`);
-          }
-        }
-      } catch (mediaError) {
-        console.warn(
-          `[APPOINTMENT_SERVICE] Could not delete media file for URL ${photoUrl}:`,
-          mediaError,
-        );
-        // Continue with metadata update even if media deletion fails
-      }
-
-      // Update appointment metadata to remove the photo entry at the specified index
-      const updatedZonePhotos: Record<string, BeforeAfterPerZone[]> = { ...zonePhotos } as any;
-      const updatedZoneArray = [...zoneArray];
-      updatedZoneArray.splice(photoIndex, 1);
-      if (updatedZoneArray.length === 0) {
-        delete updatedZonePhotos[zoneId];
-      } else {
-        updatedZonePhotos[zoneId] = updatedZoneArray;
-      }
-
-      const updateData: UpdateAppointmentData = {
-        metadata: {
-          selectedZones: appointment.metadata?.selectedZones || null,
-          zonePhotos: updatedZonePhotos,
-          zonesData: appointment.metadata?.zonesData || null,
-          appointmentProducts: appointment.metadata?.appointmentProducts || [],
-          extendedProcedures: appointment.metadata?.extendedProcedures || [],
-          recommendedProcedures: appointment.metadata?.recommendedProcedures || [],
-          // Only include zoneBilling if it exists (avoid undefined values in Firestore)
-          ...(appointment.metadata?.zoneBilling !== undefined && {
-            zoneBilling: appointment.metadata.zoneBilling,
-          }),
-          finalbilling: appointment.metadata?.finalbilling || null,
-          finalizationNotes: appointment.metadata?.finalizationNotes || null,
-        },
-        updatedAt: serverTimestamp(),
-      };
-
-      const updatedAppointment = await this.updateAppointment(appointmentId, updateData);
-
-      console.log(
-        `[APPOINTMENT_SERVICE] Successfully deleted photo index ${photoIndex} for zone ${zoneId}`,
-      );
-
-      return updatedAppointment;
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error deleting zone photo:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Adds an item (product or note) to a specific zone
-   *
-   * @param appointmentId ID of the appointment
-   * @param zoneId Zone ID (must be category.zone format, e.g., "face.forehead")
-   * @param item Zone item data to add (without parentZone - it's inferred from zoneId)
-   * @returns The updated appointment
-   */
-  async addItemToZone(
-    appointmentId: string,
-    zoneId: string,
-    item: Omit<ZoneItemData, 'subtotal' | 'parentZone'>,
-  ): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Adding item to zone ${zoneId} in appointment ${appointmentId}`,
-      );
-      return await addItemToZoneUtil(this.db, appointmentId, zoneId, item);
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error adding item to zone:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Removes an item from a specific zone
-   *
-   * @param appointmentId ID of the appointment
-   * @param zoneId Zone ID
-   * @param itemIndex Index of the item to remove in the zone's items array
-   * @returns The updated appointment
-   */
-  async removeItemFromZone(
-    appointmentId: string,
-    zoneId: string,
-    itemIndex: number,
-  ): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Removing item ${itemIndex} from zone ${zoneId} in appointment ${appointmentId}`,
-      );
-      return await removeItemFromZoneUtil(this.db, appointmentId, zoneId, itemIndex);
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error removing item from zone:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Updates a specific item in a zone
-   *
-   * @param appointmentId ID of the appointment
-   * @param zoneId Zone ID
-   * @param itemIndex Index of the item to update
-   * @param updates Partial updates to apply to the item
-   * @returns The updated appointment
-   */
-  async updateZoneItem(
-    appointmentId: string,
-    zoneId: string,
-    itemIndex: number,
-    updates: Partial<ZoneItemData>,
-  ): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Updating item ${itemIndex} in zone ${zoneId} in appointment ${appointmentId}`,
-      );
-      return await updateZoneItemUtil(this.db, appointmentId, zoneId, itemIndex, updates);
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error updating zone item:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Overrides the price for a specific zone item
-   *
-   * @param appointmentId ID of the appointment
-   * @param zoneId Zone ID
-   * @param itemIndex Index of the item
-   * @param newPrice New price amount to set
-   * @returns The updated appointment
-   */
-  async overridePriceForZoneItem(
-    appointmentId: string,
-    zoneId: string,
-    itemIndex: number,
-    newPrice: number,
-  ): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Overriding price for item ${itemIndex} in zone ${zoneId} to ${newPrice}`,
-      );
-      return await overridePriceForZoneItemUtil(
-        this.db,
-        appointmentId,
-        zoneId,
-        itemIndex,
-        newPrice,
-      );
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error overriding price:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Updates subzones for a specific zone item
-   *
-   * @param appointmentId ID of the appointment
-   * @param zoneId Zone ID
-   * @param itemIndex Index of the item
-   * @param subzones Array of subzone keys (category.zone.subzone format)
-   * @returns The updated appointment
-   */
-  async updateSubzones(
-    appointmentId: string,
-    zoneId: string,
-    itemIndex: number,
-    subzones: string[],
-  ): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Updating subzones for item ${itemIndex} in zone ${zoneId}`,
-      );
-      return await updateSubzonesUtil(this.db, appointmentId, zoneId, itemIndex, subzones);
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error updating subzones:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Adds an extended procedure to an appointment
-   * Automatically aggregates products into appointmentProducts
-   *
-   * @param appointmentId ID of the appointment
-   * @param procedureId ID of the procedure to add
-   * @returns The updated appointment
-   */
-  async addExtendedProcedure(appointmentId: string, procedureId: string): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Adding extended procedure ${procedureId} to appointment ${appointmentId}`,
-      );
-      return await addExtendedProcedureUtil(this.db, appointmentId, procedureId);
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error adding extended procedure:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Removes an extended procedure from an appointment
-   * Also removes associated products from appointmentProducts
-   *
-   * @param appointmentId ID of the appointment
-   * @param procedureId ID of the procedure to remove
-   * @returns The updated appointment
-   */
-  async removeExtendedProcedure(appointmentId: string, procedureId: string): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Removing extended procedure ${procedureId} from appointment ${appointmentId}`,
-      );
-      return await removeExtendedProcedureUtil(this.db, appointmentId, procedureId);
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error removing extended procedure:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Gets all extended procedures for an appointment
-   *
-   * @param appointmentId ID of the appointment
-   * @returns Array of extended procedures
-   */
-  async getExtendedProcedures(appointmentId: string): Promise<ExtendedProcedureInfo[]> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Getting extended procedures for appointment ${appointmentId}`,
-      );
-      return await getExtendedProceduresUtil(this.db, appointmentId);
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error getting extended procedures:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Gets all aggregated products for an appointment
-   * Includes products from main procedure and extended procedures
-   *
-   * @param appointmentId ID of the appointment
-   * @returns Array of appointment products
-   */
-  async getAppointmentProducts(appointmentId: string): Promise<AppointmentProductMetadata[]> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Getting appointment products for appointment ${appointmentId}`,
-      );
-      return await getAppointmentProductsUtil(this.db, appointmentId);
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error getting appointment products:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Recalculates final billing for an appointment based on zone items
-   *
-   * @param appointmentId ID of the appointment
-   * @param taxRate Tax rate (e.g., 0.20 for 20%)
-   * @returns The updated appointment with recalculated billing
-   */
-  async recalculateFinalBilling(appointmentId: string, taxRate?: number): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Recalculating final billing for appointment ${appointmentId}`,
-      );
-
-      const appointment = await this.getAppointmentById(appointmentId);
-      if (!appointment) {
-        throw new Error(`Appointment with ID ${appointmentId} not found`);
-      }
-
-      const zonesData = appointment.metadata?.zonesData;
-      if (!zonesData || Object.keys(zonesData).length === 0) {
-        throw new Error('No zone data available for billing calculation');
-      }
-
-      const finalbilling = calculateFinalBilling(zonesData, taxRate);
-
-      const currentMetadata = appointment.metadata || {
-        selectedZones: null,
-        zonePhotos: null,
-        zonesData: null,
-        appointmentProducts: [],
-        extendedProcedures: [],
-        recommendedProcedures: [],
-        finalbilling: null,
-        finalizationNotes: null,
-      };
-
-      const updateData: UpdateAppointmentData = {
-        metadata: {
-          selectedZones: currentMetadata.selectedZones,
-          zonePhotos: currentMetadata.zonePhotos,
-          zonesData: currentMetadata.zonesData,
-          appointmentProducts: currentMetadata.appointmentProducts || [],
-          extendedProcedures: currentMetadata.extendedProcedures || [],
-          recommendedProcedures: currentMetadata.recommendedProcedures || [],
-          // Only include zoneBilling if it exists (avoid undefined values in Firestore)
-          ...(currentMetadata.zoneBilling !== undefined && {
-            zoneBilling: currentMetadata.zoneBilling,
-          }),
-          finalbilling,
-          finalizationNotes: currentMetadata.finalizationNotes,
-        },
-        updatedAt: serverTimestamp(),
-      };
-
-      return await this.updateAppointment(appointmentId, updateData);
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error recalculating final billing:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Adds a recommended procedure to an appointment
-   * Multiple recommendations of the same procedure are allowed (e.g., touch-up in 2 weeks, full treatment in 3 months)
-   *
-   * @param appointmentId ID of the appointment
-   * @param procedureId ID of the procedure to recommend
-   * @param note Note explaining the recommendation
-   * @param timeframe Suggested timeframe for the procedure
-   * @returns The updated appointment
-   */
-  async addRecommendedProcedure(
-    appointmentId: string,
-    procedureId: string,
-    note: string,
-    timeframe: { value: number; unit: 'day' | 'week' | 'month' | 'year' },
-  ): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Adding recommended procedure ${procedureId} to appointment ${appointmentId}`,
-      );
-      return await addRecommendedProcedureUtil(
-        this.db,
-        appointmentId,
-        procedureId,
-        note,
-        timeframe,
-      );
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error adding recommended procedure:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Removes a recommended procedure from an appointment by index
-   *
-   * @param appointmentId ID of the appointment
-   * @param recommendationIndex Index of the recommendation to remove
-   * @returns The updated appointment
-   */
-  async removeRecommendedProcedure(
-    appointmentId: string,
-    recommendationIndex: number,
-  ): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Removing recommended procedure at index ${recommendationIndex} from appointment ${appointmentId}`,
-      );
-      return await removeRecommendedProcedureUtil(this.db, appointmentId, recommendationIndex);
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error removing recommended procedure:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Updates a recommended procedure in an appointment by index
-   *
-   * @param appointmentId ID of the appointment
-   * @param recommendationIndex Index of the recommendation to update
-   * @param updates Partial updates (note and/or timeframe)
-   * @returns The updated appointment
-   */
-  async updateRecommendedProcedure(
-    appointmentId: string,
-    recommendationIndex: number,
-    updates: {
-      note?: string;
-      timeframe?: { value: number; unit: 'day' | 'week' | 'month' | 'year' };
-    },
-  ): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Updating recommended procedure at index ${recommendationIndex} in appointment ${appointmentId}`,
-      );
-      return await updateRecommendedProcedureUtil(
-        this.db,
-        appointmentId,
-        recommendationIndex,
-        updates,
-      );
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error updating recommended procedure:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Gets all recommended procedures for an appointment
-   *
-   * @param appointmentId ID of the appointment
-   * @returns Array of recommended procedures
-   */
-  async getRecommendedProcedures(appointmentId: string): Promise<RecommendedProcedure[]> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Getting recommended procedures for appointment ${appointmentId}`,
-      );
-      return await getRecommendedProceduresUtil(this.db, appointmentId);
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error getting recommended procedures:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Updates a specific photo entry in a zone by index
-   * Can update before/after photos and their notes
-   *
-   * @param appointmentId ID of the appointment
-   * @param zoneId Zone ID
-   * @param photoIndex Index of the photo entry to update
-   * @param updates Partial updates to apply (before, after, beforeNote, afterNote)
-   * @returns The updated appointment
-   */
-  async updateZonePhotoEntry(
-    appointmentId: string,
-    zoneId: string,
-    photoIndex: number,
-    updates: Partial<BeforeAfterPerZone>,
-  ): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Updating photo entry at index ${photoIndex} for zone ${zoneId} in appointment ${appointmentId}`,
-      );
-      return await updateZonePhotoEntryUtil(this.db, appointmentId, zoneId, photoIndex, updates);
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error updating zone photo entry:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Adds an after photo to an existing before photo entry
-   *
-   * @param appointmentId ID of the appointment
-   * @param zoneId Zone ID
-   * @param photoIndex Index of the entry to add after photo to
-   * @param afterPhotoUrl URL of the after photo
-   * @param afterNote Optional note for the after photo
-   * @returns The updated appointment
-   */
-  async addAfterPhotoToEntry(
-    appointmentId: string,
-    zoneId: string,
-    photoIndex: number,
-    afterPhotoUrl: MediaResource,
-    afterNote?: string,
-  ): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Adding after photo to entry at index ${photoIndex} for zone ${zoneId}`,
-      );
-      return await addAfterPhotoToEntryUtil(
-        this.db,
-        appointmentId,
-        zoneId,
-        photoIndex,
-        afterPhotoUrl,
-        afterNote,
-      );
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error adding after photo to entry:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Updates notes for a photo entry
-   *
-   * @param appointmentId ID of the appointment
-   * @param zoneId Zone ID
-   * @param photoIndex Index of the entry
-   * @param beforeNote Optional note for before photo
-   * @param afterNote Optional note for after photo
-   * @returns The updated appointment
-   */
-  async updateZonePhotoNotes(
-    appointmentId: string,
-    zoneId: string,
-    photoIndex: number,
-    beforeNote?: string,
-    afterNote?: string,
-  ): Promise<Appointment> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Updating notes for photo entry at index ${photoIndex} for zone ${zoneId}`,
-      );
-      return await updateZonePhotoNotesUtil(
-        this.db,
-        appointmentId,
-        zoneId,
-        photoIndex,
-        beforeNote,
-        afterNote,
-      );
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error updating zone photo notes:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Gets a specific photo entry from a zone
-   *
-   * @param appointmentId ID of the appointment
-   * @param zoneId Zone ID
-   * @param photoIndex Index of the entry
-   * @returns Photo entry
-   */
-  async getZonePhotoEntry(
-    appointmentId: string,
-    zoneId: string,
-    photoIndex: number,
-  ): Promise<BeforeAfterPerZone> {
-    try {
-      console.log(
-        `[APPOINTMENT_SERVICE] Getting photo entry at index ${photoIndex} for zone ${zoneId}`,
-      );
-      return await getZonePhotoEntryUtil(this.db, appointmentId, zoneId, photoIndex);
-    } catch (error) {
-      console.error(`[APPOINTMENT_SERVICE] Error getting zone photo entry:`, error);
-      throw error;
-    }
-  }
-}
+import {
+  Firestore,
+  Timestamp,
+  DocumentSnapshot,
+  serverTimestamp,
+  arrayUnion,
+  arrayRemove,
+  QueryConstraint,
+  where,
+  orderBy,
+  collection,
+  query,
+  limit,
+  startAfter,
+  getDocs,
+  getCountFromServer,
+  doc,
+  getDoc,
+} from 'firebase/firestore';
+import { Auth } from 'firebase/auth';
+import { FirebaseApp } from 'firebase/app';
+import { Functions, getFunctions, httpsCallable } from 'firebase/functions';
+import { BaseService } from '../base.service';
+import {
+  Appointment,
+  AppointmentStatus,
+  UpdateAppointmentData,
+  SearchAppointmentsParams,
+  PaymentStatus,
+  AppointmentMediaItem,
+  PatientReviewInfo,
+  type CreateAppointmentHttpData,
+  type ZonePhotoUploadData,
+  BeforeAfterPerZone,
+  ZoneItemData,
+  ExtendedProcedureInfo,
+  AppointmentProductMetadata,
+  RecommendedProcedure,
+  NextStepsRecommendation,
+  APPOINTMENTS_COLLECTION,
+} from '../../types/appointment';
+import { PROCEDURES_COLLECTION } from '../../types/procedure';
+import {
+  updateAppointmentSchema,
+  searchAppointmentsSchema,
+  rescheduleAppointmentSchema,
+  zonePhotoUploadSchema,
+} from '../../validations/appointment.schema';
+
+// Import other services needed (dependency injection pattern)
+import { CalendarServiceV2 } from '../calendar/calendar.v2.service';
+import { PatientService } from '../patient/patient.service';
+import { PractitionerService } from '../practitioner/practitioner.service';
+import { ClinicService } from '../clinic/clinic.service';
+import { FilledDocumentService } from '../documentation-templates/filled-document.service';
+import {
+  MediaService,
+  MediaAccessLevel,
+  MediaMetadata,
+  MediaResource,
+} from '../media/media.service';
+
+// Import utility functions
+import {
+  updateAppointmentUtil,
+  getAppointmentByIdUtil,
+  searchAppointmentsUtil,
+} from './utils/appointment.utils';
+import {
+  addItemToZoneUtil,
+  removeItemFromZoneUtil,
+  updateZoneItemUtil,
+  overridePriceForZoneItemUtil,
+  updateSubzonesUtil,
+  calculateFinalBilling,
+} from './utils/zone-management.utils';
+import {
+  addExtendedProcedureUtil,
+  removeExtendedProcedureUtil,
+  getExtendedProceduresUtil,
+  getAppointmentProductsUtil,
+} from './utils/extended-procedure.utils';
+import {
+  addRecommendedProcedureUtil,
+  removeRecommendedProcedureUtil,
+  updateRecommendedProcedureUtil,
+  getRecommendedProceduresUtil,
+} from './utils/recommended-procedure.utils';
+import {
+  updateZonePhotoEntryUtil,
+  addAfterPhotoToEntryUtil,
+  updateZonePhotoNotesUtil,
+  getZonePhotoEntryUtil,
+} from './utils/zone-photo.utils';
+
+/**
+ * Interface for available booking slot
+ */
+interface AvailableSlot {
+  start: Date;
+}
+
+/**
+ * AppointmentService is responsible for managing appointments,
+ * including creating, updating, retrieving, and searching appointments.
+ * It serves as the main entry point for working with appointment data.
+ */
+export class AppointmentService extends BaseService {
+  private calendarService: CalendarServiceV2;
+  private patientService: PatientService;
+  private practitionerService: PractitionerService;
+  private clinicService: ClinicService;
+  private filledDocumentService: FilledDocumentService;
+  private mediaService: MediaService;
+  private functions: Functions;
+
+  /**
+   * Creates a new AppointmentService instance.
+   *
+   * @param db Firestore instance
+   * @param auth Firebase Auth instance
+   * @param app Firebase App instance
+   * @param calendarService Calendar service instance
+   * @param patientService Patient service instance
+   * @param practitionerService Practitioner service instance
+   * @param clinicService Clinic service instance
+   * @param filledDocumentService Filled document service instance
+   */
+  constructor(
+    db: Firestore,
+    auth: Auth,
+    app: FirebaseApp,
+    calendarService: CalendarServiceV2,
+    patientService: PatientService,
+    practitionerService: PractitionerService,
+    clinicService: ClinicService,
+    filledDocumentService: FilledDocumentService,
+  ) {
+    super(db, auth, app);
+    this.calendarService = calendarService;
+    this.patientService = patientService;
+    this.practitionerService = practitionerService;
+    this.clinicService = clinicService;
+    this.filledDocumentService = filledDocumentService;
+    this.mediaService = new MediaService(db, auth, app);
+    this.functions = getFunctions(app, 'europe-west6'); // Initialize Firebase Functions with the correct region
+  }
+
+  /**
+   * Gets available booking slots for a specific clinic, practitioner, and procedure using HTTP request.
+   * This is an alternative implementation using direct HTTP request instead of callable function.
+   *
+   * @param clinicId ID of the clinic
+   * @param practitionerId ID of the practitioner
+   * @param procedureId ID of the procedure
+   * @param startDate Start date of the time range to check
+   * @param endDate End date of the time range to check
+   * @returns Array of available booking slots
+   */
+  async getAvailableBookingSlotsHttp(
+    clinicId: string,
+    practitionerId: string,
+    procedureId: string,
+    startDate: Date,
+    endDate: Date,
+  ): Promise<AvailableSlot[]> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Getting available booking slots via HTTP for clinic: ${clinicId}, practitioner: ${practitionerId}, procedure: ${procedureId}`,
+      );
+
+      // Validate input parameters
+      if (!clinicId || !practitionerId || !procedureId || !startDate || !endDate) {
+        throw new Error('Missing required parameters for booking slots calculation');
+      }
+
+      if (endDate <= startDate) {
+        throw new Error('End date must be after start date');
+      }
+
+      // Check if user is authenticated
+      const currentUser = this.auth.currentUser;
+      if (!currentUser) {
+        throw new Error('User must be authenticated to get available booking slots');
+      }
+
+      // Construct the function URL for the Express app endpoint
+      const functionUrl = `https://europe-west6-metaestetics.cloudfunctions.net/bookingApi/getAvailableBookingSlots`;
+
+      // Get the authenticated user's ID token
+      // By default, getIdToken doesn't allow setting audience for web/mobile clients
+      // So we need to treat this token specially on the server side
+      const idToken = await currentUser.getIdToken();
+
+      // Log that we're getting a token
+      console.log(`[APPOINTMENT_SERVICE] Got user token, user ID: ${currentUser.uid}`);
+
+      // Alternate direct URL (if needed):
+      // const functionUrl = `https://getavailablebookingslotshttp-grqala5m6a-oa.a.run.app`;
+
+      // Request data
+      const requestData = {
+        clinicId,
+        practitionerId,
+        procedureId,
+        timeframe: {
+          start: startDate.getTime(), // Convert to timestamp
+          end: endDate.getTime(),
+        },
+      };
+
+      console.log(`[APPOINTMENT_SERVICE] Making fetch request to ${functionUrl}`);
+
+      // Make the HTTP request with expanded CORS options for browser
+      const response = await fetch(functionUrl, {
+        method: 'POST',
+        mode: 'cors', // Important for cross-origin requests
+        cache: 'no-cache', // Don't cache this request
+        credentials: 'omit', // Don't send cookies since we're using token auth
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${idToken}`,
+        },
+        redirect: 'follow',
+        referrerPolicy: 'no-referrer',
+        body: JSON.stringify(requestData),
+      });
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Received response ${response.status}: ${response.statusText}`,
+      );
+
+      // Check if the request was successful
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.error(`[APPOINTMENT_SERVICE] Error response details: ${errorText}`);
+        throw new Error(
+          `Failed to get available booking slots: ${response.status} ${response.statusText} - ${errorText}`,
+        );
+      }
+
+      // Parse the response
+      const result = await response.json();
+      console.log(`[APPOINTMENT_SERVICE] Response parsed successfully`, result);
+
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to get available booking slots');
+      }
+
+      // Convert timestamp numbers to Date objects
+      const slots: AvailableSlot[] = result.availableSlots.map((slot: { start: number }) => ({
+        start: new Date(slot.start),
+      }));
+
+      console.log(`[APPOINTMENT_SERVICE] Found ${slots.length} available booking slots via HTTP`);
+
+      return slots;
+    } catch (error) {
+      console.error('[APPOINTMENT_SERVICE] Error getting available booking slots via HTTP:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Creates an appointment via the Cloud Function orchestrateAppointmentCreation
+   *
+   * @param data - CreateAppointmentData object
+   * @returns The created appointment
+   */
+  async createAppointmentHttp(data: CreateAppointmentHttpData): Promise<Appointment> {
+    try {
+      console.log('[APPOINTMENT_SERVICE] Creating appointment via cloud function');
+
+      // Get the authenticated user's ID token
+      const currentUser = this.auth.currentUser;
+      if (!currentUser) {
+        throw new Error('User must be authenticated to create an appointment');
+      }
+      const idToken = await currentUser.getIdToken();
+
+      // Construct the function URL for the Express app endpoint
+      const functionUrl = `https://europe-west6-metaestetics.cloudfunctions.net/bookingApi/orchestrateAppointmentCreation`;
+
+      // Prepare request data for the Cloud Function
+      // Map CreateAppointmentData to OrchestrateAppointmentCreationData format
+      const requestData = {
+        patientId: data.patientId,
+        procedureId: data.procedureId,
+        appointmentStartTime: data.appointmentStartTime.toMillis
+          ? data.appointmentStartTime.toMillis()
+          : new Date(data.appointmentStartTime as any).getTime(),
+        appointmentEndTime: data.appointmentEndTime.toMillis
+          ? data.appointmentEndTime.toMillis()
+          : new Date(data.appointmentEndTime as any).getTime(),
+        patientNotes: data?.patientNotes || null,
+      };
+
+      console.log(`[APPOINTMENT_SERVICE] Making fetch request to ${functionUrl}`);
+
+      // Make the HTTP request with expanded CORS options for browser
+      const response = await fetch(functionUrl, {
+        method: 'POST',
+        mode: 'cors',
+        cache: 'no-cache',
+        credentials: 'omit',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${idToken}`,
+        },
+        redirect: 'follow',
+        referrerPolicy: 'no-referrer',
+        body: JSON.stringify(requestData),
+      });
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Received response ${response.status}: ${response.statusText}`,
+      );
+
+      // Check if the request was successful
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.error(`[APPOINTMENT_SERVICE] Error response details: ${errorText}`);
+        throw new Error(
+          `Failed to create appointment: ${response.status} ${response.statusText} - ${errorText}`,
+        );
+      }
+
+      // Parse the response
+      const result = await response.json();
+
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to create appointment');
+      }
+
+      // If the backend returns the full appointment data
+      if (result.appointmentData) {
+        console.log(`[APPOINTMENT_SERVICE] Appointment created with ID: ${result.appointmentId}`);
+        return result.appointmentData;
+      }
+
+      // If only the ID is returned, fetch the complete appointment
+      const createdAppointment = await this.getAppointmentById(result.appointmentId);
+      if (!createdAppointment) {
+        throw new Error(`Failed to retrieve created appointment with ID: ${result.appointmentId}`);
+      }
+
+      return createdAppointment;
+    } catch (error) {
+      console.error('[APPOINTMENT_SERVICE] Error creating appointment via cloud function:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets an appointment by ID.
+   *
+   * @param appointmentId ID of the appointment to retrieve
+   * @returns The appointment or null if not found
+   */
+  async getAppointmentById(appointmentId: string): Promise<Appointment | null> {
+    try {
+      console.log(`[APPOINTMENT_SERVICE] Getting appointment with ID: ${appointmentId}`);
+
+      const appointment = await getAppointmentByIdUtil(this.db, appointmentId);
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Appointment ${appointmentId} ${appointment ? 'found' : 'not found'}`,
+      );
+
+      return appointment;
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error getting appointment ${appointmentId}:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Updates an existing appointment.
+   *
+   * @param appointmentId ID of the appointment to update
+   * @param data Update data for the appointment
+   * @returns The updated appointment
+   */
+  async updateAppointment(
+    appointmentId: string,
+    data: UpdateAppointmentData,
+  ): Promise<Appointment> {
+    try {
+      console.log(`[APPOINTMENT_SERVICE] Updating appointment with ID: ${appointmentId}`);
+
+      // AUTO-MIGRATION: Convert old zonePhotos format to new array format BEFORE validation
+      if (data.metadata?.zonePhotos) {
+        const migratedZonePhotos: Record<string, BeforeAfterPerZone[]> = {};
+
+        for (const [key, value] of Object.entries(data.metadata.zonePhotos)) {
+          if (Array.isArray(value)) {
+            // Already in new format
+            migratedZonePhotos[key] = value as BeforeAfterPerZone[];
+          } else {
+            // Old format - convert to array
+            console.log(`[APPOINTMENT_SERVICE] Auto-migrating ${key} from object to array format`);
+            const oldData = value as any;
+            migratedZonePhotos[key] = [
+              {
+                before: oldData.before || null,
+                after: oldData.after || null,
+                beforeNote: null,
+                afterNote: null,
+              },
+            ];
+          }
+        }
+
+        // Replace with migrated data
+        data.metadata.zonePhotos = migratedZonePhotos;
+      }
+
+      // AUTO-CLEANUP: Remove invalid recommendedProcedures with empty notes BEFORE validation
+      console.log(
+        '[APPOINTMENT_SERVICE] 🔍 BEFORE CLEANUP - recommendedProcedures:',
+        JSON.stringify(data.metadata?.recommendedProcedures, null, 2),
+      );
+
+      if (
+        data.metadata?.recommendedProcedures &&
+        Array.isArray(data.metadata.recommendedProcedures)
+      ) {
+        const validRecommendations = data.metadata.recommendedProcedures.filter((rec: any) => {
+          const isValid = rec.note && typeof rec.note === 'string' && rec.note.trim().length > 0;
+          if (!isValid) {
+            console.log('[APPOINTMENT_SERVICE] ❌ INVALID recommendation found:', rec);
+          }
+          return isValid;
+        });
+
+        if (validRecommendations.length !== data.metadata.recommendedProcedures.length) {
+          console.log(
+            `[APPOINTMENT_SERVICE] 🧹 Removing ${
+              data.metadata.recommendedProcedures.length - validRecommendations.length
+            } invalid recommended procedures with empty notes`,
+          );
+          data.metadata.recommendedProcedures = validRecommendations;
+        } else {
+          console.log('[APPOINTMENT_SERVICE] ✅ All recommendedProcedures are valid');
+        }
+      }
+
+      console.log(
+        '[APPOINTMENT_SERVICE] 🔍 AFTER CLEANUP - recommendedProcedures:',
+        JSON.stringify(data.metadata?.recommendedProcedures, null, 2),
+      );
+
+      // Validate input data
+      console.log('[APPOINTMENT_SERVICE] 🔍 Starting Zod validation...');
+      const validatedData = await updateAppointmentSchema.parseAsync(data);
+      console.log('[APPOINTMENT_SERVICE] ✅ Zod validation passed!');
+
+      // Update the appointment using the utility function
+      const updatedAppointment = await updateAppointmentUtil(this.db, appointmentId, validatedData);
+
+      console.log(`[APPOINTMENT_SERVICE] Appointment ${appointmentId} updated successfully`);
+
+      return updatedAppointment;
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error updating appointment ${appointmentId}:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Searches for appointments based on various criteria.
+   *
+   * @param params Search parameters
+   * @returns Found appointments and the last document for pagination
+   */
+  async searchAppointments(params: SearchAppointmentsParams): Promise<{
+    appointments: Appointment[];
+    lastDoc: DocumentSnapshot | null;
+  }> {
+    try {
+      console.log('[APPOINTMENT_SERVICE] Searching appointments with params:', params);
+
+      // Validate search parameters
+      await searchAppointmentsSchema.parseAsync(params);
+
+      // Search for appointments using the utility function
+      const result = await searchAppointmentsUtil(this.db, params);
+
+      console.log(`[APPOINTMENT_SERVICE] Found ${result.appointments.length} appointments`);
+
+      return result;
+    } catch (error) {
+      console.error('[APPOINTMENT_SERVICE] Error searching appointments:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets appointments for a specific patient.
+   *
+   * @param patientId ID of the patient
+   * @param options Optional parameters for filtering and pagination
+   * @returns Found appointments and the last document for pagination
+   */
+  async getPatientAppointments(
+    patientId: string,
+    options?: {
+      startDate?: Date;
+      endDate?: Date;
+      status?: AppointmentStatus | AppointmentStatus[];
+      limit?: number;
+      startAfter?: DocumentSnapshot;
+    },
+  ): Promise<{
+    appointments: Appointment[];
+    lastDoc: DocumentSnapshot | null;
+  }> {
+    console.log(`[APPOINTMENT_SERVICE] Getting appointments for patient: ${patientId}`);
+
+    const searchParams: SearchAppointmentsParams = {
+      patientId,
+      startDate: options?.startDate,
+      endDate: options?.endDate,
+      status: options?.status,
+      limit: options?.limit,
+      startAfter: options?.startAfter,
+    };
+
+    return this.searchAppointments(searchParams);
+  }
+
+  /**
+   * Gets appointments for a specific practitioner.
+   *
+   * @param practitionerId ID of the practitioner
+   * @param options Optional parameters for filtering and pagination
+   * @returns Found appointments and the last document for pagination
+   */
+  async getPractitionerAppointments(
+    practitionerId: string,
+    options?: {
+      startDate?: Date;
+      endDate?: Date;
+      status?: AppointmentStatus | AppointmentStatus[];
+      limit?: number;
+      startAfter?: DocumentSnapshot;
+    },
+  ): Promise<{
+    appointments: Appointment[];
+    lastDoc: DocumentSnapshot | null;
+  }> {
+    console.log(`[APPOINTMENT_SERVICE] Getting appointments for practitioner: ${practitionerId}`);
+
+    const searchParams: SearchAppointmentsParams = {
+      practitionerId,
+      startDate: options?.startDate,
+      endDate: options?.endDate,
+      status: options?.status,
+      limit: options?.limit,
+      startAfter: options?.startAfter,
+    };
+
+    return this.searchAppointments(searchParams);
+  }
+
+  /**
+   * Gets appointments for a specific clinic.
+   *
+   * @param clinicBranchId ID of the clinic branch
+   * @param options Optional parameters for filtering and pagination
+   * @returns Found appointments and the last document for pagination
+   */
+  async getClinicAppointments(
+    clinicBranchId: string,
+    options?: {
+      practitionerId?: string;
+      startDate?: Date;
+      endDate?: Date;
+      status?: AppointmentStatus | AppointmentStatus[];
+      limit?: number;
+      startAfter?: DocumentSnapshot;
+    },
+  ): Promise<{
+    appointments: Appointment[];
+    lastDoc: DocumentSnapshot | null;
+  }> {
+    console.log(`[APPOINTMENT_SERVICE] Getting appointments for clinic: ${clinicBranchId}`);
+
+    const searchParams: SearchAppointmentsParams = {
+      clinicBranchId,
+      practitionerId: options?.practitionerId,
+      startDate: options?.startDate,
+      endDate: options?.endDate,
+      status: options?.status,
+      limit: options?.limit,
+      startAfter: options?.startAfter,
+    };
+
+    return this.searchAppointments(searchParams);
+  }
+
+  /**
+   * Updates the status of an appointment.
+   *
+   * @param appointmentId ID of the appointment
+   * @param newStatus New status to set
+   * @param details Optional details for the status change
+   * @returns The updated appointment
+   */
+  async updateAppointmentStatus(
+    appointmentId: string,
+    newStatus: AppointmentStatus,
+    details?: {
+      cancellationReason?: string;
+      canceledBy?: 'patient' | 'clinic' | 'practitioner' | 'system';
+    },
+  ): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Updating status of appointment ${appointmentId} to ${newStatus}`,
+    );
+    const updateData: UpdateAppointmentData = {
+      status: newStatus,
+      updatedAt: serverTimestamp(),
+    };
+
+    if (
+      newStatus === AppointmentStatus.CANCELED_CLINIC ||
+      newStatus === AppointmentStatus.CANCELED_PATIENT ||
+      newStatus === AppointmentStatus.CANCELED_PATIENT_RESCHEDULED
+    ) {
+      if (!details?.cancellationReason) {
+        throw new Error('Cancellation reason is required when canceling.');
+      }
+      if (!details?.canceledBy) {
+        throw new Error('Canceled by is required when canceling.');
+      }
+      updateData.cancellationReason = details.cancellationReason;
+      updateData.canceledBy = details.canceledBy;
+      updateData.cancellationTime = Timestamp.now();
+    }
+
+    if (newStatus === AppointmentStatus.CONFIRMED) {
+      updateData.confirmationTime = Timestamp.now();
+    }
+
+    if (newStatus === AppointmentStatus.RESCHEDULED_BY_CLINIC) {
+      updateData.rescheduleTime = Timestamp.now();
+    }
+
+    return this.updateAppointment(appointmentId, updateData);
+  }
+
+  /**
+   * Confirms a PENDING appointment by an Admin/Clinic.
+   */
+  async confirmAppointmentAdmin(appointmentId: string): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] Admin confirming appointment: ${appointmentId}`);
+    const appointment = await this.getAppointmentById(appointmentId);
+    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
+    if (appointment.status !== AppointmentStatus.PENDING) {
+      throw new Error(`Appointment ${appointmentId} is not in PENDING state to be confirmed.`);
+    }
+    return this.updateAppointmentStatus(appointmentId, AppointmentStatus.CONFIRMED);
+  }
+
+  /**
+   * Cancels an appointment by the User (Patient).
+   */
+  async cancelAppointmentUser(appointmentId: string, reason: string): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] User canceling appointment: ${appointmentId}`);
+    return this.updateAppointmentStatus(appointmentId, AppointmentStatus.CANCELED_PATIENT, {
+      cancellationReason: reason,
+      canceledBy: 'patient',
+    });
+  }
+
+  /**
+   * Cancels an appointment by an Admin/Clinic.
+   */
+  async cancelAppointmentAdmin(appointmentId: string, reason: string): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] Admin canceling appointment: ${appointmentId}`);
+    return this.updateAppointmentStatus(appointmentId, AppointmentStatus.CANCELED_CLINIC, {
+      cancellationReason: reason,
+      canceledBy: 'clinic',
+    });
+  }
+
+  /**
+   * Admin proposes to reschedule an appointment.
+   * Sets status to RESCHEDULED_BY_CLINIC and updates times.
+   */
+  async rescheduleAppointmentAdmin(params: {
+    appointmentId: string;
+    newStartTime: any; // Accept any type (number, string, Timestamp, etc.)
+    newEndTime: any; // Accept any type (number, string, Timestamp, etc.)
+  }): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] Admin rescheduling appointment: ${params.appointmentId}`);
+
+    // Validate input data
+    const validatedParams = await rescheduleAppointmentSchema.parseAsync(params);
+
+    // Convert input to Timestamp objects
+    const startTimestamp = this.convertToTimestamp(validatedParams.newStartTime);
+    const endTimestamp = this.convertToTimestamp(validatedParams.newEndTime);
+
+    if (endTimestamp.toMillis() <= startTimestamp.toMillis()) {
+      throw new Error('New end time must be after new start time.');
+    }
+
+    const updateData: UpdateAppointmentData = {
+      status: AppointmentStatus.RESCHEDULED_BY_CLINIC,
+      appointmentStartTime: startTimestamp,
+      appointmentEndTime: endTimestamp,
+      rescheduleTime: Timestamp.now(),
+      confirmationTime: null,
+      updatedAt: serverTimestamp(),
+    };
+    return this.updateAppointment(validatedParams.appointmentId, updateData);
+  }
+
+  /**
+   * Helper method to convert various timestamp formats to Firestore Timestamp
+   * @param value - Any timestamp format (Timestamp, number, string, Date, serialized Timestamp)
+   * @returns Firestore Timestamp object
+   */
+  private convertToTimestamp(value: any): Timestamp {
+    console.log(`[APPOINTMENT_SERVICE] Converting timestamp:`, {
+      value,
+      type: typeof value,
+    });
+
+    // If it's already a Timestamp object with methods
+    if (value && typeof value.toMillis === 'function') {
+      return value;
+    }
+
+    // If it's a number (milliseconds since epoch)
+    if (typeof value === 'number') {
+      return Timestamp.fromMillis(value);
+    }
+
+    // If it's a string (ISO date string)
+    if (typeof value === 'string') {
+      return Timestamp.fromDate(new Date(value));
+    }
+
+    // If it's a Date object
+    if (value instanceof Date) {
+      return Timestamp.fromDate(value);
+    }
+
+    // If it has _seconds property (serialized Timestamp) - THIS IS WHAT FRONTEND SENDS
+    if (value && typeof value._seconds === 'number') {
+      return new Timestamp(value._seconds, value._nanoseconds || 0);
+    }
+
+    // If it has seconds property (serialized Timestamp)
+    if (value && typeof value.seconds === 'number') {
+      return new Timestamp(value.seconds, value.nanoseconds || 0);
+    }
+
+    throw new Error(`Invalid timestamp format: ${typeof value}, value: ${JSON.stringify(value)}`);
+  }
+
+  /**
+   * User confirms a reschedule proposed by the clinic.
+   * Status changes from RESCHEDULED_BY_CLINIC to CONFIRMED.
+   */
+  async rescheduleAppointmentConfirmUser(appointmentId: string): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] User confirming reschedule for: ${appointmentId}`);
+    const appointment = await this.getAppointmentById(appointmentId);
+    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
+    if (appointment.status !== AppointmentStatus.RESCHEDULED_BY_CLINIC) {
+      throw new Error(`Appointment ${appointmentId} is not in RESCHEDULED_BY_CLINIC state.`);
+    }
+    return this.updateAppointmentStatus(appointmentId, AppointmentStatus.CONFIRMED);
+  }
+
+  /**
+   * User rejects a reschedule proposed by the clinic.
+   * Status changes from RESCHEDULED_BY_CLINIC to CANCELED_PATIENT_RESCHEDULED.
+   */
+  async rescheduleAppointmentRejectUser(
+    appointmentId: string,
+    reason: string,
+  ): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] User rejecting reschedule for: ${appointmentId}`);
+    const appointment = await this.getAppointmentById(appointmentId);
+    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
+    if (appointment.status !== AppointmentStatus.RESCHEDULED_BY_CLINIC) {
+      throw new Error(`Appointment ${appointmentId} is not in RESCHEDULED_BY_CLINIC state.`);
+    }
+    return this.updateAppointmentStatus(
+      appointmentId,
+      AppointmentStatus.CANCELED_PATIENT_RESCHEDULED,
+      {
+        cancellationReason: reason,
+        canceledBy: 'patient',
+      },
+    );
+  }
+
+  /**
+   * Admin checks in a patient for their appointment.
+   * Requires all pending user forms to be completed.
+   */
+  async checkInPatientAdmin(appointmentId: string): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] Admin checking in patient for: ${appointmentId}`);
+    const appointment = await this.getAppointmentById(appointmentId);
+    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
+
+    if (appointment.pendingUserFormsIds && appointment.pendingUserFormsIds.length > 0) {
+      throw new Error(
+        `Cannot check in: Patient has ${
+          appointment.pendingUserFormsIds.length
+        } pending required form(s). IDs: ${appointment.pendingUserFormsIds.join(', ')}`,
+      );
+    }
+    if (
+      appointment.status !== AppointmentStatus.CONFIRMED &&
+      appointment.status !== AppointmentStatus.RESCHEDULED_BY_CLINIC
+    ) {
+      console.warn(
+        `Checking in appointment ${appointmentId} with status ${appointment.status}. Ensure this is intended.`,
+      );
+    }
+
+    return this.updateAppointmentStatus(appointmentId, AppointmentStatus.CHECKED_IN);
+  }
+
+  /**
+   * Doctor starts the appointment procedure.
+   */
+  async startAppointmentDoctor(appointmentId: string): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] Doctor starting appointment: ${appointmentId}`);
+    const appointment = await this.getAppointmentById(appointmentId);
+    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
+    if (appointment.status !== AppointmentStatus.CHECKED_IN) {
+      throw new Error(`Appointment ${appointmentId} must be CHECKED_IN to start.`);
+    }
+    // Update status and set procedureActualStartTime
+    const updateData: UpdateAppointmentData = {
+      status: AppointmentStatus.IN_PROGRESS,
+      procedureActualStartTime: Timestamp.now(), // Set actual start time
+      updatedAt: serverTimestamp(),
+    };
+    return this.updateAppointment(appointmentId, updateData);
+  }
+
+  /**
+   * Doctor completes and finalizes the appointment.
+   */
+  async completeAppointmentDoctor(
+    appointmentId: string,
+    finalizationNotes: string,
+    actualDurationMinutesInput?: number, // Renamed to avoid conflict if we calculate
+  ): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] Doctor completing appointment: ${appointmentId}`);
+    const currentUser = this.auth.currentUser;
+    if (!currentUser) throw new Error('Authentication required to complete appointment.');
+
+    const appointment = await this.getAppointmentById(appointmentId);
+    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
+
+    let calculatedDurationMinutes = actualDurationMinutesInput;
+    const procedureCompletionTime = Timestamp.now();
+
+    // Calculate duration if not provided and actual start time is available
+    if (calculatedDurationMinutes === undefined && appointment.procedureActualStartTime) {
+      const startTimeMillis = appointment.procedureActualStartTime.toMillis();
+      const endTimeMillis = procedureCompletionTime.toMillis();
+      if (endTimeMillis > startTimeMillis) {
+        calculatedDurationMinutes = Math.round((endTimeMillis - startTimeMillis) / 60000);
+      }
+    }
+
+    const updateData: UpdateAppointmentData = {
+      status: AppointmentStatus.COMPLETED,
+      actualDurationMinutes: calculatedDurationMinutes, // Use calculated or provided duration
+      finalizedDetails: {
+        by: currentUser.uid, // This is used ID, not practitioner's profile ID (just so we know who completed the appointment)
+        at: procedureCompletionTime, // Use consistent completion timestamp
+        notes: finalizationNotes,
+      },
+      // Optionally update appointmentEndTime to the actual completion time
+      // appointmentEndTime: procedureCompletionTime,
+      updatedAt: serverTimestamp(),
+    };
+    return this.updateAppointment(appointmentId, updateData);
+  }
+
+  /**
+   * Admin marks an appointment as No-Show.
+   */
+  async markNoShowAdmin(appointmentId: string): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] Admin marking no-show for: ${appointmentId}`);
+    const appointment = await this.getAppointmentById(appointmentId);
+    if (!appointment) throw new Error(`Appointment ${appointmentId} not found.`);
+    if (Timestamp.now().toMillis() < appointment.appointmentStartTime.toMillis()) {
+      throw new Error('Cannot mark no-show before appointment start time.');
+    }
+    return this.updateAppointmentStatus(appointmentId, AppointmentStatus.NO_SHOW, {
+      cancellationReason: 'Patient did not show up for the appointment.',
+      canceledBy: 'clinic',
+    });
+  }
+
+  /**
+   * Adds a media item to an appointment.
+   */
+  async addMediaToAppointment(
+    appointmentId: string,
+    mediaItemData: Omit<AppointmentMediaItem, 'id' | 'uploadedAt'>,
+  ): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] Adding media to appointment ${appointmentId}`);
+    const currentUser = this.auth.currentUser;
+    if (!currentUser) throw new Error('Authentication required.');
+
+    const newMediaItem: AppointmentMediaItem = {
+      ...mediaItemData,
+      id: this.generateId(),
+      uploadedAt: Timestamp.now(),
+      uploadedBy: currentUser.uid,
+    };
+
+    const updateData: UpdateAppointmentData = {
+      media: arrayUnion(newMediaItem) as any,
+      updatedAt: serverTimestamp(),
+    };
+    return this.updateAppointment(appointmentId, updateData);
+  }
+
+  /**
+   * Removes a media item from an appointment.
+   */
+  async removeMediaFromAppointment(
+    appointmentId: string,
+    mediaItemId: string,
+  ): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Removing media ${mediaItemId} from appointment ${appointmentId}`,
+    );
+    const appointment = await this.getAppointmentById(appointmentId);
+    if (!appointment || !appointment.media) {
+      throw new Error('Appointment or media list not found.');
+    }
+    const mediaToRemove = appointment.media.find(m => m.id === mediaItemId);
+    if (!mediaToRemove) {
+      throw new Error(`Media item ${mediaItemId} not found in appointment.`);
+    }
+
+    const updateData: UpdateAppointmentData = {
+      media: arrayRemove(mediaToRemove) as any,
+      updatedAt: serverTimestamp(),
+    };
+    return this.updateAppointment(appointmentId, updateData);
+  }
+
+  /**
+   * Adds or updates review information for an appointment.
+   */
+  async addReviewToAppointment(
+    appointmentId: string,
+    reviewData: Omit<PatientReviewInfo, 'reviewedAt' | 'reviewId'>,
+  ): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] Adding review to appointment ${appointmentId}`);
+    const newReviewInfo: PatientReviewInfo = {
+      ...reviewData,
+      reviewId: this.generateId(),
+      reviewedAt: Timestamp.now(),
+    };
+    const updateData: UpdateAppointmentData = {
+      reviewInfo: newReviewInfo,
+      updatedAt: serverTimestamp(),
+    };
+    return this.updateAppointment(appointmentId, updateData);
+  }
+
+  /**
+   * Updates the payment status of an appointment.
+   */
+  async updatePaymentStatus(
+    appointmentId: string,
+    paymentStatus: PaymentStatus,
+    paymentTransactionId?: string,
+  ): Promise<Appointment> {
+    console.log(
+      `[APPOINTMENT_SERVICE] Updating payment status of appointment ${appointmentId} to ${paymentStatus}`,
+    );
+    const updateData: UpdateAppointmentData = {
+      paymentStatus,
+      paymentTransactionId: paymentTransactionId || null,
+      updatedAt: serverTimestamp(),
+    };
+    return this.updateAppointment(appointmentId, updateData);
+  }
+
+  /**
+   * Updates the internal notes of an appointment.
+   *
+   * @param appointmentId ID of the appointment
+   * @param notes Updated internal notes
+   * @returns The updated appointment
+   */
+  async updateInternalNotes(appointmentId: string, notes: string | null): Promise<Appointment> {
+    console.log(`[APPOINTMENT_SERVICE] Updating internal notes for appointment: ${appointmentId}`);
+
+    const updateData: UpdateAppointmentData = {
+      internalNotes: notes,
+    };
+
+    return this.updateAppointment(appointmentId, updateData);
+  }
+
+  /**
+   * Gets upcoming appointments for a specific patient.
+   * These include appointments with statuses: PENDING, CONFIRMED, CHECKED_IN, IN_PROGRESS
+   *
+   * @param patientId ID of the patient
+   * @param options Optional parameters for filtering and pagination
+   * @returns Found appointments and the last document for pagination
+   */
+  async getUpcomingPatientAppointments(
+    patientId: string,
+    options?: {
+      startDate?: Date; // Optional starting date (defaults to now)
+      endDate?: Date;
+      limit?: number;
+      startAfter?: DocumentSnapshot;
+    },
+  ): Promise<{
+    appointments: Appointment[];
+    lastDoc: DocumentSnapshot | null;
+  }> {
+    try {
+      console.log(`[APPOINTMENT_SERVICE] Getting upcoming appointments for patient: ${patientId}`);
+
+      // Default to current date/time if no startDate provided
+      const effectiveStartDate = options?.startDate || new Date();
+
+      // Define the statuses considered as "upcoming"
+      const upcomingStatuses = [
+        AppointmentStatus.PENDING,
+        AppointmentStatus.CONFIRMED,
+        AppointmentStatus.CHECKED_IN,
+        AppointmentStatus.IN_PROGRESS,
+        AppointmentStatus.RESCHEDULED_BY_CLINIC,
+      ];
+
+      // Build query constraints
+      const constraints: QueryConstraint[] = [];
+
+      // Patient ID filter
+      constraints.push(where('patientId', '==', patientId));
+
+      // Status filter - multiple statuses
+      constraints.push(where('status', 'in', upcomingStatuses));
+
+      // Date range filters
+      constraints.push(where('appointmentStartTime', '>=', Timestamp.fromDate(effectiveStartDate)));
+
+      if (options?.endDate) {
+        constraints.push(where('appointmentStartTime', '<=', Timestamp.fromDate(options.endDate)));
+      }
+
+      // Order by appointment start time (ascending for upcoming - closest first)
+      constraints.push(orderBy('appointmentStartTime', 'asc'));
+
+      // Add pagination if specified
+      if (options?.limit) {
+        constraints.push(limit(options.limit));
+      }
+
+      if (options?.startAfter) {
+        constraints.push(startAfter(options.startAfter));
+      }
+
+      // Execute query
+      const q = query(collection(this.db, APPOINTMENTS_COLLECTION), ...constraints);
+      const querySnapshot = await getDocs(q);
+
+      // Extract results
+      const appointments = querySnapshot.docs.map(doc => doc.data() as Appointment);
+
+      // Get last document for pagination
+      const lastDoc =
+        querySnapshot.docs.length > 0 ? querySnapshot.docs[querySnapshot.docs.length - 1] : null;
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Found ${appointments.length} upcoming appointments for patient ${patientId}`,
+      );
+
+      return { appointments, lastDoc };
+    } catch (error) {
+      console.error(
+        `[APPOINTMENT_SERVICE] Error getting upcoming appointments for patient ${patientId}:`,
+        error,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Gets past appointments for a specific patient.
+   * These include appointments with statuses: COMPLETED, CANCELED_PATIENT,
+   * CANCELED_PATIENT_RESCHEDULED, CANCELED_CLINIC, NO_SHOW
+   *
+   * @param patientId ID of the patient
+   * @param options Optional parameters for filtering and pagination
+   * @returns Found appointments and the last document for pagination
+   */
+  async getPastPatientAppointments(
+    patientId: string,
+    options?: {
+      startDate?: Date;
+      endDate?: Date; // Optional end date (defaults to now)
+      showCanceled?: boolean; // Whether to include canceled appointments
+      showNoShow?: boolean; // Whether to include no-show appointments
+      limit?: number;
+      startAfter?: DocumentSnapshot;
+    },
+  ): Promise<{
+    appointments: Appointment[];
+    lastDoc: DocumentSnapshot | null;
+  }> {
+    try {
+      console.log(`[APPOINTMENT_SERVICE] Getting past appointments for patient: ${patientId}`);
+
+      // Default to current date/time if no endDate provided
+      const effectiveEndDate = options?.endDate || new Date();
+
+      // Define the base status for past appointments
+      const pastStatuses: AppointmentStatus[] = [AppointmentStatus.COMPLETED];
+
+      // Add canceled statuses if requested
+      if (options?.showCanceled) {
+        pastStatuses.push(
+          AppointmentStatus.CANCELED_PATIENT,
+          AppointmentStatus.CANCELED_PATIENT_RESCHEDULED,
+          AppointmentStatus.CANCELED_CLINIC,
+        );
+      }
+
+      // Add no-show status if requested
+      if (options?.showNoShow) {
+        pastStatuses.push(AppointmentStatus.NO_SHOW);
+      }
+
+      // Build query constraints
+      const constraints: QueryConstraint[] = [];
+
+      // Patient ID filter
+      constraints.push(where('patientId', '==', patientId));
+
+      // Status filter - multiple statuses
+      constraints.push(where('status', 'in', pastStatuses));
+
+      // Date range filters
+      if (options?.startDate) {
+        constraints.push(
+          where('appointmentStartTime', '>=', Timestamp.fromDate(options.startDate)),
+        );
+      }
+
+      constraints.push(where('appointmentStartTime', '<=', Timestamp.fromDate(effectiveEndDate)));
+
+      // Order by appointment start time (descending for past - most recent first)
+      constraints.push(orderBy('appointmentStartTime', 'desc'));
+
+      // Add pagination if specified
+      if (options?.limit) {
+        constraints.push(limit(options.limit));
+      }
+
+      if (options?.startAfter) {
+        constraints.push(startAfter(options.startAfter));
+      }
+
+      // Execute query
+      const q = query(collection(this.db, APPOINTMENTS_COLLECTION), ...constraints);
+      const querySnapshot = await getDocs(q);
+
+      // Extract results
+      const appointments = querySnapshot.docs.map(doc => doc.data() as Appointment);
+
+      // Get last document for pagination
+      const lastDoc =
+        querySnapshot.docs.length > 0 ? querySnapshot.docs[querySnapshot.docs.length - 1] : null;
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Found ${appointments.length} past appointments for patient ${patientId}`,
+      );
+
+      return { appointments, lastDoc };
+    } catch (error) {
+      console.error(
+        `[APPOINTMENT_SERVICE] Error getting past appointments for patient ${patientId}:`,
+        error,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Counts completed appointments for a patient with optional clinic filtering.
+   *
+   * @param patientId ID of the patient.
+   * @param clinicBranchId Optional ID of the clinic branch to either include or exclude.
+   * @param excludeClinic Optional boolean. If true (default), excludes the specified clinic. If false, includes only that clinic.
+   * @returns The count of completed appointments.
+   */
+  async countCompletedAppointments(
+    patientId: string,
+    clinicBranchId?: string,
+    excludeClinic = true,
+  ): Promise<number> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Counting completed appointments for patient: ${patientId}`,
+        { clinicBranchId, excludeClinic },
+      );
+
+      // Build query constraints
+      const constraints: QueryConstraint[] = [
+        where('patientId', '==', patientId),
+        where('status', '==', AppointmentStatus.COMPLETED),
+      ];
+
+      if (clinicBranchId) {
+        if (excludeClinic) {
+          // Exclude appointments from the specified clinic
+          constraints.push(where('clinicBranchId', '!=', clinicBranchId));
+        } else {
+          // Include only appointments from the specified clinic
+          constraints.push(where('clinicBranchId', '==', clinicBranchId));
+        }
+      }
+
+      // Execute query to get only the count
+      const q = query(collection(this.db, APPOINTMENTS_COLLECTION), ...constraints);
+      const snapshot = await getCountFromServer(q);
+      const count = snapshot.data().count;
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Found ${count} completed appointments for patient ${patientId}`,
+      );
+
+      return count;
+    } catch (error) {
+      console.error(
+        `[APPOINTMENT_SERVICE] Error counting completed appointments for patient ${patientId}:`,
+        error,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Uploads a zone photo and updates appointment metadata
+   *
+   * @param uploadData Zone photo upload data containing appointment ID, zone ID, photo type, file, and optional notes
+   * @returns The uploaded media metadata
+   */
+  async uploadZonePhoto(uploadData: ZonePhotoUploadData): Promise<MediaMetadata> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Uploading ${uploadData.photoType} photo for zone ${uploadData.zoneId} in appointment ${uploadData.appointmentId}`,
+      );
+
+      // Validate input data
+      const validatedData = await zonePhotoUploadSchema.parseAsync(uploadData);
+
+      // Check if user is authenticated
+      const currentUser = this.auth.currentUser;
+      if (!currentUser) {
+        throw new Error('User must be authenticated to upload zone photos');
+      }
+
+      // Get the appointment to verify it exists and user has access
+      const appointment = await this.getAppointmentById(validatedData.appointmentId);
+      if (!appointment) {
+        throw new Error(`Appointment with ID ${validatedData.appointmentId} not found`);
+      }
+
+      // Generate collection name for the media
+      const collectionName = `appointment_${validatedData.appointmentId}_zone_photos`;
+
+      // Generate filename with zone and photo type info
+      const timestamp = Date.now();
+      const fileExtension = validatedData.file.type?.split('/')[1] || 'jpg';
+      const fileName = `${validatedData.photoType}_${validatedData.zoneId}_${timestamp}.${fileExtension}`;
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Uploading file: ${fileName} to collection: ${collectionName}`,
+      );
+
+      // Upload the media file using MediaService
+      const uploadedMedia = await this.mediaService.uploadMedia(
+        validatedData.file,
+        validatedData.appointmentId, // ownerId is the appointment ID
+        MediaAccessLevel.PRIVATE, // Zone photos are private
+        collectionName,
+        fileName,
+      );
+
+      console.log(`[APPOINTMENT_SERVICE] Media uploaded successfully with ID: ${uploadedMedia.id}`);
+
+      // Update appointment metadata with the new photo
+      await this.updateAppointmentZonePhoto(
+        validatedData.appointmentId,
+        validatedData.zoneId,
+        validatedData.photoType,
+        uploadedMedia,
+        validatedData.notes,
+      );
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Successfully uploaded and linked ${validatedData.photoType} photo for zone ${validatedData.zoneId}`,
+      );
+
+      return uploadedMedia;
+    } catch (error) {
+      console.error('[APPOINTMENT_SERVICE] Error uploading zone photo:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Updates appointment metadata with zone photo information
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId ID of the zone
+   * @param photoType Type of photo ('before' or 'after')
+   * @param mediaMetadata Uploaded media metadata
+   * @param notes Optional notes for the photo
+   * @returns The updated appointment
+   */
+  private async updateAppointmentZonePhoto(
+    appointmentId: string,
+    zoneId: string,
+    photoType: 'before' | 'after',
+    mediaMetadata: MediaMetadata,
+    notes?: string,
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Updating appointment metadata for ${photoType} photo in zone ${zoneId}`,
+      );
+
+      // Get current appointment
+      const appointment = await this.getAppointmentById(appointmentId);
+      if (!appointment) {
+        throw new Error(`Appointment with ID ${appointmentId} not found`);
+      }
+
+      // Initialize metadata if it doesn't exist
+      const currentMetadata = appointment.metadata || {
+        selectedZones: null,
+        zonePhotos: null,
+        zonesData: null,
+        appointmentProducts: [],
+        extendedProcedures: [],
+        recommendedProcedures: [],
+        zoneBilling: null,
+        finalbilling: null,
+        finalizationNotes: null,
+      };
+
+      // Initialize zonePhotos if it doesn't exist (array model per zone)
+      let currentZonePhotos: Record<string, BeforeAfterPerZone[]> = {};
+
+      // AUTO-MIGRATION: Convert old object format to new array format
+      if (currentMetadata.zonePhotos) {
+        for (const [key, value] of Object.entries(currentMetadata.zonePhotos)) {
+          if (Array.isArray(value)) {
+            // Already in new format
+            currentZonePhotos[key] = value as BeforeAfterPerZone[];
+          } else {
+            // Old format - convert to array
+            console.log(`[APPOINTMENT_SERVICE] Auto-migrating ${key} from object to array format`);
+            const oldData = value as any;
+            currentZonePhotos[key] = [
+              {
+                before: oldData.before || null,
+                after: oldData.after || null,
+                beforeNote: null,
+                afterNote: null,
+              },
+            ];
+          }
+        }
+      }
+
+      // Initialize the zone array if it doesn't exist
+      if (!currentZonePhotos[zoneId]) {
+        currentZonePhotos[zoneId] = [];
+      }
+
+      // Create a new entry for this uploaded photo with per-photo notes
+      const newEntry: BeforeAfterPerZone = {
+        before: photoType === 'before' ? mediaMetadata.url : null,
+        after: photoType === 'after' ? mediaMetadata.url : null,
+        beforeNote: photoType === 'before' ? notes || null : null,
+        afterNote: photoType === 'after' ? notes || null : null,
+      };
+
+      // Append to the zone's photo list
+      currentZonePhotos[zoneId] = [...currentZonePhotos[zoneId], newEntry];
+      // Enforce max 10 photos per zone by keeping the most recent 10
+      if (currentZonePhotos[zoneId].length > 10) {
+        currentZonePhotos[zoneId] = currentZonePhotos[zoneId].slice(-10);
+      }
+
+      // Update the appointment with new metadata
+      const updateData: UpdateAppointmentData = {
+        metadata: {
+          selectedZones: currentMetadata.selectedZones,
+          zonePhotos: currentZonePhotos,
+          zonesData: currentMetadata.zonesData || null,
+          appointmentProducts: currentMetadata.appointmentProducts || [],
+          extendedProcedures: currentMetadata.extendedProcedures || [],
+          recommendedProcedures: currentMetadata.recommendedProcedures || [],
+          // Only include zoneBilling if it exists (avoid undefined values in Firestore)
+          ...(currentMetadata.zoneBilling !== undefined && {
+            zoneBilling: currentMetadata.zoneBilling,
+          }),
+          finalbilling: currentMetadata.finalbilling,
+          finalizationNotes: currentMetadata.finalizationNotes,
+        },
+        updatedAt: serverTimestamp(),
+      };
+
+      const updatedAppointment = await this.updateAppointment(appointmentId, updateData);
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Successfully updated appointment metadata for ${photoType} photo in zone ${zoneId}`,
+      );
+
+      return updatedAppointment;
+    } catch (error) {
+      console.error(
+        `[APPOINTMENT_SERVICE] Error updating appointment metadata for zone photo:`,
+        error,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Gets zone photos for a specific appointment and zone
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId ID of the zone (optional - if not provided, returns all zones)
+   * @returns Zone photos data
+   */
+  async getZonePhotos(
+    appointmentId: string,
+    zoneId?: string,
+  ): Promise<Record<string, BeforeAfterPerZone[]> | BeforeAfterPerZone[] | null> {
+    try {
+      console.log(`[APPOINTMENT_SERVICE] Getting zone photos for appointment ${appointmentId}`);
+
+      const appointment = await this.getAppointmentById(appointmentId);
+      if (!appointment) {
+        throw new Error(`Appointment with ID ${appointmentId} not found`);
+      }
+
+      const zonePhotos = appointment.metadata?.zonePhotos as
+        | Record<string, BeforeAfterPerZone[]>
+        | undefined
+        | null;
+      if (!zonePhotos) {
+        return null;
+      }
+
+      // If specific zone requested, return only that zone's photos
+      if (zoneId) {
+        return zonePhotos[zoneId] || null;
+      }
+
+      // Return all zone photos
+      return zonePhotos;
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error getting zone photos:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Deletes a zone photo entry (by index) and updates appointment metadata
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId ID of the zone
+   * @param photoIndex Index of the photo entry to delete in the zone array
+   * @returns The updated appointment
+   */
+  async deleteZonePhoto(
+    appointmentId: string,
+    zoneId: string,
+    photoIndex: number,
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Deleting zone photo index ${photoIndex} for zone ${zoneId} in appointment ${appointmentId}`,
+      );
+
+      // Get current appointment
+      const appointment = await this.getAppointmentById(appointmentId);
+      if (!appointment) {
+        throw new Error(`Appointment with ID ${appointmentId} not found`);
+      }
+
+      const zonePhotos = appointment.metadata?.zonePhotos as
+        | Record<string, BeforeAfterPerZone[]>
+        | undefined
+        | null;
+      if (!zonePhotos || !zonePhotos[zoneId] || !Array.isArray(zonePhotos[zoneId])) {
+        throw new Error(`No photos found for zone ${zoneId} in appointment ${appointmentId}`);
+      }
+
+      const zoneArray = [...zonePhotos[zoneId]];
+      if (photoIndex < 0 || photoIndex >= zoneArray.length) {
+        throw new Error(`Invalid photo index ${photoIndex} for zone ${zoneId}`);
+      }
+
+      const entry = zoneArray[photoIndex];
+      const photoUrl = (entry.before || entry.after) as MediaResource | null;
+      if (!photoUrl) {
+        throw new Error(`No photo URL found for index ${photoIndex} in zone ${zoneId}`);
+      }
+
+      // Try to find and delete the media from storage
+      try {
+        // Only try to delete if photoUrl is a string (URL)
+        if (typeof photoUrl === 'string') {
+          const mediaMetadata = await this.mediaService.getMediaMetadataByUrl(photoUrl);
+          if (mediaMetadata) {
+            await this.mediaService.deleteMedia(mediaMetadata.id);
+            console.log(`[APPOINTMENT_SERVICE] Deleted media file with ID: ${mediaMetadata.id}`);
+          }
+        }
+      } catch (mediaError) {
+        console.warn(
+          `[APPOINTMENT_SERVICE] Could not delete media file for URL ${photoUrl}:`,
+          mediaError,
+        );
+        // Continue with metadata update even if media deletion fails
+      }
+
+      // Update appointment metadata to remove the photo entry at the specified index
+      const updatedZonePhotos: Record<string, BeforeAfterPerZone[]> = { ...zonePhotos } as any;
+      const updatedZoneArray = [...zoneArray];
+      updatedZoneArray.splice(photoIndex, 1);
+      if (updatedZoneArray.length === 0) {
+        delete updatedZonePhotos[zoneId];
+      } else {
+        updatedZonePhotos[zoneId] = updatedZoneArray;
+      }
+
+      const updateData: UpdateAppointmentData = {
+        metadata: {
+          selectedZones: appointment.metadata?.selectedZones || null,
+          zonePhotos: updatedZonePhotos,
+          zonesData: appointment.metadata?.zonesData || null,
+          appointmentProducts: appointment.metadata?.appointmentProducts || [],
+          extendedProcedures: appointment.metadata?.extendedProcedures || [],
+          recommendedProcedures: appointment.metadata?.recommendedProcedures || [],
+          // Only include zoneBilling if it exists (avoid undefined values in Firestore)
+          ...(appointment.metadata?.zoneBilling !== undefined && {
+            zoneBilling: appointment.metadata.zoneBilling,
+          }),
+          finalbilling: appointment.metadata?.finalbilling || null,
+          finalizationNotes: appointment.metadata?.finalizationNotes || null,
+        },
+        updatedAt: serverTimestamp(),
+      };
+
+      const updatedAppointment = await this.updateAppointment(appointmentId, updateData);
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Successfully deleted photo index ${photoIndex} for zone ${zoneId}`,
+      );
+
+      return updatedAppointment;
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error deleting zone photo:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Adds an item (product or note) to a specific zone
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId Zone ID (must be category.zone format, e.g., "face.forehead")
+   * @param item Zone item data to add (without parentZone - it's inferred from zoneId)
+   * @returns The updated appointment
+   */
+  async addItemToZone(
+    appointmentId: string,
+    zoneId: string,
+    item: Omit<ZoneItemData, 'subtotal' | 'parentZone'>,
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Adding item to zone ${zoneId} in appointment ${appointmentId}`,
+      );
+      return await addItemToZoneUtil(this.db, appointmentId, zoneId, item);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error adding item to zone:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Removes an item from a specific zone
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId Zone ID
+   * @param itemIndex Index of the item to remove in the zone's items array
+   * @returns The updated appointment
+   */
+  async removeItemFromZone(
+    appointmentId: string,
+    zoneId: string,
+    itemIndex: number,
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Removing item ${itemIndex} from zone ${zoneId} in appointment ${appointmentId}`,
+      );
+      return await removeItemFromZoneUtil(this.db, appointmentId, zoneId, itemIndex);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error removing item from zone:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Updates a specific item in a zone
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId Zone ID
+   * @param itemIndex Index of the item to update
+   * @param updates Partial updates to apply to the item
+   * @returns The updated appointment
+   */
+  async updateZoneItem(
+    appointmentId: string,
+    zoneId: string,
+    itemIndex: number,
+    updates: Partial<ZoneItemData>,
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Updating item ${itemIndex} in zone ${zoneId} in appointment ${appointmentId}`,
+      );
+      return await updateZoneItemUtil(this.db, appointmentId, zoneId, itemIndex, updates);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error updating zone item:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Overrides the price for a specific zone item
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId Zone ID
+   * @param itemIndex Index of the item
+   * @param newPrice New price amount to set
+   * @returns The updated appointment
+   */
+  async overridePriceForZoneItem(
+    appointmentId: string,
+    zoneId: string,
+    itemIndex: number,
+    newPrice: number,
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Overriding price for item ${itemIndex} in zone ${zoneId} to ${newPrice}`,
+      );
+      return await overridePriceForZoneItemUtil(
+        this.db,
+        appointmentId,
+        zoneId,
+        itemIndex,
+        newPrice,
+      );
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error overriding price:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Updates subzones for a specific zone item
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId Zone ID
+   * @param itemIndex Index of the item
+   * @param subzones Array of subzone keys (category.zone.subzone format)
+   * @returns The updated appointment
+   */
+  async updateSubzones(
+    appointmentId: string,
+    zoneId: string,
+    itemIndex: number,
+    subzones: string[],
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Updating subzones for item ${itemIndex} in zone ${zoneId}`,
+      );
+      return await updateSubzonesUtil(this.db, appointmentId, zoneId, itemIndex, subzones);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error updating subzones:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Adds an extended procedure to an appointment
+   * Automatically aggregates products into appointmentProducts
+   *
+   * @param appointmentId ID of the appointment
+   * @param procedureId ID of the procedure to add
+   * @returns The updated appointment
+   */
+  async addExtendedProcedure(appointmentId: string, procedureId: string): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Adding extended procedure ${procedureId} to appointment ${appointmentId}`,
+      );
+      return await addExtendedProcedureUtil(this.db, appointmentId, procedureId);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error adding extended procedure:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Removes an extended procedure from an appointment
+   * Also removes associated products from appointmentProducts
+   *
+   * @param appointmentId ID of the appointment
+   * @param procedureId ID of the procedure to remove
+   * @returns The updated appointment
+   */
+  async removeExtendedProcedure(appointmentId: string, procedureId: string): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Removing extended procedure ${procedureId} from appointment ${appointmentId}`,
+      );
+      return await removeExtendedProcedureUtil(this.db, appointmentId, procedureId);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error removing extended procedure:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets all extended procedures for an appointment
+   *
+   * @param appointmentId ID of the appointment
+   * @returns Array of extended procedures
+   */
+  async getExtendedProcedures(appointmentId: string): Promise<ExtendedProcedureInfo[]> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Getting extended procedures for appointment ${appointmentId}`,
+      );
+      return await getExtendedProceduresUtil(this.db, appointmentId);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error getting extended procedures:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets all aggregated products for an appointment
+   * Includes products from main procedure and extended procedures
+   *
+   * @param appointmentId ID of the appointment
+   * @returns Array of appointment products
+   */
+  async getAppointmentProducts(appointmentId: string): Promise<AppointmentProductMetadata[]> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Getting appointment products for appointment ${appointmentId}`,
+      );
+      return await getAppointmentProductsUtil(this.db, appointmentId);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error getting appointment products:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Recalculates final billing for an appointment based on zone items
+   *
+   * @param appointmentId ID of the appointment
+   * @param taxRate Tax rate (e.g., 0.20 for 20%)
+   * @returns The updated appointment with recalculated billing
+   */
+  async recalculateFinalBilling(appointmentId: string, taxRate?: number): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Recalculating final billing for appointment ${appointmentId}`,
+      );
+
+      const appointment = await this.getAppointmentById(appointmentId);
+      if (!appointment) {
+        throw new Error(`Appointment with ID ${appointmentId} not found`);
+      }
+
+      const zonesData = appointment.metadata?.zonesData;
+      if (!zonesData || Object.keys(zonesData).length === 0) {
+        throw new Error('No zone data available for billing calculation');
+      }
+
+      const finalbilling = calculateFinalBilling(zonesData, taxRate);
+
+      const currentMetadata = appointment.metadata || {
+        selectedZones: null,
+        zonePhotos: null,
+        zonesData: null,
+        appointmentProducts: [],
+        extendedProcedures: [],
+        recommendedProcedures: [],
+        finalbilling: null,
+        finalizationNotes: null,
+      };
+
+      const updateData: UpdateAppointmentData = {
+        metadata: {
+          selectedZones: currentMetadata.selectedZones,
+          zonePhotos: currentMetadata.zonePhotos,
+          zonesData: currentMetadata.zonesData,
+          appointmentProducts: currentMetadata.appointmentProducts || [],
+          extendedProcedures: currentMetadata.extendedProcedures || [],
+          recommendedProcedures: currentMetadata.recommendedProcedures || [],
+          // Only include zoneBilling if it exists (avoid undefined values in Firestore)
+          ...(currentMetadata.zoneBilling !== undefined && {
+            zoneBilling: currentMetadata.zoneBilling,
+          }),
+          finalbilling,
+          finalizationNotes: currentMetadata.finalizationNotes,
+        },
+        updatedAt: serverTimestamp(),
+      };
+
+      return await this.updateAppointment(appointmentId, updateData);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error recalculating final billing:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Adds a recommended procedure to an appointment
+   * Multiple recommendations of the same procedure are allowed (e.g., touch-up in 2 weeks, full treatment in 3 months)
+   *
+   * @param appointmentId ID of the appointment
+   * @param procedureId ID of the procedure to recommend
+   * @param note Note explaining the recommendation
+   * @param timeframe Suggested timeframe for the procedure
+   * @returns The updated appointment
+   */
+  async addRecommendedProcedure(
+    appointmentId: string,
+    procedureId: string,
+    note: string,
+    timeframe: { value: number; unit: 'day' | 'week' | 'month' | 'year' },
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Adding recommended procedure ${procedureId} to appointment ${appointmentId}`,
+      );
+      return await addRecommendedProcedureUtil(
+        this.db,
+        appointmentId,
+        procedureId,
+        note,
+        timeframe,
+      );
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error adding recommended procedure:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Removes a recommended procedure from an appointment by index
+   *
+   * @param appointmentId ID of the appointment
+   * @param recommendationIndex Index of the recommendation to remove
+   * @returns The updated appointment
+   */
+  async removeRecommendedProcedure(
+    appointmentId: string,
+    recommendationIndex: number,
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Removing recommended procedure at index ${recommendationIndex} from appointment ${appointmentId}`,
+      );
+      return await removeRecommendedProcedureUtil(this.db, appointmentId, recommendationIndex);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error removing recommended procedure:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Updates a recommended procedure in an appointment by index
+   *
+   * @param appointmentId ID of the appointment
+   * @param recommendationIndex Index of the recommendation to update
+   * @param updates Partial updates (note and/or timeframe)
+   * @returns The updated appointment
+   */
+  async updateRecommendedProcedure(
+    appointmentId: string,
+    recommendationIndex: number,
+    updates: {
+      note?: string;
+      timeframe?: { value: number; unit: 'day' | 'week' | 'month' | 'year' };
+    },
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Updating recommended procedure at index ${recommendationIndex} in appointment ${appointmentId}`,
+      );
+      return await updateRecommendedProcedureUtil(
+        this.db,
+        appointmentId,
+        recommendationIndex,
+        updates,
+      );
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error updating recommended procedure:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets all recommended procedures for an appointment
+   *
+   * @param appointmentId ID of the appointment
+   * @returns Array of recommended procedures
+   */
+  async getRecommendedProcedures(appointmentId: string): Promise<RecommendedProcedure[]> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Getting recommended procedures for appointment ${appointmentId}`,
+      );
+      return await getRecommendedProceduresUtil(this.db, appointmentId);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error getting recommended procedures:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Updates a specific photo entry in a zone by index
+   * Can update before/after photos and their notes
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId Zone ID
+   * @param photoIndex Index of the photo entry to update
+   * @param updates Partial updates to apply (before, after, beforeNote, afterNote)
+   * @returns The updated appointment
+   */
+  async updateZonePhotoEntry(
+    appointmentId: string,
+    zoneId: string,
+    photoIndex: number,
+    updates: Partial<BeforeAfterPerZone>,
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Updating photo entry at index ${photoIndex} for zone ${zoneId} in appointment ${appointmentId}`,
+      );
+      return await updateZonePhotoEntryUtil(this.db, appointmentId, zoneId, photoIndex, updates);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error updating zone photo entry:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Adds an after photo to an existing before photo entry
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId Zone ID
+   * @param photoIndex Index of the entry to add after photo to
+   * @param afterPhotoUrl URL of the after photo
+   * @param afterNote Optional note for the after photo
+   * @returns The updated appointment
+   */
+  async addAfterPhotoToEntry(
+    appointmentId: string,
+    zoneId: string,
+    photoIndex: number,
+    afterPhotoUrl: MediaResource,
+    afterNote?: string,
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Adding after photo to entry at index ${photoIndex} for zone ${zoneId}`,
+      );
+      return await addAfterPhotoToEntryUtil(
+        this.db,
+        appointmentId,
+        zoneId,
+        photoIndex,
+        afterPhotoUrl,
+        afterNote,
+      );
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error adding after photo to entry:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Updates notes for a photo entry
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId Zone ID
+   * @param photoIndex Index of the entry
+   * @param beforeNote Optional note for before photo
+   * @param afterNote Optional note for after photo
+   * @returns The updated appointment
+   */
+  async updateZonePhotoNotes(
+    appointmentId: string,
+    zoneId: string,
+    photoIndex: number,
+    beforeNote?: string,
+    afterNote?: string,
+  ): Promise<Appointment> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Updating notes for photo entry at index ${photoIndex} for zone ${zoneId}`,
+      );
+      return await updateZonePhotoNotesUtil(
+        this.db,
+        appointmentId,
+        zoneId,
+        photoIndex,
+        beforeNote,
+        afterNote,
+      );
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error updating zone photo notes:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets a specific photo entry from a zone
+   *
+   * @param appointmentId ID of the appointment
+   * @param zoneId Zone ID
+   * @param photoIndex Index of the entry
+   * @returns Photo entry
+   */
+  async getZonePhotoEntry(
+    appointmentId: string,
+    zoneId: string,
+    photoIndex: number,
+  ): Promise<BeforeAfterPerZone> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Getting photo entry at index ${photoIndex} for zone ${zoneId}`,
+      );
+      return await getZonePhotoEntryUtil(this.db, appointmentId, zoneId, photoIndex);
+    } catch (error) {
+      console.error(`[APPOINTMENT_SERVICE] Error getting zone photo entry:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets all next steps recommendations for a patient from their past appointments.
+   * Returns recommendations with context about which appointment, practitioner, and clinic suggested them.
+   *
+   * @param patientId ID of the patient
+   * @param options Optional parameters for filtering
+   * @returns Array of next steps recommendations with context
+   */
+  async getPatientNextStepsRecommendations(
+    patientId: string,
+    options?: {
+      /** Include dismissed recommendations (default: false) */
+      includeDismissed?: boolean;
+      /** Filter by clinic branch ID */
+      clinicBranchId?: string;
+      /** Filter by practitioner ID */
+      practitionerId?: string;
+      /** Limit the number of results */
+      limit?: number;
+    },
+  ): Promise<NextStepsRecommendation[]> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Getting next steps recommendations for patient: ${patientId}`,
+        options,
+      );
+
+      // Get patient profile to check dismissed recommendations
+      const patientProfile = await this.patientService.getPatientProfile(patientId);
+      const dismissedIds = new Set(
+        patientProfile?.dismissedNextStepsRecommendations || [],
+      );
+
+      // Get past appointments (completed appointments)
+      const pastAppointments = await this.getPastPatientAppointments(patientId, {
+        showCanceled: false,
+        showNoShow: false,
+      });
+
+      const recommendations: NextStepsRecommendation[] = [];
+
+      // Iterate through past appointments and extract recommendations
+      for (const appointment of pastAppointments.appointments) {
+        // Filter by clinic if specified
+        if (options?.clinicBranchId && appointment.clinicBranchId !== options.clinicBranchId) {
+          continue;
+        }
+
+        // Filter by practitioner if specified
+        if (options?.practitionerId && appointment.practitionerId !== options.practitionerId) {
+          continue;
+        }
+
+        // Get recommended procedures from appointment metadata
+        const recommendedProcedures =
+          appointment.metadata?.recommendedProcedures || [];
+
+        // Create NextStepsRecommendation for each recommended procedure
+        for (let index = 0; index < recommendedProcedures.length; index++) {
+          const recommendedProcedure = recommendedProcedures[index];
+          const recommendationId = `${appointment.id}:${index}`;
+
+          // Skip if dismissed and not including dismissed
+          if (!options?.includeDismissed && dismissedIds.has(recommendationId)) {
+            continue;
+          }
+
+          const nextStepsRecommendation: NextStepsRecommendation = {
+            id: recommendationId,
+            recommendedProcedure,
+            appointmentId: appointment.id,
+            appointmentDate: appointment.appointmentStartTime,
+            practitionerId: appointment.practitionerId,
+            practitionerName: appointment.practitionerInfo?.name || 'Unknown Practitioner',
+            clinicBranchId: appointment.clinicBranchId,
+            clinicName: appointment.clinicInfo?.name || 'Unknown Clinic',
+            appointmentStatus: appointment.status,
+            isDismissed: dismissedIds.has(recommendationId),
+            dismissedAt: null, // We don't track when it was dismissed, just that it was
+          };
+
+          recommendations.push(nextStepsRecommendation);
+        }
+      }
+
+      // Sort by appointment date (most recent first)
+      recommendations.sort((a, b) => {
+        const dateA = a.appointmentDate.toMillis();
+        const dateB = b.appointmentDate.toMillis();
+        return dateB - dateA;
+      });
+
+      // Apply limit if specified
+      const limitedRecommendations = options?.limit
+        ? recommendations.slice(0, options.limit)
+        : recommendations;
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Found ${limitedRecommendations.length} next steps recommendations for patient ${patientId}`,
+      );
+
+      return limitedRecommendations;
+    } catch (error) {
+      console.error(
+        `[APPOINTMENT_SERVICE] Error getting next steps recommendations for patient ${patientId}:`,
+        error,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Dismisses a next steps recommendation for a patient.
+   * This prevents the recommendation from showing up in the default view.
+   *
+   * @param patientId ID of the patient
+   * @param recommendationId ID of the recommendation to dismiss (format: appointmentId:recommendationIndex)
+   * @returns Updated patient profile
+   */
+  async dismissNextStepsRecommendation(
+    patientId: string,
+    recommendationId: string,
+  ): Promise<void> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Dismissing recommendation ${recommendationId} for patient ${patientId}`,
+      );
+
+      // Get patient profile
+      const patientProfile = await this.patientService.getPatientProfile(patientId);
+      if (!patientProfile) {
+        throw new Error(`Patient profile not found for patient ${patientId}`);
+      }
+
+      // Get current dismissed recommendations
+      const dismissedRecommendations =
+        patientProfile.dismissedNextStepsRecommendations || [];
+
+      // Check if already dismissed
+      if (dismissedRecommendations.includes(recommendationId)) {
+        console.log(
+          `[APPOINTMENT_SERVICE] Recommendation ${recommendationId} already dismissed`,
+        );
+        return;
+      }
+
+      // Add to dismissed list
+      const updatedDismissed = [...dismissedRecommendations, recommendationId];
+
+      // Update patient profile
+      await this.patientService.updatePatientProfile(patientId, {
+        dismissedNextStepsRecommendations: updatedDismissed,
+      });
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Successfully dismissed recommendation ${recommendationId} for patient ${patientId}`,
+      );
+    } catch (error) {
+      console.error(
+        `[APPOINTMENT_SERVICE] Error dismissing recommendation for patient ${patientId}:`,
+        error,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Undismisses a next steps recommendation for a patient.
+   * This makes the recommendation visible again in the default view.
+   *
+   * @param patientId ID of the patient
+   * @param recommendationId ID of the recommendation to undismiss (format: appointmentId:recommendationIndex)
+   * @returns Updated patient profile
+   */
+  async undismissNextStepsRecommendation(
+    patientId: string,
+    recommendationId: string,
+  ): Promise<void> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Undismissing recommendation ${recommendationId} for patient ${patientId}`,
+      );
+
+      // Get patient profile
+      const patientProfile = await this.patientService.getPatientProfile(patientId);
+      if (!patientProfile) {
+        throw new Error(`Patient profile not found for patient ${patientId}`);
+      }
+
+      // Get current dismissed recommendations
+      const dismissedRecommendations =
+        patientProfile.dismissedNextStepsRecommendations || [];
+
+      // Check if not dismissed
+      if (!dismissedRecommendations.includes(recommendationId)) {
+        console.log(
+          `[APPOINTMENT_SERVICE] Recommendation ${recommendationId} is not dismissed`,
+        );
+        return;
+      }
+
+      // Remove from dismissed list
+      const updatedDismissed = dismissedRecommendations.filter(
+        id => id !== recommendationId,
+      );
+
+      // Update patient profile
+      await this.patientService.updatePatientProfile(patientId, {
+        dismissedNextStepsRecommendations: updatedDismissed,
+      });
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Successfully undismissed recommendation ${recommendationId} for patient ${patientId}`,
+      );
+    } catch (error) {
+      console.error(
+        `[APPOINTMENT_SERVICE] Error undismissing recommendation for patient ${patientId}:`,
+        error,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Gets next steps recommendations for a clinic.
+   * Returns all recommendations from appointments at the specified clinic.
+   * This is useful for clinic admins to see what treatments have been recommended to their patients.
+   *
+   * @param clinicBranchId ID of the clinic branch
+   * @param options Optional parameters for filtering
+   * @returns Array of next steps recommendations with context
+   */
+  async getClinicNextStepsRecommendations(
+    clinicBranchId: string,
+    options?: {
+      /** Filter by patient ID */
+      patientId?: string;
+      /** Filter by practitioner ID */
+      practitionerId?: string;
+      /** Limit the number of results */
+      limit?: number;
+    },
+  ): Promise<NextStepsRecommendation[]> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Getting next steps recommendations for clinic: ${clinicBranchId}`,
+        options,
+      );
+
+      // Get past appointments for the clinic
+      const searchParams: SearchAppointmentsParams = {
+        clinicBranchId,
+        patientId: options?.patientId,
+        practitionerId: options?.practitionerId,
+        status: AppointmentStatus.COMPLETED,
+      };
+
+      const { appointments } = await this.searchAppointments(searchParams);
+
+      const recommendations: NextStepsRecommendation[] = [];
+
+      // Iterate through appointments and extract recommendations
+      for (const appointment of appointments) {
+        // Get recommended procedures from appointment metadata
+        const recommendedProcedures =
+          appointment.metadata?.recommendedProcedures || [];
+
+        // Create NextStepsRecommendation for each recommended procedure
+        for (let index = 0; index < recommendedProcedures.length; index++) {
+          const recommendedProcedure = recommendedProcedures[index];
+          const recommendationId = `${appointment.id}:${index}`;
+
+          const nextStepsRecommendation: NextStepsRecommendation = {
+            id: recommendationId,
+            recommendedProcedure,
+            appointmentId: appointment.id,
+            appointmentDate: appointment.appointmentStartTime,
+            practitionerId: appointment.practitionerId,
+            practitionerName: appointment.practitionerInfo?.name || 'Unknown Practitioner',
+            clinicBranchId: appointment.clinicBranchId,
+            clinicName: appointment.clinicInfo?.name || 'Unknown Clinic',
+            appointmentStatus: appointment.status,
+            isDismissed: false, // Clinic view doesn't track dismissals
+            dismissedAt: null,
+          };
+
+          recommendations.push(nextStepsRecommendation);
+        }
+      }
+
+      // Sort by appointment date (most recent first)
+      recommendations.sort((a, b) => {
+        const dateA = a.appointmentDate.toMillis();
+        const dateB = b.appointmentDate.toMillis();
+        return dateB - dateA;
+      });
+
+      // Apply limit if specified
+      const limitedRecommendations = options?.limit
+        ? recommendations.slice(0, options.limit)
+        : recommendations;
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Found ${limitedRecommendations.length} next steps recommendations for clinic ${clinicBranchId}`,
+      );
+
+      return limitedRecommendations;
+    } catch (error) {
+      console.error(
+        `[APPOINTMENT_SERVICE] Error getting next steps recommendations for clinic ${clinicBranchId}:`,
+        error,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Gets next steps recommendations from a specific appointment.
+   * This is useful when viewing an appointment detail page in the clinic app
+   * to see what procedures were recommended during that appointment.
+   *
+   * @param appointmentId ID of the appointment
+   * @param options Optional parameters for filtering
+   * @returns Array of next steps recommendations from that appointment
+   */
+  async getAppointmentNextStepsRecommendations(
+    appointmentId: string,
+    options?: {
+      /** Filter by clinic branch ID - only show recommendations for procedures available at this clinic */
+      clinicBranchId?: string;
+    },
+  ): Promise<NextStepsRecommendation[]> {
+    try {
+      console.log(
+        `[APPOINTMENT_SERVICE] Getting next steps recommendations for appointment: ${appointmentId}`,
+        options,
+      );
+
+      // Get the appointment
+      const appointment = await this.getAppointmentById(appointmentId);
+      if (!appointment) {
+        throw new Error(`Appointment with ID ${appointmentId} not found`);
+      }
+
+      // Get recommended procedures from appointment metadata
+      const recommendedProcedures =
+        appointment.metadata?.recommendedProcedures || [];
+
+      const recommendations: NextStepsRecommendation[] = [];
+
+      // If clinicBranchId is provided, we need to check which procedures are available at that clinic
+      let availableProcedureIds: Set<string> | null = null;
+      if (options?.clinicBranchId) {
+        // Query procedures collection to get all procedure IDs available at this clinic
+        const proceduresQuery = query(
+          collection(this.db, PROCEDURES_COLLECTION),
+          where('clinicBranchId', '==', options.clinicBranchId),
+          where('isActive', '==', true),
+        );
+        const proceduresSnapshot = await getDocs(proceduresQuery);
+        availableProcedureIds = new Set(
+          proceduresSnapshot.docs.map(doc => doc.id),
+        );
+        console.log(
+          `[APPOINTMENT_SERVICE] Found ${availableProcedureIds.size} procedures available at clinic ${options.clinicBranchId}`,
+        );
+      }
+
+      // Create NextStepsRecommendation for each recommended procedure
+      for (let index = 0; index < recommendedProcedures.length; index++) {
+        const recommendedProcedure = recommendedProcedures[index];
+        const procedureId = recommendedProcedure.procedure.procedureId;
+
+        // If clinicBranchId is provided, filter to only include procedures available at that clinic
+        if (options?.clinicBranchId && availableProcedureIds) {
+          if (!availableProcedureIds.has(procedureId)) {
+            console.log(
+              `[APPOINTMENT_SERVICE] Skipping recommendation for procedure ${procedureId} - not available at clinic ${options.clinicBranchId}`,
+            );
+            continue;
+          }
+        }
+
+        const recommendationId = `${appointment.id}:${index}`;
+
+        const nextStepsRecommendation: NextStepsRecommendation = {
+          id: recommendationId,
+          recommendedProcedure,
+          appointmentId: appointment.id,
+          appointmentDate: appointment.appointmentStartTime,
+          practitionerId: appointment.practitionerId,
+          practitionerName: appointment.practitionerInfo?.name || 'Unknown Practitioner',
+          clinicBranchId: appointment.clinicBranchId,
+          clinicName: appointment.clinicInfo?.name || 'Unknown Clinic',
+          appointmentStatus: appointment.status,
+          isDismissed: false, // Clinic view doesn't track dismissals
+          dismissedAt: null,
+        };
+
+        recommendations.push(nextStepsRecommendation);
+      }
+
+      console.log(
+        `[APPOINTMENT_SERVICE] Found ${recommendations.length} next steps recommendations for appointment ${appointmentId}`,
+        options?.clinicBranchId
+          ? `(filtered to procedures available at clinic ${options.clinicBranchId})`
+          : '',
+      );
+
+      return recommendations;
+    } catch (error) {
+      console.error(
+        `[APPOINTMENT_SERVICE] Error getting next steps recommendations for appointment ${appointmentId}:`,
+        error,
+      );
+      throw error;
+    }
+  }
+}