@blackcode_sa/metaestetics-api 1.12.67 → 1.13.0

package/src/backoffice/services/analytics.service.summary.md

@@ -0,0 +1,143 @@
+# Analytics Service - Executive Summary
+
+## Overview
+
+This document provides a high-level summary of the proposed Analytics Service for the Clinic Admin app. The full detailed proposal can be found in [analytics.service.proposal.md](./analytics.service.proposal.md).
+
+## Purpose
+
+The Analytics Service will provide comprehensive financial and operational intelligence to clinic administrators, enabling data-driven decision making across:
+
+- **Practitioner Performance**: Track doctor efficiency, revenue generation, and patient satisfaction
+- **Procedure Analytics**: Understand procedure popularity, profitability, and product usage
+- **Financial Intelligence**: Monitor revenue, costs, payment status, and trends
+- **Operational Efficiency**: Analyze time utilization, cancellations, and no-shows
+- **Patient Insights**: Track patient lifetime value, retention, and behavior patterns
+
+## Key Data Sources
+
+The service will aggregate data from:
+
+1. **Appointments Collection**: Primary source for all appointment-related metrics
+2. **Procedures Collection**: Procedure metadata and categorization
+3. **Practitioners Collection**: Doctor information and associations
+4. **Patients Collection**: Patient profiles and history
+5. **Clinics Collection**: Clinic and branch information
+6. **Products Collection**: Product usage and pricing data
+
+## Core Analytics Categories
+
+### 1. Practitioner Analytics
+- Total and completed appointments
+- Cancellation and no-show rates
+- Time efficiency (booked vs actual)
+- Revenue generation
+- Patient retention
+
+### 2. Procedure Analytics
+- Appointment counts and popularity
+- Revenue and profitability
+- Cancellation rates
+- Product usage patterns
+- Performance by category/technology
+
+### 3. Time Analytics
+- Booked vs actual time comparison
+- Efficiency percentages
+- Overrun/underutilization analysis
+- Peak hours and trends
+
+### 4. Cancellation & No-Show Analytics
+- Rates by clinic, practitioner, patient, procedure
+- Cancellation reasons breakdown
+- Patterns and trends
+- Lead time analysis
+
+### 5. Financial Analytics
+- Total and average revenue
+- Cost per patient/appointment
+- Payment status breakdown
+- Revenue trends
+- Product cost analysis
+
+### 6. Product Usage Analytics
+- Products used per appointment
+- Revenue contribution
+- Usage by procedure/zone
+- Quantity and pricing trends
+
+### 7. Patient Analytics
+- Lifetime value
+- Retention rates
+- Appointment frequency
+- Cancellation patterns
+
+### 8. Clinic Analytics
+- Overall performance metrics
+- Practitioner comparisons
+- Procedure popularity
+- Efficiency metrics
+
+## Proposed Service Structure
+
+The `AnalyticsService` will extend `BaseService` and provide methods organized by analytics category:
+
+- `getPractitionerAnalytics()` - Comprehensive practitioner metrics
+- `getProcedureAnalytics()` - Procedure performance data
+- `getTimeEfficiencyMetrics()` - Time utilization analysis
+- `getCancellationMetrics()` - Cancellation insights
+- `getRevenueMetrics()` - Financial intelligence
+- `getProductUsageMetrics()` - Product analytics
+- `getPatientAnalytics()` - Patient insights
+- `getClinicAnalytics()` - Clinic performance
+- `getDashboardData()` - Comprehensive dashboard aggregation
+
+## Key Calculations
+
+### Cost Calculation Priority
+1. `metadata.finalbilling.finalPrice` (if available)
+2. Sum of `metadata.zonesData` subtotals
+3. `appointment.cost` (fallback)
+
+### Time Efficiency
+```
+efficiency = (actualDuration / bookedDuration) * 100
+overrun = actualDuration > bookedDuration ? difference : 0
+```
+
+### Cancellation Rate
+```
+cancellationRate = (canceledCount / totalAppointments) * 100
+```
+
+## Implementation Phases
+
+1. **Phase 1**: Core infrastructure and utilities
+2. **Phase 2**: Basic metrics (practitioner, procedure, financial)
+3. **Phase 3**: Advanced analytics (time, products, patients)
+4. **Phase 4**: Dashboard and trend analysis
+
+## Performance Considerations
+
+- Firestore composite indexes for query optimization
+- Pagination for large datasets
+- Caching strategy for frequently accessed metrics
+- Batch processing for complex aggregations
+- Server-side calculations via Cloud Functions
+
+## Next Steps
+
+1. Review and approve the detailed proposal
+2. Create TypeScript type definitions
+3. Implement core service structure
+4. Build utility functions for calculations
+5. Implement metrics methods incrementally
+6. Add comprehensive tests
+7. Create API documentation
+8. Integrate with Clinic Admin app
+
+## Documentation
+
+- **Full Proposal**: [analytics.service.proposal.md](./analytics.service.proposal.md)
+- **Service README**: [README.md](./README.md)
+

