@blackcode_sa/metaestetics-api 1.14.79 → 1.15.2

package/src/services/patient/utils/skin-quality-assessment.utils.ts

@@ -0,0 +1,160 @@
+import { getDoc, updateDoc, setDoc, serverTimestamp, Firestore, doc } from 'firebase/firestore';
+import {
+  SkinQualityAssessment,
+  CreateSkinQualityAssessmentData,
+  UpdateSkinQualityAssessmentData,
+  SKIN_QUALITY_ASSESSMENT_COLLECTION,
+  PATIENTS_COLLECTION,
+  SkinQualityAssessmentStatus,
+} from '../../../types/patient';
+import { UserRole } from '../../../types';
+import {
+  createSkinQualityAssessmentSchema,
+  updateSkinQualityAssessmentSchema,
+  skinQualityAssessmentSchema,
+} from '../../../validations/patient/skin-quality-assessment.schema';
+import { getPatientDocRef } from './docs.utils';
+import { AuthError } from '../../../errors/auth.errors';
+import { getPractitionerProfileByUserRef } from './practitioner.utils';
+import { getClinicAdminByUserRef } from '../../clinic/utils/admin.utils';
+
+export const getSkinQualityAssessmentDocRef = (db: Firestore, patientId: string) => {
+  return doc(db, PATIENTS_COLLECTION, patientId, SKIN_QUALITY_ASSESSMENT_COLLECTION, patientId);
+};
+
+const checkSkinQualityAssessmentAccessUtil = async (
+  db: Firestore,
+  patientId: string,
+  requesterId: string,
+  requesterRoles: UserRole[]
+): Promise<void> => {
+  const patientDoc = await getDoc(getPatientDocRef(db, patientId));
+  if (!patientDoc.exists()) {
+    throw new Error('Patient profile not found');
+  }
+  const patientData = patientDoc.data() as any;
+
+  if (patientData.userRef && patientData.userRef === requesterId) {
+    return;
+  }
+
+  if (requesterRoles.includes(UserRole.PRACTITIONER)) {
+    const practitionerProfile = await getPractitionerProfileByUserRef(db, requesterId);
+    if (practitionerProfile && patientData.doctorIds?.includes(practitionerProfile.id)) {
+      return;
+    }
+  }
+
+  if (requesterRoles.includes(UserRole.CLINIC_ADMIN)) {
+    const adminProfile = await getClinicAdminByUserRef(db, requesterId);
+    if (adminProfile && adminProfile.clinicsManaged) {
+      const hasAccess = adminProfile.clinicsManaged.some((managedClinicId) =>
+        patientData.clinicIds?.includes(managedClinicId)
+      );
+      if (hasAccess) {
+        return;
+      }
+    }
+  }
+
+  throw new AuthError(
+    'Unauthorized access to skin quality assessment.',
+    'AUTH/UNAUTHORIZED_ACCESS',
+    403
+  );
+};
+
+export const calculateSkinQualityCompletionPercentage = (data: Partial<SkinQualityAssessment>): number => {
+  let completed = 0;
+  const total = 4;
+
+  if (data.characteristics) completed++;
+  if (data.conditions && data.conditions.length > 0) completed++;
+  if (data.zoneAssessments && data.zoneAssessments.length > 0) completed++;
+  if (data.scales && (data.scales.fitzpatrick || data.scales.glogau || data.scales.elastosis)) completed++;
+
+  return Math.round((completed / total) * 100);
+};
+
+export const determineSkinQualityStatus = (completionPercentage: number): SkinQualityAssessmentStatus => {
+  if (completionPercentage < 50) return 'incomplete';
+  if (completionPercentage >= 50) return 'ready_for_planning';
+  return 'incomplete';
+};
+
+export const getSkinQualityAssessmentUtil = async (
+  db: Firestore,
+  patientId: string,
+  requesterId: string,
+  requesterRoles: UserRole[]
+): Promise<SkinQualityAssessment | null> => {
+  await checkSkinQualityAssessmentAccessUtil(db, patientId, requesterId, requesterRoles);
+
+  const docRef = getSkinQualityAssessmentDocRef(db, patientId);
+  const snapshot = await getDoc(docRef);
+
+  if (!snapshot.exists()) {
+    return null;
+  }
+
+  const data = snapshot.data();
+  return skinQualityAssessmentSchema.parse({
+    ...data,
+    id: patientId,
+  });
+};
+
+export const createOrUpdateSkinQualityAssessmentUtil = async (
+  db: Firestore,
+  patientId: string,
+  data: CreateSkinQualityAssessmentData | UpdateSkinQualityAssessmentData,
+  requesterId: string,
+  requesterRoles: UserRole[],
+  isUpdate: boolean = false
+): Promise<void> => {
+  await checkSkinQualityAssessmentAccessUtil(db, patientId, requesterId, requesterRoles);
+
+  const validatedData = isUpdate
+    ? updateSkinQualityAssessmentSchema.parse(data)
+    : createSkinQualityAssessmentSchema.parse(data);
+
+  const docRef = getSkinQualityAssessmentDocRef(db, patientId);
+  const snapshot = await getDoc(docRef);
+
+  const requesterRole = requesterRoles.includes(UserRole.PRACTITIONER) ? 'PRACTITIONER' : 'PATIENT';
+
+  const existingData = snapshot.exists() ? snapshot.data() : null;
+  const mergedData: any = {
+    ...(existingData || {}),
+    ...validatedData,
+  };
+
+  const completionPercentage = calculateSkinQualityCompletionPercentage(mergedData);
+  const status = determineSkinQualityStatus(completionPercentage);
+
+  if (!snapshot.exists()) {
+    await setDoc(docRef, {
+      id: patientId,
+      patientId,
+      conditions: [],
+      zoneAssessments: [],
+      scales: {},
+      ...validatedData,
+      completionPercentage,
+      status,
+      lastUpdatedBy: requesterId,
+      lastUpdatedByRole: requesterRole,
+      createdAt: serverTimestamp(),
+      updatedAt: serverTimestamp(),
+    });
+  } else {
+    await updateDoc(docRef, {
+      ...validatedData,
+      completionPercentage,
+      status,
+      lastUpdatedBy: requesterId,
+      lastUpdatedByRole: requesterRole,
+      updatedAt: serverTimestamp(),
+    });
+  }
+};

