T-334 - Implementar na API o painel de operações da auditoria

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

Entregável

• GET /auditoria/eventos e GET /auditoria/eventos/filtros na fatia synapse.api.auditoria, conforme o contrato da T-333.
• Testes de autorização, de filtros, de paginação, de contadores e de observabilidade.

Descrição

O auditor precisa ver numa tela só o que aconteceu em todas as regras, de todos os usuários, e filtrar por usuário, mês, loja, marca, cargo e regra. Esta tarefa implementa as duas rotas do painel definidas na T-333.

Contexto e decisões tomadas

• A fatia auditoria da T-305 já tem a recusa de quem não é auditor, o tratamento de erro {codigo, mensagem} e o uso da resolução do nome exposta pela fatia job. As rotas novas reaproveitam esses três pontos.
• Os eventos vêm das tabelas listadas na T-333. Os filtros, a ordenação, a paginação e os contadores são resolvidos no banco, numa consulta que une as fontes, para que a API não carregue os eventos de todos os jobs para filtrar em memória.
• Loja, marca e cargo estão em regras.nucleo (loja, marca e cargo, listas de códigos), e o filtro usa a versão de maior versao do job.
• O mês é calculado no fuso America/Sao_Paulo.
• 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 das duas rotas na fatia auditoria.
• Testes da fatia.

Fora do escopo

• GET /auditoria/jobs e GET /auditoria/jobs/{id}, que são da T-305.
• O resumo do dossiê, que é da T-335.

Requisitos

Acesso e validação

1. As duas rotas chamam UsuarioAtual.obter() antes de ler dados e recusam com 403 sem_permissao quem não tem o papel auditor. Sessão ausente recebe 401 pela cadeia existente.
2. pagina e tamanho seguem as regras de GET /auditoria/jobs. mes fora do formato AAAA-MM e demais parâmetros inválidos recebem 400 requisicao_invalida.

Eventos

3. Montar cada evento com os campos do contrato, a partir das fontes da T-333, sem as execuções candidatas da busca da meta.
4. Aplicar os filtros combinados com E. O filtro regra compara o id exato quando o valor é um UUID e, nos outros casos, procura o texto no nome resolvido sem diferenciar maiúsculas de minúsculas, escapando % e _.
5. Ordenar do instante mais recente para o mais antigo, com desempate estável, para que nenhum evento se repita ou suma entre páginas.
6. Calcular os contadores com os mesmos filtros, sobre todas as páginas.

Opções dos filtros

7. GET /auditoria/eventos/filtros devolve as opções descritas no contrato.

Restrições

8. Nenhuma consulta lê submissoes.binario, resultados_simulacao.linhas, o texto de prompts e respostas ou a fonte dos códigos.
9. Todo filtro vai como parâmetro da consulta, nunca concatenado ao SQL.

Observabilidade

10. Abrir o CorrelationContext com o id do usuário auditor e fechá-lo ao terminar, inclusive em erro.
11. Registrar em info a consulta concluída, com mensagem estável, quais filtros vieram preenchidos, a página, o tamanho e o total. O valor do filtro regra não vai para o log, porque é texto livre. Registrar em warn a recusa por papel, sem dados do token.

Contexto técnico

• Entradas: token do usuário e os parâmetros da rota.
• Saídas: as duas respostas 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), metrics (api/.agents/skills/metrics/SKILL.md), docs/database/modelo-dados.dbml, a fatia auditoria da T-305 e JobRepository.java (api/src/main/java/synapse/api/job/JobRepository.java) como exemplo de listagem paginada com filtro opcional.

Critérios de aceitação

• Com jobs de dois usuários, o filtro pelo login de um traz só os eventos dele, e os contadores mudam junto.
• Um evento às 23h30 de 31/10 no horário de Brasília entra no filtro de outubro.
• Um job cuja versão 1 tinha a loja 13 e cuja versão 2 não a tem não aparece no filtro da loja 13.
• O filtro regra acha o job por parte do nome, em maiúsculas ou minúsculas, e pelo id exato.
• "Simulações com falha" conta um resultado erro_codigo e não conta as execuções candidatas da busca da meta.
• Percorrer todas as páginas devolve cada evento uma vez.
• Um profissional de RH recebe 403 nas duas rotas, e uma requisição sem sessão recebe 401.

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 e à ausência do texto do filtro regra.
• Saída de /metrics conferida depois de exercitar as rotas, com http_server_requests para os templates /auditoria/eventos e /auditoria/eventos/filtros.
• Respostas validadas contra o schema da especificação num teste.