T-318 - Ligar a flag de baixa rastreabilidade e expor a explicação na API

• Componente: api.
• Depende de: T-316 no develop e T-301, que grava trilhas_auditoria.resultado_id. A T-317 é necessária para a verificação manual.
• Data máxima: 16/11/2026
• Estimativa: 5 pontos (Fibonacci)

Entregável

• Flag de baixa rastreabilidade ligada quando a etapa de explicação termina sem narrativa ou com a narrativa reprovada.
• Campo explicacao na simulação de GET /jobs/{id}.
• Evento explicacao no stream do job.
• Contador do desfecho registrado e logs sem conteúdo.
• Testes do consumidor, da consulta e do stream.

Descrição

A etapa de explicação do codegen grava a narrativa em explicacoes e publica a conclusão no evento no-concluido. A API já grava a linha da trilha desse evento, mas não liga a flag de baixa rastreabilidade, não devolve a narrativa e não avisa a tela quando ela fica pronta. Esta tarefa faz as três coisas.

Contexto e decisões tomadas

• O consumidor de no-concluido é ConsumidoresJob.receber, que chama JobEventosService.registrarNoConcluido. A linha da etapa explicacao traz resultado_id, explicacao_id quando há linha em explicacoes e desfecho_explicacao na conclusão.
• A flag fica em simulacoes.flag_baixa_rastreabilidade, e a API tem UPDATE em simulacoes (012-cria-simulacoes.sql). A simulação do resultado é achada pelo código, porque simulacoes.codigo_gerado_id é único. A linha de simulacoes é criada quando a geração do código é registrada, antes da execução. Por isso ela já existe quando a explicação chega.
• A flag liga quando o evento vem sem explicacao_id, ou quando a linha de explicacoes tem aderencia_conferida = false. Ligar de novo não muda nada, então a reentrega é segura.
• A consulta do job devolve a narrativa só quando ela é do resultado vigente da simulação e foi conferida. Depois do aceite da meta, o resultado vigente é a candidata, que não tem narrativa.
• O evento explicacao é emitido depois do commit, como os demais eventos do stream (skill sse (api/.agents/skills/sse/SKILL.md)). Ele não carrega o texto. A tela busca o job de novo.

Escopo

Dentro do escopo

• O tratamento da etapa explicacao no consumo de no-concluido, a leitura da explicação em JobRepository e RespostasJob, o evento do stream, AppMetrics e os testes.

Fora do escopo

• A consulta de auditoria, que já devolve as explicações (T-305).
• Qualquer escrita em explicacoes, que é do codegen.

Requisitos

1. No consumo de no-concluido com no = explicacao, na mesma transação da linha da trilha, ligar a flag da simulação cujo código é o do resultado do evento quando o evento vem sem explicacao_id ou quando a explicação tem aderencia_conferida = false.
2. Se a simulação do resultado não existir, registrar em warn e propagar a exceção, para a mensagem voltar à fila, como numa falha de banco.
3. Uma reentrega do mesmo evento_id não emite outro evento no stream nem conta outro desfecho.
4. Em GET /jobs/{id}, preencher simulacao.explicacao com o texto e a data da explicação conferida do resultado vigente.
5. Depois do commit, emitir no stream do job o evento explicacao com job_id, simulacao_id e disponivel.
6. Acrescentar a AppMetrics um contador do desfecho registrado (conferida, reprovada e ausente), no padrão dos contadores de consumo existentes, contando só a primeira gravação de cada evento.
7. Logs com job_id e o desfecho, sem o texto da narrativa.

Contexto técnico

• Entradas: evento no-concluido da etapa explicacao e a linha de explicacoes.
• Saídas: flag gravada, campo na consulta e evento no stream.
• Componentes afetados: api/src/main/java/synapse/api/job/ConsumidoresJob.java, api/src/main/java/synapse/api/job/JobEventosService.java, api/src/main/java/synapse/api/job/JobRepository.java, api/src/main/java/synapse/api/job/RespostasJob.java, api/src/main/java/synapse/api/job/EventosSseJob.java e api/src/main/java/synapse/api/core/metrics/AppMetrics.java.
• Restrições: nenhuma escrita em tabela de artefato do codegen; o stream não carrega texto; a resposta de erro não expõe detalhe interno.
• Referências: consumidores (api/.agents/skills/consumidores/SKILL.md), sse (api/.agents/skills/sse/SKILL.md), metrics (api/.agents/skills/metrics/SKILL.md), logging (api/.agents/skills/logging/SKILL.md), NoConcluidoConsumidorTests (api/src/test/java/synapse/api/job/NoConcluidoConsumidorTests.java), ContratoDoStreamTests (api/src/test/java/synapse/api/job/ContratoDoStreamTests.java).

Critérios de aceitação

• Uma explicação conferida deixa a flag falsa, aparece em GET /jobs/{id} e gera o evento com disponivel verdadeiro.
• Uma explicação reprovada liga a flag, não aparece na consulta e gera o evento com disponivel falso.
• Um evento sem explicacao_id liga a flag.
• A reentrega do mesmo evento não emite segundo aviso nem conta segundo desfecho.
• Depois do aceite da meta, a consulta não traz a explicação do resultado anterior.

Definição de concluído (DoD)

• make check na api sem falha.
• Evento do stream validado contra a especificação, como em ContratoDoStreamTests.
• Saída de /metrics conferida com o contador novo depois dos testes, e logs serializados sem o texto.