Como ler este documento

A documentação está dividida em cinco camadas. Cada camada tem um início (objetivo e mapa), subcamadas com o conteúdo e uma conclusão (resumo, checklist e próximo passo). Cada uma aprofunda a anterior: leia só até onde o seu papel exige.

Dica: use a busca no topo para filtrar as seções por palavra-chave.

Visão geral

Entender o que é o RKAVision, que problema ele resolve e para quem foi feito.

Ao final desta camada você vai saber

• O que o sistema faz, em poucas palavras
• Quais problemas do dia a dia ele elimina
• Quais módulos existem e o que cada um entrega
• Por onde cada perfil deve começar

Subcamadas

O que é o RKAVision

O RKAVision é uma plataforma web para provedoras de internet por fibra óptica documentarem, operarem e expandirem a sua rede sobre um mapa interativo.

Ele reúne em um único lugar o que normalmente fica espalhado em planilhas, arquivos KMZ, fotos no celular e no conhecimento de poucas pessoas: onde está cada CTO, emenda, POP e cabo; como as fibras estão fundidas; quanto sinal chega em cada ponto; quais clientes e ordens de serviço estão em cada região; e, em tempo quase real, quais caixas estão com clientes offline.

Funciona no navegador do computador e do celular, sem instalação, com tema claro e escuro e acesso controlado por login.

Módulos em um olhar

O problema que resolve

Por que o RKAVision

Para quem é

Conclusão: Visão geral

Em resumo

• O RKAVision coloca a rede FTTH inteira em um mapa: estrutura física, fusões, sinal e clientes.
• Ele troca KMZ, planilhas e conhecimento informal por uma fonte única, com registro de quem mudou o quê.
• O monitoramento de ONUs mostra quedas antes de o cliente ligar e separa falha de rede de problema isolado.

Você pode seguir se já sabe responder

• Que problema o RKAVision resolve para a sua provedora?
• Quais são os módulos principais?
• Qual perfil você é e por qual parte do sistema começa?

Próximo passo

Guia de uso

Aprender a usar cada tela e recurso no trabalho do dia a dia.

Ao final desta camada você vai saber

• Entrar no sistema e se localizar no mapa
• Documentar caixas, cabos, POPs e áreas
• Ligar fibras e conferir o sinal no diagrama
• Planejar expansões no Modo Projeto
• Acompanhar ONUs, O.S. e desligamentos
• Desfazer um erro

Subcamadas

Primeiro acesso

O acesso é por convite implícito: qualquer pessoa pode se cadastrar, mas só entra depois que um administrador aprova.

1. Cadastro. Na tela /login, escolha criar conta, informe e-mail, nome de usuário e senha. A senha precisa ser forte.
2. Confirmação do e-mail. Um código é enviado ao e-mail informado. Digite-o para validar o cadastro.
3. Aceite dos termos. É obrigatório aceitar os Termos de Uso de Dados e a Política de Privacidade. O aceite fica registrado.
4. Aprovação. A conta fica pendente até um administrador liberar e definir o nível de acesso.
5. Entrar. Depois de aprovado, faça login. A sessão é mantida em cookie seguro.

O mapa

A tela principal é o mapa em tela cheia. Todos os controles flutuam por cima dele.

Controles

Rede existente e rede planejada

Fora do Modo Projeto o mapa mostra só a rede existente. Elementos planejados aparecem apenas quando um projeto está aberto. Veja Modo Projeto.

Busca e pin temporário

Busca

Digite no campo "Buscar rua, cliente, caixa ou O.S.". Os resultados levam direto ao ponto no mapa.

Pin temporário

Marca um ponto provisório, sem gravar nada, para responder "qual a CTO mais perto daqui?".

• Por coordenadas: cole latitude e longitude na busca.
• Por link do Google Maps: cole o link, inclusive o link curto compartilhado pelo celular. O sistema resolve o endereço sozinho.
• Por duplo clique: dê dois cliques no mapa.

O pin mostra a CTO mais próxima com a distância pelas ruas (OpenRouteService, perfil a pé, que se aproxima do traçado do cabo). Se o serviço de rotas não responder, o sistema usa a distância em linha reta e avisa.

CTOs, emendas e fotos

CTO é a caixa de atendimento onde o cliente é ligado. CEO (emenda) é a caixa onde os cabos são fundidos.

Criar uma caixa

