Ir para o conteúdo

Interface de Administração — iproute Softswitch

Guia visual da interface administrativa (admin/frontend), com capturas de tela reais da UI. Os retângulos vermelhos nos prints indicam o botão/ação principal descrito em cada seção.

Ambiente de referência: http://localhost:5173 (dev Vite, proxy /api para o backend FastAPI em 127.0.0.1:8080). Tema claro, usuário admin.

Como acessar

  1. Abra a URL do admin (em dev: http://localhost:5173).
  2. Entre com usuário/senha de administrador (JWT + refresh token; sessão persistida no navegador).
  3. "Lembrar-me" mantém a sessão; "Esqueceu a senha?" depende de configuração de e-mail no ambiente.

Tela de login

Layout padrão

Todas as páginas autenticadas compartilham o mesmo shell:

  • Sidebar esquerda com seções: Operação, Comercial, Roteamento, Segurança e Rede, Plataforma (+ Conta e Administração no rodapé). Colapsa pelo botão no header.
  • Header superior: busca de número no BDO (consulta de portabilidade direto do header), tema claro/escuro, notificações e menu do usuário.
  • Cabeçalho de página (PageHeader): eyebrow da seção, título, descrição e ações primárias à direita.
  • Tabelas CRUD (CrudTable): toolbar com busca, filtros, criação, ordenação, paginação e ações por linha (editar/excluir).

Operação

Dashboard

Painel de tempo real: chamadas ativas, registros SIP, estatísticas do dia e gráficos por hora, com seletor de janela no cabeçalho.

Dashboard

Chamadas Ativas

Chamadas em curso segundo o OpenSIPS (MI dialogs), com estado/suspeitas (early, no-ACK, confirmadas há muito tempo) e integração com CDR.

Chamadas ativas

Registros SIP

Endpoints registrados (tabela location): AOR, IP:porta, expires, user-agent.

Registros SIP

CDR

Visualizador de chamadas concluídas com filtros avançados (período, número, status, carrier etc.), estatísticas do resultado, e Exportar CSV para download do resultado filtrado. Cada linha permite abrir os logs SIP e o fluxo SIP da chamada (janela sip-flow com INGRESS/EGRESS/REPLY/MEDIA).

CDR com exportação

Comercial

Clientes

Cadastro de clientes. O botão Novo Cliente abre o formulário (nome, contrato, contato, estado).

Clientes

A página de detalhe do cliente concentra as linhas, DIDs e CDRs daquele cliente, com busca e criação inline.

Detalhe do cliente

Planos

Planos comerciais e suas franquias/allowances (minutos, buckets) e mapeamento de tarifas.

Planos

Linhas

Linhas telefônicas dos clientes: cada linha aponta para um perfil de linha (comportamento técnico) e carrega DIDs, endereços e políticas associadas.

Linhas

Políticas de Saída

Perfis de saída e a cadeia de normalização outbound do número B (regras ordenadas por prioridade, com teste de normalização no final da página).

Políticas de saída

Políticas de Entrada

Política global única para chamadas inbound + regras por linha (normalização inbound, bloqueio seletivo), com teste de normalização.

Políticas de entrada

DIDs

Cadastro de números DID: número/E.164, cliente/linha, carrier de entrada, habilitado.

DIDs

Tarifação

Uso em tempo real por cliente/linha e ciclos de faturamento fechados.

Tarifação

Roteamento

Endpoints

Endpoints SIP (trunks dos clientes/PBX). Novo Endpoint abre o formulário completo (nome, IP/sigla de autenticação, credenciais SIP, perfil, codec/media).

Endpoints

Novo endpoint (dialog)

Grupos

Grupos de endpoints usados em políticas e roteamento.

Grupos

Operadoras e Troncos

Motor de carrier routing, organizado em abas:

  • Rotas por Operadora: regras de saída por operadora (prioridade, destino, status, janela de aplicação — sempre/portado/LDN/só saída/só entrada).
  • Operadoras: cadastro de carriers.
  • Troncos: troncos SIP por operadora (host, codecs, limites, CLI wire format).
  • Headers: políticas de headers SIP aplicadas por tronco.
  • Como funciona: resumo do motor.

Rotas por operadora

Operadoras

Troncos

Headers

Testar Classificação

Simula o classificador de chamadas (LOC/LDN/MOV/INT, portabilidade RN1/RN2, CadUP) para um número A/B dado, mostrando o resultado por etapa. Útil para validar regras antes de produção.

Testar classificação

Avançado

  • Dialplan: regras de dialplan (regex match) com teste em tempo real.
  • Endereços Confiáveis: IPs autorizados sem registro (address groups, desambiguação via contexto).
  • Usuários SIP: subscribers diretos no domínio SIP.
  • SUP / Serviços Públicos: serviços SUP e traduções por CNL.

Dialplan

Endereços confiáveis

Usuários SIP

SUP / Serviços públicos

Segurança e Rede

Firewall

Regras allow/drop, conjuntos de portas (SIP, RTP), bloqueio por IPset/país/ASN e abertura automática para IPs de endpoints e endereços confiáveis. A aplicação é explícita: Aplicar firewall materializa as regras via nftables (nada é aplicado automaticamente ao salvar).

Firewall

Rede

IPs, rotas, VLAN e DNS do host (com apply e persistência via netplan quando configurado).

Rede

Plataforma

Infraestrutura

  • RTPEngine: destinos de mídia e status.
  • Media Servers: servidores FreeSWITCH para tratamento de mídia.
  • Dispatcher: destinos dispatcher do OpenSIPS.
  • Anúncios: códigos de anúncio (*an-*), SIP code/reason associado, TTS.

RTPEngine

Media servers

Dispatcher

Anúncios

Sistema

  • Configurações Globais: tabela config (key/value) que alimenta o softswitch, com abas por grupo.
  • Logs: leitura de logs do OpenSIPS/RTPEngine em janela selecionável.
  • OpenSIPS (Reload): recarga de dados via MI por módulo (address, dialplan, dispatcher) ou Recarregar todos os módulos. Toda mutação de dado reload-to-memory deve ser seguida do reload correspondente.
  • SIP Profiles: perfis SIP do OpenSIPS.
  • Domínios SIP: domínios aceitos no SIP.
  • Backups: geração, download e exclusão de backups do banco.
  • BDO: configuração da consulta de portabilidade (procedure consultaTN_BDO) com Testar Lookup e auditoria de consultas.
  • CadUP: dados CadUP, localidades Anatel e status de migração CN.
  • MCP Troubleshooting: credenciais MCP read-only para agentes de diagnóstico; o segredo é exibido uma única vez.

Configurações globais

Logs

OpenSIPS reload

SIP Profiles

Domínios SIP

Backups

BDO

CadUP

MCP

Novo token MCP (dialog)

Conta e Administração

  • Minha Conta: dados do usuário e troca de senha.
  • Usuários: usuários administrativos (admin/viewer) e chaves API (PAT revogáveis para consumo direto da API sem relogin).

Minha conta

Usuários

Roteiros operacionais (passo a passo por tarefa)

Guias profundos por funcionalidade do softswitch, seguindo o padrão de DOCS-SPEC.md (botão exato destacado, campos de formulário, validação e erros comuns):

Roteiro Funcionalidade
Provisionar cliente PBX com auth por IP cliente → linha → DIDs → endereço confiável → reload → validar
Investigar chamada por CDR e fluxo SIP filtros CDR, logs, sip-flow, leitura por estágio
Cadastrar operadora de saída operadora → tronco → rotas → headers → shadow → validar
Criar endpoint SIP e atributos de mídia trunk do cliente, toggles de mídia/segurança
Ajustar firewall com segurança regras/portas/IPset → aplicar → validar sem lockout
Política de entrada e bloqueio política global inbound + regras por linha
Perfil de saída e normalização do B cadeia de normalização, destinos, teste
Testar classificação BR / SUP / BDO classifier tester, SUP, BDO lookup, CadUP
Plano comercial com franquias plano, allowances, vínculo na linha, consumo
Dialplan: regra e teste DPID, regex, teste em tempo real, reload
Usuário SIP e domínio subscribers, domínios, senhas, registro
Diagnóstico de mídia RTPEngine, media servers, anúncios/TTS, dispatcher
Rotina de reload pós-mudança quando/qual módulo recarregar no MI

Roteiros por domínio (agentes, padrão DOCS-SPEC)

Domínio Guias
NOC/Operação noc-investigar-chamada · noc-chamadas-ativas · noc-registros-sip · noc-triagem-inicial
Comercial commercial-criar-cliente · commercial-criar-linha · commercial-criar-did · commercial-customer-detail · commercial-plano-franquias · commercial-tarifacao · commercial-did-portabilidade · commercial-line-terminacao · commercial-line-bloqueio · commercial-auditoria-tarifacao
Roteamento base routing-endpoint-completo · routing-grupos-membros · routing-grupos-failover · routing-endereco-confiavel · routing-usuario-sip-registro
Carrier routing carrier-operator · carrier-trunk · carrier-route · carrier-headers · carrier-homologation · carrier-route-simulator · carrier-help
Políticas policy-inbound · policy-outbound · policy-external-forward
Classificação BR br-classification · br-sup-bdo-cadup · br-sup-uncataloged
Infra/Mídia media-rtpengine · media-media-servers · media-dispatcher · media-announcements · media-diagnostico
Sistema/Segurança system-firewall · system-reload · system-config · system-backups · system-backup-restauracao · system-dialplan · system-emergency-routes · system-sip-profiles-domains · system-network
Administração admin-users · admin-pat · admin-mcp-tokens · admin-account

O padrão completo (estrutura obrigatória, convenção do quadrado vermelho, captura via --spec, limitações do capturador e critério de aceite) está em DOCS-SPEC.md.

Fluxos comuns (resumo rápido)

  1. Clientes → Novo Cliente (dados comerciais).
  2. No detalhe do cliente: Nova Linha (escolhe perfil de linha) e Novo DID (número).
  3. Se o cliente usa IP autenticado: Endpoints → Novo Endpoint (ou endereço confiável em Avançado → Endereços Confiáveis).
  4. Sistema → OpenSIPS (Reload) para carregar address/dispatcher/dialplan na memória.

Provisionar saída por operadora

  1. Operadoras e Troncos → Operadoras → Nova Operadora.
  2. Aba Troncos → Novo Tronco (host/porta, codecs, limites).
  3. Aba Rotas por Operadora → Nova Rota (prioridade, destino, janela de aplicação).
  4. Sistema → OpenSIPS (Reload) (dispatcher/routes) e validação com o Testar Classificação/shadow comparison quando aplicável.

Regenerar os prints

Os PNGs são gerados automaticamente contra o ambiente local:

# backend + frontend rodando (ver docs/context/INFRA.md)
cd admin/frontend
node scripts/docs-shots.mjs

Variáveis de ambiente: SW_DOCS_BASE_URL (default http://localhost:5173), SW_DOCS_USERNAME/SW_DOCS_PASSWORD (default admin/admin). O script força tema claro, navega pelas 43 telas, abre abas/diálogos quando o shot pede (tab:/click:) e desenha o destaque vermelho no botão (highlight:).

Renderizando como site de documentação

Este diretório é um site MkDocs Material (busca, navegação por domínio, dark/light) com as imagens de img/:

# 1ª vez: instalar (Python 3.10+)
pip install mkdocs mkdocs-material

# Servir localmente com hot-reload → http://127.0.0.1:8000
mkdocs serve

# Gerar site estático em site/ (deploy em qualquer static host)
mkdocs build

Notas: - docs/ é um junction para a raiz (mklink /J docs .); o MkDocs exige docs_dir separado do mkdocs.yml. Recrie após clonar. - O nav por domínio fica em mkdocs.yml; página nova precisa ser adicionada lá para entrar na navegação.

Docker

Build multi-stage (Python renderiza com --strict, nginx serve o estático):

docker build -t admin-ui-docs .
docker run --rm -d -p 8088:80 --name admin-ui-docs admin-ui-docs
# → http://localhost:8088
  • O estágio de build monta o layout docs/ explicitamente (o junction NTFS não existe dentro do container Linux).
  • nginx.conf inclui fallback .html (clean URLs do Material) e página 404 customizada.
  • Versões fixadas em requirements.txt.