package/src/backoffice/services/category.service.ts

@@ -17,6 +17,12 @@ import { Category, CATEGORIES_COLLECTION, ICategoryService } from '../types/cate
 import { BaseService } from '../../services/base.service';
 import { ProcedureFamily } from '../types/static/procedure-family.types';
 
+/**
+ * ID of the consultation category that should be hidden from admin backoffice.
+ * This category is used internally for free consultation procedures.
+ */
+const EXCLUDED_CATEGORY_ID = 'consultation';
+
 /**
  * Servis za upravljanje kategorijama procedura.
  * Kategorije su prvi nivo organizacije nakon procedure family (aesthetics/surgery).
@@ -31,6 +37,14 @@ import { ProcedureFamily } from '../types/static/procedure-family.types';
  * });
  */
 export class CategoryService extends BaseService implements ICategoryService {
+  /**
+   * Filters out excluded categories from a list.
+   * @param categories - List of categories to filter
+   * @returns Filtered list without excluded categories
+   */
+  private filterExcludedCategories(categories: Category[]): Category[] {
+    return categories.filter(cat => cat.id !== EXCLUDED_CATEGORY_ID);
+  }
   /**
    * Referenca na Firestore kolekciju kategorija
    */
@@ -71,8 +85,10 @@ export class CategoryService extends BaseService implements ICategoryService {
         where('family', '==', family),
         where('isActive', '==', active),
       );
-      const snapshot = await getCountFromServer(q);
-      counts[family] = snapshot.data().count;
+      const snapshot = await getDocs(q);
+      // Filter out excluded category and count
+      const filteredDocs = snapshot.docs.filter(doc => doc.id !== EXCLUDED_CATEGORY_ID);
+      counts[family] = filteredDocs.length;
     }
     return counts;
   }