1. Clique em + Adicionar no mapa → CTO ou emenda.
2. Clique no local exato no mapa.
3. Preencha nome, tipo (CTO ou CEO), quantidade de portas e observações.
4. Salve. A caixa aparece no mapa e entra nas contagens do dashboard.

Criar caixas a partir de fotos

Use Enviar fotos: o sistema lê a localização gravada na foto (GPS do EXIF). Se a foto não tiver GPS, tenta ler as coordenadas escritas na imagem por OCR, como as de aplicativos de câmera com carimbo. A cidade mais próxima é preenchida automaticamente.

Fotos de uma caixa

Cada caixa pode ter várias fotos, adicionadas ou removidas no painel da caixa. As fotos só abrem para quem está logado.

Editar, mover e remover

Abra a caixa para editar dados, ver o diagrama ou remover. Toda remoção pede confirmação e pode ser desfeita com Ctrl+Z (veja Lixeira).

Cabos

Desenhar um cabo

1. Clique em + Adicionar no mapa → Cabo.
2. Clique ponto a ponto ao longo do traçado. Com o Ímã ligado, cada ponto gruda na CTO, emenda, POP ou poste mais perto. Segure Alt para soltar um clique avulso.
3. Use Desfazer para tirar o último ponto e Concluir para terminar.
4. Informe nome, quantidade de fibras, lançamento (aéreo ou subterrâneo), cor e reserva técnica.

Metragem

Editar o traçado

No editor de vértices, arraste os pontos para ajustar o caminho. Os mesmos controles servem para áreas demarcadas. Alterar o traçado não desatualiza o diagrama: a posição das caixas ao longo do cabo é recalculada a cada leitura.

POPs e áreas

POP de rede é o ponto de presença onde ficam as OLTs. No POP você cadastra as OLTs e as PONs que alimentam a rede, e é dali que o cálculo de sinal parte.

Área demarcada é um polígono livre para marcar bairros, condomínios, regiões de atendimento ou de expansão. Desenhe clicando nos cantos e edite com o editor de vértices.

Diagrama de rede óptica

Cada caixa e cada POP tem um diagrama: os cabos que chegam, cada fibra no código de cores, os splitters, as portas e, no POP, as OLTs e PONs.

O que dá para fazer

• Anexar cabos à caixa. Numa caixa no meio do cabo, cada fibra tem dois lados (A, em direção ao início do traçado, e B, em direção ao fim).
• Adicionar splitters balanceados (1:2 a 1:64) ou desbalanceados (1/99 a 45/55).
• Ligar pontas: clique numa ponta livre e depois em outra. Fibra com fibra ou splitter vira fusão; porta ou PON vira conector.
• Desfazer ligação: clique na ligação e escolha "Desfazer ligação".
• Ver o sinal: clique em qualquer ponta. O painel mostra o caminho OLT → ponta, com a perda de cada trecho e o sinal teórico.
• Organizar o desenho: arraste os blocos, inverta lados e mude cores de pontas. A aparência não altera o cálculo.
• Registrar materiais usados na caixa.

Faixas de sinal (padrão)

Os limites são editáveis pelo Admin ISP no próprio diagrama. Detalhes do cálculo em Motor de cálculo óptico.

Modo Projeto

Um projeto é um conjunto de CTOs, emendas e cabos planejados, mantidos separados da rede real até a obra terminar.

• Dentro do projeto: a rede existente fica esmaecida e os elementos do projeto aparecem com contorno tracejado âmbar. Tudo o que você criar entra no projeto.
• Fora do projeto: só a rede existente aparece.
• Resumo: cada projeto mostra quantidades e metros planejados.

Ciclo de vida

Monitoramento de ONUs

O sistema lê periodicamente o sinal das ONUs nas OLTs, associa cada ONU à sua CTO e destaca no mapa as caixas com clientes offline.

O que aparece no mapa

Ao abrir uma CTO, o painel lista os clientes ligados a ela (PPPoE) com o sinal recebido (Rx) de cada ONU. O mapa confere a cada minuto se houve leitura nova e só baixa os dados quando algo mudou.

Avisos no Telegram

Quando uma CTO entra em alerta, uma mensagem é enviada ao grupo configurado. Quando ela volta, chega outro aviso com o percentual de ONUs recuperadas.

Ordens de serviço

