ADR 0011 — Acesso restrito por VLAN (parceiros)¶

Status: Aceita (implementação na F1) · Data: 09/11/2026 (ajustada no mesmo dia: parceiro vê todas as CTOs)

Contexto¶

A rede de fibra pode ser compartilhada com parceiros: outros provedores que atendem os próprios clientes usando a mesma infraestrutura, cada um na sua VLAN. Um parceiro precisa acompanhar os clientes dele, mas não pode ver os clientes dos outros nem o restante da rede.

Exemplo: o usuário João pertence ao parceiro dono da vlan 200. Ele deve ver somente o que é da VLAN 200, em todo o sistema: listas, mapa, relatórios, alertas e API.

Decisão¶

Modelo¶

Parceiro: empresa que usa a rede (nome, contato, ativo).
VLAN: número (1–4094), nome e dono (parceiro, ou vazio quando é da própria operadora). Cada VLAN tem no máximo um dono; um parceiro pode ter várias VLANs.
Usuário: campo opcional parceiro.
Sem parceiro (equipe interna): vê tudo, conforme o papel (ADR 0005).
Com parceiro: acesso restrito às VLANs do parceiro e somente consulta, qualquer que seja o papel.

O que o usuário de parceiro vê¶

Item	Visibilidade
ONUs (com o nome do cliente)	Só as das VLANs do parceiro
Sinal (RX), histórico, eventos	Só dessas ONUs
CTOs	Todas (localização, código, capacidade)
Ocupação das portas	Portas com ONU das VLANs do parceiro aparecem identificadas (nome do cliente); as demais aparecem só como ocupada ou livre, sem nenhum dado do cliente
Cabos, fibras, emendas, splitters, postes, POPs, OLTs	Não vê
Auditoria, usuários, configurações, admin	Não vê

O que o usuário de parceiro faz¶

Consulta o que está acima.
Recebe alertas (sinal ruim, ONU offline, rompimento que afete clientes dele) somente das VLANs dele.
Não altera nada (não autoriza ONU, não edita cadastro).

Como garantir que nada vaze¶

O filtro fica num único lugar e é aplicado por padrão, não tela a tela:

Cada modelo com dado de parceiro declara como chega à VLAN (ex.: ONU → vlan; leitura de sinal → ONU → vlan). CTOs não são filtradas. O sistema não tem cadastro de clientes: o cliente é o nome gravado na ONU.
Um método central, visiveis_para(usuario), aplica esse caminho. Para a equipe interna ele não filtra; para parceiro, filtra pelas VLANs dele. Para modelos que o parceiro não pode ver, devolve vazio.
Na ocupação das portas, a porta só traz o nome do cliente quando a ONU ligada nela é visível para o usuário; caso contrário, mostra apenas o estado (ocupada/livre).
Toda view da API herda de uma base que sempre usa visiveis_para, e parceiros recebem só métodos de leitura.
Alertas e relatórios usam o mesmo método para escolher destinatários e conteúdo.
Testes automáticos: um usuário de parceiro percorre todas as rotas da API e nunca pode receber dado de outra VLAN; além disso, um teste falha se alguma rota da API não usar a base com filtro.

Alternativas consideradas¶

Filtrar tela a tela: simples no início, mas basta esquecer um filtro numa tela nova para vazar dados de um parceiro para outro.
Banco separado por parceiro: isolamento total, mas a rede física é a mesma; duplicar dados quebraria a fonte única da verdade.
Segurança em nível de linha no PostgreSQL (RLS): forte, mas complexa de manter com o ORM. Pode ser acrescentada depois como segunda camada.

Consequências¶

A VLAN vira entidade própria no modelo de dados (F1), ligada à ONU.
Mudar o dono de uma VLAN muda imediatamente o que cada parceiro vê (fica registrado na auditoria).
Usuários de parceiro não acessam o /admin/; usam as telas do sistema (F2) e a API.