package/src/types/patient/body-assessment.types.ts

@@ -0,0 +1,93 @@
+import { Timestamp } from 'firebase/firestore';
+
+export const BODY_ASSESSMENT_COLLECTION = 'body-assessment';
+
+export type BodyAssessmentStatus = 'incomplete' | 'ready_for_planning' | 'treatment_planned';
+
+export type BodyZone =
+  | 'abdomen'
+  | 'flanks'
+  | 'back'
+  | 'upper_arms'
+  | 'thighs_inner'
+  | 'thighs_outer'
+  | 'buttocks'
+  | 'chest'
+  | 'knees'
+  | 'submental';
+
+export type SeverityLevel = 'none' | 'mild' | 'moderate' | 'severe';
+export type MuscleDefinitionLevel = 'well_defined' | 'moderate' | 'poor' | 'none';
+
+export interface BodyZoneAssessment {
+  zone: BodyZone;
+  fatDeposit: SeverityLevel;
+  skinLaxity: SeverityLevel;
+  stretchMarks: SeverityLevel;
+  cellulite: SeverityLevel;
+  muscleDefinition: MuscleDefinitionLevel;
+  notes?: string;
+}
+
+export interface BodyCompositionData {
+  bmi?: number;
+  bodyFatPercentage?: number;
+  waistHipRatio?: number;
+  weight?: number;
+  height?: number;
+}
+
+export interface BodyMeasurementsData {
+  waist?: number;
+  hips?: number;
+  chest?: number;
+  upperArm?: number;
+  thigh?: number;
+  units: 'cm' | 'inches';
+}
+
+export interface BodySymmetryData {
+  overallSymmetry: 'symmetric' | 'mild_asymmetry' | 'moderate_asymmetry' | 'significant_asymmetry';
+  notes?: string;
+  affectedAreas?: string[];
+}
+
+export interface BodyAssessment {
+  id: string;
+  patientId: string;
+  appointmentId?: string;
+
+  selectedZones: BodyZone[];
+  zoneAssessments: BodyZoneAssessment[];
+  composition?: BodyCompositionData;
+  measurements?: BodyMeasurementsData;
+  symmetry?: BodySymmetryData;
+
+  completionPercentage: number;
+  status: BodyAssessmentStatus;
+
+  lastUpdatedBy: string;
+  lastUpdatedByRole: 'PATIENT' | 'PRACTITIONER';
+
+  createdAt?: Timestamp | any;
+  updatedAt?: Timestamp | any;
+}
+
+export interface CreateBodyAssessmentData {
+  patientId: string;
+  appointmentId?: string;
+  selectedZones?: BodyZone[];
+  zoneAssessments?: BodyZoneAssessment[];
+  composition?: BodyCompositionData;
+  measurements?: BodyMeasurementsData;
+  symmetry?: BodySymmetryData;
+}
+
+export interface UpdateBodyAssessmentData {
+  appointmentId?: string;
+  selectedZones?: BodyZone[];
+  zoneAssessments?: BodyZoneAssessment[];
+  composition?: BodyCompositionData;
+  measurements?: BodyMeasurementsData;
+  symmetry?: BodySymmetryData;
+}

