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

package/src/services/appointment/utils/zone-management.utils.ts

@@ -1,468 +1,468 @@
-import { Firestore, getDoc, updateDoc, serverTimestamp } from 'firebase/firestore';
-import {
-  ZoneItemData,
-  AppointmentMetadata,
-  FinalBilling,
-  Appointment,
-  APPOINTMENTS_COLLECTION,
-} from '../../../types/appointment';
-import { getAppointmentByIdUtil } from './appointment.utils';
-import { doc } from 'firebase/firestore';
-
-/**
- * Swiss 5-centime rounding (nearest 0.05 CHF)
- * @param value Amount to round
- * @returns Rounded amount
- */
-export function swissRound(value: number): number {
-  return Math.round(value / 0.05) * 0.05;
-}
-
-/**
- * Validates that a zone key follows the category.zone format
- * @param zoneKey Zone key to validate
- * @throws Error if format is invalid
- */
-export function validateZoneKeyFormat(zoneKey: string): void {
-  const parts = zoneKey.split('.');
-  if (parts.length !== 2) {
-    throw new Error(
-      `Invalid zone key format: "${zoneKey}". Must be "category.zone" (e.g., "face.forehead")`,
-    );
-  }
-}
-
-/**
- * Calculates subtotal for a zone item
- * @param item Zone item data
- * @returns Calculated subtotal
- */
-export function calculateItemSubtotal(item: Partial<ZoneItemData>): number {
-  if (item.type === 'note') {
-    return 0;
-  }
-
-  const quantity = item.quantity || 0;
-
-  // If price override amount is set, use it as price per unit
-  if (item.priceOverrideAmount !== undefined && item.priceOverrideAmount !== null) {
-    return item.priceOverrideAmount * quantity;
-  }
-
-  // Calculate normally: price * quantity
-  const price = item.price || 0;
-  return price * quantity;
-}
-
-/**
- * Recalculates final billing based on all zone items
- * @param zonesData Zone items data
- * @param taxRate Tax rate (e.g., 0.20 for 20%)
- * @param discount Optional overall discount to apply
- * @returns Calculated final billing
- */
-export function calculateFinalBilling(
-  zonesData: Record<string, ZoneItemData[]>,
-  taxRate: number = 0.081,
-  discount?: { type: 'percentage' | 'fixed'; value: number } | null,
-): FinalBilling {
-  let subtotalAll = 0;
-
-  // Sum up all zone items
-  Object.values(zonesData).forEach(items => {
-    items.forEach(item => {
-      if (item.type === 'item' && item.subtotal) {
-        subtotalAll += item.subtotal;
-      }
-    });
-  });
-
-  // Get currency from first item (assuming all same currency)
-  let currency: any = 'CHF'; // Default
-
-  for (const items of Object.values(zonesData)) {
-    const firstItem = items.find(i => i.type === 'item');
-    if (firstItem) {
-      currency = firstItem.currency || currency;
-      break;
-    }
-  }
-
-  // Apply overall discount if provided
-  if (discount && discount.value > 0) {
-    let discountAmount: number;
-    if (discount.type === 'percentage') {
-      discountAmount = subtotalAll * (discount.value / 100);
-    } else {
-      discountAmount = discount.value;
-    }
-    // Cap discount at subtotal (can't go negative)
-    discountAmount = Math.min(discountAmount, subtotalAll);
-
-    const discountedSubtotal = subtotalAll - discountAmount;
-    const taxPrice = discountedSubtotal * taxRate;
-    const finalPrice = swissRound(discountedSubtotal + taxPrice);
-
-    return {
-      subtotalAll,
-      discount: {
-        type: discount.type,
-        value: discount.value,
-        amount: discountAmount,
-      },
-      discountedSubtotal,
-      taxRate,
-      taxPrice,
-      finalPrice,
-      currency,
-    };
-  }
-
-  const taxPrice = subtotalAll * taxRate;
-  const finalPrice = swissRound(subtotalAll + taxPrice);
-
-  return {
-    subtotalAll,
-    taxRate,
-    taxPrice,
-    finalPrice,
-    currency,
-  };
-}
-
-/**
- * Gets appointment and validates it exists
- * @param db Firestore instance
- * @param appointmentId Appointment ID
- * @returns Appointment document
- */
-export async function getAppointmentOrThrow(
-  db: Firestore,
-  appointmentId: string,
-): Promise<Appointment> {
-  const appointment = await getAppointmentByIdUtil(db, appointmentId);
-  if (!appointment) {
-    throw new Error(`Appointment with ID ${appointmentId} not found`);
-  }
-  return appointment;
-}
-
-/**
- * Initializes appointment metadata if it doesn't exist
- * @param appointment Appointment document
- * @returns Initialized metadata
- */
-export function initializeMetadata(appointment: Appointment): AppointmentMetadata {
-  return (
-    appointment.metadata || {
-      selectedZones: null,
-      zonePhotos: null,
-      zonesData: null,
-      appointmentProducts: [],
-      extendedProcedures: [],
-      recommendedProcedures: [],
-      finalbilling: null,
-      finalizationNotesShared: null,
-      finalizationNotesInternal: null,
-      finalizationNotes: null, // @deprecated - kept for backward compatibility
-    }
-  );
-}
-
-/**
- * Adds an item to a specific zone
- * @param db Firestore instance
- * @param appointmentId Appointment ID
- * @param zoneId Zone ID (must be category.zone format)
- * @param item Zone item data to add (without parentZone)
- * @returns Updated appointment
- */
-export async function addItemToZoneUtil(
-  db: Firestore,
-  appointmentId: string,
-  zoneId: string,
-  item: Omit<ZoneItemData, 'subtotal' | 'parentZone'>,
-): Promise<Appointment> {
-  // Validate zone key format
-  validateZoneKeyFormat(zoneId);
-
-  // Get appointment
-  const appointment = await getAppointmentOrThrow(db, appointmentId);
-  const metadata = initializeMetadata(appointment);
-
-  // Initialize zonesData if needed
-  const zonesData = metadata.zonesData || {};
-
-  // Initialize zone array if needed
-  if (!zonesData[zoneId]) {
-    zonesData[zoneId] = [];
-  }
-
-  // Calculate subtotal for the item
-  const now = new Date().toISOString();
-  
-  // Filter out undefined values from item (Firestore doesn't allow undefined)
-  const cleanItem = Object.fromEntries(
-    Object.entries(item).filter(([_, value]) => value !== undefined)
-  ) as Omit<ZoneItemData, 'subtotal' | 'parentZone'>;
-  
-  // Determine notesVisibleToPatient value (privacy-first: default to false if notes exist, otherwise omit)
-  const notesVisibleToPatientValue = cleanItem.notesVisibleToPatient !== undefined
-    ? cleanItem.notesVisibleToPatient
-    : (cleanItem.notes ? false : undefined);
-  
-  const itemWithSubtotal: ZoneItemData = {
-    ...cleanItem,
-    parentZone: zoneId, // Set parentZone to the zone key
-    subtotal: calculateItemSubtotal(cleanItem),
-    createdAt: now,
-    updatedAt: now,
-    // Only include notesVisibleToPatient if it has a defined boolean value
-    ...(typeof notesVisibleToPatientValue === 'boolean' && { notesVisibleToPatient: notesVisibleToPatientValue }),
-  };
-
-  // Add item to zone
-  zonesData[zoneId].push(itemWithSubtotal);
-
-  // Recalculate final billing with Swiss tax rate (8.1%), preserving existing discount
-  const existingDiscount = metadata.finalbilling?.discount;
-  const discountParam = existingDiscount
-    ? { type: existingDiscount.type, value: existingDiscount.value }
-    : undefined;
-  const finalbilling = calculateFinalBilling(zonesData, 0.081, discountParam);
-
-  // Update appointment
-  const appointmentRef = doc(db, APPOINTMENTS_COLLECTION, appointmentId);
-  await updateDoc(appointmentRef, {
-    'metadata.zonesData': zonesData,
-    'metadata.finalbilling': finalbilling,
-    updatedAt: serverTimestamp(),
-  });
-
-  // Return updated appointment
-  return getAppointmentOrThrow(db, appointmentId);
-}
-
-/**
- * Removes an item from a specific zone
- * @param db Firestore instance
- * @param appointmentId Appointment ID
- * @param zoneId Zone ID
- * @param itemIndex Index of item to remove
- * @returns Updated appointment
- */
-export async function removeItemFromZoneUtil(
-  db: Firestore,
-  appointmentId: string,
-  zoneId: string,
-  itemIndex: number,
-): Promise<Appointment> {
-  validateZoneKeyFormat(zoneId);
-
-  const appointment = await getAppointmentOrThrow(db, appointmentId);
-  const metadata = initializeMetadata(appointment);
-
-  if (!metadata.zonesData || !metadata.zonesData[zoneId]) {
-    throw new Error(`No items found for zone ${zoneId}`);
-  }
-
-  const items = metadata.zonesData[zoneId];
-  if (itemIndex < 0 || itemIndex >= items.length) {
-    throw new Error(`Invalid item index ${itemIndex} for zone ${zoneId}`);
-  }
-
-  // Remove item
-  items.splice(itemIndex, 1);
-
-  // If zone is now empty, remove it
-  if (items.length === 0) {
-    delete metadata.zonesData[zoneId];
-  }
-
-  // Recalculate final billing with Swiss tax rate (8.1%), preserving existing discount
-  const existingDiscount = metadata.finalbilling?.discount;
-  const discountParam = existingDiscount
-    ? { type: existingDiscount.type, value: existingDiscount.value }
-    : undefined;
-  const finalbilling = calculateFinalBilling(metadata.zonesData, 0.081, discountParam);
-
-  // Update appointment
-  const appointmentRef = doc(db, APPOINTMENTS_COLLECTION, appointmentId);
-  await updateDoc(appointmentRef, {
-    'metadata.zonesData': metadata.zonesData,
-    'metadata.finalbilling': finalbilling,
-    updatedAt: serverTimestamp(),
-  });
-
-  return getAppointmentOrThrow(db, appointmentId);
-}
-
-/**
- * Updates a specific item in a zone
- * @param db Firestore instance
- * @param appointmentId Appointment ID
- * @param zoneId Zone ID
- * @param itemIndex Index of item to update
- * @param updates Partial updates to apply
- * @returns Updated appointment
- */
-export async function updateZoneItemUtil(
-  db: Firestore,
-  appointmentId: string,
-  zoneId: string,
-  itemIndex: number,
-  updates: Partial<ZoneItemData>,
-): Promise<Appointment> {
-  validateZoneKeyFormat(zoneId);
-
-  const appointment = await getAppointmentOrThrow(db, appointmentId);
-  const metadata = initializeMetadata(appointment);
-
-  if (!metadata.zonesData || !metadata.zonesData[zoneId]) {
-    throw new Error(`No items found for zone ${zoneId}`);
-  }
-
-  const items = metadata.zonesData[zoneId];
-  if (itemIndex < 0 || itemIndex >= items.length) {
-    throw new Error(`Invalid item index ${itemIndex} for zone ${zoneId}`);
-  }
-
-  // Filter out undefined values from updates (Firestore doesn't store undefined)
-  // Keep null values as they're used to explicitly delete/clear fields
-  // Convert empty strings to null for consistency
-  const cleanUpdates = Object.fromEntries(
-    Object.entries(updates)
-      .filter(([_, value]) => value !== undefined)
-      .map(([key, value]) => [
-        key,
-        value === '' ? null : value, // Convert empty strings to null
-      ])
-  ) as Partial<ZoneItemData>;
-
-  console.log(`[updateZoneItemUtil] Updates received:`, {
-    itemIndex,
-    zoneId,
-    rawUpdates: updates,
-    cleanUpdates,
-    hasIonNumber: 'ionNumber' in cleanUpdates,
-    hasExpiryDate: 'expiryDate' in cleanUpdates,
-    ionNumberValue: cleanUpdates.ionNumber,
-    expiryDateValue: cleanUpdates.expiryDate,
-  });
-
-  // Update item with updatedAt timestamp
-  items[itemIndex] = {
-    ...items[itemIndex],
-    ...cleanUpdates,
-    updatedAt: new Date().toISOString(),
-  };
-
-  console.log(`[updateZoneItemUtil] Item after update:`, {
-    itemIndex,
-    ionNumber: items[itemIndex].ionNumber,
-    expiryDate: items[itemIndex].expiryDate,
-    quantity: items[itemIndex].quantity,
-    priceOverrideAmount: items[itemIndex].priceOverrideAmount,
-    price: items[itemIndex].price,
-    oldSubtotal: items[itemIndex].subtotal,
-    allItemKeys: Object.keys(items[itemIndex]),
-  });
-
-  // Recalculate subtotal for this item
-  items[itemIndex].subtotal = calculateItemSubtotal(items[itemIndex]);
-
-  console.log(`[updateZoneItemUtil] AFTER recalculation:`, {
-    itemIndex,
-    newSubtotal: items[itemIndex].subtotal,
-  });
-
-  // Recalculate final billing with Swiss tax rate (8.1%), preserving existing discount
-  const existingDiscount = metadata.finalbilling?.discount;
-  const discountParam = existingDiscount
-    ? { type: existingDiscount.type, value: existingDiscount.value }
-    : undefined;
-  const finalbilling = calculateFinalBilling(metadata.zonesData, 0.081, discountParam);
-
-  // Log what we're about to save to Firestore
-  console.log(`[updateZoneItemUtil] Saving to Firestore:`, {
-    appointmentId,
-    zoneId,
-    itemIndex,
-    itemToSave: items[itemIndex],
-    itemIonNumber: items[itemIndex].ionNumber,
-    itemExpiryDate: items[itemIndex].expiryDate,
-    zonesDataKeys: Object.keys(metadata.zonesData),
-    zoneItemsCount: metadata.zonesData[zoneId]?.length,
-  });
-
-  // Update appointment
-  const appointmentRef = doc(db, APPOINTMENTS_COLLECTION, appointmentId);
-  await updateDoc(appointmentRef, {
-    'metadata.zonesData': metadata.zonesData,
-    'metadata.finalbilling': finalbilling,
-    updatedAt: serverTimestamp(),
-  });
-
-  // Verify what was actually saved
-  const savedAppointment = await getAppointmentOrThrow(db, appointmentId);
-  const savedItem = savedAppointment.metadata?.zonesData?.[zoneId]?.[itemIndex];
-  console.log(`[updateZoneItemUtil] Verification after save:`, {
-    savedItemIonNumber: savedItem?.ionNumber,
-    savedItemExpiryDate: savedItem?.expiryDate,
-    savedItemKeys: savedItem ? Object.keys(savedItem) : [],
-  });
-
-  return savedAppointment;
-}
-
-/**
- * Overrides price for a specific zone item
- * @param db Firestore instance
- * @param appointmentId Appointment ID
- * @param zoneId Zone ID
- * @param itemIndex Index of item
- * @param newPrice New price amount
- * @returns Updated appointment
- */
-export async function overridePriceForZoneItemUtil(
-  db: Firestore,
-  appointmentId: string,
-  zoneId: string,
-  itemIndex: number,
-  newPrice: number,
-): Promise<Appointment> {
-  return updateZoneItemUtil(db, appointmentId, zoneId, itemIndex, {
-    priceOverrideAmount: newPrice,
-  });
-}
-
-/**
- * Updates subzones for a specific zone item
- * @param db Firestore instance
- * @param appointmentId Appointment ID
- * @param zoneId Zone ID
- * @param itemIndex Index of item
- * @param subzones Array of subzone keys (empty array = entire zone)
- * @returns Updated appointment
- */
-export async function updateSubzonesUtil(
-  db: Firestore,
-  appointmentId: string,
-  zoneId: string,
-  itemIndex: number,
-  subzones: string[],
-): Promise<Appointment> {
-  // Validate subzone format if provided
-  subzones.forEach(subzone => {
-    const parts = subzone.split('.');
-    if (parts.length !== 3) {
-      throw new Error(
-        `Invalid subzone format: "${subzone}". Must be "category.zone.subzone" (e.g., "face.forehead.left")`,
-      );
-    }
-  });
-
-  return updateZoneItemUtil(db, appointmentId, zoneId, itemIndex, {
-    subzones,
-  });
-}
+import { Firestore, getDoc, updateDoc, serverTimestamp } from 'firebase/firestore';
+import {
+  ZoneItemData,
+  AppointmentMetadata,
+  FinalBilling,
+  Appointment,
+  APPOINTMENTS_COLLECTION,
+} from '../../../types/appointment';
+import { getAppointmentByIdUtil } from './appointment.utils';
+import { doc } from 'firebase/firestore';
+
+/**
+ * Swiss 5-centime rounding (nearest 0.05 CHF)
+ * @param value Amount to round
+ * @returns Rounded amount
+ */
+export function swissRound(value: number): number {
+  return Math.round(value / 0.05) * 0.05;
+}
+
+/**
+ * Validates that a zone key follows the category.zone format
+ * @param zoneKey Zone key to validate
+ * @throws Error if format is invalid
+ */
+export function validateZoneKeyFormat(zoneKey: string): void {
+  const parts = zoneKey.split('.');
+  if (parts.length !== 2) {
+    throw new Error(
+      `Invalid zone key format: "${zoneKey}". Must be "category.zone" (e.g., "face.forehead")`,
+    );
+  }
+}
+
+/**
+ * Calculates subtotal for a zone item
+ * @param item Zone item data
+ * @returns Calculated subtotal
+ */
+export function calculateItemSubtotal(item: Partial<ZoneItemData>): number {
+  if (item.type === 'note') {
+    return 0;
+  }
+
+  const quantity = item.quantity || 0;
+
+  // If price override amount is set, use it as price per unit
+  if (item.priceOverrideAmount !== undefined && item.priceOverrideAmount !== null) {
+    return item.priceOverrideAmount * quantity;
+  }
+
+  // Calculate normally: price * quantity
+  const price = item.price || 0;
+  return price * quantity;
+}
+
+/**
+ * Recalculates final billing based on all zone items
+ * @param zonesData Zone items data
+ * @param taxRate Tax rate (e.g., 0.20 for 20%)
+ * @param discount Optional overall discount to apply
+ * @returns Calculated final billing
+ */
+export function calculateFinalBilling(
+  zonesData: Record<string, ZoneItemData[]>,
+  taxRate: number = 0.081,
+  discount?: { type: 'percentage' | 'fixed'; value: number } | null,
+): FinalBilling {
+  let subtotalAll = 0;
+
+  // Sum up all zone items
+  Object.values(zonesData).forEach(items => {
+    items.forEach(item => {
+      if (item.type === 'item' && item.subtotal) {
+        subtotalAll += item.subtotal;
+      }
+    });
+  });
+
+  // Get currency from first item (assuming all same currency)
+  let currency: any = 'CHF'; // Default
+
+  for (const items of Object.values(zonesData)) {
+    const firstItem = items.find(i => i.type === 'item');
+    if (firstItem) {
+      currency = firstItem.currency || currency;
+      break;
+    }
+  }
+
+  // Apply overall discount if provided
+  if (discount && discount.value > 0) {
+    let discountAmount: number;
+    if (discount.type === 'percentage') {
+      discountAmount = subtotalAll * (discount.value / 100);
+    } else {
+      discountAmount = discount.value;
+    }
+    // Cap discount at subtotal (can't go negative)
+    discountAmount = Math.min(discountAmount, subtotalAll);
+
+    const discountedSubtotal = subtotalAll - discountAmount;
+    const taxPrice = discountedSubtotal * taxRate;
+    const finalPrice = swissRound(discountedSubtotal + taxPrice);
+
+    return {
+      subtotalAll,
+      discount: {
+        type: discount.type,
+        value: discount.value,
+        amount: discountAmount,
+      },
+      discountedSubtotal,
+      taxRate,
+      taxPrice,
+      finalPrice,
+      currency,
+    };
+  }
+
+  const taxPrice = subtotalAll * taxRate;
+  const finalPrice = swissRound(subtotalAll + taxPrice);
+
+  return {
+    subtotalAll,
+    taxRate,
+    taxPrice,
+    finalPrice,
+    currency,
+  };
+}
+
+/**
+ * Gets appointment and validates it exists
+ * @param db Firestore instance
+ * @param appointmentId Appointment ID
+ * @returns Appointment document
+ */
+export async function getAppointmentOrThrow(
+  db: Firestore,
+  appointmentId: string,
+): Promise<Appointment> {
+  const appointment = await getAppointmentByIdUtil(db, appointmentId);
+  if (!appointment) {
+    throw new Error(`Appointment with ID ${appointmentId} not found`);
+  }
+  return appointment;
+}
+
+/**
+ * Initializes appointment metadata if it doesn't exist
+ * @param appointment Appointment document
+ * @returns Initialized metadata
+ */
+export function initializeMetadata(appointment: Appointment): AppointmentMetadata {
+  return (
+    appointment.metadata || {
+      selectedZones: null,
+      zonePhotos: null,
+      zonesData: null,
+      appointmentProducts: [],
+      extendedProcedures: [],
+      recommendedProcedures: [],
+      finalbilling: null,
+      finalizationNotesShared: null,
+      finalizationNotesInternal: null,
+      finalizationNotes: null, // @deprecated - kept for backward compatibility
+    }
+  );
+}
+
+/**
+ * Adds an item to a specific zone
+ * @param db Firestore instance
+ * @param appointmentId Appointment ID
+ * @param zoneId Zone ID (must be category.zone format)
+ * @param item Zone item data to add (without parentZone)
+ * @returns Updated appointment
+ */
+export async function addItemToZoneUtil(
+  db: Firestore,
+  appointmentId: string,
+  zoneId: string,
+  item: Omit<ZoneItemData, 'subtotal' | 'parentZone'>,
+): Promise<Appointment> {
+  // Validate zone key format
+  validateZoneKeyFormat(zoneId);
+
+  // Get appointment
+  const appointment = await getAppointmentOrThrow(db, appointmentId);
+  const metadata = initializeMetadata(appointment);
+
+  // Initialize zonesData if needed
+  const zonesData = metadata.zonesData || {};
+
+  // Initialize zone array if needed
+  if (!zonesData[zoneId]) {
+    zonesData[zoneId] = [];
+  }
+
+  // Calculate subtotal for the item
+  const now = new Date().toISOString();
+  
+  // Filter out undefined values from item (Firestore doesn't allow undefined)
+  const cleanItem = Object.fromEntries(
+    Object.entries(item).filter(([_, value]) => value !== undefined)
+  ) as Omit<ZoneItemData, 'subtotal' | 'parentZone'>;
+  
+  // Determine notesVisibleToPatient value (privacy-first: default to false if notes exist, otherwise omit)
+  const notesVisibleToPatientValue = cleanItem.notesVisibleToPatient !== undefined
+    ? cleanItem.notesVisibleToPatient
+    : (cleanItem.notes ? false : undefined);
+  
+  const itemWithSubtotal: ZoneItemData = {
+    ...cleanItem,
+    parentZone: zoneId, // Set parentZone to the zone key
+    subtotal: calculateItemSubtotal(cleanItem),
+    createdAt: now,
+    updatedAt: now,
+    // Only include notesVisibleToPatient if it has a defined boolean value
+    ...(typeof notesVisibleToPatientValue === 'boolean' && { notesVisibleToPatient: notesVisibleToPatientValue }),
+  };
+
+  // Add item to zone
+  zonesData[zoneId].push(itemWithSubtotal);
+
+  // Recalculate final billing with Swiss tax rate (8.1%), preserving existing discount
+  const existingDiscount = metadata.finalbilling?.discount;
+  const discountParam = existingDiscount
+    ? { type: existingDiscount.type, value: existingDiscount.value }
+    : undefined;
+  const finalbilling = calculateFinalBilling(zonesData, 0.081, discountParam);
+
+  // Update appointment
+  const appointmentRef = doc(db, APPOINTMENTS_COLLECTION, appointmentId);
+  await updateDoc(appointmentRef, {
+    'metadata.zonesData': zonesData,
+    'metadata.finalbilling': finalbilling,
+    updatedAt: serverTimestamp(),
+  });
+
+  // Return updated appointment
+  return getAppointmentOrThrow(db, appointmentId);
+}
+
+/**
+ * Removes an item from a specific zone
+ * @param db Firestore instance
+ * @param appointmentId Appointment ID
+ * @param zoneId Zone ID
+ * @param itemIndex Index of item to remove
+ * @returns Updated appointment
+ */
+export async function removeItemFromZoneUtil(
+  db: Firestore,
+  appointmentId: string,
+  zoneId: string,
+  itemIndex: number,
+): Promise<Appointment> {
+  validateZoneKeyFormat(zoneId);
+
+  const appointment = await getAppointmentOrThrow(db, appointmentId);
+  const metadata = initializeMetadata(appointment);
+
+  if (!metadata.zonesData || !metadata.zonesData[zoneId]) {
+    throw new Error(`No items found for zone ${zoneId}`);
+  }
+
+  const items = metadata.zonesData[zoneId];
+  if (itemIndex < 0 || itemIndex >= items.length) {
+    throw new Error(`Invalid item index ${itemIndex} for zone ${zoneId}`);
+  }
+
+  // Remove item
+  items.splice(itemIndex, 1);
+
+  // If zone is now empty, remove it
+  if (items.length === 0) {
+    delete metadata.zonesData[zoneId];
+  }
+
+  // Recalculate final billing with Swiss tax rate (8.1%), preserving existing discount
+  const existingDiscount = metadata.finalbilling?.discount;
+  const discountParam = existingDiscount
+    ? { type: existingDiscount.type, value: existingDiscount.value }
+    : undefined;
+  const finalbilling = calculateFinalBilling(metadata.zonesData, 0.081, discountParam);
+
+  // Update appointment
+  const appointmentRef = doc(db, APPOINTMENTS_COLLECTION, appointmentId);
+  await updateDoc(appointmentRef, {
+    'metadata.zonesData': metadata.zonesData,
+    'metadata.finalbilling': finalbilling,
+    updatedAt: serverTimestamp(),
+  });
+
+  return getAppointmentOrThrow(db, appointmentId);
+}
+
+/**
+ * Updates a specific item in a zone
+ * @param db Firestore instance
+ * @param appointmentId Appointment ID
+ * @param zoneId Zone ID
+ * @param itemIndex Index of item to update
+ * @param updates Partial updates to apply
+ * @returns Updated appointment
+ */
+export async function updateZoneItemUtil(
+  db: Firestore,
+  appointmentId: string,
+  zoneId: string,
+  itemIndex: number,
+  updates: Partial<ZoneItemData>,
+): Promise<Appointment> {
+  validateZoneKeyFormat(zoneId);
+
+  const appointment = await getAppointmentOrThrow(db, appointmentId);
+  const metadata = initializeMetadata(appointment);
+
+  if (!metadata.zonesData || !metadata.zonesData[zoneId]) {
+    throw new Error(`No items found for zone ${zoneId}`);
+  }
+
+  const items = metadata.zonesData[zoneId];
+  if (itemIndex < 0 || itemIndex >= items.length) {
+    throw new Error(`Invalid item index ${itemIndex} for zone ${zoneId}`);
+  }
+
+  // Filter out undefined values from updates (Firestore doesn't store undefined)
+  // Keep null values as they're used to explicitly delete/clear fields
+  // Convert empty strings to null for consistency
+  const cleanUpdates = Object.fromEntries(
+    Object.entries(updates)
+      .filter(([_, value]) => value !== undefined)
+      .map(([key, value]) => [
+        key,
+        value === '' ? null : value, // Convert empty strings to null
+      ])
+  ) as Partial<ZoneItemData>;
+
+  console.log(`[updateZoneItemUtil] Updates received:`, {
+    itemIndex,
+    zoneId,
+    rawUpdates: updates,
+    cleanUpdates,
+    hasIonNumber: 'ionNumber' in cleanUpdates,
+    hasExpiryDate: 'expiryDate' in cleanUpdates,
+    ionNumberValue: cleanUpdates.ionNumber,
+    expiryDateValue: cleanUpdates.expiryDate,
+  });
+
+  // Update item with updatedAt timestamp
+  items[itemIndex] = {
+    ...items[itemIndex],
+    ...cleanUpdates,
+    updatedAt: new Date().toISOString(),
+  };
+
+  console.log(`[updateZoneItemUtil] Item after update:`, {
+    itemIndex,
+    ionNumber: items[itemIndex].ionNumber,
+    expiryDate: items[itemIndex].expiryDate,
+    quantity: items[itemIndex].quantity,
+    priceOverrideAmount: items[itemIndex].priceOverrideAmount,
+    price: items[itemIndex].price,
+    oldSubtotal: items[itemIndex].subtotal,
+    allItemKeys: Object.keys(items[itemIndex]),
+  });
+
+  // Recalculate subtotal for this item
+  items[itemIndex].subtotal = calculateItemSubtotal(items[itemIndex]);
+
+  console.log(`[updateZoneItemUtil] AFTER recalculation:`, {
+    itemIndex,
+    newSubtotal: items[itemIndex].subtotal,
+  });
+
+  // Recalculate final billing with Swiss tax rate (8.1%), preserving existing discount
+  const existingDiscount = metadata.finalbilling?.discount;
+  const discountParam = existingDiscount
+    ? { type: existingDiscount.type, value: existingDiscount.value }
+    : undefined;
+  const finalbilling = calculateFinalBilling(metadata.zonesData, 0.081, discountParam);
+
+  // Log what we're about to save to Firestore
+  console.log(`[updateZoneItemUtil] Saving to Firestore:`, {
+    appointmentId,
+    zoneId,
+    itemIndex,
+    itemToSave: items[itemIndex],
+    itemIonNumber: items[itemIndex].ionNumber,
+    itemExpiryDate: items[itemIndex].expiryDate,
+    zonesDataKeys: Object.keys(metadata.zonesData),
+    zoneItemsCount: metadata.zonesData[zoneId]?.length,
+  });
+
+  // Update appointment
+  const appointmentRef = doc(db, APPOINTMENTS_COLLECTION, appointmentId);
+  await updateDoc(appointmentRef, {
+    'metadata.zonesData': metadata.zonesData,
+    'metadata.finalbilling': finalbilling,
+    updatedAt: serverTimestamp(),
+  });
+
+  // Verify what was actually saved
+  const savedAppointment = await getAppointmentOrThrow(db, appointmentId);
+  const savedItem = savedAppointment.metadata?.zonesData?.[zoneId]?.[itemIndex];
+  console.log(`[updateZoneItemUtil] Verification after save:`, {
+    savedItemIonNumber: savedItem?.ionNumber,
+    savedItemExpiryDate: savedItem?.expiryDate,
+    savedItemKeys: savedItem ? Object.keys(savedItem) : [],
+  });
+
+  return savedAppointment;
+}
+
+/**
+ * Overrides price for a specific zone item
+ * @param db Firestore instance
+ * @param appointmentId Appointment ID
+ * @param zoneId Zone ID
+ * @param itemIndex Index of item
+ * @param newPrice New price amount
+ * @returns Updated appointment
+ */
+export async function overridePriceForZoneItemUtil(
+  db: Firestore,
+  appointmentId: string,
+  zoneId: string,
+  itemIndex: number,
+  newPrice: number,
+): Promise<Appointment> {
+  return updateZoneItemUtil(db, appointmentId, zoneId, itemIndex, {
+    priceOverrideAmount: newPrice,
+  });
+}
+
+/**
+ * Updates subzones for a specific zone item
+ * @param db Firestore instance
+ * @param appointmentId Appointment ID
+ * @param zoneId Zone ID
+ * @param itemIndex Index of item
+ * @param subzones Array of subzone keys (empty array = entire zone)
+ * @returns Updated appointment
+ */
+export async function updateSubzonesUtil(
+  db: Firestore,
+  appointmentId: string,
+  zoneId: string,
+  itemIndex: number,
+  subzones: string[],
+): Promise<Appointment> {
+  // Validate subzone format if provided
+  subzones.forEach(subzone => {
+    const parts = subzone.split('.');
+    if (parts.length !== 3) {
+      throw new Error(
+        `Invalid subzone format: "${subzone}". Must be "category.zone.subzone" (e.g., "face.forehead.left")`,
+      );
+    }
+  });
+
+  return updateZoneItemUtil(db, appointmentId, zoneId, itemIndex, {
+    subzones,
+  });
+}