@@ -84,13 +100,14 @@ export class CategoryService extends BaseService implements ICategoryService {
   async getAllForFilter() {
     const q = query(this.categoriesRef, where('isActive', '==', true));
     const snapshot = await getDocs(q);
-    return snapshot.docs.map(
+    const categories = snapshot.docs.map(
       doc =>
         ({
           id: doc.id,
           ...doc.data(),
         } as Category),
     );
+    return this.filterExcludedCategories(categories);
   }
 
   /**
@@ -106,13 +123,14 @@ export class CategoryService extends BaseService implements ICategoryService {
       orderBy('name'),
     );
     const snapshot = await getDocs(q);
-    return snapshot.docs.map(
+    const categories = snapshot.docs.map(
       doc =>
         ({
           id: doc.id,
           ...doc.data(),
         } as Category),
     );
+    return this.filterExcludedCategories(categories);
   }
 
   /**
@@ -144,8 +162,9 @@ export class CategoryService extends BaseService implements ICategoryService {
           ...doc.data(),
         } as Category),
     );
+    const filteredCategories = this.filterExcludedCategories(categories);
     const newLastVisible = snapshot.docs[snapshot.docs.length - 1];
-    return { categories, lastVisible: newLastVisible };
+    return { categories: filteredCategories, lastVisible: newLastVisible };
   }
 
   /**
@@ -180,8 +199,9 @@ export class CategoryService extends BaseService implements ICategoryService {
           ...doc.data(),
         } as Category),
     );
+    const filteredCategories = this.filterExcludedCategories(categories);
     const newLastVisible = snapshot.docs[snapshot.docs.length - 1];
-    return { categories, lastVisible: newLastVisible };
+    return { categories: filteredCategories, lastVisible: newLastVisible };
   }
 
   /**
@@ -223,6 +243,25 @@ export class CategoryService extends BaseService implements ICategoryService {
    * @returns Kategorija ili null ako ne postoji
    */
   async getById(id: string) {
+    // Prevent access to excluded category
+    if (id === EXCLUDED_CATEGORY_ID) return null;
+    
+    const docRef = doc(this.categoriesRef, id);
+    const docSnap = await getDoc(docRef);
+    if (!docSnap.exists()) return null;
+    return {
+      id: docSnap.id,
+      ...docSnap.data(),
+    } as Category;
+  }
+
+  /**
+   * Internal method to get category by ID without filtering.
+   * Used internally for consultation procedures.
+   * @param id - ID of the category to get
+   * @returns Category or null if not found
+   */
+  async getByIdInternal(id: string): Promise<Category | null> {
     const docRef = doc(this.categoriesRef, id);
     const docSnap = await getDoc(docRef);
     if (!docSnap.exists()) return null;
@@ -249,6 +288,8 @@ export class CategoryService extends BaseService implements ICategoryService {
     const snapshot = await getDocs(q);
     if (snapshot.empty) return null;
     const doc = snapshot.docs[0];
+    // Exclude consultation category
+    if (doc.id === EXCLUDED_CATEGORY_ID) return null;
     return {
       id: doc.id,
       ...doc.data(),
@@ -299,6 +340,8 @@ export class CategoryService extends BaseService implements ICategoryService {
       if (snapshot.empty) break;
 
       for (const d of snapshot.docs) {
+        // Exclude consultation category from CSV export
+        if (d.id === EXCLUDED_CATEGORY_ID) continue;
         const category = ({ id: d.id, ...d.data() } as unknown) as Category;
         rows.push(this.categoryToCsvRow(category));
       }

package/src/backoffice/services/subcategory.service.ts

@@ -23,6 +23,12 @@ import {
 import { BaseService } from "../../services/base.service";
 import { CATEGORIES_COLLECTION } from "../types/category.types";
 
+/**
+ * ID of the free-consultation subcategory that should be hidden from admin backoffice.
+ * This subcategory is used internally for free consultation procedures.
+ */
+const EXCLUDED_SUBCATEGORY_ID = 'free-consultation';
+
 /**
  * Servis za upravljanje podkategorijama procedura.
  * Podkategorije su drugi nivo organizacije i pripadaju određenoj kategoriji.
@@ -37,6 +43,14 @@ import { CATEGORIES_COLLECTION } from "../types/category.types";
  * });
  */
 export class SubcategoryService extends BaseService {
+  /**
+   * Filters out excluded subcategories from a list.
+   * @param subcategories - List of subcategories to filter
+   * @returns Filtered list without excluded subcategories
+   */
+  private filterExcludedSubcategories(subcategories: Subcategory[]): Subcategory[] {
+    return subcategories.filter(sub => sub.id !== EXCLUDED_SUBCATEGORY_ID);
+  }
   /**
    * Vraća referencu na Firestore kolekciju podkategorija za određenu kategoriju
    * @param categoryId - ID roditeljske kategorije
@@ -90,8 +104,10 @@ export class SubcategoryService extends BaseService {
       const categoryId = categoryDoc.id;
       const subcategoriesRef = this.getSubcategoriesRef(categoryId);
       const q = query(subcategoriesRef, where("isActive", "==", active));
-      const snapshot = await getCountFromServer(q);
-      counts[categoryId] = snapshot.data().count;
+      const snapshot = await getDocs(q);
+      // Filter out excluded subcategory and count
+      const filteredDocs = snapshot.docs.filter(doc => doc.id !== EXCLUDED_SUBCATEGORY_ID);
+      counts[categoryId] = filteredDocs.length;
     }
 
     return counts;
@@ -129,8 +145,9 @@ export class SubcategoryService extends BaseService {
           ...doc.data(),
         } as Subcategory)
     );
+    const filteredSubcategories = this.filterExcludedSubcategories(subcategories);
     const newLastVisible = querySnapshot.docs[querySnapshot.docs.length - 1];
-    return { subcategories, lastVisible: newLastVisible };
+    return { subcategories: filteredSubcategories, lastVisible: newLastVisible };
   }
 
   /**
@@ -169,8 +186,9 @@ export class SubcategoryService extends BaseService {
           ...doc.data(),
         } as Subcategory)
     );
+    const filteredSubcategories = this.filterExcludedSubcategories(subcategories);
     const newLastVisible = querySnapshot.docs[querySnapshot.docs.length - 1];
-    return { subcategories, lastVisible: newLastVisible };
+    return { subcategories: filteredSubcategories, lastVisible: newLastVisible };
   }
 
   /**
@@ -184,13 +202,14 @@ export class SubcategoryService extends BaseService {
       where("isActive", "==", true)
     );
     const querySnapshot = await getDocs(q);
-    return querySnapshot.docs.map(
+    const subcategories = querySnapshot.docs.map(
       (doc) =>
         ({
           id: doc.id,
           ...doc.data(),
         } as Subcategory)
     );
+    return this.filterExcludedSubcategories(subcategories);
   }
 
   /**
@@ -203,13 +222,14 @@ export class SubcategoryService extends BaseService {
       where("isActive", "==", true)
     );
     const querySnapshot = await getDocs(q);
-    return querySnapshot.docs.map(
+    const subcategories = querySnapshot.docs.map(
       (doc) =>
         ({
           id: doc.id,
           ...doc.data(),
         } as Subcategory)
     );
+    return this.filterExcludedSubcategories(subcategories);
   }
 
   /**
@@ -297,6 +317,26 @@ export class SubcategoryService extends BaseService {
    * @returns Podkategorija ili null ako ne postoji
    */
   async getById(categoryId: string, subcategoryId: string) {
+    // Prevent access to excluded subcategory
+    if (subcategoryId === EXCLUDED_SUBCATEGORY_ID) return null;
+    
+    const docRef = doc(this.getSubcategoriesRef(categoryId), subcategoryId);
+    const docSnap = await getDoc(docRef);
+    if (!docSnap.exists()) return null;
+    return {
+      id: docSnap.id,
+      ...docSnap.data(),
+    } as Subcategory;
+  }
+
+  /**
+   * Internal method to get subcategory by ID without filtering.
+   * Used internally for consultation procedures.
+   * @param categoryId - ID of the category
+   * @param subcategoryId - ID of the subcategory to get
+   * @returns Subcategory or null if not found
+   */
+  async getByIdInternal(categoryId: string, subcategoryId: string): Promise<Subcategory | null> {
     const docRef = doc(this.getSubcategoriesRef(categoryId), subcategoryId);
     const docSnap = await getDoc(docRef);
     if (!docSnap.exists()) return null;
@@ -322,6 +362,8 @@ export class SubcategoryService extends BaseService {
     const querySnapshot = await getDocs(q);
     if (querySnapshot.empty) return null;
     const doc = querySnapshot.docs[0];
+    // Exclude free-consultation subcategory
+    if (doc.id === EXCLUDED_SUBCATEGORY_ID) return null;
     return {
       id: doc.id,
       ...doc.data(),
@@ -375,6 +417,8 @@ export class SubcategoryService extends BaseService {
       if (snapshot.empty) break;
 
       for (const d of snapshot.docs) {
+        // Exclude free-consultation subcategory from CSV export
+        if (d.id === EXCLUDED_SUBCATEGORY_ID) continue;
         const subcategory = ({ id: d.id, ...d.data() } as unknown) as Subcategory;
         rows.push(this.subcategoryToCsvRow(subcategory));
       }

package/src/backoffice/services/technology.service.ts

@@ -33,6 +33,12 @@ import { ProcedureFamily } from '../types/static/procedure-family.types';
 import { Practitioner, PractitionerCertification } from '../../types/practitioner';
 import { Product, PRODUCTS_COLLECTION } from '../types/product.types';
 
+/**
+ * ID of the free-consultation-tech technology that should be hidden from admin backoffice.
+ * This technology is used internally for free consultation procedures.
+ */
+const EXCLUDED_TECHNOLOGY_ID = 'free-consultation-tech';
+
 /**
  * Default vrednosti za sertifikaciju
  */
@@ -45,6 +51,14 @@ const DEFAULT_CERTIFICATION_REQUIREMENT: CertificationRequirement = {
  * Service for managing technologies.
  */
 export class TechnologyService extends BaseService implements ITechnologyService {
+  /**
+   * Filters out excluded technologies from a list.
+   * @param technologies - List of technologies to filter
+   * @returns Filtered list without excluded technologies
+   */
+  private filterExcludedTechnologies(technologies: Technology[]): Technology[] {
+    return technologies.filter(tech => tech.id !== EXCLUDED_TECHNOLOGY_ID);
+  }
   /**
    * Reference to the Firestore collection of technologies.
    */
@@ -100,6 +114,8 @@ export class TechnologyService extends BaseService implements ITechnologyService
     const snapshot = await getDocs(q);
     const counts: Record<string, number> = {};
     snapshot.docs.forEach(doc => {
+      // Exclude free-consultation-tech from counts
+      if (doc.id === EXCLUDED_TECHNOLOGY_ID) return;
       const tech = doc.data() as Technology;
       counts[tech.subcategoryId] = (counts[tech.subcategoryId] || 0) + 1;
     });
@@ -116,6 +132,8 @@ export class TechnologyService extends BaseService implements ITechnologyService
     const snapshot = await getDocs(q);
     const counts: Record<string, number> = {};
     snapshot.docs.forEach(doc => {
+      // Exclude free-consultation-tech from counts
+      if (doc.id === EXCLUDED_TECHNOLOGY_ID) return;
       const tech = doc.data() as Technology;
       counts[tech.categoryId] = (counts[tech.categoryId] || 0) + 1;
     });
@@ -151,8 +169,9 @@ export class TechnologyService extends BaseService implements ITechnologyService
           ...doc.data(),
         } as Technology),
     );
+    const filteredTechnologies = this.filterExcludedTechnologies(technologies);
     const newLastVisible = snapshot.docs[snapshot.docs.length - 1];
-    return { technologies, lastVisible: newLastVisible };
+    return { technologies: filteredTechnologies, lastVisible: newLastVisible };
   }
 
   /**
@@ -187,8 +206,9 @@ export class TechnologyService extends BaseService implements ITechnologyService
           ...doc.data(),
         } as Technology),
     );
+    const filteredTechnologies = this.filterExcludedTechnologies(technologies);
     const newLastVisible = snapshot.docs[snapshot.docs.length - 1];
-    return { technologies, lastVisible: newLastVisible };
+    return { technologies: filteredTechnologies, lastVisible: newLastVisible };
   }
 
   /**
@@ -223,8 +243,9 @@ export class TechnologyService extends BaseService implements ITechnologyService
           ...doc.data(),
         } as Technology),
     );
+    const filteredTechnologies = this.filterExcludedTechnologies(technologies);
     const newLastVisible = snapshot.docs[snapshot.docs.length - 1];
-    return { technologies, lastVisible: newLastVisible };
+    return { technologies: filteredTechnologies, lastVisible: newLastVisible };
   }
 
   /**
@@ -300,6 +321,25 @@ export class TechnologyService extends BaseService implements ITechnologyService
    * @returns The technology or null if it doesn't exist.
    */
   async getById(id: string): Promise<Technology | null> {
+    // Prevent access to excluded technology
+    if (id === EXCLUDED_TECHNOLOGY_ID) return null;
+    
+    const docRef = doc(this.technologiesRef, id);
+    const docSnap = await getDoc(docRef);
+    if (!docSnap.exists()) return null;
+    return {
+      id: docSnap.id,
+      ...docSnap.data(),
+    } as Technology;
+  }
+
+  /**
+   * Internal method to get technology by ID without filtering.
+   * Used internally for consultation procedures.
+   * @param id - The ID of the requested technology
+   * @returns The technology or null if it doesn't exist
+   */
+  async getByIdInternal(id: string): Promise<Technology | null> {
     const docRef = doc(this.technologiesRef, id);
     const docSnap = await getDoc(docRef);
     if (!docSnap.exists()) return null;
@@ -324,6 +364,8 @@ export class TechnologyService extends BaseService implements ITechnologyService
     const snapshot = await getDocs(q);
     if (snapshot.empty) return null;
     const doc = snapshot.docs[0];
+    // Exclude free-consultation-tech
+    if (doc.id === EXCLUDED_TECHNOLOGY_ID) return null;
     return {
       id: doc.id,
       ...doc.data(),
@@ -780,13 +822,14 @@ export class TechnologyService extends BaseService implements ITechnologyService
       orderBy('name'),
     );
     const snapshot = await getDocs(q);
-    return snapshot.docs.map(
+    const technologies = snapshot.docs.map(
       doc =>
         ({
           id: doc.id,
           ...doc.data(),
         } as Technology),
     );
+    return this.filterExcludedTechnologies(technologies);
   }
 
   /**
@@ -806,13 +849,14 @@ export class TechnologyService extends BaseService implements ITechnologyService
       orderBy('name'),
     );
     const snapshot = await getDocs(q);
-    return snapshot.docs.map(
+    const technologies = snapshot.docs.map(
       doc =>
         ({
           id: doc.id,
           ...doc.data(),
         } as Technology),
     );
+    return this.filterExcludedTechnologies(technologies);
   }
 
   /**
@@ -825,13 +869,14 @@ export class TechnologyService extends BaseService implements ITechnologyService
       orderBy('name'),
     );
     const snapshot = await getDocs(q);
-    return snapshot.docs.map(
+    const technologies = snapshot.docs.map(
       doc =>
         ({
           id: doc.id,
           ...doc.data(),
         } as Technology),
     );
+    return this.filterExcludedTechnologies(technologies);
   }
 
   // ==========================================
@@ -1040,6 +1085,8 @@ export class TechnologyService extends BaseService implements ITechnologyService
       if (snapshot.empty) break;
 
       for (const d of snapshot.docs) {
+        // Exclude free-consultation-tech from CSV export
+        if (d.id === EXCLUDED_TECHNOLOGY_ID) continue;
         const technology = ({ id: d.id, ...d.data() } as unknown) as Technology;
         // Fetch products for this technology
         const productNames = await this.getProductNamesForTechnology(technology.id!);