Skip to content

Cadastro de Pessoas

Jump to bottom
ControleOnline Documentation edited this page Sep 6, 2026 · 1 revision

Fluxo de cadastro de pessoas

Esta página é a referência do backend para o cadastro de pessoas, empresas, contatos, usuários e vendedores. A visão de telas está na wiki do ui-people.

Modelo canônico

People é o cadastro de PF e PJ. PeopleLink relaciona uma pessoa a uma empresa e guarda o papel ou relação (client, provider, employee, manager, owner, salesman, franchisee, sellers-client e outros vínculos do domínio). Autenticação pertence a User, associado a uma pessoa física.

flowchart LR
    P[People PF] -->|pode ter| U[User de autenticação]
    J[People PJ] -->|não possui| NU[User próprio]
    J -->|possui contatos| L[PeopleLink]
    L --> C[People PF contato]
    C -->|pode ter| CU[User do contato]
    P -->|vínculo direto| R[PeopleLink de papel]
    P -->|salesman| S[Recebe clientes]
    S -->|sellers-client| K[Cliente da empresa]
Loading

Fluxo de persistência

sequenceDiagram
    participant UI as ui-people/ui-customers
    participant API as People API
    participant DB as People/PeopleLink
    participant CRM as ui-crm
    UI->>API: POST/PUT People PF ou PJ
    API->>DB: valida escopo e salva cadastro
    UI->>API: cria contato PF e/ou PeopleLink
    API->>DB: salva vínculo PJ-contato
    UI->>API: cria User somente para PF, se necessário
    API->>DB: associa User à pessoa física
    UI->>API: adiciona linkType=client
    API->>API: SalesmanService verifica vendedor
    API->>API: distribui ou usa vendedor atual
    API->>DB: salva linkType=sellers-client
    API-->>CRM: vínculo pronto para o fluxo comercial
Loading

Fluxos separados por finalidade

Cada fluxo abaixo conclui o cadastro cadastral e do vínculo antes de executar, como última etapa opcional, a criação/associação de User para a pessoa física.

Cliente

  1. Criar ou reutilizar People PF/PJ.
  2. Persistir dados cadastrais e recursos relacionados.
  3. Para PJ, persistir contatos como People PF e seus PeopleLink.
  4. Criar PeopleLink.linkType=client no contexto da empresa.
  5. Se necessário, disparar a atribuição específica de vendedor.
  6. Último passo opcional: criar/vincular User somente para a PF que acessará o sistema.

Fornecedor

  1. Criar ou reutilizar People PF/PJ.
  2. Persistir dados cadastrais e contatos da PJ, se houver.
  3. Criar PeopleLink.linkType=provider.
  4. Último passo opcional: criar/vincular User para uma PF responsável ou contato; nunca para a PJ.

Vendedor

  1. Criar/reutilizar uma People PF.
  2. Criar PeopleLink.linkType=salesman entre PF e empresa.
  3. Quando um cliente for criado sem vendedor, SalesmanService procura o vendedor autenticado ou chama SalesmanDistributionService.
  4. Persistir PeopleLink.linkType=sellers-client para a atribuição comercial.
  5. Aplicar proteção de escopo e de comissão no backend.
  6. Último passo opcional: criar/vincular User para o vendedor PF.

Funcionário

  1. Criar/reutilizar People PF.
  2. Criar o vínculo humano de funcionário com a empresa.
  3. Persistir dados de EmployeeProfile e recursos de RH nos módulos responsáveis.
  4. Último passo opcional: criar/vincular User para o funcionário PF.

Empresa e contatos

  1. Criar/reutilizar People PJ.
  2. Persistir dados empresariais.
  3. Não criar User para a PJ.
  4. Criar cada contato como People PF.
  5. Persistir o vínculo PJ-contato em PeopleLink.
  6. Último passo opcional de cada contato: criar/vincular User para o contato PF.

Usuário

É sempre a etapa final de cada fluxo: validar PF, vínculo/contexto e então criar ou associar o User. O usuário autentica a PF; permissões vêm dos vínculos e não transformam a PJ em conta autenticável.

Regras invariáveis

PF, PJ, contato e usuário

  • PJ não recebe User próprio.
  • Contato é PF vinculada à PJ; o contato pode receber User próprio.
  • PF não apresenta aba de contatos; somente PJ pode manter contatos empresariais.
  • Um usuário autenticável representa uma PF. O contexto da empresa é resolvido pelos vínculos e pela empresa selecionada.
  • Cadastro cadastral, vínculo com empresa e autenticação são etapas distintas e podem ter permissões diferentes.

Vendedores

Vendedor é um fluxo especializado. salesman identifica a PF que atua como vendedor de uma empresa. sellers-client identifica a atribuição comercial dessa pessoa a um cliente. Não reutilizar employee, client ou contato para representar essa atribuição.

Quando uma empresa recebe um cliente sem vendedor, SalesmanService:

  1. ignora a reação quando o vínculo não é client;
  2. evita a recursão quando a empresa atual já é vendedor;
  3. usa o usuário atual se ele for vendedor da empresa;
  4. caso contrário chama SalesmanDistributionService;
  5. cria o vínculo sellers-client idempotentemente e notifica o cliente quando aplicável.

As estratégias de distribuição são random, round_robin, least_clients e last_received. Comissão (comission, minimum_comission) e alterações de vendedor exigem contexto de gestão autorizado. A API deve proteger leitura e escrita com escopo próprio; a UI não é uma barreira de segurança.

Responsabilidades no código

  • People: recurso cadastral e operações de leitura/escrita.
  • PeopleLink: relacionamento pessoa-empresa e relações comerciais.
  • PeopleService/PeopleLinkService: criação, descoberta, escopo e proteção de vínculos.
  • AccountRegistrationService/CreateAccountAction: criação de conta pública para pessoa física.
  • SalesmanService/SalesmanDistributionService: seleção e associação de vendedor.
  • Controllers de empresas, contatos, mídia e exportação: entradas especializadas que continuam submetidas ao escopo de pessoas.

Critérios de aceite do fluxo

  • Nenhuma rota cria usuário para PJ.
  • Contato PJ é PF persistida e vinculada por PeopleLink.
  • Usuário de contato é associado ao contato PF, não à PJ.
  • PF não recebe representação de aba/coleção de contatos.
  • Vendedor autenticado é preferido quando atribui cliente.
  • Sem vendedor autenticado, a estratégia da empresa é aplicada.
  • Vínculo de vendedor existente não é duplicado ou substituído indevidamente.
  • Escopo de empresa e campos de comissão são aplicados no backend.
  • Soft-delete remove a pessoa das listas operacionais sem apagar fisicamente seus vínculos históricos.

Módulos consumidores

Clone this wiki locally