T-305 - Implementar na API a consulta de auditoria

• Componente: api.
• Depende de: T-304 no develop e T-301, que cria trilhas_auditoria.resultado_id.
• Data máxima: 11/11/2026
• Estimativa: 8 pontos (Fibonacci)

Entregável

• Fatia synapse.api.auditoria com GET /auditoria/jobs e GET /auditoria/jobs/{id} conforme o contrato.
• Política de acesso própria, que permite só o papel auditor e não confere posse.
• Log da consulta com o usuário e o job consultado.
• Testes de autorização, de conteúdo e de observabilidade.

Descrição

A API grava a trilha de auditoria e os artefatos, mas nenhuma rota os devolve, e o auditor recebe 403 em todas as rotas de job. Esta tarefa implementa as duas rotas de leitura definidas na T-304.

Contexto e decisões tomadas

• A API é organizada em fatias por domínio, com visibilidade de pacote como fronteira (skill architecture (api/.agents/skills/architecture/SKILL.md)). A consulta de auditoria é uma fatia nova, synapse.api.auditoria, que lê as tabelas com consultas próprias e não usa classes da fatia job.
• A autorização das rotas de job (AutorizacaoJobs.java) é privada da fatia job e só cobre /jobs/**. A fatia nova obtém o usuário com UsuarioAtual.obter(), que é público em core.security, e recusa quem não tem PapelDoUsuario.AUDITOR.
• O corpo de erro segue o formato {codigo, mensagem} usado pela API, com sem_permissao e job_nao_encontrado.
• O nome padrão do job é resolvido em SQL na fatia job (NOME_RESOLVIDO e a junção da submissão inicial em JobRepository.java). A regra é do contrato HTTP e não pode divergir entre as telas. A fatia job passa a expor essa resolução por uma interface pública mínima (opção 3 da skill de arquitetura), e a fatia de auditoria a usa.
• simulacao_id só vem preenchido na linha de geração. Para as demais linhas, a consulta deriva a simulação pelo código do resultado apontado, porque simulacoes.codigo_gerado_id é único.
• A submissão de uma linha de extração é derivada na leitura. A extração inicial chega a ela pela resposta do modelo (respostas_modelo.prompt_id e extracoes_regras.resposta_id). A reextração chega pela rodada de correção cuja versão analisada é a regra_id da linha.
• 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, DTOs e tratamento de erro da fatia auditoria.
• A interface pública mínima da resolução do nome na fatia job.
• Testes da fatia.

Fora do escopo

• Mudança nas rotas e na autorização de /jobs/**.
• Filtros da listagem, áudio e detalhamento por matrícula.
• Fontes da simulação e modelo da transcrição, que entram na T-310 e na T-312.

Requisitos

Acesso

1. Toda rota da fatia chama UsuarioAtual.obter() antes de ler qualquer dado. Papel diferente de auditor recebe 403 sem_permissao. Sessão ausente continua recebendo 401 pela cadeia de segurança existente.
2. GET /auditoria/jobs/{id} com id inexistente recebe 404 job_nao_encontrado. Id malformado recebe 400.

Listagem

3. GET /auditoria/jobs pagina como GET /jobs (padrões, limites e validação de pagina e tamanho iguais) e devolve jobs de todos os usuários em ordem decrescente de criação, com o dono e o nome resolvido.

Registro do job

4. GET /auditoria/jobs/{id} monta as seções do contrato com uma consulta por seção, filtrada pelo job e ordenada cronologicamente.
5. Em etapas, preencher simulacao_id pela linha quando ela o traz, e senão pelo código do resultado apontado. Preencher submissao_id nas linhas de extração conforme o contexto acima.
6. Nenhuma seção lê submissoes.binario nem resultados_simulacao.linhas.
7. Campos jsonb são devolvidos como vieram do banco, sem recompor números. Decimais preservam a precisão, como em JobRepository.

Observabilidade

8. Abrir o CorrelationContext com o job_id e o id do usuário auditor na consulta de um job, e só com o usuário na listagem, fechando-o ao terminar, inclusive em erro. O formatador de log já emite os dois campos (JsonLogFormatter).
9. Registrar em info a consulta concluída, com mensagem estável, e na listagem a página e o tamanho. Registrar em warn a recusa por papel, sem dados do token. Nenhum log inclui prompt, resposta, código, entrada ou conclusão.

Contexto técnico

• Entradas: token do usuário e id do job.
• Saídas: as duas respostas do contrato.
• Componentes afetados: pacote novo api/src/main/java/synapse/api/auditoria/ e um método público na fatia job para o nome resolvido.
• Restrições: só leitura; nenhuma escrita em tabela; nenhuma consulta por concatenação de texto; resposta de erro sem detalhe interno.
• Referências: architecture (api/.agents/skills/architecture/SKILL.md), logging (api/.agents/skills/logging/SKILL.md), metrics (api/.agents/skills/metrics/SKILL.md), api/src/main/java/synapse/api/core/security/UsuarioAtual.java, api/src/main/java/synapse/api/job/AutorizacaoJobs.java, api/src/main/java/synapse/api/job/JobRepository.java, AutorizacaoJobsTests (api/src/test/java/synapse/api/job/AutorizacaoJobsTests.java).

Critérios de aceitação

• Um auditor lista jobs de dois usuários diferentes e consulta um job que não é dele.
• Um profissional de RH recebe 403 nas duas rotas, e uma requisição sem sessão recebe 401.
• Num job com sugestão de adaptação, busca da meta e correção do código, etapas traz cada linha com o resultado e a simulação derivada, e resultados traz as execuções candidatas da busca.
• Num job de texto com uma rodada de correção, as duas linhas de extração apontam a submissão inicial e a de correção.
• A resposta não tem o binário do áudio nem linhas.
• O nome da listagem de auditoria é igual ao de GET /jobs para o mesmo job.

Definição de concluído (DoD)

• make check na api sem falha.
• Testes exercitando as rotas com token de auditor, de RH e sem token, com logs serializados conferidos quanto ao usuário, ao job_id e à ausência de conteúdo.
• Saída de /metrics conferida depois de exercitar as rotas, com http_server_requests para os templates /auditoria/jobs e /auditoria/jobs/{id}.
• Resposta validada contra o schema da especificação num teste, como faz ContratoDoStreamTests para o stream.