Pular para conteúdo

F1 — Proposta do modelo de dados

Situação: aprovada em 09/11/2026

Este documento descreve como os dados do sistema são organizados. Foi revisado e aprovado antes do código. Implementada na versão 0.4.0 (ver ADR 0012 e as páginas de Módulos); as respostas às perguntas de revisão estão no fim desta página.

Visão geral

O sistema guarda quatro grupos de informação, todos ligados entre si:

Grupo O que é Módulo
Rede física Onde as coisas estão: POPs, postes, cabos, fibras, caixas (CTO/CEO), splitters e suas portas rede
Equipamentos ativos OLTs, portas PON e ONUs (com o nome do cliente) olt, onu
Parceiros e VLANs Quais VLANs existem e de qual parceiro é cada uma parceiros
Sinal e eventos Leituras de potência óptica e o que aconteceu com cada ONU monitoramento

Sem cadastro de clientes

O sistema não tem cadastro de clientes. O cliente é identificado pelo nome gravado na ONU, usado na descrição que vai para a OLT (ex.: 3030.10.4-JOAO_DA_SILVA). Uma integração com o sistema de gestão (MK-Auth) pode ser feita no futuro.

Existem duas ordens diferentes ligando as coisas, e as duas se encontram na ONU.

A. Caminho físico (por onde a luz passa), da OLT até o equipamento na casa:

flowchart LR
    OLT[OLT] --> PON[Porta PON]
    PON -->|fibra do cabo| SP1[Splitter primário]
    SP1 -->|porta de cascata| SP2[Splitter da CTO]
    SP2 --> PORTA[Porta da CTO]
    PORTA -->|drop| ONU["ONU<br/>(nome do cliente)"]
    CTO[Caixa CTO] -. contém .-> SP2

B. Caminho de propriedade (de quem é):

flowchart LR
    PARC[Parceiro] -->|é dono da| VLAN[VLAN]
    VLAN -->|configurada na| ONU["ONU<br/>(nome do cliente)"]
  • A luz termina na ONU: é ela que está ligada ao drop e é dela o sinal medido (RX).
  • A VLAN é configurada na ONU (é assim que a OLT trabalha) e define o parceiro dono daquele atendimento. VLAN sem parceiro é da própria operadora.

Com essas duas ordens, o sistema responde perguntas que hoje exigem dois sistemas e conferência manual:

  • "Quais ONUs (clientes) estão atrás deste splitter?" → para detectar rompimento.
  • "Qual é o sinal esperado para esta ONU?" → orçamento óptico pelo caminho.
  • "Quais portas estão livres nesta CTO?" → provisionamento guiado.
  • "O que o parceiro X pode ver?" → filtro por VLAN.

Diagrama de entidades

