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/apipara o backend FastAPI em127.0.0.1:8080). Tema claro, usuário admin.
Como acessar¶
- Abra a URL do admin (em dev:
http://localhost:5173). - Entre com usuário/senha de administrador (JWT + refresh token; sessão persistida no navegador).
- "Lembrar-me" mantém a sessão; "Esqueceu a senha?" depende de configuração de e-mail no ambiente.

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.

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.

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

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).

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

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

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

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.

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 Entrada¶
Política global única para chamadas inbound + regras por linha (normalização inbound, bloqueio seletivo), com teste de normalização.

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

Tarifação¶
Uso em tempo real por cliente/linha e ciclos de faturamento fechados.

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).


Grupos¶
Grupos de endpoints usados em políticas e roteamento.

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.




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.

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.




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).

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

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.




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.










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).


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)¶
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)¶
- Clientes → Novo Cliente (dados comerciais).
- No detalhe do cliente: Nova Linha (escolhe perfil de linha) e Novo DID (número).
- Se o cliente usa IP autenticado: Endpoints → Novo Endpoint (ou endereço confiável em Avançado → Endereços Confiáveis).
- Sistema → OpenSIPS (Reload) para carregar address/dispatcher/dialplan na memória.
Provisionar saída por operadora¶
- Operadoras e Troncos → Operadoras → Nova Operadora.
- Aba Troncos → Novo Tronco (host/porta, codecs, limites).
- Aba Rotas por Operadora → Nova Rota (prioridade, destino, janela de aplicação).
- 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.confinclui fallback.html(clean URLs do Material) e página 404 customizada.- Versões fixadas em
requirements.txt.