Profissionalização: CI que roda, ingestão em lote real, OPC-UA plugado e vitrine no padrão

[Roberton003]

Contexto

O repositório já tinha substância técnica — adapters Modbus/OPC-UA, regras de qualidade, dashboard HTMX, OTel opcional. O problema era que o que estava público não correspondia ao que o código fazia.

O que estava quebrado

Gap	Evidência
O CI nunca rodou	ci.yml disparava em main; o branch default é master. Os jobs de lint e de teste com Postgres nunca executaram uma única vez.
Ingestão em lote decorativa	evaluate_and_alert() fazia um INSERT por leitura; o bulk_create() seguinte era no-op silencioso sobre objetos já com pk. Reprocessar a mesma janela estourava IntegrityError.
Docs contradizendo o código	replay-idempotency.md afirmava "deduplicação não existe" com a UniqueConstraint(sensor, timestamp) no modelo desde a migration 0004.
Sem LICENSE	Repo público sem licença = todos os direitos reservados.
Trabalho não publicado	Todo o refactor de sources/ + 184 linhas de teste só existiam no disco local.
Vazamento de caminho local	manual_validacao_ponta_a_ponta.md expunha o caminho absoluto do disco do autor, 4×.

O que mudou

CI (3c85544, 6a4d07f) — dois workflows sobrepostos consolidados em um, no branch certo: ruff + Postgres 16 + manage.py check + makemigrations --check + check --deploy informativo.

Ingestão (6a4d07f) — raise_alert() extraído de evaluate_and_alert(). O loop agora avalia em memória (evaluate_reading() é pura), persiste o lote uma vez e alerta depois. ignore_conflicts=True finalmente faz o que promete.

Teste negativo — test_replay_same_window_is_idempotent foi verificado falhando sem o fix, com IntegrityError: UNIQUE constraint failed. Guardrail só existe depois de observar o bloqueio.

Vitrine (30373fb) — LICENSE MIT; README em pt-BR nas 10 seções do padrão, com diagrama Mermaid nativo e badge de CI (agora honesto); wiki alinhada, incluindo página nova de Idempotência e a menção a OPC-UA que faltava.

Compose (eff8155) — validando docker compose up --build numa máquina com Postgres e collector OTLP locais, o stack não subia (colisão em 5432, depois 4317), e com o Jaeger fora do ar todo manage.py no container inundava a saída com erros de export. Portas agora sobrescrevíveis por variável.

Verificação

• 73 testes verdes, ruff limpo, migrations em sincronia
• Docker end-to-end em portas alternativas: dashboard HTTP 200, ingestão limpa, /api/summary/ com dados, Jaeger reportando o serviço labtelemetry
• Comandos de setup do README executados antes de serem documentados

Fora de escopo (registrado, não feito)

• OpcUaAdapter existe e tem testes, mas ingest_telemetry tem choices=["modbus", "simulator"] — inalcançável na prática
• Modbus lê registradores uint16 crus, sem escala/decodificação float32
• Deps não pinadas, sem pre-commit, sem gate de coverage

[Roberton003]

Adendo: OPC-UA plugado (ce16377)

O PR original listava isto como fora de escopo. Agora está dentro.

Por que não era só adicionar uma opção ao --source

O OpcUaAdapter emitia sensor_id=idx — o índice posicional do node. Mas _sample_to_reading() trata esse campo como chave primária de TelemetrySensor. Node 0 vira "sensor 0", que ou não existe ou é o sensor errado: dado plausível e silenciosamente incorreto, a pior classe de bug em telemetria.

O mesmo vale para o ModbusTCPAdapter (sensor_id = índice do registrador). Ele passa nos testes porque o adapter é stubado; contra um CLP real tem a mesma fragilidade. Não corrigi o Modbus neste PR — fora do escopo pedido, mas fica registrado.

O que foi feito

• OpcUaAdapter aceita sensor_ids paralelo a node_ids, validado 1:1. Sem ele, mantém o índice posicional — os 3 testes existentes seguem válidos.
• --source opcua com --opcua-url, --opcua-timeout e --opcua-node repetível, formato NODE_ID:SENSOR_ID. O split é no último :, já que node ids contêm = e ; (ns=2;i=101). Sem mapeamento, o comando recusa iniciar.
• Guard de coerência em _sample_to_reading(): avisa quando o parâmetro da fonte diverge do sensor, sem descartar a leitura. Vale para as três fontes.
• /api/health/sources/ passa a incluir opcua — README e wiki afirmavam cobertura das três fontes, o endpoint devolvia duas.

Verificação

Contra servidor OPC-UA real, fora da suíte de testes:

Cenário	Resultado
Sem --opcua-node	Recusa iniciar com mensagem acionável
Spec malformado (ns=2;i=101)	Recusa, aponta o formato esperado
Mapeamento correto	PH=7.0 → sensor 1, TOC=5.0 → sensor 5, com lineage opcua:opc.tcp://...
Node de pH → sensor de TOC	Sensor 5 e TOC, mas a fonte enviou PH — verifique o mapeamento

79 testes verdes (6 novos, incluindo integração contra servidor OPC-UA real, rodada 3× para checar flakiness), ruff limpo, CI verde nos dois jobs.

[Roberton003]

Adendo 2: Modbus corrigido (9e96c5d)

Fecha o gap que o adendo anterior deixou registrado.

Dois bugs, um deles silencioso

1. Índice de registrador tratado como chave primária. O adapter emitia sensor_id = índice do registrador (0/1/2 via PARAMETER_MAP). Contra um CLP real, o registrador 0 tentaria gravar no "sensor 0" — que nunca existe, porque o autoincrement do Django começa em 1. Passava nos testes só porque o adapter era stubado.

2. Holding register é uint16, e o valor era usado cru. Um pH de 7.40 é publicado pelo CLP como 740. Sem fator de escala, entrava no banco como pH 740:

Leitura bruta	Escala	Valor gravado	Dentro de 6.0–8.5?
740	— (bug)	pH 740.0	❌
740	0.01	pH 7.40	✅

Esse é o pior dos dois: não falha, só produz série temporal errada. A escala é o mesmo tipo de ajuste que calibration_factor faz um nível acima — uma corrige o protocolo, a outra o sensor.

O que foi feito

• RegisterSpec(address, sensor_id, scale) e o parâmetro registers no ModbusTCPAdapter. Sem ele, cai no caminho legado (bloco 0–2), preservado só para inspeção rápida de um CLP e documentado como tal.
• --modbus-register "ADDRESS:SENSOR_ID[:SCALE]", repetível. Escala omitida vale 1.0. Sem mapeamento, o comando recusa iniciar — simétrico ao --opcua-node.
• Uma leitura por registrador em vez de um bloco 0..N: endereços esparsos tornam a leitura em bloco inválida em muitos CLPs (registrador não mapeado no meio do span). O ceiling e o caminho de upgrade estão anotados no código.
• Registrador que falha é pulado sem derrubar os demais do ciclo.

85 testes verdes (6 novos), ruff limpo, CI verde nos dois jobs.

Com isso as três fontes têm o mesmo contrato: mapeamento explícito, recusa de iniciar sem ele, e guard de coerência de parâmetro na ingestão.