package/src/types/patient/hair-scalp-assessment.types.ts

@@ -0,0 +1,98 @@
+import { Timestamp } from 'firebase/firestore';
+
+export const HAIR_SCALP_ASSESSMENT_COLLECTION = 'hair-scalp-assessment';
+
+export type HairScalpAssessmentStatus = 'incomplete' | 'ready_for_planning' | 'treatment_planned';
+
+export type NorwoodStage = 'I' | 'II' | 'IIa' | 'III' | 'IIIa' | 'III_vertex' | 'IV' | 'IVa' | 'V' | 'Va' | 'VI' | 'VII';
+export type LudwigStage = 'I' | 'II' | 'III';
+export type HairLossType = 'androgenetic' | 'diffuse' | 'areata' | 'traction' | 'scarring' | 'telogen_effluvium';
+
+export interface HairLossPattern {
+  type: HairLossType;
+  norwoodStage?: NorwoodStage;
+  ludwigStage?: LudwigStage;
+  onsetDuration?: string;
+  familyHistory?: boolean;
+  notes?: string;
+}
+
+export type HairType = 'straight' | 'wavy' | 'curly' | 'coily';
+export type HairDensity = 'high' | 'medium' | 'low' | 'very_low';
+export type HairColor = 'black' | 'dark_brown' | 'brown' | 'light_brown' | 'blonde' | 'red' | 'grey' | 'white';
+export type HairTextureGrade = 'fine' | 'medium' | 'coarse';
+
+export interface HairCharacteristics {
+  type: HairType;
+  density: HairDensity;
+  color: HairColor;
+  texture: HairTextureGrade;
+  diameter?: 'thin' | 'medium' | 'thick';
+}
+
+export type ScalpScalinessLevel = 'none' | 'mild' | 'moderate' | 'severe';
+export type ScalpRednessLevel = 'none' | 'mild' | 'moderate' | 'severe';
+export type ScalpSebumLevel = 'dry' | 'normal' | 'oily' | 'very_oily';
+
+export interface ScalpCondition {
+  scaliness: ScalpScalinessLevel;
+  redness: ScalpRednessLevel;
+  sebum: ScalpSebumLevel;
+  folliculitis: boolean;
+  scarring: boolean;
+  notes?: string;
+}
+
+export type HairLossZone =
+  | 'frontal'
+  | 'temporal_left'
+  | 'temporal_right'
+  | 'mid_scalp'
+  | 'vertex'
+  | 'occipital'
+  | 'parietal_left'
+  | 'parietal_right';
+
+export interface HairLossZoneAssessment {
+  zone: HairLossZone;
+  miniaturization: 'none' | 'mild' | 'moderate' | 'severe';
+  density: HairDensity;
+  notes?: string;
+}
+
+export interface HairScalpAssessment {
+  id: string;
+  patientId: string;
+  appointmentId?: string;
+
+  hairLossPattern?: HairLossPattern;
+  hairCharacteristics?: HairCharacteristics;
+  scalpCondition?: ScalpCondition;
+  zoneAssessments: HairLossZoneAssessment[];
+
+  completionPercentage: number;
+  status: HairScalpAssessmentStatus;
+
+  lastUpdatedBy: string;
+  lastUpdatedByRole: 'PATIENT' | 'PRACTITIONER';
+
+  createdAt?: Timestamp | any;
+  updatedAt?: Timestamp | any;
+}
+
+export interface CreateHairScalpAssessmentData {
+  patientId: string;
+  appointmentId?: string;
+  hairLossPattern?: HairLossPattern;
+  hairCharacteristics?: HairCharacteristics;
+  scalpCondition?: ScalpCondition;
+  zoneAssessments?: HairLossZoneAssessment[];
+}
+
+export interface UpdateHairScalpAssessmentData {
+  appointmentId?: string;
+  hairLossPattern?: HairLossPattern;
+  hairCharacteristics?: HairCharacteristics;
+  scalpCondition?: ScalpCondition;
+  zoneAssessments?: HairLossZoneAssessment[];
+}