erDiagram
    PARCEIRO ||--o{ VLAN : "é dono de"
    PARCEIRO ||--o{ USUARIO : "tem usuários"
    VLAN ||--o{ ONU : "configurada na"

    POP ||--o{ OLT : abriga
    OLT ||--o{ PORTA_PON : tem
    PORTA_PON ||--o{ ONU : "atende"
    PORTA_PON |o--o| FIBRA : "sai pela"

    POSTE |o--o{ CAIXA : sustenta
    MODELO_CABO ||--o{ CABO : "é do modelo"
    CABO ||--o{ FIBRA : contém
    CABO ||--o{ RESERVA_TECNICA : tem
    CAIXA ||--o{ FUSAO : abriga
    FIBRA ||--o{ FUSAO : "ponta A / B"

    CAIXA |o--o{ SPLITTER : contém
    POP |o--o{ SPLITTER : contém
    SPLITTER ||--o{ PORTA_SPLITTER : tem
    PORTA_SPLITTER |o--o| SPLITTER : "alimenta (cascata)"
    FIBRA |o--o| SPLITTER : "alimenta"

    PORTA_SPLITTER |o--o| ONU : "ligada por drop"
    ONU ||--o{ LEITURA_OPTICA : mede
    ONU ||--o{ EVENTO_ONU : registra
    OLT ||--o{ ONU_PENDENTE : detecta

Entidades

As tabelas abaixo mostram os campos principais. Campos técnicos (data de criação, autor e auditoria) existem em todas e foram omitidos.

Parceiros e VLANs — parceiros

Entidade Campos principais Regras
Parceiro nome, documento, contato, WhatsApp, e-mail, ativo Provedor que usa a rede. Ver ADR 0011
VLAN número (1–4094, único), nome, parceiro (opcional) Sem parceiro = VLAN da própria operadora

O usuário ganha o campo opcional parceiro: com parceiro, só consulta e só vê o que é das VLANs dele.

Rede física — rede

Entidade Campos principais Regras
POP nome, endereço, localização (ponto) Onde ficam as OLTs
Poste código, localização, altura, material, proprietário, código da concessionária
Modelo de cabo nome, nº de fibras, fibras por tubo, padrão de cores (ABNT/EIA) As cores das fibras são geradas a partir do modelo
Cabo código, modelo, tipo (alimentador, distribuição, drop), traçado (linha), situação (planejado, instalado, certificado), ponta A e ponta B (caixa ou POP) Comprimento calculado pelo traçado
Fibra cabo, número, tubo, cor Única por cabo + número; criada automaticamente com o cabo
Reserva técnica cabo, localização, metros, caixa (opcional) Entra no cálculo de comprimento óptico
Caixa código (único), nome, tipo (CTO, CEO, DIO), localização, poste ou POP, situação, endereço Só a CTO tem porta de atendimento; CEO e DIO só têm emendas e cascatas
Fusão caixa, fibra A, fibra B, tipo (fusão, conector), perda (dB) Ligação fibra ↔ fibra com chave estrangeira, sem campos "tipo + id" soltos
Splitter local (caixa ou POP), nome, razão (1:2…1:64), balanceado ou não, perda (dB), entrada (fibra ou porta de outro splitter) Exatamente um local e uma entrada
Porta de splitter (na CTO: porta da CTO) splitter, número, perda (dB, para desbalanceados), papel (atendimento ou cascata), estado (livre, reservada, com defeito) Ocupada quando tem uma ONU ligada (calculado). Porta de cascata alimenta outro splitter e nunca recebe ONU

Equipamentos ativos — olt e onu

Entidade Campos principais Regras
OLT nome (único), POP, fabricante, modelo, tecnologia (EPON, GPON), IP de gerência, firmware, nº de série, driver, SNMP (versão, community de leitura, community de escrita), CLI (SSH ou Telnet, porta, usuário, senha/chave), situação, último teste Communities e senhas criptografadas no banco
Porta PON OLT, placa, porta, potência TX (dBm), fibra de saída, ativa Única por OLT + placa + porta
ONU OLT, porta PON, MAC (EPON) ou nº de série (GPON), ID na PON, porta da CTO (onde o drop está ligado), VLAN principal, VLANs adicionais (opcional), nome do cliente, comprimento do drop (m), localização da instalação (opcional), modelo, firmware, estado (autorizada, removida), estado operacional (online, offline, desconhecido), último RX/TX, descrição gravada na OLT, autorizada em/por MAC e nº de série únicos no sistema; a VLAN principal define o parceiro e entra na descrição; VLANs adicionais precisam ser do mesmo dono
ONU pendente OLT, porta PON, MAC ou série, detectada em, vista por último em, avisos enviados Some quando a ONU é autorizada; vira histórico de eventos

A descrição gravada na OLT passa a ser gerada pelo sistema a partir de VLAN, CTO, porta e nome do cliente. O formato é configurável; o padrão é o mesmo usado hoje, {vlan}.{cto}.{porta}-{cliente}, com _ no lugar de espaço.

Sinal e eventos — monitoramento

Entidade Campos principais Regras
Leitura óptica ONU, data/hora, RX (dBm), TX (dBm), temperatura, origem (SNMP ou manual), usuário (se manual) Histórico, não sobrescreve. Medições manuais de campo entram aqui também
Resumo diário ONU, dia, RX mínimo/médio/máximo, nº de leituras Guarda a tendência de longo prazo
Evento de ONU ONU, OLT, porta PON, identificador (MAC/série), tipo (detectada, autorizada, removida, online, offline, falta de energia, perda de sinal, sinal crítico, vinculada, substituída…), detalhes, usuário, quando Trilha completa, com chave estrangeira; o identificador fica guardado mesmo se a ONU for excluída

Retenção proposta: leituras detalhadas por 90 dias e resumo diário sem prazo. Com 2.000 ONUs lidas a cada 15 minutos, são cerca de 190 mil leituras por dia; 90 dias cabem com folga no PostgreSQL com o índice adequado.

Configurações

Configuração Conteúdo
Parâmetros ópticos Perda por km (1310/1490 nm), por fusão e por conector, margem de segurança
Limiares de sinal RX ótimo, normal e crítico
ONU Formato da descrição gravada na OLT, autorização automática (liga/desliga)

Alertas, destinos de WhatsApp e templates de mensagem são modelados na F4.

Acesso por VLAN (parceiros)

Cada entidade declara como chega à VLAN. Um único método, visiveis_para(usuario), aplica a regra em toda a API, nos alertas e nos relatórios.

Entidade Equipe interna Usuário de parceiro
ONU (com o nome do cliente), leituras, eventos tudo só das VLANs do parceiro
Caixa (CTO) tudo todas
Ocupação de portas tudo todas as portas; as ocupadas por ONU das VLANs dele aparecem com o nome do cliente; as demais só como ocupada ou livre
Cabos, fibras, fusões, splitters, postes, POPs, OLTs, portas PON, ONU pendente tudo nada
Usuários, auditoria, configurações conforme o papel nada

Decisões de modelagem

  1. Chaves inteiras (como no SysOLT) no lugar de UUID. Índices menores e mais rápidos. Para rastrear a importação, cada registro importado guarda sistema de origem + id original numa tabela de mapeamento.
  2. Nada de ligação "tipo + id" solta (o polimorfismo do SysFTTH). Toda ligação é chave estrangeira de verdade, com o banco garantindo que a ponta existe.
  3. Uma ONU = um registro. Some a ONU espalhada em 5 tabelas do SysOLT.
  4. VLAN é entidade, ligada à ONU. A VLAN principal define o parceiro e entra na descrição; a ONU pode ter VLANs adicionais (casos raros, ~2%), sempre do mesmo dono da principal.
  5. Sem cadastro de clientes. O cliente é o nome na ONU, usado na descrição gravada na OLT. Os dados de cliente do SysFTTH (documento, contrato, velocidade) não são migrados; o nome, o comprimento do drop e a localização passam para a ONU correspondente.
  6. Leituras de sinal são histórico, com resumo diário para longo prazo.
  7. Geografia em geography (SRID 4326), como no SysFTTH. Distâncias e comprimentos saem em metros direto do banco.
  8. Comprimentos e estados derivados são calculados, não digitados: comprimento do cabo pelo traçado, porta ocupada quando tem ONU, cores das fibras pelo modelo do cabo.
  9. Splitter guarda a porta PON de origem resolvida (calculada ao alterar a topologia). Acelera a detecção de rompimento e a ocupação por PON, sem percorrer a rede toda a cada consulta.
  10. A porta da CTO liga na ONU: é a ONU que está fisicamente ligada ao drop e é dela o sinal medido.
  11. Porta da CTO ocupada no provisionamento: se o técnico escolher uma porta que já tem ONU, o sistema mostra quem está nela e pergunta "Esta porta está ocupada por NOME DO CLIENTE (ONU MAC…). Deseja substituir?". Ao confirmar, a ONU antiga fica sem porta (aparece numa lista de pendências para não se perder) e a troca vai para o histórico e a auditoria. A ação "Substituir ONU" (troca de equipamento com defeito) passa porta, VLAN e nome do cliente da antiga para a nova.
  12. Auditoria em todas as entidades de cadastro. Leituras de sinal e eventos não passam pela auditoria, porque já são o próprio histórico.

Respostas da revisão (09/11/2026)

Pergunta Resposta
Uma ONU tem uma única VLAN? Quase sempre (~98%). Modelo: VLAN principal + VLANs adicionais opcionais, do mesmo dono
Tipos de caixa CTO, CEO e DIO
Onde fica o splitter primário Na rua (caixa) ou no POP/armário
Retenção do sinal 90 dias detalhado + resumo diário para sempre
Localização da instalação na ONU Sim, opcional

O que a F1 entrega

  • Models, migrações e admin de todas as entidades acima, já com o filtro por VLAN.
  • Testes: regras de cada entidade, mais o teste que percorre a API como parceiro e falha se aparecer dado de outra VLAN.
  • Documentação: um módulo por grupo, ADRs das decisões de modelagem e o diagrama gerado automaticamente.
  • Sem telas novas (elas são a F2). O cadastro pode ser feito pelo admin para testes.