As O.S. abertas no ERP MK aparecem como pins na camada O.S. Clique no pin para ver o número e os detalhes da ordem.

O Admin ISP pode personalizar os pins pelo botão ao lado da camada: a cor vale para todas as O.S., e cada equipe ou técnico ganha um símbolo (número 1 a 3, carrinho com número ou carrinho com "R" de rompimento). A configuração vale para todos os usuários.

Desligamentos de energia Módulo opcional

Para provedoras na área da Celesc, o sistema coleta as interrupções de energia programadas no portal público da distribuidora e as mostra no mapa, na camada Desligamentos e na lista Eventos no mapa (Todos, Hoje, Amanhã, Próximos dias).

Assim a equipe sabe com antecedência quais regiões da rede ficarão sem energia. Os usuários marcados em Alertas de rede recebem o aviso por e-mail.

Dashboard Editor+

Painel com os números da rede existente. O que está em projeto aparece à parte.

Lixeira e desfazer

Remover caixa, POP, área, cabo ou foto sempre pede confirmação, explicando as consequências. Depois de remover, Ctrl+Z restaura o item no servidor, fotos incluídas.

Conclusão: Guia de uso

Em resumo

• O mapa é a tela central: tudo é criado, encontrado e conferido nele.
• O diagrama de cada caixa e POP guarda as fusões e calcula o sinal teórico até cada ponta.
• O que é planejado fica no Modo Projeto e só vira rede existente quando a obra é concluída.
• Alertas de ONU, O.S. e desligamentos aparecem no próprio mapa.

Tarefas que você já sabe fazer

• Entrar no sistema e alternar entre cidades, camadas e satélite
• Encontrar a CTO mais próxima de um endereço com o pin temporário
• Cadastrar uma CTO e enviar fotos
• Desenhar um cabo usando o Ímã
• Ligar fibras no diagrama e conferir o sinal
• Criar um projeto e acompanhar o status até Concluído
• Ver as ONUs de uma CTO em alerta
• Desfazer uma remoção com Ctrl+Z

Próximo passo

Administração

Configurar a provedora e controlar quem acessa o quê.

Ao final desta camada você vai saber

• Os cinco níveis de permissão e como aprovar usuários
• Configurar identidade, cidades e OLTs
• Definir os padrões de rede e importar postes
• Gerenciar alertas, exportação e auditoria

Subcamadas

Níveis de permissão

Cada usuário tem um nível. Cada nível inclui tudo o que os anteriores podem fazer.

Usuários e aprovação

Em Admin → Usuários (Aprovação e Permissões) aparecem todos os cadastros. Para liberar alguém, escolha o nível e salve. Para bloquear, volte o usuário para Pendente.

Provedora

Em Admin → Provedora ficam a identidade e a região da sua empresa:

• Título e subtítulo do cabeçalho do mapa.
• Cidades atendidas, com sigla, município (IBGE), coordenadas e zoom. Cada cidade pode ou não virar aba; mesmo sem aba, ela conta para o enquadramento, para a "cidade mais próxima" das fotos e para o filtro de clientes.
• Aba aberta no primeiro acesso e o enquadramento da visão "Todas".

Coleta de ONUs (OLTs)

Em Admin → Coleta de ONUs você cadastra as OLTs de onde o sistema lê o sinal:

Padrões de rede

Em Admin → Padrões de rede fica a reserva técnica padrão dos cabos, usada quando o cabo não define a sua.

Dentro do diagrama de rede, o Admin ISP também ajusta:

• Parâmetros de perda óptica: atenuação por km, perda de fusão e de conector, potência da PON, drop médio, limites de sinal e tabelas de splitter. Ao salvar, todos os sinais são recalculados.
• Aparência padrão do diagrama: sequência de cores de fibras e tubos, separadores e cores das pontas, com opção de voltar ao padrão de fábrica.

Base de postes

Em Admin → Base de postes você importa a base de postes da distribuidora no formato KML ou KMZ da BDGD (ANEEL), com até 300 MB por arquivo. A importação atualiza o que já existe, sem duplicar. A tela mostra o total importado e a data da última importação.

Os postes aparecem na camada Infraestrutura → Base de postes e servem de ponto de encaixe para o Ímã ao desenhar cabos.

Alertas de rede

Escolha quem recebe por e-mail os avisos de desligamento de energia que afetam a rede (usuários de nível 2 ou mais, com e-mail cadastrado). O botão Disparar Alertas de Manutenção envia o aviso na hora, sem esperar a rotina.

