OLTs e ONUs¶

Código: backend/apps/olt/ e backend/apps/onu/ · Decisões: ADR 0007, ADR 0012, ADR 0013

OLT¶

Model	Uso
`Olt`	Equipamento: POP, fabricante, modelo, tecnologia (EPON/GPON), driver, IP de gerência, potência TX padrão, SNMP e acesso por linha de comando (SSH/Telnet)
`PortaPon`	Placa/porta, potência TX própria (opcional) e `fibra_saida`: a fibra do alimentador ligada nela, que conecta a OLT à rede física

O driver precisa combinar com a tecnologia (V-Sol EPON ↔ EPON, V-Sol GPON ↔ GPON).
Credenciais (communities SNMP, senha) ficam cifradas no banco, nunca aparecem na API, na auditoria nem no formulário do admin (deixar em branco mantém o valor guardado). Acesso por chave SSH: senha vazia.

ONU¶

Entidade única: autorizada na OLT, com o nome do cliente e ligada a uma porta da CTO.

Campo	Uso
`mac` / `numero_serie`	Identificação: EPON pelo MAC, GPON pelo nº de série (normalizados; únicos)
`olt`, `porta_pon`, `id_na_pon`	Onde está na OLT (`id_na_pon` único por porta PON)
`porta_cto`	Porta da CTO onde o drop está ligado (uma ONU por porta; só portas de atendimento de CTO)
`vlan`	VLAN principal: define o parceiro e entra na descrição
`vlans_adicionais`	Raro. Só do mesmo parceiro da principal ou da operadora
`nome_cliente`	O "cliente" do sistema (não há cadastro de clientes)
`local`, `comprimento_drop_m`	Localização da instalação e comprimento do drop
`estado` / `estado_operacional`	Autorizada, sem porta, removida… / online, offline, sem energia, sem sinal
`ultimo_rx_dbm`, `ultimo_tx_dbm`	Última leitura (histórico em Sinal)
`descricao_olt`	O que está de fato gravado na OLT

Descrição na OLT¶

Três formatos, conforme o que se sabe do cliente (todos em Admin → Configuração de ONU):

Situação	Formato padrão	Exemplo
CTO e porta conhecidas	`{vlan}.{cto_numero}.{porta}-{cliente}`	`3030.010.04-JOAO_DA_SILVA`
Só a CTO (porta desconhecida)	`{vlan}.{cto_numero}-{cliente}`	`3030.010-JOAO_DA_SILVA`
Nem CTO nem porta (ex.: reaproveitamento de cabo)	`{vlan}-{cliente}`	`3030-JOAO_DA_SILVA`

A ONU sem porta pode ter só a CTO informada (campo "CTO" da ONU). Na leitura das OLTs, zeros no lugar da CTO ou da porta (100.000.00-NOME, 100.010.00-NOME) contam como "não informada".

Formato completo configurável; padrão {vlan}.{cto_numero}.{porta}-{cliente} (ex.: 3030.010.04-Jose_da_Silva). Acentos são removidos e espaços viram _. Na mesma tela, dígitos do número da CTO (padrão 3: 010) e dígitos da porta (padrão 2: 04) completam com zeros à esquerda.

Variável	Valor
`{vlan}`	Número da VLAN principal
`{cto}`	Código da caixa (ex.: `CTO-010`)
`{cto_numero}`	Só o número do código, com os dígitos configurados (ex.: `010`)
`{porta}`	Número da porta da CTO (com os dígitos configurados)
`{cliente}`	Nome do cliente

Na leitura das OLTs, o número é comparado sem os zeros: 10, 010 e CTO-010 são a mesma CTO.

Porta ocupada (regra da F3)¶

Ao provisionar numa porta da CTO já usada, o sistema pergunta: "Esta porta está ocupada por NOME (ONU MAC…). Deseja substituir?". Confirmando, a ONU antiga fica sem porta (evento sem_porta) e a nova assume a porta.

Leitura das OLTs (SNMP)¶

O sistema lê das próprias OLTs, pela community de leitura cadastrada:

ONUs autorizadas: porta PON, ID, MAC, modelo, descrição, online/offline, RX, TX;
ONUs pendentes (pedindo autorização).

Quando roda:

