Skip to content

Regras de Negocio

Jump to bottom
technical-documenter edited this page Sep 6, 2026 · 5 revisions

Regras de Negócio

← Contratos | Store →

Cadastro completo (PF/PJ, contatos, usuários e vendedores)

Regras obrigatórias de cadastro (PJ sem usuário próprio; contatos só na PJ; usuário na PF; fluxo salesman / sellers-client) e diagrama de fluxo:

→ Cadastro-de-Pessoas-Contatos-Usuarios-e-Vendedores

Espelho API: https://github.com/ControleOnline/api-platform-people/wiki/Cadastro-de-Pessoas-Contatos-Usuarios-e-Vendedores

1. Tipos de pessoa

Código Nome Descrição
F Pessoa Física CPF, nome, data de nascimento
J Pessoa Jurídica CNPJ, razão social, data de fundação

A distinção é feita via campo peopleType. O módulo trata imagens, labels e comportamentos de forma diferente para cada tipo.

2. Contextos de vínculo (linkType)

Um People pode ser vinculado a uma empresa através de um link com um linkType. Os tipos suportados são:

linkType Categoria Descrição
client Comercial Cliente da empresa
prospect CRM Potencial cliente (em negociação)
provider Compras Fornecedor/prestador
franchisee Franquia Franqueado
employee RH Funcionário
owner Societário Sócio/proprietário
director Societário Diretor
manager Societário Gerente
salesman Comercial Vendedor
after-sales Pós-venda Responsável por pós-venda
courier Logística Entregador

Vínculos humanos com empresa (HUMAN_COMPANY_LINK_TYPES)

Os tipos employee, owner, director, manager, salesman, after-sales, courier são classificados como vínculos humanos. Eles são usados na página MyCompaniesPage para encontrar as empresas às quais o usuário pertence como pessoa (e não como cliente ou fornecedor).

3. Resolução de empresa atual (currentCompany)

A empresa ativa no contexto da sessão é:

  1. Lida do store people.getters.currentCompany
  2. Persistida via currentCompanySelection.js no localStorage (chave session)
  3. Usada como escopo padrão nos filtros de busca de pessoas

4. Normalização de contexto

buildPeopleContextConfig(context) é o único ponto autorizado para normalizar context props:

  • Recebe props brutas do componente pai
  • Deduplica tipos, normaliza para minúsculo
  • Define defaultType como o primeiro tipo disponível se não especificado
  • Calcula hasTypeFilter (true quando há mais de 1 tipo disponível)
  • Não espalhar essa lógica em outros módulos

5. Resolução de imagem de pessoa

A lógica de imagem está encapsulada em peopleImage.js:

  • Pessoa física (F): procura mídias dos tipos avatar, photo, profile, profile-photo; fallback para campos avatar, photo, image, profilePicture, picture, icon
  • Pessoa jurídica (J): procura mídias dos tipos icon, logo; fallback para campos icon, logo, image, avatar, photo, picture
  • Normaliza coleções aceitas: people.media, people.medias, people.peopleMedia, people.peopleMedias

6. Resolução de ID do usuário logado

resolveLoggedUserId(currentUser) tenta extrair o ID numérico via múltiplos caminhos (fallback chain):

  1. currentUser.user_id
  2. currentUser.userId
  3. currentUser.user.id
  4. currentUser.user['@id']
  5. currentUser.idUser
  6. session.user_id (localStorage)
  7. session.userId
  8. session.user.id
  9. session.user['@id']
  10. session['@id']

Isso garante compatibilidade com diferentes formatos de resposta de autenticação.

7. Filtros de busca de pessoas

Dois helpers constroem os parâmetros de requisição à API:

buildPeopleLinkRequestParams

Usado quando a busca é de pessoas vinculadas a uma empresa específica:

link.company = /people/{currentCompany.id}
link.linkType = selectedLinkType

buildParentCompanyRequestParams

Usado quando o objetivo é encontrar empresas às quais o usuário pertence:

company.people = /people/{user.id}
company.linkType = [tipos humanos resolvidos]

8. Persistência de avatar na sessão

Ao trocar a foto de perfil, persistSessionAvatar(avatarFile):

  1. Lê a sessão atual do localStorage
  2. Substitui apenas o campo avatar (preserva demais campos)
  3. Salva de volta no localStorage

O avatar null limpa a foto na sessão (remoção explícita).

9. Tipos de documento suportados

O sub-store documentsTypes carrega dinamicamente os tipos disponíveis na API. O sub-store documents possui documentsTypes.js para mapear tipos conhecidos (CPF, CNPJ, RG, etc.).

10. Domínios de acesso (people_domains)

  • Cada pessoa/empresa pode ter domínios de acesso associados (URLs, apps, etc.)
  • O store people_domains possui colunas configuradas via peopleDomainColumns
  • Ações customizadas em actions.js para testes de domínio (testDomain) e status de carregamento (detailLoading)
  • Flag isSaving separada de isLoading para UI de feedback granular

11. Abertura automática do modal de criação

Se initialShowAddModal === true e o modal ainda não foi aberto nessa montagem, People abre automaticamente o AddCompanyModal na primeira renderização. O controle é feito via useRef para evitar aberturas repetidas em re-renders.

Capitalização de nomes (name / alias)

Campos nominais digitados pelo usuário (nome, alias/fantasia) preservam a capitalização informada.

  • normalizeIdentityValue (helpers de My Companies / formulários) apenas faz trim e colapso de espaços — não aplica toUpperCase / formatDisplayUppercase.
  • Cards de lista (People / My Companies) exibem o valor gravado sem forçar CAIXA ALTA.
  • Utilitários uppercaseText / formatDisplayUppercase em ui-common ficam reservados a códigos legítimos (ex.: UF), não a identidade de pessoa.

Página canônica (UI + API):
https://github.com/ControleOnline/ui-customers/wiki/Client-Details-People-Name-Case

Backend: People::getName() / getAlias() em api-platform-people devolvem o valor armazenado sem upper na leitura
https://github.com/ControleOnline/api-platform-people/wiki/People-Name-Alias-Case

Trilhas: app-community#626, #376.

7. Lista de colaboradores (employees-index) e filtros de linkType

A rota MANAGER /employees-index reutiliza People com contexto employee + owner + courier.

  • O valor do filtro de coluna link.linkType pode chegar como string, { value } ou array; a normalização para escalar é obrigatória antes de setSelectedLinkType (ver People-List-LinkType-Filters-Employees-Index).
  • Escopo de company: sempre link.company = IRI da currentCompany.
  • Navegação de detalhe em contexto empresa usa companyId (não clientId).

Detalhes e diagrama: People-List-LinkType-Filters-Employees-Index.

Clone this wiki locally