T-335 - Implementar na API o resumo do dossiê do auditor

• Componente: api.
• Depende de: T-333 no develop e T-305, que cria a fatia auditoria e a política de acesso do auditor.
• Data máxima: 16/11/2026
• Estimativa: 5 pontos (Fibonacci)

Entregável

• GET /auditoria/jobs/{id}/resumo na fatia synapse.api.auditoria, conforme o contrato da T-333.
• Testes de autorização, de conteúdo e de observabilidade.

Descrição

O dossiê do auditor mostra quantas simulações a regra teve, quantas concluíram e quantas falharam, o que mudou de uma versão para a outra e a variação de uma simulação para a anterior. O frontend não calcula valor exibido, então a API devolve esses números prontos. Esta tarefa implementa a rota do resumo definida na T-333.

Contexto e decisões tomadas

• A fatia auditoria da T-305 já tem a recusa de quem não é auditor e o tratamento de erro {codigo, mensagem}. A rota nova reaproveita os dois.
• As alterações de uma versão comparam regras.nucleo e regras.especificacoes com os da versão apontada por regra_origem_id. Uma parte do núcleo é identificada como nucleo.<campo> e um elemento pelo seu ref, como em elemento_ref.
• A comparação entre simulações usa resultados_simulacao.totais e resultados_simulacao.meta_venda do resultado de cada simulação, e compara cada simulação concluída com sucesso com a anterior também concluída com sucesso, pela ordem de criação.
• A versão vigente é a da simulação vigente do job, a mesma que GET /jobs/{id} usa.
• As métricas HTTP do Micrometer já medem volume, falha e duração por rota. Nenhuma métrica de domínio é criada.

Escopo

Dentro do escopo

• Controller, serviço, repositório e DTOs da rota na fatia auditoria.
• Testes da fatia.

Fora do escopo

• GET /auditoria/jobs/{id}, que é da T-305.
• O painel de eventos, que é da T-334.

Requisitos

Acesso

1. A rota chama UsuarioAtual.obter() antes de ler dados e recusa com 403 sem_permissao quem não tem o papel auditor. Sessão ausente recebe 401 pela cadeia existente. Id inexistente recebe 404 job_nao_encontrado, e id malformado recebe 400.

Conteúdo

2. Contar as simulações registradas do job, as concluídas com sucesso e as que terminaram com outro status, sem as execuções candidatas da busca da meta.
3. Para cada versão com origem, listar só as partes que mudaram: incluídas, removidas e alteradas, com o valor anterior e o novo como estão gravados.
4. Para cada simulação comparada, calcular a variação de cada indicador do contrato como atual menos anterior.
5. Calcular com BigDecimal e devolver os valores sem arredondamento, com a precisão gravada, como faz JobRepository.

Restrições

6. Nenhuma consulta lê resultados_simulacao.linhas, submissoes.binario, prompts, respostas ou a fonte dos códigos.

Observabilidade

7. Abrir o CorrelationContext com o job_id e o id do usuário auditor e fechá-lo ao terminar, inclusive em erro.
8. Registrar em info a consulta concluída, com mensagem estável, e em warn a recusa por papel, sem dados do token. Nenhum log traz valores da regra ou do resultado.

Contexto técnico

• Entradas: token do usuário e id do job.
• Saídas: a resposta do resumo do contrato.
• Componentes afetados: api/src/main/java/synapse/api/auditoria/.
• Restrições: só leitura; nenhuma escrita em tabela; resposta de erro sem detalhe interno.
• Referências: architecture (api/.agents/skills/architecture/SKILL.md), logging (api/.agents/skills/logging/SKILL.md), docs/database/modelo-dados.dbml, contracts/domain/resultado-totais.schema.json, contracts/domain/comum.schema.json (elemento_ref), JobRepository.java (api/src/main/java/synapse/api/job/JobRepository.java).

Critérios de aceitação

• Num job com a versão 1 extraída e a versão 2 corrigida, que muda só o percentual, a versão 2 traz só nucleo.percentual, com o valor anterior e o novo, e a versão 1 não traz alterações.
• Num job com a simulação 1 em erro_codigo e as simulações 2 e 3 em sucesso, os contadores são 3, 2 e 1, a simulação 3 é comparada com a 2, e as simulações 1 e 2 não têm comparação.
• A variação de simulado é igual à diferença exata entre os dois totais gravados.
• Um profissional de RH recebe 403, uma requisição sem sessão recebe 401 e um job inexistente recebe 404.

Definição de concluído (DoD)

• make check na api sem falha.
• Testes exercitando a rota com token de auditor, de RH e sem token, com logs serializados conferidos quanto ao usuário, ao job_id e à ausência de valores.
• Saída de /metrics conferida depois de exercitar a rota, com http_server_requests para o template /auditoria/jobs/{id}/resumo.
• Resposta validada contra o schema da especificação num teste.