Como	Quando
Rotina "OLTs: ler ONUs e sinal"	A cada 15 minutos, em todas as OLTs ativas (horário ajustável em Admin → Rotinas agendadas)
Rotina "OLTs: ONUs pendentes de autorização"	A cada minuto (leitura rápida, só a tabela de pendentes)
SNMP trap vindo da OLT	Na hora: qualquer trap de uma OLT cadastrada dispara a leitura das pendentes dela (no máximo uma a cada 10 s) — ver Receber traps das OLTs
Admin → OLTs → selecionar → Ler ONUs e sinal agora	Na hora
Admin → OLTs → selecionar → Testar conexão (SNMP)	Só confere o acesso e grava o resultado em "último teste"
`docker compose exec web python manage.py ler_olts [--olt NOME] [--testar]`	No terminal, com a lista de ONUs que ficaram sem porta

O que a leitura faz:

Acha a ONU pelo MAC (EPON) ou série (GPON); se não existe, cria (evento "detectada").
Atualiza OLT, porta PON, ID, modelo, situação e sinal; grava a leitura no histórico de sinal; registra eventos de online/offline quando muda.
Quando a descrição na OLT é nova ou mudou, interpreta-a e liga a ONU:
- formato configurado (Configuração de ONU) ou VLAN.CTO.PORTA-CLIENTE (ex.: 3030.10.4-JOAO_DA_SILVA): VLAN, cliente e porta da CTO (CTO achada pelo número do código: 10 → CTO-010);
- VLAN-CLIENTE (ex.: 100-jose.carlos): só VLAN e cliente;
- outro texto: vira o nome do cliente. VLAN que ainda não existe é criada como da operadora. A porta não é tomada de outra ONU: o conflito aparece na lista "sem porta". Se a descrição não mudou, nome e VLAN não são tocados — correções feitas no sistema ficam. ONU ainda sem porta é tentada de novo a cada leitura (a CTO pode ter sido cadastrada depois), e o motivo fica no campo Pendência de vínculo (Admin → ONUs → filtro "Sem porta").
MAC duplicado (o mesmo MAC em duas portas, ou ativo em duas OLTs): a ONU fica onde já estava, a duplicidade vai para a pendência e gera um evento "duplicada" (uma vez).
ONU que sumiu da OLT vira removida e libera a porta da CTO. Proteção: se faltar mais de 30% das ONUs de uma vez, nada é removido (leitura provavelmente incompleta).
Pendentes: entram e saem conforme a OLT.

Se a OLT não responde, nada é alterado e o "último teste" fica como falha.

Drivers disponíveis: V-Sol EPON (V1600D). Os demais (V-Sol GPON, Huawei, ZTE, Intelbras) entram na mesma interface (backend/apps/olt/drivers/), conforme o ADR 0007.

Autorizar e vincular¶

Pela tela Provisionar (ver Telas) ou pela API (/api/provisionar/…, só técnico e administrador). Regras em backend/apps/onu/provisionamento.py:

confere a porta escolhida; ocupada → pede confirmação (HTTP 409 na API);
fala com a OLT: autoriza (MAC em minúsculas na V-Sol), espera o ID, grava a descrição;
só então grava no sistema, numa transação, com os eventos (autorizada, porta_alterada, substituida na ONU que perdeu a porta).

Se a OLT recusar no passo 2, nada muda no sistema. Se a autorização passar e só a descrição falhar, a ONU é registrada com a pendência "descrição não gravada na OLT".

O SysOLT pode continuar autorizando em paralelo: o NOC FTTH lê o resultado na próxima leitura. Só não autorize a mesma ONU nos dois ao mesmo tempo.

Outras entidades¶

Model	Uso
`OnuPendente`	ONU vista na OLT e ainda não autorizada (alimenta os avisos da F3)
`EventoOnu`	Histórico: detectada, autorizada, removida, substituída, porta alterada, sem porta, online/offline, falta de energia, perda de sinal, sinal crítico, duplicada
`ConfiguracaoOnu`	Formato da descrição e autorização automática (registro único)

API (leitura)¶

Endpoint	Filtros	Parceiro
`/api/onus/`	`vlan` (número), `olt`, `porta_pon`, `cto` (código), `estado`, `estado_operacional`, `busca` (cliente, MAC, série)	só VLANs dele, sem dados da OLT
`/api/onus-eventos/`	`onu`, `tipo`	só das ONUs dele, sem detalhes técnicos
`/api/onus-pendentes/`, `/api/olts/`, `/api/olts-portas-pon/` (`olt`)	—	vazio