package/src/types/patient/index.ts

@@ -259,6 +259,10 @@ export interface RequesterInfo {
 
 export * from "./medical-info.types";
 export * from "./aesthetic-analysis.types";
+export * from "./skin-quality-assessment.types";
+export * from "./body-assessment.types";
+export * from "./hair-scalp-assessment.types";
+export * from "./pre-surgical-assessment.types";
 
 // This is a type that combines all the patient data - used only in UI Frontend App
 export interface PatientProfileComplete {

package/src/types/patient/pre-surgical-assessment.types.ts

@@ -0,0 +1,95 @@
+import { Timestamp } from 'firebase/firestore';
+
+export const PRE_SURGICAL_ASSESSMENT_COLLECTION = 'pre-surgical-assessment';
+
+export type PreSurgicalAssessmentStatus = 'incomplete' | 'ready_for_planning' | 'treatment_planned';
+
+export type ASAClassification = 'I' | 'II' | 'III' | 'IV';
+
+export interface AnesthesiaHistory {
+  previousAnesthesia: boolean;
+  adverseReactions?: boolean;
+  reactionDetails?: string;
+  preferredType?: 'local' | 'regional' | 'general' | 'sedation';
+  malignantHyperthermiaRisk?: boolean;
+}
+
+export type BleedingRiskLevel = 'low' | 'moderate' | 'high';
+
+export interface BleedingRisk {
+  level: BleedingRiskLevel;
+  anticoagulantUse: boolean;
+  anticoagulantDetails?: string;
+  bleedingDisorderHistory: boolean;
+  bleedingDisorderDetails?: string;
+}
+
+export type TissueQualityLevel = 'excellent' | 'good' | 'fair' | 'poor';
+
+export interface SurgicalSiteAssessment {
+  site: string;
+  skinQuality: TissueQualityLevel;
+  scarringHistory: 'none' | 'normal' | 'hypertrophic' | 'keloid';
+  tissueQuality: TissueQualityLevel;
+  previousSurgery: boolean;
+  previousSurgeryDetails?: string;
+  notes?: string;
+}
+
+export interface LabResult {
+  name: string;
+  value: string;
+  unit?: string;
+  date?: string;
+  isNormal?: boolean;
+  notes?: string;
+}
+
+export type SmokingStatus = 'never' | 'former' | 'current' | 'quit_recently';
+export type ClearanceStatus = 'not_required' | 'pending' | 'obtained' | 'denied';
+
+export interface PreSurgicalAssessment {
+  id: string;
+  patientId: string;
+  appointmentId?: string;
+
+  asaClassification?: ASAClassification;
+  anesthesiaHistory?: AnesthesiaHistory;
+  bleedingRisk?: BleedingRisk;
+  surgicalSiteAssessments: SurgicalSiteAssessment[];
+  labResults: LabResult[];
+  smokingStatus?: SmokingStatus;
+  clearance: ClearanceStatus;
+
+  completionPercentage: number;
+  status: PreSurgicalAssessmentStatus;
+
+  lastUpdatedBy: string;
+  lastUpdatedByRole: 'PATIENT' | 'PRACTITIONER';
+
+  createdAt?: Timestamp | any;
+  updatedAt?: Timestamp | any;
+}
+
+export interface CreatePreSurgicalAssessmentData {
+  patientId: string;
+  appointmentId?: string;
+  asaClassification?: ASAClassification;
+  anesthesiaHistory?: AnesthesiaHistory;
+  bleedingRisk?: BleedingRisk;
+  surgicalSiteAssessments?: SurgicalSiteAssessment[];
+  labResults?: LabResult[];
+  smokingStatus?: SmokingStatus;
+  clearance?: ClearanceStatus;
+}
+
+export interface UpdatePreSurgicalAssessmentData {
+  appointmentId?: string;
+  asaClassification?: ASAClassification;
+  anesthesiaHistory?: AnesthesiaHistory;
+  bleedingRisk?: BleedingRisk;
+  surgicalSiteAssessments?: SurgicalSiteAssessment[];
+  labResults?: LabResult[];
+  smokingStatus?: SmokingStatus;
+  clearance?: ClearanceStatus;
+}

package/src/types/patient/skin-quality-assessment.types.ts

@@ -0,0 +1,105 @@
+import { Timestamp } from 'firebase/firestore';
+
+export const SKIN_QUALITY_ASSESSMENT_COLLECTION = 'skin-quality-assessment';
+
+export type SkinQualityAssessmentStatus = 'incomplete' | 'ready_for_planning' | 'treatment_planned';
+
+export type SkinHydrationLevel = 'very_dry' | 'dry' | 'normal' | 'oily' | 'very_oily';
+export type SkinSensitivityLevel = 'none' | 'mild' | 'moderate' | 'severe';
+export type SkinElasticityLevel = 'excellent' | 'good' | 'fair' | 'poor';
+export type PoreSizeLevel = 'fine' | 'small' | 'medium' | 'large' | 'very_large';
+export type SkinTextureLevel = 'smooth' | 'slightly_rough' | 'rough' | 'very_rough';
+
+export interface SkinCharacteristics {
+  hydration: SkinHydrationLevel;
+  oiliness: SkinHydrationLevel;
+  sensitivity: SkinSensitivityLevel;
+  elasticity: SkinElasticityLevel;
+  poreSize: PoreSizeLevel;
+  texture: SkinTextureLevel;
+}
+
+export type SkinConditionType =
+  | 'acne'
+  | 'rosacea'
+  | 'melasma'
+  | 'hyperpigmentation'
+  | 'hypopigmentation'
+  | 'eczema'
+  | 'psoriasis'
+  | 'sun_damage'
+  | 'scarring'
+  | 'keratosis';
+
+export interface SkinConditionEntry {
+  type: SkinConditionType;
+  severity: string;
+  location?: string;
+  notes?: string;
+}
+
+export type SkinZone =
+  | 'forehead'
+  | 'periorbital'
+  | 'cheeks'
+  | 'nose'
+  | 'perioral'
+  | 'chin'
+  | 'neck'
+  | 'decolletage';
+
+export interface SkinZoneAssessment {
+  zone: SkinZone;
+  pigmentation: string;
+  texture: string;
+  vascularity: string;
+  photoaging: string;
+  notes?: string;
+}
+
+export type FitzpatrickType = 'I' | 'II' | 'III' | 'IV' | 'V' | 'VI';
+export type GlogauClassification = 'I' | 'II' | 'III' | 'IV';
+export type ElastosisGrade = 'none' | 'mild' | 'moderate' | 'severe';
+
+export interface SkinQualityScales {
+  fitzpatrick?: FitzpatrickType;
+  glogau?: GlogauClassification;
+  elastosis?: ElastosisGrade;
+}
+
+export interface SkinQualityAssessment {
+  id: string;
+  patientId: string;
+  appointmentId?: string;
+
+  characteristics?: SkinCharacteristics;
+  conditions: SkinConditionEntry[];
+  zoneAssessments: SkinZoneAssessment[];
+  scales: SkinQualityScales;
+
+  completionPercentage: number;
+  status: SkinQualityAssessmentStatus;
+
+  lastUpdatedBy: string;
+  lastUpdatedByRole: 'PATIENT' | 'PRACTITIONER';
+
+  createdAt?: Timestamp | any;
+  updatedAt?: Timestamp | any;
+}
+
+export interface CreateSkinQualityAssessmentData {
+  patientId: string;
+  appointmentId?: string;
+  characteristics?: SkinCharacteristics;
+  conditions?: SkinConditionEntry[];
+  zoneAssessments?: SkinZoneAssessment[];
+  scales?: SkinQualityScales;
+}
+
+export interface UpdateSkinQualityAssessmentData {
+  appointmentId?: string;
+  characteristics?: SkinCharacteristics;
+  conditions?: SkinConditionEntry[];
+  zoneAssessments?: SkinZoneAssessment[];
+  scales?: SkinQualityScales;
+}

package/src/validations/patient/body-assessment.schema.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+
+export const bodyZoneAssessmentSchema = z.object({
+  zone: z.enum([
+    'abdomen', 'flanks', 'back', 'upper_arms', 'thighs_inner',
+    'thighs_outer', 'buttocks', 'chest', 'knees', 'submental',
+  ]),
+  fatDeposit: z.enum(['none', 'mild', 'moderate', 'severe']),
+  skinLaxity: z.enum(['none', 'mild', 'moderate', 'severe']),
+  stretchMarks: z.enum(['none', 'mild', 'moderate', 'severe']),
+  cellulite: z.enum(['none', 'mild', 'moderate', 'severe']),
+  muscleDefinition: z.enum(['well_defined', 'moderate', 'poor', 'none']),
+  notes: z.string().optional(),
+});
+
+export const bodyCompositionSchema = z.object({
+  bmi: z.number().optional(),
+  bodyFatPercentage: z.number().min(0).max(100).optional(),
+  waistHipRatio: z.number().optional(),
+  weight: z.number().optional(),
+  height: z.number().optional(),
+});
+
+export const bodyMeasurementsSchema = z.object({
+  waist: z.number().optional(),
+  hips: z.number().optional(),
+  chest: z.number().optional(),
+  upperArm: z.number().optional(),
+  thigh: z.number().optional(),
+  units: z.enum(['cm', 'inches']),
+});
+
+export const bodySymmetrySchema = z.object({
+  overallSymmetry: z.enum(['symmetric', 'mild_asymmetry', 'moderate_asymmetry', 'significant_asymmetry']),
+  notes: z.string().optional(),
+  affectedAreas: z.array(z.string()).optional(),
+});
+
+export const createBodyAssessmentSchema = z.object({
+  patientId: z.string().min(1, 'Patient ID is required'),
+  appointmentId: z.string().optional(),
+  selectedZones: z.array(z.enum([
+    'abdomen', 'flanks', 'back', 'upper_arms', 'thighs_inner',
+    'thighs_outer', 'buttocks', 'chest', 'knees', 'submental',
+  ])).optional(),
+  zoneAssessments: z.array(bodyZoneAssessmentSchema).optional(),
+  composition: bodyCompositionSchema.optional(),
+  measurements: bodyMeasurementsSchema.optional(),
+  symmetry: bodySymmetrySchema.optional(),
+});
+
+export const updateBodyAssessmentSchema = z.object({
+  appointmentId: z.string().optional(),
+  selectedZones: z.array(z.enum([
+    'abdomen', 'flanks', 'back', 'upper_arms', 'thighs_inner',
+    'thighs_outer', 'buttocks', 'chest', 'knees', 'submental',
+  ])).optional(),
+  zoneAssessments: z.array(bodyZoneAssessmentSchema).optional(),
+  composition: bodyCompositionSchema.optional(),
+  measurements: bodyMeasurementsSchema.optional(),
+  symmetry: bodySymmetrySchema.optional(),
+}).partial();
+
+export const bodyAssessmentSchema = z.object({
+  id: z.string(),
+  patientId: z.string(),
+  appointmentId: z.string().optional(),
+  selectedZones: z.array(z.enum([
+    'abdomen', 'flanks', 'back', 'upper_arms', 'thighs_inner',
+    'thighs_outer', 'buttocks', 'chest', 'knees', 'submental',
+  ])),
+  zoneAssessments: z.array(bodyZoneAssessmentSchema),
+  composition: bodyCompositionSchema.optional(),
+  measurements: bodyMeasurementsSchema.optional(),
+  symmetry: bodySymmetrySchema.optional(),
+  completionPercentage: z.number().min(0).max(100),
+  status: z.enum(['incomplete', 'ready_for_planning', 'treatment_planned']),
+  lastUpdatedBy: z.string(),
+  lastUpdatedByRole: z.enum(['PATIENT', 'PRACTITIONER']),
+  createdAt: z.any(),
+  updatedAt: z.any(),
+});