T-301 - Gravar na trilha o resultado sobre o qual a etapa agiu

• Componente: api, com a documentação do banco em docs/database/.
• Depende de: T-300 no develop.
• Data máxima: 05/11/2026
• Estimativa: 3 pontos (Fibonacci)

Entregável

• Migration 032-adiciona-resultado-em-trilhas-auditoria.sql com a coluna resultado_id, a chave estrangeira e o índice.
• NoConcluidoDto com o campo resultado_id.
• Gravação de resultado_id em JobRepository.inserirTrilhaNo.
• modelo-dados.dbml e modelo-dados.md atualizados.
• Testes da migration, do consumidor e da busca da meta.

Descrição

O evento no-concluido passa a trazer resultado_id, o resultado sobre o qual a etapa agiu. A tabela trilhas_auditoria não tem coluna para ele, e o consumidor da API ignora o campo. Esta tarefa cria a coluna e faz o consumidor gravá-la. A API precisa estar implantada antes de o codegen publicar o campo (T-302).

Contexto e decisões tomadas

• O consumidor está em ConsumidoresJob.receber (fila no-concluido), que chama JobEventosService.registrarNoConcluido, que chama JobRepository.inserirTrilhaNo. A deduplicação é pelo índice único de evento_id com ON CONFLICT (evento_id) DO NOTHING.
• A coluna é opcional e sem backfill. As linhas existentes ficam com o valor nulo.
• A chave estrangeira aponta para resultados_simulacao (id), como as que já existem na tabela para simulacoes, prompts, codigos_gerados e explicacoes. O resultado é gravado pelo worker antes de o codegen recebê-lo, então a referência existe quando o evento chega.
• A permissão da API em trilhas_auditoria é de tabela (GRANT SELECT, INSERT em 013-cria-trilhas-auditoria.sql) e cobre a coluna nova. Codegen e worker não acessam a tabela. A migration não tem GRANT.
• simulacao_id não substitui a coluna nova, porque as execuções candidatas da busca da meta não têm linha em simulacoes e o aceite da meta troca o resultado para o qual simulacoes.resultado_id aponta.
• A API não preenche simulacao_id nas linhas novas. Quem lê a trilha chega à simulação pelo código do resultado, que é único em simulacoes. Preencher na gravação dependeria da ordem entre consumidores, porque a linha de simulacoes pode ainda não existir quando a decisão chega.
• buscaMetaEmCurso lê o encaminhamento da decisão e a existência de uma decisão posterior da mesma versão. A T-302 mantém o nome decisao na linha que encerra a busca, e esta tarefa não muda essa consulta.

Escopo

Dentro do escopo

• Migration nova, NoConcluidoDto em MensagensRecebidasJob.java, inserirTrilhaNo em JobRepository.java e os testes afetados.
• docs/database/modelo-dados.dbml e a seção trilhas_auditoria de docs/database/modelo-dados.md.

Fora do escopo

• Rota ou leitura da trilha para o auditor.
• Preenchimento de simulacao_id fora da geração.
• Linhas confirmacao gravadas por TrilhaDaConfirmacao, que não têm resultado.
• Publicação do campo pelo codegen.

Requisitos

Migration

1. Criar api/src/main/resources/db/changelog/changesets/032-adiciona-resultado-em-trilhas-auditoria.sql, seguindo a skill migrations (api/.agents/skills/migrations/SKILL.md) e o padrão de 031-preserva-resultado-anterior-ao-aceite-da-meta.sql. O changeset adiciona resultado_id uuid, a constraint fk_trilhas_auditoria_resultado_id para resultados_simulacao (id) e o índice idx_trilhas_auditoria_resultado_id. O rollback é ALTER TABLE trilhas_auditoria DROP COLUMN resultado_id;. Conferir antes que 032 é o próximo número livre.

Consumo

2. Acrescentar @Nullable UUID resultado_id a NoConcluidoDto.
3. Em inserirTrilhaNo, incluir resultado_id na lista de colunas e no VALUES, com o valor do evento.
4. A violação da chave estrangeira não recebe tratamento próprio. Ela propaga como as das demais referências e volta para a fila, conforme a skill consumidores (api/.agents/skills/consumidores/SKILL.md).

Documentação do banco

5. Em modelo-dados.dbml, acrescentar à tabela trilhas_auditoria a coluna resultado_id uuid [ref: > resultados_simulacao.id], com nota que explica o que ela aponta em cada etapa (a mesma descrição do campo em no-concluido.schema.json, definida na T-300), quando fica nula e por que não substitui simulacao_id. Acrescentar o índice (resultado_id).
6. Na nota de evento_id, registrar que a API gera a chave das linhas confirmacao e que a linha que encerra a busca da meta usa chave própria, derivada do job e da versão.
7. Na nota de simulacao_id, trocar "null p/ nos 1-2" por um texto que diga que só a linha de geracao_codigo o traz e que as demais chegam à simulação pelo código do resultado.
8. Na seção trilhas_auditoria de modelo-dados.md, trocar "Uma linha por nó do grafo concluído" por "uma linha por etapa concluída", incluir a coluna resultado_id entre as referências e acrescentar o exemplo da conclusão da linha que encerra a busca. No parágrafo da chave de idempotência, registrar as duas exceções do requisito 6.

Observabilidade

9. Nenhuma métrica nova. Os logs atuais do consumidor continuam sendo emitidos e não passam a incluir conteúdo da conclusão.

Contexto técnico

• Entradas: evento no-concluido com resultado_id opcional.
• Saídas: linha de trilhas_auditoria com resultado_id quando o evento o traz.
• Componentes afetados: MensagensRecebidasJob.java, JobRepository.java, a migration nova, modelo-dados.dbml e modelo-dados.md.
• Restrições: changeset publicado é imutável; nenhum GRANT; sem backfill; um serviço por PR.
• Referências: migrations (api/.agents/skills/migrations/SKILL.md), consumidores (api/.agents/skills/consumidores/SKILL.md), logging (api/.agents/skills/logging/SKILL.md), api/src/main/resources/db/changelog/changesets/013-cria-trilhas-auditoria.sql, NoConcluidoConsumidorTests (api/src/test/java/synapse/api/job/NoConcluidoConsumidorTests.java), BuscaMetaAnunciadaTests (api/src/test/java/synapse/api/job/BuscaMetaAnunciadaTests.java), MigrationTests (api/src/test/java/synapse/api/core/persistence/MigrationTests.java), PermissoesDeBancoTests (api/src/test/java/synapse/api/core/persistence/PermissoesDeBancoTests.java).

Critérios de aceitação

• A migration aplica sobre um banco com linhas na trilha e o rollback remove só a coluna.
• Um evento com resultado_id grava a linha com a referência.
• Um evento sem resultado_id grava a linha com a coluna nula, como hoje.
• A reentrega do mesmo evento_id com resultado_id não grava segunda linha.
• A busca da meta continua aberta pela decisão com encaminhamento de busca e encerrada pela decisão posterior da mesma versão, com e sem resultado_id nas duas linhas.
• PermissoesDeBancoTests continua passando sem permissão nova para codegen e worker.

Definição de concluído (DoD)

• make check na api sem falha.
• Teste do consumidor exercitando ConsumidoresJob.receber com evento real serializado, conferindo a linha gravada e os logs serializados sem conteúdo.
• modelo-dados.dbml e a migration descrevem a mesma coluna, a mesma chave estrangeira e o mesmo índice.

Observações

• Uma violação da chave estrangeira volta para a fila indefinidamente, como já acontece com as referências existentes. Isso não ocorre no fluxo atual, porque o resultado é gravado antes de qualquer etapa citá-lo.