Exportar mapa

Baixe a rede em KML ou KMZ (compactado) para abrir no Google Earth ou em outros sistemas. A exportação leva CTOs, CEOs e cabos. Postes, POPs, áreas, clientes e O.S. ficam de fora de propósito, para não expor dados pessoais.

Auditoria de ações

Em Admin → Registro de ações: toda criação, edição, remoção, login e mudança de permissão fica registrada com usuário, data, hora, IP e detalhe. Filtre por usuário ou tipo de ação.

A rotação acontece automaticamente. O botão Rotacionar agora força a rotação.

Conclusão: Administração

Em resumo

• Ninguém entra sem aprovação, e cada pessoa recebe só o nível de que precisa.
• Marca, cidades e OLTs ficam no banco da provedora e são editados no Admin, sem mexer em código.
• Toda ação fica na auditoria: 27 dias para consulta na tela e 1 ano em arquivo.

Checklist de configuração inicial

• Preencher título, subtítulo e cidades em Provedora
• Cadastrar as OLTs em Coleta de ONUs
• Definir a reserva técnica padrão dos cabos
• Revisar os parâmetros ópticos no diagrama
• Importar a base de postes da distribuidora
• Escolher quem recebe os alertas por e-mail
• Aprovar os usuários com o menor nível necessário

Próximo passo

Técnica

Entender como o sistema é construído, protegido e colocado no ar.

Ao final desta camada você vai saber

• A arquitetura e o modelo de uma instância por provedora
• Os controles de segurança e LGPD
• Como o sinal e os alertas são calculados
• As integrações externas
• Como implantar, agendar rotinas e configurar o .env

Subcamadas

Arquitetura

Multi-provedora

O mesmo código roda uma vez por provedora. Cada processo só conhece o seu .env, então não existe consulta que esqueça um filtro e vaze dados de outra provedora.

Garantias

• Configuração validada na subida: se faltar algo obrigatório, o processo não sobe e lista todos os problemas de uma vez.
• Login não atravessa provedoras: cada instância assina tokens com a sua chave, e o cookie é por domínio.
• Coletas não se atropelam: trava no PostgreSQL por banco; provedoras diferentes coletam em paralelo.
• Custo: cerca de 150 a 250 MB de memória por instância; 20 a 30 provedoras por servidor sem problema.

Segurança e LGPD

Motor de cálculo óptico

A rede vira um grafo de "pontas", que são os lugares onde a luz entra ou sai. Cada ligação tem uma perda em dB: fusão, conector, trecho de cabo, splitter ou passagem expressa (0 dB). A luz é propagada a partir de cada PON pelo caminho de maior sinal (Dijkstra). O splitter é a única ligação com sentido: sinal que chega por uma saída não volta pela entrada, então um splitter instalado ao contrário aparece como "sem sinal", como na vida real.

Parâmetros padrão (GPON classe B+/C+, 1490 nm)

O cálculo é teórico. Ele não substitui a medição com power meter, mas aponta erros de projeto antes da obra.

Regras de alerta de ONU

Os valores ficam como constantes no início de py/main.py e em py/core/notificador.py. Para mudar, edite e reinicie o serviço.

Integrações

Implantação de uma provedora nova

1. Banco e usuário próprios

   CREATE ROLE rkav_provedora_x LOGIN PASSWORD 'senha-forte';
   CREATE DATABASE rkav_provedora_x OWNER rkav_provedora_x;

   As tabelas são criadas na primeira subida.
2. Arquivo .env da instância: copie .env.example para /etc/gmaphub/provedora-x.env, preencha e gere chaves novas. Permissão 600, dono = usuário do serviço.
3. Pasta de dados: mkdir -p /srv/gmaphub/dados/provedora-x (as subpastas são criadas pelo sistema).
4. Serviço: use o modelo deploy/gmaphub@.service com uma porta livre em PORTA=.

   sudo systemctl enable --now gmaphub@provedora-x
   journalctl -u gmaphub@provedora-x -n 20

5. Domínio e HTTPS: um bloco server por provedora (modelo em deploy/nginx-gmaphub.conf.exemplo) e certificado com certbot --nginx -d provedora-x.seudominio.com.br.
6. Primeiro usuário: cadastre-se em /login e promova a Dono no banco da instância:

   UPDATE usuarios SET codigo = 4 WHERE username = '...';

