@hed-hog/contact 0.0.266 → 0.0.274

package/src/person/person.service.ts

@@ -1,15 +1,29 @@
 import { DeleteDTO } from '@hed-hog/api';
 import { getLocaleText } from '@hed-hog/api-locale';
 import { PaginationDTO, PaginationService } from '@hed-hog/api-pagination';
-import { PrismaService } from '@hed-hog/api-prisma';
+import { Prisma, PrismaService } from '@hed-hog/api-prisma';
+import { FileService, SettingService } from '@hed-hog/core';
 import {
   BadRequestException,
   Inject,
   Injectable,
+  NotFoundException,
   forwardRef,
 } from '@nestjs/common';
 import { CreateDTO } from './dto/create.dto';
 
+const CONTACT_ALLOW_COMPANY_REGISTRATION_SETTING =
+  'contact-allow-company-registration';
+const CONTACT_OWNER_ROLE_SLUG = 'owner-contact';
+const CONTACT_OWNER_ALLOWED_ROLE_SLUGS = [
+  'admin',
+  'admin-contact',
+  CONTACT_OWNER_ROLE_SLUG,
+];
+type PersonActivityAction = 'created' | 'updated' | 'interaction_created';
+const EMPLOYER_COMPANY_METADATA_KEY = 'employer_company_id';
+const NOTES_METADATA_KEY = 'notes';
+
 @Injectable()
 export class PersonService {
   constructor(
@@ -17,9 +31,35 @@ export class PersonService {
     private readonly prismaService: PrismaService,
     @Inject(forwardRef(() => PaginationService))
     private readonly paginationService: PaginationService,
+    @Inject(forwardRef(() => FileService))
+    private readonly fileService: FileService,
+    @Inject(forwardRef(() => SettingService))
+    private readonly settingService: SettingService,
   ) {}
 
   async getStats() {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+
+    if (!allowCompanyRegistration) {
+      const [individual, active, inactive] = await Promise.all([
+        this.prismaService.person.count({ where: { type: 'individual' } }),
+        this.prismaService.person.count({
+          where: { type: 'individual', status: 'active' },
+        }),
+        this.prismaService.person.count({
+          where: { type: 'individual', status: 'inactive' },
+        }),
+      ]);
+
+      return {
+        total: individual,
+        individual,
+        company: 0,
+        active,
+        inactive,
+      };
+    }
+
     const [total, individual, company, active, inactive] = await Promise.all([
       this.prismaService.person.count(),
       this.prismaService.person.count({ where: { type: 'individual' } }),
@@ -37,173 +77,266 @@ export class PersonService {
     };
   }
 
-  async list(paginationParams: PaginationDTO & { type: string; status: string }) {
-    const OR: any[] = [];
-    const search = paginationParams.search?.trim();
+  async getOwnerOptions(currentUserId?: number) {
+    const where: Prisma.userWhereInput = {
+      OR: [
+        {
+          role_user: {
+            some: {
+              role: {
+                slug: {
+                  in: CONTACT_OWNER_ALLOWED_ROLE_SLUGS,
+                },
+              },
+            },
+          },
+        },
+        ...(Number(currentUserId) > 0
+          ? [
+              {
+                id: Number(currentUserId),
+              },
+            ]
+          : []),
+      ],
+    };
 
-    if (search) {
-      if (!isNaN(+search)) {
-        OR.push({ id: { equals: +search } });
-      }
-      OR.push({ name: { contains: search, mode: 'insensitive' } });
+    const users = await this.prismaService.user.findMany({
+      where,
+      select: {
+        id: true,
+        name: true,
+      },
+      orderBy: {
+        name: 'asc',
+      },
+      take: 500,
+    });
+
+    const byId = new Map<number, { id: number; name: string }>();
+    for (const user of users) {
+      if (!user?.id) continue;
+      byId.set(user.id, {
+        id: user.id,
+        name: user.name || `#${user.id}`,
+      });
     }
 
+    return Array.from(byId.values());
+  }
+
+  async list(
+    paginationParams: PaginationDTO & {
+      type?: string;
+      status?: string;
+      owner_user_id?: string | number;
+      source?: string;
+      lifecycle_stage?: string;
+      follow_up_status?: string;
+      mine?: string | boolean;
+    },
+    currentUserId?: number,
+  ) {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
     const where: any = {};
-    if (OR.length > 0) {
-      where.OR = OR;
+    const search = paginationParams.search?.trim();
+    const requestedType = paginationParams.type;
+
+    if (!allowCompanyRegistration && requestedType === 'company') {
+      return this.paginationService.paginate(
+        this.prismaService.person,
+        paginationParams,
+        {
+          where: {
+            id: -1,
+          },
+        },
+      );
     }
 
-    if (paginationParams.type && paginationParams.type !== 'all') {
-      where.type = paginationParams.type;
+    if (!allowCompanyRegistration) {
+      where.type = 'individual';
+    } else if (requestedType && requestedType !== 'all') {
+      where.type = requestedType;
     }
+
     if (paginationParams.status && paginationParams.status !== 'all') {
       where.status = paginationParams.status;
     }
 
-    return this.paginationService.paginate(
+    if (search) {
+      where.OR = await this.buildSearchFilters(search);
+    }
+
+    const result = await this.paginationService.paginate(
       this.prismaService.person,
       paginationParams,
       {
         where,
         include: {
-          address: true,
+          person_address: {
+            include: {
+              address: true,
+            },
+          },
           contact: true,
           document: true,
+          person_metadata: true,
         },
       },
     );
-  }
 
-  async get(locale: string, id: number) {
-    const person = await this.prismaService.person.findUnique({ where: { id } });
-    if (!person) {
-      throw new BadRequestException(getLocaleText('personNotFound', locale, `Person with ID ${id} not found`));
-    }
+    const enriched = await this.enrichPeople(
+      result.data as any[],
+      allowCompanyRegistration,
+    );
 
-    return person
+    return {
+      ...result,
+      data: enriched,
+    };
   }
 
-  async create(data: CreateDTO) {
-    return this.prismaService.person.create({
-      data,
+  async get(locale: string, id: number) {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+
+    const person = await this.prismaService.person.findUnique({
+      where: { id },
+      include: {
+        person_address: {
+          include: {
+            address: true,
+          },
+        },
+        contact: true,
+        document: true,
+        person_metadata: true,
+      },
     });
-  }
 
-  async update(id: number, data: any, locale: string) {
-    const person = await this.prismaService.person.findUnique({ where: { id } });
     if (!person) {
-      throw new BadRequestException(getLocaleText('personNotFound', locale, `Person with ID ${id} not found`));
+      throw new BadRequestException(
+        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
+      );
     }
 
-    const incomingContacts = data.contacts || [];
-    const incomingAddresses = data.addresses || [];
-    const incomingDocuments = data.documents || [];
-    const contactPrimaryMap = new Map();
-    for (const c of incomingContacts) {
-      if (c.is_primary) {
-        const key = String(c.contact_type_id);
-        contactPrimaryMap.set(key, (contactPrimaryMap.get(key) || 0) + 1);
-      }
-    }
-    for (const [_, count] of contactPrimaryMap.entries()) {
-      if (count > 1) {
-        throw new BadRequestException(
-          getLocaleText('moreThanOnePrimaryContact', locale, 'More than one contact of the same type cannot be marked as primary.')
-        );
-      }
+    if (!allowCompanyRegistration && person.type === 'company') {
+      throw new NotFoundException(
+        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
+      );
     }
 
-    const addressPrimaryMap = new Map();
-    for (const a of incomingAddresses) {
-      if (a.is_primary) {
-        const key = String(a.address_type_id);
-        addressPrimaryMap.set(key, (addressPrimaryMap.get(key) || 0) + 1);
-      }
-    }
-    for (const [_, count] of addressPrimaryMap.entries()) {
-      if (count > 1) {
-        throw new BadRequestException(
-          getLocaleText('moreThanOnePrimaryAddress', locale, 'More than one address of the same type cannot be marked as primary.')
-        );
-      }
-    }
+    const [normalized] = await this.enrichPeople(
+      [person as any],
+      allowCompanyRegistration,
+    );
+    return normalized;
+  }
 
-    const documentPrimaryMap = new Map();
-    for (const d of incomingDocuments) {
-      if (d.is_primary) {
-        const key = String(d.document_type_id);
-        documentPrimaryMap.set(key, (documentPrimaryMap.get(key) || 0) + 1);
-      }
-    }
-    for (const [_, count] of documentPrimaryMap.entries()) {
-      if (count > 1) {
-        throw new BadRequestException(
-          getLocaleText('moreThanOnePrimaryDocument', locale, 'More than one document of the same type cannot be marked as primary.')
-        );
-      }
-    }
+  async create(data: CreateDTO, locale: string) {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+
+    await this.ensureCompanyRegistrationAllowed({
+      nextType: data.type,
+      locale,
+    });
 
     return this.prismaService.$transaction(async (tx) => {
-      await tx.person.update({
-        where: { id },
+      const person = await tx.person.create({
         data: {
           name: data.name,
           type: data.type,
           status: data.status,
+          avatar_id: data.avatar_id ?? null,
         },
       });
 
-      const existingContacts = await tx.contact.findMany({ where: { person_id: id } });
-      for (const c of incomingContacts) {
-        if (c.id) {
-          await tx.contact.update({ where: { id: c.id }, data: c });
-        } else {
-          await tx.contact.create({ data: { ...c, person_id: id } });
-        }
-      }
+      await this.syncPersonSubtypeData(tx, person.id, null, data, locale);
+      await this.syncPersonMetadata(tx, person.id, {
+        notes: data.notes,
+        employer_company_id: allowCompanyRegistration
+          ? data.employer_company_id ?? null
+          : null,
+      });
 
-      for (const old of existingContacts) {
-        if (!incomingContacts.find((c: any) => c.id === old.id)) {
-          await tx.contact.delete({ where: { id: old.id } });
-        }
-      }
+      return person;
+    });
+  }
 
-      const existingAddresses = await tx.address.findMany({ where: { person_id: id } });
-      for (const a of incomingAddresses) {
-        if (a.id) {
-          await tx.address.update({ where: { id: a.id }, data: a });
-        } else {
-          await tx.address.create({ data: { ...a, person_id: id } });
-        }
-      }
-      for (const old of existingAddresses) {
-        if (!incomingAddresses.find((a: any) => a.id === old.id)) {
-          await tx.address.delete({ where: { id: old.id } });
-        }
-      }
+  async update(id: number, data: any, locale: string) {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+    const person = await this.prismaService.person.findUnique({ where: { id } });
+    if (!person) {
+      throw new BadRequestException(
+        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
+      );
+    }
 
-      const existingDocuments = await tx.document.findMany({ where: { person_id: id } });
-      for (const d of incomingDocuments) {
-        if (d.id) {
-          await tx.document.update({ where: { id: d.id }, data: d });
-        } else {
-          await tx.document.create({ data: { ...d, person_id: id } });
-        }
-      }
-      for (const old of existingDocuments) {
-        if (!incomingDocuments.find((d: any) => d.id === old.id)) {
-          await tx.document.delete({ where: { id: old.id } });
-        }
-      }
+    if (!allowCompanyRegistration && person.type === 'company') {
+      throw new NotFoundException(
+        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
+      );
+    }
 
-      return { success: true };
+    await this.ensureCompanyRegistrationAllowed({
+      currentType: person.type,
+      nextType: data.type,
+      locale,
     });
+
+    const incomingContacts = Array.isArray(data.contacts) ? data.contacts : [];
+    const incomingAddresses = Array.isArray(data.addresses) ? data.addresses : [];
+    const incomingDocuments = Array.isArray(data.documents) ? data.documents : [];
+
+    this.validateSinglePrimaryPerType(incomingContacts, 'contact_type_id', locale, 'moreThanOnePrimaryContact', 'More than one contact of the same type cannot be marked as primary.');
+    this.validateSinglePrimaryPerType(incomingAddresses, 'address_type', locale, 'moreThanOnePrimaryAddress', 'More than one address of the same type cannot be marked as primary.');
+    this.validateSinglePrimaryPerType(incomingDocuments, 'document_type_id', locale, 'moreThanOnePrimaryDocument', 'More than one document of the same type cannot be marked as primary.');
+
+    return this.prismaService
+      .$transaction(async (tx) => {
+        const nextType = data.type ?? person.type;
+
+        await tx.person.update({
+          where: { id },
+          data: {
+            name: data.name ?? person.name,
+            type: nextType,
+            status: data.status ?? person.status,
+            avatar_id:
+              data.avatar_id === undefined ? person.avatar_id : data.avatar_id,
+          },
+        });
+
+        await this.syncPersonSubtypeData(tx, id, person.type, data, locale);
+        await this.syncPersonMetadata(tx, id, {
+          notes: data.notes,
+          employer_company_id: allowCompanyRegistration
+            ? data.employer_company_id === undefined
+              ? undefined
+              : data.employer_company_id
+            : null,
+        });
+
+        await this.syncContacts(tx, id, incomingContacts);
+        await this.syncAddresses(tx, id, incomingAddresses, locale);
+        await this.syncDocuments(tx, id, incomingDocuments);
+
+        return { success: true };
+      })
+      .then(async (result) => {
+        await this.cleanupReplacedAvatar(locale, person.avatar_id, data.avatar_id);
+        return result;
+      });
   }
 
   async delete({ ids }: DeleteDTO, locale: string) {
     if (ids == undefined || ids == null) {
       throw new BadRequestException(
-        getLocaleText('deleteItemsRequired', locale, 'You must select at least one item to delete.'),
+        getLocaleText(
+          'deleteItemsRequired',
+          locale,
+          'You must select at least one item to delete.',
+        ),
       );
     }
 
@@ -211,22 +344,62 @@ export class PersonService {
       where: { id: { in: ids } },
       select: { id: true },
     });
-    const existingIds = existing.map(p => p.id);
-    const missingIds = ids.filter(id => !existingIds.includes(id));
+    const existingIds = existing.map((p) => p.id);
+    const missingIds = ids.filter((itemId) => !existingIds.includes(itemId));
     if (missingIds.length > 0) {
       throw new BadRequestException(
         getLocaleText(
           'personNotFound',
           locale,
-          `Person(s) with ID(s) ${missingIds.join(', ')} not found.`
-        )
+          `Person(s) with ID(s) ${missingIds.join(', ')} not found.`,
+        ),
       );
     }
 
+    const personAddresses = await this.prismaService.person_address.findMany({
+      where: {
+        person_id: { in: ids },
+      },
+      select: {
+        id: true,
+        address_id: true,
+      },
+    });
+
+    const addressIds = personAddresses.map((item) => item.address_id);
+
     return this.prismaService.$transaction([
       this.prismaService.contact.deleteMany({ where: { person_id: { in: ids } } }),
-      this.prismaService.address.deleteMany({ where: { person_id: { in: ids } } }),
       this.prismaService.document.deleteMany({ where: { person_id: { in: ids } } }),
+      this.prismaService.person_individual_relation.deleteMany({
+        where: {
+          OR: [
+            { person_individual_id: { in: ids } },
+            { related_person_individual_id: { in: ids } },
+          ],
+        },
+      }),
+      this.prismaService.person_company.deleteMany({
+        where: {
+          OR: [{ id: { in: ids } }, { headquarter_id: { in: ids } }],
+        },
+      }),
+      this.prismaService.person_individual.deleteMany({
+        where: { id: { in: ids } },
+      }),
+      this.prismaService.person_metadata.deleteMany({
+        where: { person_id: { in: ids } },
+      }),
+      this.prismaService.person_address.deleteMany({
+        where: { person_id: { in: ids } },
+      }),
+      this.prismaService.address.deleteMany({
+        where: {
+          id: {
+            in: addressIds,
+          },
+        },
+      }),
       this.prismaService.person.deleteMany({
         where: {
           id: {
@@ -236,4 +409,729 @@ export class PersonService {
       }),
     ]);
   }
+
+  async openPublicAvatar(locale: string, fileId: number, res: any) {
+    const personWithAvatar = await this.prismaService.person.findFirst({
+      where: {
+        avatar_id: fileId,
+      },
+      select: {
+        id: true,
+      },
+    });
+
+    if (!personWithAvatar) {
+      throw new NotFoundException(
+        getLocaleText('personNotFound', locale, 'Person not found'),
+      );
+    }
+
+    const { file, buffer } = await this.fileService.getBuffer(fileId);
+
+    res.set({
+      'Content-Type': file.file_mimetype.name,
+      'Content-Length': buffer.length,
+      'Cache-Control': 'public, max-age=3600',
+    });
+
+    res.send(buffer);
+  }
+
+  private async enrichPeople(people: any[], allowCompanyRegistration = true) {
+    if (people.length === 0) {
+      return [];
+    }
+
+    const personIds = people.map((person) => person.id);
+
+    const [companies, individuals, companyBranches, employerMetadata] =
+      await Promise.all([
+        this.prismaService.person_company.findMany({
+          where: { id: { in: personIds } },
+        }),
+        this.prismaService.person_individual.findMany({
+          where: { id: { in: personIds } },
+        }),
+        this.prismaService.person_company.findMany({
+          where: { headquarter_id: { in: personIds } },
+          select: { id: true, headquarter_id: true },
+        }),
+        this.prismaService.person_metadata.findMany({
+          where: {
+            person_id: { in: personIds },
+            key: EMPLOYER_COMPANY_METADATA_KEY,
+          },
+          select: {
+            person_id: true,
+            value: true,
+          },
+        }).then((metadata) => (allowCompanyRegistration ? metadata : [])),
+      ]);
+
+    const companyById = new Map(companies.map((item) => [item.id, item]));
+    const individualById = new Map(individuals.map((item) => [item.id, item]));
+
+    const branchesByHeadquarterId = new Map<number, number[]>();
+    for (const branch of companyBranches) {
+      if (!branch.headquarter_id) continue;
+      const current = branchesByHeadquarterId.get(branch.headquarter_id) || [];
+      current.push(branch.id);
+      branchesByHeadquarterId.set(branch.headquarter_id, current);
+    }
+
+    const employerCompanyIdByPersonId = new Map<number, number>();
+    for (const meta of employerMetadata) {
+      const employerId = this.coerceNumber(meta.value);
+      if (employerId > 0) {
+        employerCompanyIdByPersonId.set(meta.person_id, employerId);
+      }
+    }
+
+    const employerCompanyIds = Array.from(
+      new Set(Array.from(employerCompanyIdByPersonId.values())),
+    );
+    const employerCompanies =
+      employerCompanyIds.length > 0
+        ? await this.prismaService.person.findMany({
+            where: {
+              id: { in: employerCompanyIds },
+              type: 'company',
+            },
+          })
+        : [];
+    const employerCompanyRows =
+      employerCompanyIds.length > 0
+        ? await this.prismaService.person_company.findMany({
+            where: {
+              id: { in: employerCompanyIds },
+            },
+          })
+        : [];
+    const employerCompanyRowById = new Map(
+      employerCompanyRows.map((item) => [item.id, item]),
+    );
+    const employerCompanyById = new Map(
+      employerCompanies.map((item: any) => [
+        item.id,
+        {
+          ...item,
+          person_company: employerCompanyRowById.get(item.id) ?? null,
+        },
+      ]),
+    );
+
+    return people.map((person) => {
+      const metadata = this.metadataArrayToMap(person.person_metadata);
+      const companyData = companyById.get(person.id);
+      const individualData = individualById.get(person.id);
+      const employerCompanyId = allowCompanyRegistration
+        ? employerCompanyIdByPersonId.get(person.id) ?? null
+        : null;
+      const employerCompany =
+        allowCompanyRegistration && employerCompanyId != null
+          ? this.normalizeRelationPersonSummary(
+              employerCompanyById.get(employerCompanyId),
+            )
+          : null;
+
+      return {
+        id: person.id,
+        name: person.name,
+        type: person.type,
+        status: person.status,
+        avatar_id: person.avatar_id ?? null,
+        created_at: person.created_at,
+        updated_at: person.updated_at,
+        birth_date: individualData?.birth_date ?? null,
+        gender: individualData?.gender ?? null,
+        job_title: individualData?.job_title ?? null,
+        trade_name: companyData?.trade_name ?? null,
+        foundation_date: companyData?.foundation_date ?? null,
+        legal_nature: companyData?.legal_nature ?? null,
+        headquarter_id: companyData?.headquarter_id ?? null,
+        branch_ids: branchesByHeadquarterId.get(person.id) || [],
+        notes: this.metadataToString(metadata.get(NOTES_METADATA_KEY)),
+        employer_company_id: allowCompanyRegistration ? employerCompanyId : null,
+        employer_company: allowCompanyRegistration ? employerCompany : null,
+        contact: person.contact || [],
+        document: person.document || [],
+        address: Array.isArray(person.person_address)
+          ? person.person_address
+              .map((item: any) => item.address)
+              .filter((address: any) => address != null)
+          : [],
+      };
+    });
+  }
+
+  private metadataArrayToMap(metadata: any[]) {
+    const map = new Map<string, unknown>();
+
+    for (const item of Array.isArray(metadata) ? metadata : []) {
+      map.set(item.key, item.value);
+    }
+
+    return map;
+  }
+
+  private metadataToString(value: unknown): string | null {
+    if (value == null) return null;
+    if (typeof value === 'string') return value;
+    if (typeof value === 'number' || typeof value === 'boolean') {
+      return String(value);
+    }
+
+    return null;
+  }
+
+  private async syncPersonSubtypeData(
+    tx: any,
+    personId: number,
+    currentType: string | null,
+    data: any,
+    locale: string,
+  ) {
+    const targetType = data.type ?? currentType;
+    if (!targetType) return;
+
+    if (targetType === 'individual') {
+      await tx.person_company.deleteMany({ where: { id: personId } });
+
+      await tx.person_individual.upsert({
+        where: { id: personId },
+        create: {
+          id: personId,
+          birth_date: this.parseDateOrNull(data.birth_date),
+          gender: data.gender ?? null,
+          job_title: this.normalizeTextOrNull(data.job_title),
+        },
+        update: {
+          birth_date:
+            data.birth_date === undefined
+              ? undefined
+              : this.parseDateOrNull(data.birth_date),
+          gender: data.gender === undefined ? undefined : data.gender ?? null,
+          job_title:
+            data.job_title === undefined
+              ? undefined
+              : this.normalizeTextOrNull(data.job_title),
+        },
+      });
+      return;
+    }
+
+    await tx.person_individual_relation.deleteMany({
+      where: {
+        OR: [
+          { person_individual_id: personId },
+          { related_person_individual_id: personId },
+        ],
+      },
+    });
+    await tx.person_individual.deleteMany({ where: { id: personId } });
+
+    const normalizedHeadquarterId = this.coerceNumber(data.headquarter_id);
+
+    if (normalizedHeadquarterId > 0) {
+      if (normalizedHeadquarterId === personId) {
+        throw new BadRequestException(
+          getLocaleText(
+            'companyRelationSelfReference',
+            locale,
+            'A company cannot be its own headquarter.',
+          ),
+        );
+      }
+
+      const headquarter = await tx.person.findFirst({
+        where: { id: normalizedHeadquarterId, type: 'company' },
+        select: { id: true },
+      });
+
+      if (!headquarter) {
+        throw new BadRequestException(
+          getLocaleText(
+            'companyRelationInvalidTarget',
+            locale,
+            'Only company records can be linked as headquarters or branches.',
+          ),
+        );
+      }
+    }
+
+    await tx.person_company.upsert({
+      where: { id: personId },
+      create: {
+        id: personId,
+        trade_name: this.normalizeTextOrNull(data.trade_name),
+        foundation_date: this.parseDateOrNull(data.foundation_date),
+        legal_nature: this.normalizeTextOrNull(data.legal_nature),
+        headquarter_id: normalizedHeadquarterId > 0 ? normalizedHeadquarterId : null,
+      },
+      update: {
+        trade_name:
+          data.trade_name === undefined
+            ? undefined
+            : this.normalizeTextOrNull(data.trade_name),
+        foundation_date:
+          data.foundation_date === undefined
+            ? undefined
+            : this.parseDateOrNull(data.foundation_date),
+        legal_nature:
+          data.legal_nature === undefined
+            ? undefined
+            : this.normalizeTextOrNull(data.legal_nature),
+        headquarter_id:
+          data.headquarter_id === undefined
+            ? undefined
+            : normalizedHeadquarterId > 0
+              ? normalizedHeadquarterId
+              : null,
+      },
+    });
+
+    if (Object.prototype.hasOwnProperty.call(data, 'branch_ids')) {
+      await this.syncCompanyBranches(tx, personId, data.branch_ids, locale);
+    }
+  }
+
+  private async syncCompanyBranches(
+    tx: any,
+    personId: number,
+    branchIds: number[] | undefined,
+    locale: string,
+  ) {
+    const normalizedBranchIds = Array.from(
+      new Set(
+        (Array.isArray(branchIds) ? branchIds : [])
+          .map((value) => Number(value))
+          .filter((value) => Number.isInteger(value) && value > 0 && value !== personId),
+      ),
+    );
+
+    if (normalizedBranchIds.length > 0) {
+      const companies = await tx.person.findMany({
+        where: {
+          id: { in: normalizedBranchIds },
+          type: 'company',
+        },
+        select: { id: true },
+      });
+
+      if (companies.length !== normalizedBranchIds.length) {
+        throw new BadRequestException(
+          getLocaleText(
+            'companyRelationInvalidTarget',
+            locale,
+            'Only company records can be linked as headquarters or branches.',
+          ),
+        );
+      }
+
+      await tx.person_company.updateMany({
+        where: {
+          id: { in: normalizedBranchIds },
+        },
+        data: {
+          headquarter_id: personId,
+        },
+      });
+    }
+
+    await tx.person_company.updateMany({
+      where: {
+        headquarter_id: personId,
+        id: { notIn: normalizedBranchIds.length > 0 ? normalizedBranchIds : [-1] },
+      },
+      data: {
+        headquarter_id: null,
+      },
+    });
+  }
+
+  private async syncPersonMetadata(
+    tx: any,
+    personId: number,
+    data: { notes?: unknown; employer_company_id?: unknown },
+  ) {
+    if (data.notes !== undefined) {
+      await this.upsertMetadataValue(tx, personId, NOTES_METADATA_KEY, data.notes);
+    }
+
+    if (data.employer_company_id !== undefined) {
+      await this.upsertMetadataValue(
+        tx,
+        personId,
+        EMPLOYER_COMPANY_METADATA_KEY,
+        data.employer_company_id,
+      );
+    }
+  }
+
+  private async upsertMetadataValue(
+    tx: any,
+    personId: number,
+    key: string,
+    value: unknown,
+  ) {
+    const existing = await tx.person_metadata.findFirst({
+      where: {
+        person_id: personId,
+        key,
+      },
+      select: { id: true },
+    });
+
+    const normalizedValue = this.normalizeMetadataValue(value);
+
+    if (normalizedValue == null) {
+      if (existing) {
+        await tx.person_metadata.delete({ where: { id: existing.id } });
+      }
+      return;
+    }
+
+    if (existing) {
+      await tx.person_metadata.update({
+        where: { id: existing.id },
+        data: { value: normalizedValue },
+      });
+      return;
+    }
+
+    await tx.person_metadata.create({
+      data: {
+        person_id: personId,
+        key,
+        value: normalizedValue,
+      },
+    });
+  }
+
+  private normalizeMetadataValue(value: unknown): string | number | boolean | null {
+    if (value == null) return null;
+
+    if (typeof value === 'string') {
+      const trimmed = value.trim();
+      return trimmed.length > 0 ? trimmed : null;
+    }
+
+    if (typeof value === 'number') {
+      return Number.isFinite(value) ? value : null;
+    }
+
+    if (typeof value === 'boolean') {
+      return value;
+    }
+
+    return null;
+  }
+
+  private async syncContacts(tx: any, personId: number, incomingContacts: any[]) {
+    const existingContacts = await tx.contact.findMany({ where: { person_id: personId } });
+
+    for (const contact of incomingContacts) {
+      if (contact.id) {
+        await tx.contact.update({ where: { id: contact.id }, data: contact });
+      } else {
+        await tx.contact.create({ data: { ...contact, person_id: personId } });
+      }
+    }
+
+    for (const old of existingContacts) {
+      if (!incomingContacts.find((item: any) => item.id === old.id)) {
+        await tx.contact.delete({ where: { id: old.id } });
+      }
+    }
+  }
+
+  private async syncAddresses(
+    tx: any,
+    personId: number,
+    incomingAddresses: any[],
+    locale: string,
+  ) {
+    const existingAddresses = await tx.person_address.findMany({
+      where: { person_id: personId },
+      include: { address: true },
+    });
+
+    for (const address of incomingAddresses) {
+      const addressData = {
+        line1: address.line1,
+        line2: address.line2 || '',
+        city: address.city,
+        state: address.state,
+        country_code: address.country_code || 'BRA',
+        postal_code: address.postal_code || '',
+        is_primary: address.is_primary,
+        address_type: address.address_type,
+      };
+
+      if (address.id) {
+        const existingLink = existingAddresses.find(
+          (item: any) => item.address_id === address.id,
+        );
+
+        if (!existingLink) {
+          throw new BadRequestException(
+            getLocaleText(
+              'personNotFound',
+              locale,
+              `Address with ID ${address.id} not found for person ${personId}.`,
+            ),
+          );
+        }
+
+        await tx.address.update({
+          where: { id: address.id },
+          data: addressData,
+        });
+      } else {
+        const createdAddress = await tx.address.create({
+          data: addressData,
+        });
+
+        await tx.person_address.create({
+          data: {
+            person_id: personId,
+            address_id: createdAddress.id,
+          },
+        });
+      }
+    }
+
+    for (const old of existingAddresses) {
+      if (!incomingAddresses.find((item: any) => item.id === old.address_id)) {
+        await tx.person_address.delete({ where: { id: old.id } });
+        await tx.address.delete({ where: { id: old.address_id } });
+      }
+    }
+  }
+
+  private async syncDocuments(tx: any, personId: number, incomingDocuments: any[]) {
+    const existingDocuments = await tx.document.findMany({ where: { person_id: personId } });
+
+    for (const document of incomingDocuments) {
+      if (document.id) {
+        await tx.document.update({ where: { id: document.id }, data: document });
+      } else {
+        await tx.document.create({ data: { ...document, person_id: personId } });
+      }
+    }
+
+    for (const old of existingDocuments) {
+      if (!incomingDocuments.find((item: any) => item.id === old.id)) {
+        await tx.document.delete({ where: { id: old.id } });
+      }
+    }
+  }
+
+  private validateSinglePrimaryPerType(
+    items: any[],
+    groupKey: string,
+    locale: string,
+    localeKey: string,
+    fallbackMessage: string,
+  ) {
+    const map = new Map<string, number>();
+
+    for (const item of items) {
+      if (!item.is_primary) continue;
+
+      const key = String(item[groupKey]);
+      map.set(key, (map.get(key) || 0) + 1);
+    }
+
+    for (const count of map.values()) {
+      if (count > 1) {
+        throw new BadRequestException(getLocaleText(localeKey, locale, fallbackMessage));
+      }
+    }
+  }
+
+  private parseDateOrNull(value: unknown): Date | null {
+    if (!value) return null;
+    const date = value instanceof Date ? value : new Date(String(value));
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+
+  private normalizeTextOrNull(value: unknown): string | null {
+    if (typeof value !== 'string') {
+      return value == null ? null : String(value);
+    }
+
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+
+  private coerceNumber(value: unknown): number {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+  }
+
+  private async buildSearchFilters(search: string) {
+    const normalizedDigits = this.normalizeDigits(search);
+    const filters: any[] = [];
+
+    if (!Number.isNaN(+search)) {
+      filters.push({ id: { equals: +search } });
+    }
+
+    filters.push(
+      { name: { contains: search, mode: 'insensitive' } },
+      {
+        person_metadata: {
+          some: {
+            value: { path: [], equals: search } as any,
+          },
+        },
+      },
+      {
+        contact: {
+          some: {
+            value: { contains: search, mode: 'insensitive' },
+          },
+        },
+      },
+      {
+        document: {
+          some: {
+            value: { contains: search, mode: 'insensitive' },
+          },
+        },
+      },
+      {
+        person_address: {
+          some: {
+            address: {
+              OR: [
+                { line1: { contains: search, mode: 'insensitive' } },
+                { line2: { contains: search, mode: 'insensitive' } },
+                { city: { contains: search, mode: 'insensitive' } },
+                { state: { contains: search, mode: 'insensitive' } },
+                { postal_code: { contains: search, mode: 'insensitive' } },
+                { country_code: { contains: search, mode: 'insensitive' } },
+              ],
+            },
+          },
+        },
+      },
+    );
+
+    if (normalizedDigits.length > 0) {
+      const normalizedMatches =
+        await this.findPersonIdsByNormalizedDigits(normalizedDigits);
+
+      if (normalizedMatches.length > 0) {
+        filters.push({
+          id: {
+            in: normalizedMatches,
+          },
+        });
+      }
+    }
+
+    return filters;
+  }
+
+  private normalizeDigits(value: string) {
+    return value.replace(/\D/g, '');
+  }
+
+  private async findPersonIdsByNormalizedDigits(normalizedDigits: string) {
+    const likeValue = `%${normalizedDigits}%`;
+
+    const rows = await this.prismaService.$queryRaw<Array<{ id: number }>>(
+      Prisma.sql`
+        SELECT DISTINCT p.id
+        FROM person p
+        LEFT JOIN contact c ON c.person_id = p.id
+        LEFT JOIN document d ON d.person_id = p.id
+        LEFT JOIN person_address pa ON pa.person_id = p.id
+        LEFT JOIN address a ON a.id = pa.address_id
+        WHERE regexp_replace(COALESCE(c.value, ''), '[^0-9]+', '', 'g') ILIKE ${likeValue}
+          OR regexp_replace(COALESCE(d.value, ''), '[^0-9]+', '', 'g') ILIKE ${likeValue}
+          OR regexp_replace(COALESCE(a.postal_code, ''), '[^0-9]+', '', 'g') ILIKE ${likeValue}
+      `,
+    );
+
+    return rows.map((row) => row.id);
+  }
+
+  private async ensureCompanyRegistrationAllowed({
+    currentType,
+    nextType,
+    locale,
+  }: {
+    currentType?: string;
+    nextType?: string;
+    locale: string;
+  }) {
+    const targetType = nextType ?? currentType;
+    const isNewCompanyRegistration =
+      targetType === 'company' && currentType !== 'company';
+
+    if (!isNewCompanyRegistration) {
+      return;
+    }
+
+    const settings = await this.settingService.getSettingValues(
+      CONTACT_ALLOW_COMPANY_REGISTRATION_SETTING,
+    );
+
+    if (settings[CONTACT_ALLOW_COMPANY_REGISTRATION_SETTING] !== false) {
+      return;
+    }
+
+    throw new BadRequestException(
+      getLocaleText(
+        'companyRegistrationDisabled',
+        locale,
+        'Company registration is disabled. Only individual records can be created.',
+      ),
+    );
+  }
+
+  private async isCompanyRegistrationAllowed() {
+    const settings = await this.settingService.getSettingValues(
+      CONTACT_ALLOW_COMPANY_REGISTRATION_SETTING,
+    );
+
+    return settings[CONTACT_ALLOW_COMPANY_REGISTRATION_SETTING] !== false;
+  }
+
+  private async cleanupReplacedAvatar(
+    locale: string,
+    previousAvatarId?: number | null,
+    nextAvatarId?: number | null,
+  ) {
+    if (!previousAvatarId || previousAvatarId === nextAvatarId) {
+      return;
+    }
+
+    try {
+      await this.fileService.delete(locale, { ids: [previousAvatarId] });
+    } catch {
+      // Keep the person update successful even if avatar cleanup fails.
+    }
+  }
+
+  private normalizeRelationPersonSummary(person: any) {
+    if (!person) return null;
+
+    const tradeName =
+      person.person_company?.trade_name != null
+        ? String(person.person_company.trade_name)
+        : null;
+
+    return {
+      id: person.id,
+      name: person.name,
+      type: person.type,
+      status: person.status,
+      avatar_id: person.avatar_id ?? null,
+      trade_name: tradeName,
+    };
+  }
 }