Ir para o conteúdo

Roteiro: Criar cliente comercial no admin (CustomerFormDialog completo)

Perfil necessário: admin (viewer consulta; criar exige admin) Menus usados: Comercial Risco: baixo (erro comum é documento duplicado ou dia de fatura inválido — não afeta tráfego) Rollback: excluir o cliente em Clientes → Ações → Excluir, ou editar campos errados pelo mesmo dialog

Pré-requisitos

  • [ ] Login admin no ambiente (http://localhost:5173, usuário/senha de admin)
  • [ ] Documento do cliente (CPF/CNPJ) definido e ainda não cadastrado
  • [ ] Nome / razão social e contato definidos
  • [ ] Regra comercial de crédito decidida (limite, dia de fatura, limite simultâneo)

Passo a passo

1. Abrir a listagem de clientes

Caminho: Comercial → Clientes Clique: nenhum (página de consulta)

Listagem de clientes com o botão Novo Cliente destacado

Resultado esperado: tabela com colunas Cliente, Documento, Contrato, Status, Limite Crédito e Dia Fatura; busca aceita nome, documento ou contrato.

2. Abrir o dialog de criação

Caminho: Comercial → Clientes Clique: [Novo Cliente]

Listagem de clientes com o botão Novo Cliente destacado

Resultado esperado: dialog Novo Cliente com as seções Documentação, Configuração e Contato.

3. Preencher documentação

Caminho: dialog Novo Cliente → Documentacao Clique: preenchimento direto nos campos

Dialog Novo Cliente, seção Documentação com o campo Tipo de Documento destacado

Preencha:

Campo Obrig. Formato/exemplo Efeito
Tipo de Documento * sim CPF ou CNPJ (seletor) tipo de identificação fiscal
Numero do Documento * sim 12.345.678/0001-99 documento fiscal; backend rejeita duplicado com 409
Numero do Contrato não CT-2025-001 referência comercial/legado
Nome / Razao Social * sim ACME Telecom nome exibido na listagem e no detalhe
Nome Fantasia não ACME exibição alternativa

Resultado esperado: campos obrigatórios marcados em vermelho se vazios ao salvar ("Nome e obrigatorio", "Numero do documento e obrigatorio").

4. Preencher configuração (status, crédito, simultaneidade, fatura)

Caminho: dialog Novo Cliente → Configuracao Clique: preenchimento direto nos campos

Dialog Novo Cliente, seção Configuração com o campo Limite de Credito destacado

Preencha:

Campo Obrig. Formato/exemplo Efeito
Status * sim Ativo (default), Suspenso, Cancelado vigência do cliente
Limite de Credito não valor em BRL, default R$ 0,00 teto de crédito usado em cobrança
Limite simultaneo do cliente não inteiro ≥ 0, default 0 teto agregado de chamadas simultâneas; 0 desativa e controla por linha
Dia da Fatura (1-31) não inteiro 1–31, default 10 dia do ciclo em que a fatura é gerada

Resultado esperado: hint "Use 0 para desativar o limite agregado e controlar a simultaneidade por linha" visível no campo de simultaneidade.

5. Preencher contato e observações e salvar

Caminho: dialog Novo Cliente → Contato Clique: [Criar]

Dialog Novo Cliente com o botão Criar destacado no rodapé

Preencha:

Campo Obrig. Formato/exemplo Efeito
Nome do Contato não Maria Souza contato operacional
Email de Contato não noc@cliente.com.br contato por e-mail
Telefone de Contato não +55 (11) 99999-9999 contato telefônico
Observacoes não texto livre anotações internas

Resultado esperado: toast verde Cliente criado, dialog fecha, cliente aparece na listagem com Status Ativo e Dia Fatura 10.

Validação

  • [ ] Visual: cliente listado com documento, contrato e status corretos
  • [ ] Funcional: abrir o detalhe (/customers/<id>) mostra os mesmos dados nos cartões Dados Cadastrais, Faturamento e Contato
  • [ ] Funcional: duplicar o documento em outro cliente retorna toast de erro (backend 409 "Documento já cadastrado")

Erros comuns

Sintoma Causa provável Correção
Toast "Falha ao salvar" documento já cadastrado (409) usar o documento correto ou editar o cliente existente
Campo Nome/Documento/Status em vermelho validação de obrigatório do dialog preencher o campo destacado antes de Criar
"Informe um numero inteiro maior ou igual a zero" limite simultâneo negativo ou não inteiro corrigir o valor do campo Limite simultaneo do cliente
Cliente criado mas sem tráfego esperado criação não provisiona linha/DID seguir os roteiros de linha e DID do domínio Comercial

Tabela de referência rápida

Botão Onde O que faz
[Novo Cliente] toolbar de Clientes abre o dialog de criação
[Criar] rodapé do dialog salva via POST /customers
[Editar] detalhe do cliente reabre o dialog em modo edição