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)

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]

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

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

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]

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 |