Roteiro: Ler tarifação e consumo de um cliente (BillingView)¶
Perfil necessário: admin | viewer (somente leitura) Menus usados: Comercial Risco: baixo (página de consulta; nenhuma mutação de faturamento acontece aqui) Rollback: não aplicável — nada é alterado; discrepâncias se resolvem nos CRUDs de origem (plano, linha, classificação)
Pré-requisitos¶
- [ ] Pelo menos um cliente com plano vinculado às linhas
- [ ] Tráfego tarifado no ciclo (CDR gerado) para haver consumo
- [ ] Ciclos fechados, quando for consultar a aba de ciclos
Passo a passo¶
1. Abrir a página de tarifação¶
Caminho: Comercial → Tarifação
Clique: nenhum (página de consulta)

Resultado esperado: aba Uso Atual com o seletor de cliente e o botão Atualizar; painel informa franquias, consumo e alertas do cliente selecionado.
2. Selecionar o cliente e atualizar o uso¶
Caminho: Comercial → Tarifação → Uso Atual
Clique: [Atualizar]

Preencha/Opções:
| Controle | Obrig. | Formato/opções | Efeito |
|---|---|---|---|
| Seletor de cliente | sim | clientes com plano (ex.: Maicon Bez Fontana) |
recarrega o painel de uso do cliente escolhido |
| Atualizar | não | botão | refaz a consulta GET /billing/usage/<cliente> |
Resultado esperado: cartões por bucket de chamada com usado / franquia, barra de progresso, percentual utilizado e Tags de estado: Alerta acima de 80% e Excedido acima de 100% do ciclo atual (o ciclo começa no Dia da Fatura do cliente).
3. Consultar os ciclos fechados¶
Caminho: Comercial → Tarifação → Ciclos Fechados
Clique: aba [Ciclos Fechados]

Preencha/Opções:
| Controle | Obrig. | Formato/opções | Efeito |
|---|---|---|---|
| Busca | não | cliente ou período | filtra a tabela |
| Filtrar status | não | Aberto, Fechado, Processado, Faturado |
recarrega a lista por status |
Resultado esperado: tabela com Cliente, Período (mm/aaaa), Assinatura (R$), Excedente (R$) em vermelho quando > 0, Total (R$) e Status.
4. Abrir o detalhe do ciclo¶
Caminho: Comercial → Tarifação → Ciclos Fechados
Clique: [Visualizar] na linha do ciclo
Nota: o ambiente de referência não possui ciclos fechados ainda — sem print deste dialog de propósito (evitar link quebrado). Em produção a tabela estará populada; os campos abaixo refletem o componente real.
Resultado esperado: dialog Detalhes do Ciclo com Cliente, Período, Status, tabela de linhas por tipo de chamada (Tipo, Quantidade, Preço Unitário, Total) e o resumo Assinatura + Excedente = Total. Exportar CSV baixa o CSV do ciclo; Fechar encerra o dialog.
Validação¶
- [ ] Visual: cartões de uso exibem buckets com consumo coerente com o tráfego do cliente no ciclo
- [ ] Funcional: total do detalhe do ciclo = Assinatura + Excedente; excedente aparece em vermelho quando > 0
- [ ] Funcional: CSV exportado abre com colunas de minutos da franquia, excedente e totais por linha do ciclo
- [ ] Cruzamento: consumo do bucket no cartão bate com a soma dos CDRs do cliente no mesmo período (
Operação → CDRfiltrado pelo cliente)
Erros comuns¶
| Sintoma | Causa provável | Correção |
|---|---|---|
| "Escolha um cliente" com painel vazio | nenhum cliente selecionado | escolher o cliente no seletor e clicar Atualizar |
| "Nenhum cliente disponível" | clientes sem plano de tarifação | vincular plano às linhas do cliente (roteiro de plano/linha) |
| "Sem consumo no ciclo atual" | cliente sem tráfego tarifado no período | conferir CDRs do período e o Dia da Fatura (ciclo em curso) |
| Cartão de bucket não aparece | franquia não configurada para o bucket usado | criar a franquia no plano (roteiro de plano com franquias) |
| Consumo não bate com a franquia | classificação do tráfego divergente do bucket | validar em Testar Classificação e ajustar plano/classificação |
| Excedente alto inesperado | franquia subdimensionada ou Max CPS/limites frouxos | revisar franquias e limites da linha |
Tabela de referência rápida¶
| Controle | Onde | O que faz |
|---|---|---|
| [Atualizar] | aba Uso Atual | refaz o painel de uso do cliente |
| [Ciclos Fechados] | seções no topo | alterna para a lista de ciclos |
| [Visualizar] | ações da linha de ciclo | abre o dialog Detalhes do Ciclo |
| [Exportar CSV] | ações da linha / rodapé do dialog | baixa o CSV do ciclo |