@blackcode_sa/metaestetics-api 1.12.0 → 1.12.1

package/src/services/procedure/README.md

@@ -18,7 +18,8 @@ constructor(
   categoryService: CategoryService,
   subcategoryService: SubcategoryService,
   technologyService: TechnologyService,
-  productService: ProductService
+  productService: ProductService,
+  mediaService: MediaService
 )
 ```
 
@@ -31,7 +32,9 @@ Initializes the service with Firestore, Auth, App instances, and required depend
   - Creates a new procedure document in Firestore.
   - Validates input data using `createProcedureSchema`.
   - Fetches full Category, Subcategory, Technology, and Product documents using injected services.
+  - **Products Metadata:** Transforms `productsMetadata` from validation format (with `productId` strings) to full `ProcedureProduct` objects (with complete `product` objects).
   - Retrieves associated Clinic and Practitioner documents to embed `clinicInfo` and `doctorInfo`.
+  - Processes and uploads media files using the MediaService.
   - Embeds treatment details from the technology (blocking conditions, benefits, requirements).
   - Initializes default `reviewInfo` with zero values.
   - Sets `isActive` to `true` by default.
@@ -56,11 +59,13 @@ Initializes the service with Firestore, Auth, App instances, and required depend
 
   - Updates an existing procedure document with partial data.
   - Validates input data using `updateProcedureSchema`.
+  - **Products Metadata:** If `productsMetadata` is provided, transforms from validation format to full `ProcedureProduct` objects.
   - Handles complex updates of related entities:
     - If practitioner changes: Fetches new practitioner data and updates embedded `doctorInfo`.
     - If clinic changes: Fetches new clinic data and updates embedded `clinicInfo`.
     - If category/subcategory changes: Fetches and updates embedded objects.
     - If technology/product changes: Fetches and updates embedded objects plus derived fields.
+  - Processes and uploads media files if photos are provided.
   - Updates the `updatedAt` timestamp.
   - **Aggregation Note:** Updating aggregated data in related entities is handled by Cloud Functions.
 
@@ -83,6 +88,76 @@ Initializes the service with Firestore, Auth, App instances, and required depend
   - Returns an object containing arrays of allowed technologies, families, categories, and subcategories.
 
 - **`getAllProcedures(pagination?: number, lastDoc?: any): Promise<{ procedures: Procedure[]; lastDoc: any }>`**
+
   - Retrieves all procedures, ordered by name.
   - Supports optional pagination with `limit` and `startAfter`.
   - Returns both the procedures array and the last document for cursor-based pagination.
+
+- **`bulkCreateProcedures(baseData: Omit<CreateProcedureData, "practitionerId">, practitionerIds: string[]): Promise<Procedure[]>`**
+
+  - Creates multiple procedures for different practitioners using common base data.
+  - Optimized for bulk creation to reduce database reads and writes.
+  - Uses Firestore batch writes for atomic creation.
+  - Transforms `productsMetadata` once and reuses for all procedures.
+
+- **`createConsultationProcedure(data: Omit<CreateProcedureData, "productId">): Promise<Procedure>`**
+  - Special method for consultation procedures that don't require specific products.
+  - Creates a placeholder product for consultation procedures.
+  - Transforms `productsMetadata` from validation format to full objects.
+
+### Private Helper Methods
+
+- **`transformProductsMetadata(productsMetadata, technologyId): Promise<ProcedureProduct[]>`**
+
+  - Converts validation format (with `productId` strings) to full `ProcedureProduct` objects.
+  - Fetches complete product objects for each product ID.
+  - Essential for maintaining type safety between validation and storage formats.
+
+- **`processMedia(media, ownerId, collectionName): Promise<string | null>`**
+
+  - Handles media file uploads using MediaService.
+  - Supports string URLs, File objects, and Blob objects.
+
+- **`processMediaArray(mediaArray, ownerId, collectionName): Promise<string[]>`**
+  - Processes arrays of media resources.
+  - Used for handling procedure photos.
+
+## Data Transformation
+
+The service handles a critical data transformation between input and storage:
+
+- **Input (`CreateProcedureData`/`UpdateProcedureData`):** `productsMetadata` contains objects with `productId: string`
+
+  ```typescript
+  productsMetadata: {
+    productId: string;
+    price: number;
+    currency: Currency;
+    pricingMeasure: PricingMeasure;
+    isDefault?: boolean;
+  }[]
+  ```
+
+- **Storage (Firestore `Procedure`):** `productsMetadata` contains objects with `product: Product` (full object)
+  ```typescript
+  productsMetadata: ProcedureProduct[] // where ProcedureProduct contains full Product object
+  ```
+
+This transformation ensures:
+
+1. **Type safety** throughout the application
+2. **Denormalized data** for efficient queries (no need to fetch products separately)
+3. **Consistent API contract** for clients (input uses IDs, storage uses full objects)
+4. **Performance optimization** (embedded product data in procedures)
+
+## Validation Schemas
+
+The service uses different validation schemas for different stages:
+
+- **`procedureProductDataSchema`**: Validates input data with `productId` strings (used in `createProcedureSchema`/`updateProcedureSchema`)
+- **`storedProcedureProductSchema`**: Validates stored data with full `Product` objects (used in `procedureSchema`)
+- **`createProcedureSchema`**: Validates procedure creation data (input format)
+- **`updateProcedureSchema`**: Validates procedure update data (input format)
+- **`procedureSchema`**: Validates complete stored procedure documents (storage format)
+
+This ensures validation matches the actual data format at each stage of the process.

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

@@ -67,10 +67,15 @@ import {
   ProcedureFamily,
   type TreatmentBenefitDynamic,
 } from "../../backoffice/types";
+import {
+  Currency,
+  PricingMeasure,
+} from "../../backoffice/types/static/pricing.types";
 import { Clinic, CLINICS_COLLECTION } from "../../types/clinic";
 import { ProcedureReviewInfo } from "../../types/reviews";
 import { distanceBetween, geohashQueryBounds } from "geofire-common";
 import { MediaService, MediaAccessLevel } from "../media/media.service";
+import type { ProcedureProduct } from "../../backoffice/types/procedure-product.types";
 
 export class ProcedureService extends BaseService {
   private categoryService: CategoryService;
@@ -163,6 +168,49 @@ export class ProcedureService extends BaseService {
     return result;
   }
 
+  /**
+   * Transforms validated procedure product data (with productId) to ProcedureProduct objects (with full product)
+   * @param productsMetadata Array of validated procedure product data
+   * @param technologyId Technology ID to fetch products from
+   * @returns Array of ProcedureProduct objects with full product information
+   */
+  private async transformProductsMetadata(
+    productsMetadata: {
+      productId: string;
+      price: number;
+      currency: Currency;
+      pricingMeasure: PricingMeasure;
+      isDefault?: boolean;
+    }[],
+    technologyId: string
+  ): Promise<ProcedureProduct[]> {
+    const transformedProducts: ProcedureProduct[] = [];
+
+    for (const productData of productsMetadata) {
+      // Fetch the full product object
+      const product = await this.productService.getById(
+        technologyId,
+        productData.productId
+      );
+      if (!product) {
+        throw new Error(
+          `Product with ID ${productData.productId} not found for technology ${technologyId}`
+        );
+      }
+
+      // Transform to ProcedureProduct
+      transformedProducts.push({
+        product,
+        price: productData.price,
+        currency: productData.currency,
+        pricingMeasure: productData.pricingMeasure,
+        isDefault: productData.isDefault,
+      });
+    }
+
+    return transformedProducts;
+  }
+
   /**
    * Creates a new procedure
    * @param data - The data for creating a new procedure
@@ -229,6 +277,12 @@ export class ProcedureService extends BaseService {
       );
     }
 
+    // Transform productsMetadata from validation format to ProcedureProduct format
+    const transformedProductsMetadata = await this.transformProductsMetadata(
+      validatedData.productsMetadata,
+      validatedData.technologyId
+    );
+
     // Create aggregated clinic info for the procedure document
     const clinicInfo = {
       id: clinicSnapshot.id,
@@ -271,6 +325,7 @@ export class ProcedureService extends BaseService {
       subcategory,
       technology,
       product,
+      productsMetadata: transformedProductsMetadata,
       blockingConditions: technology.blockingConditions,
       contraindications: technology.contraindications || [],
       contraindicationIds: technology.contraindications?.map((c) => c.id) || [],
@@ -367,6 +422,12 @@ export class ProcedureService extends BaseService {
       );
     }
 
+    // Transform productsMetadata from validation format to ProcedureProduct format
+    const transformedProductsMetadata = await this.transformProductsMetadata(
+      validatedData.productsMetadata,
+      validatedData.technologyId
+    );
+
     // 4. Fetch all practitioner data efficiently
     const practitionersMap = new Map<string, Practitioner>();
     // Use 'in' query in chunks of 30, as this is the Firestore limit
@@ -443,6 +504,7 @@ export class ProcedureService extends BaseService {
         subcategory,
         technology,
         product,
+        productsMetadata: transformedProductsMetadata,
         blockingConditions: technology.blockingConditions,
         contraindications: technology.contraindications || [],
         contraindicationIds:
@@ -581,7 +643,23 @@ export class ProcedureService extends BaseService {
     }
 
     const existingProcedure = procedureSnapshot.data() as Procedure;
-    let updatedProcedureData: Partial<Procedure> = { ...validatedData };
+    let updatedProcedureData: Partial<Procedure> = {};
+
+    // Copy validated simple fields
+    if (validatedData.name !== undefined)
+      updatedProcedureData.name = validatedData.name;
+    if (validatedData.description !== undefined)
+      updatedProcedureData.description = validatedData.description;
+    if (validatedData.price !== undefined)
+      updatedProcedureData.price = validatedData.price;
+    if (validatedData.currency !== undefined)
+      updatedProcedureData.currency = validatedData.currency;
+    if (validatedData.pricingMeasure !== undefined)
+      updatedProcedureData.pricingMeasure = validatedData.pricingMeasure;
+    if (validatedData.duration !== undefined)
+      updatedProcedureData.duration = validatedData.duration;
+    if (validatedData.isActive !== undefined)
+      updatedProcedureData.isActive = validatedData.isActive;
 
     let practitionerChanged = false;
     let clinicChanged = false;
@@ -599,6 +677,22 @@ export class ProcedureService extends BaseService {
       );
     }
 
+    // Transform productsMetadata if provided
+    if (validatedData.productsMetadata !== undefined) {
+      const technologyId =
+        validatedData.technologyId ?? existingProcedure.technology.id;
+      if (!technologyId) {
+        throw new Error(
+          "Technology ID is required for updating products metadata"
+        );
+      }
+      updatedProcedureData.productsMetadata =
+        await this.transformProductsMetadata(
+          validatedData.productsMetadata,
+          technologyId
+        );
+    }
+
     // --- Prepare updates and fetch new related data if IDs change ---
 
     // Handle Practitioner Change
@@ -1479,6 +1573,12 @@ export class ProcedureService extends BaseService {
       );
     }
 
+    // Transform productsMetadata from validation format to ProcedureProduct format
+    const transformedProductsMetadata = await this.transformProductsMetadata(
+      data.productsMetadata,
+      data.technologyId
+    );
+
     // Create aggregated clinic info for the procedure document
     const clinicInfo = {
       id: clinicSnapshot.id,
@@ -1535,6 +1635,7 @@ export class ProcedureService extends BaseService {
       subcategory,
       technology,
       product: consultationProduct, // Use placeholder product
+      productsMetadata: transformedProductsMetadata,
       blockingConditions: technology.blockingConditions,
       contraindications: technology.contraindications || [],
       contraindicationIds: technology.contraindications?.map((c) => c.id) || [],

package/src/types/procedure/index.ts

@@ -20,6 +20,7 @@ import {
   Currency,
 } from "../../backoffice/types/static/pricing.types";
 import { MediaResource } from "../../services/media/media.service";
+import type { ProcedureProduct } from "../../backoffice/types/procedure-product.types";
 
 /**
  * Procedure represents a specific medical procedure that can be performed by a practitioner in a clinic
@@ -44,15 +45,16 @@ export interface Procedure {
   subcategory: Subcategory;
   /** Technology used in this procedure */
   technology: Technology;
-  /** Product used in this procedure */
+  /** Default product used in this procedure */
   product: Product;
-  /** Price of the procedure */
+  /** Default price of the procedure */
   price: number;
   /** Currency for the price */
   currency: Currency;
-  /** How the price is measured (per ml, per zone, etc.) */
+  /** How the price is measured (per ml, per zone, etc.) - for default product*/
   pricingMeasure: PricingMeasure;
   /** Duration of the procedure in minutes */
+  productsMetadata: ProcedureProduct[];
   duration: number;
   /** Blocking conditions that prevent this procedure */
   blockingConditions: BlockingCondition[];
@@ -104,6 +106,13 @@ export interface CreateProcedureData {
   technologyId: string;
   productId: string;
   price: number;
+  productsMetadata: {
+    productId: string;
+    price: number;
+    currency: Currency;
+    pricingMeasure: PricingMeasure;
+    isDefault?: boolean;
+  }[];
   currency: Currency;
   pricingMeasure: PricingMeasure;
   duration: number;
@@ -123,6 +132,13 @@ export interface UpdateProcedureData {
   price?: number;
   currency?: Currency;
   pricingMeasure?: PricingMeasure;
+  productsMetadata?: {
+    productId: string;
+    price: number;
+    currency: Currency;
+    pricingMeasure: PricingMeasure;
+    isDefault?: boolean;
+  }[];
   duration?: number;
   isActive?: boolean;
   practitionerId?: string;

package/src/validations/procedure-product.schema.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import {
+  Currency,
+  PricingMeasure,
+} from "../backoffice/types/static/pricing.types";
+
+/**
+ * Schema for validating procedure product data.
+ * This is used when creating or updating a procedure to validate the products associated with it.
+ */
+export const procedureProductDataSchema = z.object({
+  /**
+   * The ID of the product. Must be a non-empty string.
+   * @validation
+   */
+  productId: z.string().min(1, "Product ID is required"),
+
+  /**
+   * The price of the product. Must be a non-negative number.
+   * @validation
+   */
+  price: z.number().min(0, "Price must be a non-negative number"),
+
+  /**
+   * The currency for the price. Must be one of the values from the Currency enum.
+   * @validation
+   */
+  currency: z.nativeEnum(Currency),
+
+  /**
+   * The pricing measure for the product. Must be one of the values from the PricingMeasure enum.
+   * @validation
+   */
+  pricingMeasure: z.nativeEnum(PricingMeasure),
+
+  /**
+   * Whether this is the default product for the procedure.
+   * @validation
+   */
+  isDefault: z.boolean().optional(),
+});

package/src/validations/procedure.schema.ts

@@ -1,9 +1,45 @@
-import { z } from 'zod';
-import { ProcedureFamily } from '../backoffice/types/static/procedure-family.types';
-import { Currency, PricingMeasure } from '../backoffice/types/static/pricing.types';
-import { clinicInfoSchema, doctorInfoSchema } from './shared.schema';
-import { procedureReviewInfoSchema } from './reviews.schema';
-import { mediaResourceSchema } from './media.schema';
+import { z } from "zod";
+import { ProcedureFamily } from "../backoffice/types/static/procedure-family.types";
+import {
+  Currency,
+  PricingMeasure,
+} from "../backoffice/types/static/pricing.types";
+import { clinicInfoSchema, doctorInfoSchema } from "./shared.schema";
+import { procedureReviewInfoSchema } from "./reviews.schema";
+import { mediaResourceSchema } from "./media.schema";
+import { procedureProductDataSchema } from "./procedure-product.schema";
+
+/**
+ * Schema for validating stored procedure product data (with full product objects).
+ * This is used when validating complete procedure documents from Firestore.
+ */
+export const storedProcedureProductSchema = z.object({
+  /**
+   * The full product object used in the procedure.
+   */
+  product: z.any(), // We'll validate the full product object separately
+
+  /**
+   * The price of the procedure when using this specific product.
+   */
+  price: z.number().min(0, "Price must be a non-negative number"),
+
+  /**
+   * The currency for the price of this product.
+   */
+  currency: z.nativeEnum(Currency),
+
+  /**
+   * How the price is measured (e.g., per ml, per zone).
+   */
+  pricingMeasure: z.nativeEnum(PricingMeasure),
+
+  /**
+   * Whether this is the default product for the procedure.
+   */
+  isDefault: z.boolean().optional(),
+});
+
 /**
  * Schema for creating a new procedure
  */
@@ -20,6 +56,7 @@ export const createProcedureSchema = z.object({
   price: z.number().min(0),
   currency: z.nativeEnum(Currency),
   pricingMeasure: z.nativeEnum(PricingMeasure),
+  productsMetadata: z.array(procedureProductDataSchema).min(1),
   duration: z.number().min(1).max(480), // Max 8 hours
   practitionerId: z.string().min(1),
   clinicBranchId: z.string().min(1),
@@ -36,6 +73,7 @@ export const updateProcedureSchema = z.object({
   price: z.number().min(0).optional(),
   currency: z.nativeEnum(Currency).optional(),
   pricingMeasure: z.nativeEnum(PricingMeasure).optional(),
+  productsMetadata: z.array(procedureProductDataSchema).min(1).optional(),
   duration: z.number().min(0).optional(),
   isActive: z.boolean().optional(),
   practitionerId: z.string().optional(),
@@ -48,18 +86,31 @@ export const updateProcedureSchema = z.object({
 });
 
 /**
- * Schema for validating a complete procedure object
+ * Schema for validating a complete procedure object (as stored in Firestore)
  */
-export const procedureSchema = createProcedureSchema.extend({
+export const procedureSchema = z.object({
   id: z.string().min(1),
+  name: z.string().min(1).max(200),
   nameLower: z.string().min(1).max(200),
+  description: z.string().min(1).max(2000),
+  family: z.nativeEnum(ProcedureFamily),
   category: z.any(), // We'll validate the full category object separately
   subcategory: z.any(), // We'll validate the full subcategory object separately
   technology: z.any(), // We'll validate the full technology object separately
   product: z.any(), // We'll validate the full product object separately
+  productsMetadata: z.array(storedProcedureProductSchema).min(1), // Use stored format schema
+  price: z.number().min(0),
+  currency: z.nativeEnum(Currency),
+  pricingMeasure: z.nativeEnum(PricingMeasure),
+  duration: z.number().min(1).max(480),
+  practitionerId: z.string().min(1),
+  clinicBranchId: z.string().min(1),
+  photos: z.array(z.string()).optional(), // Stored as URL strings
   blockingConditions: z.array(z.any()), // We'll validate blocking conditions separately
   contraindications: z.array(z.any()), // We'll validate contraindications separately
+  contraindicationIds: z.array(z.string()), // Array of IDs for efficient querying
   treatmentBenefits: z.array(z.any()), // We'll validate treatment benefits separately
+  treatmentBenefitIds: z.array(z.string()), // Array of IDs for efficient querying
   preRequirements: z.array(z.any()), // We'll validate requirements separately
   postRequirements: z.array(z.any()), // We'll validate requirements separately
   certificationRequirement: z.any(), // We'll validate certification requirement separately