@hed-hog/contact 0.0.270 → 0.0.275

package/src/person/person.service.ts

@@ -1,1071 +1,1137 @@
-import { DeleteDTO } from '@hed-hog/api';
-import { getLocaleText } from '@hed-hog/api-locale';
-import { PaginationDTO, PaginationService } from '@hed-hog/api-pagination';
-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 EMPLOYER_COMPANY_METADATA_KEY = 'employer_company_id';
-const NOTES_METADATA_KEY = 'notes';
-
-@Injectable()
-export class PersonService {
-  constructor(
-    @Inject(forwardRef(() => PrismaService))
-    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' } }),
-      this.prismaService.person.count({ where: { type: 'company' } }),
-      this.prismaService.person.count({ where: { status: 'active' } }),
-      this.prismaService.person.count({ where: { status: 'inactive' } }),
-    ]);
-
-    return {
-      total,
-      individual,
-      company,
-      active,
-      inactive,
-    };
-  }
-
-  async list(paginationParams: PaginationDTO & { type: string; status: string }) {
-    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
-    const where: any = {};
-    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 (!allowCompanyRegistration) {
-      where.type = 'individual';
-    } else if (requestedType && requestedType !== 'all') {
-      where.type = requestedType;
-    }
-
-    if (paginationParams.status && paginationParams.status !== 'all') {
-      where.status = paginationParams.status;
-    }
-
-    if (search) {
-      where.OR = await this.buildSearchFilters(search);
-    }
-
-    const result = await this.paginationService.paginate(
-      this.prismaService.person,
-      paginationParams,
-      {
-        where,
-        include: {
-          person_address: {
-            include: {
-              address: true,
-            },
-          },
-          contact: true,
-          document: true,
-          person_metadata: true,
-        },
-      },
-    );
-
-    const enriched = await this.enrichPeople(
-      result.data as any[],
-      allowCompanyRegistration,
-    );
-
-    return {
-      ...result,
-      data: enriched,
-    };
-  }
-
-  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,
-      },
-    });
-
-    if (!person) {
-      throw new BadRequestException(
-        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
-      );
-    }
-
-    if (!allowCompanyRegistration && person.type === 'company') {
-      throw new NotFoundException(
-        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
-      );
-    }
-
-    const [normalized] = await this.enrichPeople(
-      [person as any],
-      allowCompanyRegistration,
-    );
-    return normalized;
-  }
-
-  async create(data: CreateDTO, locale: string) {
-    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
-
-    await this.ensureCompanyRegistrationAllowed({
-      nextType: data.type,
-      locale,
-    });
-
-    return this.prismaService.$transaction(async (tx) => {
-      const person = await tx.person.create({
-        data: {
-          name: data.name,
-          type: data.type,
-          status: data.status,
-          avatar_id: data.avatar_id ?? null,
-        },
-      });
-
-      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,
-      });
-
-      return person;
-    });
-  }
-
-  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`),
-      );
-    }
-
-    if (!allowCompanyRegistration && person.type === 'company') {
-      throw new NotFoundException(
-        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
-      );
-    }
-
-    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.',
-        ),
-      );
-    }
-
-    const existing = await this.prismaService.person.findMany({
-      where: { id: { in: ids } },
-      select: { id: true },
-    });
-    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.`,
-        ),
-      );
-    }
-
-    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.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: {
-            in: ids,
-          },
-        },
-      }),
-    ]);
-  }
-
-  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,
-    };
-  }
-}
+import { DeleteDTO } from '@hed-hog/api';
+import { getLocaleText } from '@hed-hog/api-locale';
+import { PaginationDTO, PaginationService } from '@hed-hog/api-pagination';
+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(
+    @Inject(forwardRef(() => PrismaService))
+    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' } }),
+      this.prismaService.person.count({ where: { type: 'company' } }),
+      this.prismaService.person.count({ where: { status: 'active' } }),
+      this.prismaService.person.count({ where: { status: 'inactive' } }),
+    ]);
+
+    return {
+      total,
+      individual,
+      company,
+      active,
+      inactive,
+    };
+  }
+
+  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),
+              },
+            ]
+          : []),
+      ],
+    };
+
+    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 = {};
+    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 (!allowCompanyRegistration) {
+      where.type = 'individual';
+    } else if (requestedType && requestedType !== 'all') {
+      where.type = requestedType;
+    }
+
+    if (paginationParams.status && paginationParams.status !== 'all') {
+      where.status = paginationParams.status;
+    }
+
+    if (search) {
+      where.OR = await this.buildSearchFilters(search);
+    }
+
+    const result = await this.paginationService.paginate(
+      this.prismaService.person,
+      paginationParams,
+      {
+        where,
+        include: {
+          person_address: {
+            include: {
+              address: true,
+            },
+          },
+          contact: true,
+          document: true,
+          person_metadata: true,
+        },
+      },
+    );
+
+    const enriched = await this.enrichPeople(
+      result.data as any[],
+      allowCompanyRegistration,
+    );
+
+    return {
+      ...result,
+      data: enriched,
+    };
+  }
+
+  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,
+      },
+    });
+
+    if (!person) {
+      throw new BadRequestException(
+        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
+      );
+    }
+
+    if (!allowCompanyRegistration && person.type === 'company') {
+      throw new NotFoundException(
+        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
+      );
+    }
+
+    const [normalized] = await this.enrichPeople(
+      [person as any],
+      allowCompanyRegistration,
+    );
+    return normalized;
+  }
+
+  async create(data: CreateDTO, locale: string) {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+
+    await this.ensureCompanyRegistrationAllowed({
+      nextType: data.type,
+      locale,
+    });
+
+    return this.prismaService.$transaction(async (tx) => {
+      const person = await tx.person.create({
+        data: {
+          name: data.name,
+          type: data.type,
+          status: data.status,
+          avatar_id: data.avatar_id ?? null,
+        },
+      });
+
+      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,
+      });
+
+      return person;
+    });
+  }
+
+  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`),
+      );
+    }
+
+    if (!allowCompanyRegistration && person.type === 'company') {
+      throw new NotFoundException(
+        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
+      );
+    }
+
+    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.',
+        ),
+      );
+    }
+
+    const existing = await this.prismaService.person.findMany({
+      where: { id: { in: ids } },
+      select: { id: true },
+    });
+    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.`,
+        ),
+      );
+    }
+
+    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.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: {
+            in: ids,
+          },
+        },
+      }),
+    ]);
+  }
+
+  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,
+    };
+  }
+}