persons

O submódulo Persons é o núcleo do CRM: uma única tabela `person` representa tanto indivíduos quanto empresas (discriminados pelo campo `type`), com os registros de empresa adicionalmente expostos através de uma superfície dedicada de Accounts (`/person/accounts`) que filtra por `type: company` e adiciona campos específicos de conta, como setor, website, receita anual e número de funcionários. A tabela base `person` guarda apenas campos estruturais (nome, tipo, status, avatar). Todo o resto que o PersonController aceita na criação/atualização — notes, employer_company_id, owner_user_id, source, lifecycle_stage, next_action_at, score, deal_value, tags — é persistido como linhas de chave/valor em uma tabela companheira person_metadata e remontado no formato de resposta pelo serviço. Isso mantém o schema central estável enquanto permite que atributos específicos de CRM evoluam sem uma migration para cada novo campo.

O rastreamento de propriedade e de ciclo de vida são preocupações de primeira classe. Cada pessoa pode receber um owner_user_id (restrito às roles admin, admin-crm ou owner-crm) e um lifecycle_stage extraído de um funil de vendas (new, contacted, qualified, proposal, negotiation, customer, lost). O POST /person/:id/lifecycle-stage registra a transição explicitamente, em vez de silenciosamente sobrescrever o valor em uma atualização genérica, o que mantém um histórico limpo para relatórios. Os endpoints GET /person/dashboard e GET /person/reports agregam essas transições de estágio e logs de interação em métricas de funil e relatórios agrupados por tempo (dia/semana/mês/ano), dando ao painel de admin suas visualizações de pipeline sem um data warehousing separado.

Interações (call, email, whatsapp, meeting, note) e follow-ups (um next_action_at agendado mais notas) são registrados por pessoa e também expostos como endpoints de worklist entre pessoas — GET /person/followups e GET /person/activities retornam visões paginadas e filtráveis de todo o CRM para que um representante possa trabalhar uma fila sem abrir cada registro de pessoa individualmente. Atividades são um conceito separado e mais estruturado do que interações: elas carregam status e podem ser explicitamente concluídas via POST /person/activities/:id/complete.

A prevenção de duplicatas e a consolidação são tratadas por dois endpoints complementares. O GET /person/duplicates realiza uma verificação difusa por nome, e-mail ou telefone antes de criar um novo registro. O POST /person/merge consolida um par de duplicatas existente: contatos, documentos, endereços e metadata são mesclados no registro alvo dentro de uma única transação, a pessoa de origem é marcada como inativa e um ponteiro de metadata merged_into_person_id é deixado para rastreabilidade. Apenas pessoas do mesmo tipo podem ser mescladas, e somente a estratégia contact_only está implementada atualmente — o campo strategy do DTO é tipado para estratégias futuras, mas o serviço só aceita esse valor hoje.

O onboarding em massa é suportado via um fluxo de CSV em duas etapas: o POST /person/import/preview faz o parsing do arquivo enviado e retorna os cabeçalhos e linhas de amostra para que o chamador possa montar um mapeamento de colunas; em seguida, o POST /person/import aplica esse mapeamento (passado como uma string JSON em um campo multipart) para criar registros de pessoa, opcionalmente associando todos eles a uma empresa via company_id. Ambos os endpoints rejeitam uploads que não sejam CSV e limitam o tamanho do arquivo a 10 MB.

O GET /person/avatar/:id é o único endpoint público e não autenticado do submódulo — ele serve a imagem de avatar de uma pessoa por ID de arquivo com cache baseado em ETag (If-None-Match), de modo que o painel de admin e quaisquer widgets incorporados possam renderizar avatares sem precisar de um token de sessão. Vincular uma pessoa a uma conta de usuário da plataforma (user_id) é restrito a uma role dedicada person-user-linker, além de admin/admin-crm, já que isso concede àquele usuário visibilidade atrelada ao registro do CRM.