7. No Admin, como Dono: preencha Provedora (título, cidades, visão inicial) e Coleta de ONUs (OLTs).
8. Agende as rotinas (próxima seção).

Rotinas agendadas

Sempre com o .env da instância em GMAP_ENV_FILE:

# Coleta de sinal das ONUs, a cada 30 minutos
*/30 * * * * cd /srv/gmaphub/app && GMAP_ENV_FILE=/etc/gmaphub/provedora-x.env venv/bin/python py/coletor_onu/executar.py >> /srv/gmaphub/dados/provedora-x/logs/coleta.log 2>&1

# Desligamentos Celesc, a cada 2 horas (só com MODULO_DESLIGAMENTOS=1)
0 */2 * * *  cd /srv/gmaphub/app && GMAP_ENV_FILE=/etc/gmaphub/provedora-x.env venv/bin/python py/scraper.py >> /srv/gmaphub/dados/provedora-x/logs/scraper.log 2>&1

Opções do coletor de ONUs

Sincronização de clientes e O.S. do MK: py/sincronizar_clientes.py e py/coletor_os.py, agendados conforme a necessidade da provedora.

Configuração (.env)

Toda configuração de instância passa por py/core/config.py. As principais:

Gerar uma chave Fernet:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Conclusão: Técnica

Em resumo

• Cada provedora roda em uma instância própria, com banco, chave e pastas separados.
• Credenciais de OLT são cifradas, fotos exigem login e a exportação não leva dados pessoais.
• O sinal é calculado por um grafo de perdas a partir de cada PON, e os alertas têm regras contra alarme falso.
• Implantar uma provedora nova é um checklist de oito passos, sem alterar código.

Checklist de entrada em produção

• Banco e usuário próprios criados
• Arquivo .env com chaves novas e permissão 600
• HTTPS ativo e COOKIE_SEGURO=1
• CHAVE_CREDENCIAIS guardada em local seguro, fora do servidor
• Serviço ativo e primeira linha do log conferida
• Coletor testado com --listar e --dry-run antes do cron
• Backup do banco e da pasta DADOS_DIR agendado

Próximo passo

Referência

Consultar rapidamente rotas, tabelas, limites, dúvidas comuns e termos.

Ao final desta camada você vai saber

• Onde fica cada rota da API e qual permissão ela exige
• Como os dados estão organizados no banco
• Os limites conhecidos do sistema
• Respostas para as dúvidas mais comuns

Subcamadas

Mapa da API

Todas as rotas exigem login, exceto as de autenticação. As de escrita exigem o nível indicado.

Modelo de dados

Limites conhecidos

• Scraper da Celesc: usa os nomes exatos das cidades no site da distribuidora, por isso a lista fica em py/scraper.py e não no Admin.
• Marca: o Admin muda título e subtítulo. Logo e favicon continuam os do RKAVision.
• Desfazer: só vale enquanto a aba estiver aberta.
• Coordenadas por OCR: ler as coordenadas escritas na foto exige o Tesseract instalado no servidor, e o caminho do programa hoje é o padrão do Windows. Sem ele, só fotos com GPS no EXIF criam caixas.
• Desligamentos: o scraper da Celesc usa o Playwright, que precisa do navegador Chromium instalado no servidor (playwright install chromium).
• Sinal calculado: é teórico e depende de a rede estar documentada corretamente.
• Rotas pelas ruas: o plano gratuito do OpenRouteService tem cota diária; acima dela, a distância cai para linha reta.
• Instâncias: acima de 20 a 30 provedoras por servidor, vale estudar juntar tudo num processo só (caminho descrito em docs/MULTI_TENANT.md).

Perguntas frequentes

Glossário

Conclusão: Referência

Em resumo

• A API segue a mesma regra de permissões das telas: ler exige login, alterar exige o nível certo.
• Os dados se dividem em rede física, rede lógica, monitoramento, planejamento, negócio e controle.
• Na dúvida sobre um termo, o glossário explica; na dúvida sobre uma situação, o FAQ.

Fim da documentação

Você percorreu as cinco camadas. Para voltar a qualquer uma delas:

• Camada 1 · Visão geral
• Camada 2 · Guia de uso
• Camada 3 · Administração
• Camada 4 · Técnica
• Camada 5 · Referência

Próximo passo