T-333 - Definir o contrato do painel de operações e do resumo do dossiê do auditor

• Componente: raiz, em contracts/http/openapi.yaml e docs/decisoes/dec-087.md, sujeito a autorização.
• Depende de: T-304.
• Data máxima: 12/11/2026
• Estimativa: 3 pontos (Fibonacci)

Entregável

• Rota GET /auditoria/eventos, com filtros, paginação e contadores.
• Rota GET /auditoria/eventos/filtros, com as opções de cada filtro.
• Rota GET /auditoria/jobs/{id}/resumo, com os contadores do dossiê, as alterações de cada versão e a comparação entre simulações.
• Exemplos válidos das três respostas.
• DEC-087 com as rotas novas na matriz HTTP.

Descrição

O mockup da área do auditor tem um painel com os eventos de todas as regras, filtros e contadores, e um dossiê por regra com contadores de simulações, a variação entre uma simulação e a anterior e o que mudou entre versões. O contrato da T-304 lista jobs sem filtro e devolve o registro do job sem esses valores. Como o frontend não calcula valor exibido, a API precisa devolvê-los. Esta tarefa especifica três rotas novas de leitura, exclusivas do auditor.

Contexto e decisões tomadas

• No mockup, produto é marca, canal é loja e funcionário é cargo. A regra vale por loja, marca e cargo, e o cargo é a menor granularidade. Não existe regra por matrícula.
• A regra é a única coisa com nome: o nome resolvido de JobResumo.nome. Loja, marca e cargo são referenciados pelo código, o usuário pelo login (usuarios.login) e os demais artefatos pelo id.
• Totais, contadores e variações vêm da API. O frontend só formata.
• Evento é um registro gravado com instante. As fontes são as entradas (submissoes, inicial e de correção), as rodadas de correção abertas (rodadas_correcao), as versões da regra (regras), os códigos gerados (codigos_gerados), os resultados de simulação (resultados_simulacao com proposito igual a simulacao), as sugestões de meta criadas e aceitas (sugestoes_meta_venda), as ações do usuário (job_acoes) e a parada do job em erro (job_transicoes com status_novo igual a erro).
• Renomear a regra não é registrado e não é evento. As execuções candidatas da busca da meta não são eventos.
• Cada job tem um único dono, e todo evento do job é atribuído a ele. O evento informa se foi ato do usuário ou do sistema.
• A loja, a marca e o cargo de um evento, e os dos filtros, são os do núcleo da versão mais recente da regra do job (maior regras.versao). Um job sem versão não tem esses códigos e não aparece quando um desses filtros é usado.
• O mês de um evento é o do seu instante no fuso de Brasília (America/Sao_Paulo).
• "Simulações com falha" conta os resultados de simulação com status diferente de sucesso.
• As alterações de uma versão são comparadas com a versão de origem (regra_origem_id). A versão raiz não tem alterações.
• A comparação de uma simulação é feita com a simulação do mesmo job concluída com sucesso imediatamente antes, pela ordem de criação. Só simulações com sucesso são comparadas.
• A exportação do dossiê é o JSON de GET /auditoria/jobs/{id}, salvo pelo frontend. Não há rota de exportação.
• As rotas são novas e nada existente muda. A T-305 e a T-307 continuam valendo sem alteração.

Escopo

Dentro do escopo

• As três rotas, seus schemas, os exemplos e a DEC-087.

Fora do escopo

• Implementação, que fica com a T-334 e a T-335.
• Filtros em GET /auditoria/jobs.
• Nome de loja, marca, cargo ou usuário.

Requisitos

Autorização

1. Antes de editar contracts/, pedir autorização conforme contract-change (.agents/skills/contract-change/SKILL.md), informando as rotas novas, o produtor (API), o consumidor (frontend), a compatibilidade (só rotas novas) e as validações.

Painel de eventos

2. GET /auditoria/eventos aceita pagina e tamanho com as mesmas regras de GET /auditoria/jobs, e os filtros opcionais usuario (login), mes (AAAA-MM), loja, marca e cargo (código) e regra. Os filtros se combinam com E.
3. O filtro regra acha o job pelo id exato quando o valor é um UUID e, nos outros casos, pela presença do texto no nome resolvido, sem diferenciar maiúsculas de minúsculas.
4. Cada evento traz o instante, o tipo, se foi ato do usuário ou do sistema, o login do dono, o id, o nome e o status atual do job, o id do registro de origem, os códigos de loja, marca e cargo e a situação própria do tipo: a finalidade e o tipo da entrada, a origem e o número da versão, o status e o veredito do resultado, a ação executada.
5. A ordem é do instante mais recente para o mais antigo, com desempate estável entre páginas.
6. A resposta traz, com os mesmos filtros e sobre todas as páginas, o total de eventos, de usuários com evento, de regras com evento e de simulações com falha.
7. GET /auditoria/eventos/filtros devolve os logins dos donos de jobs, os meses com evento e os códigos de loja, marca e cargo presentes nas versões mais recentes.

Resumo do dossiê

8. GET /auditoria/jobs/{id}/resumo devolve a quantidade de simulações registradas, concluídas com sucesso e com falha, e o número da versão da regra da simulação vigente do job.
9. Para cada versão com origem, a lista das partes alteradas em relação à origem, identificadas como em elemento_ref (nucleo.<campo> ou o ref do elemento), com o valor anterior e o novo. A parte incluída não tem valor anterior, e a removida não tem valor novo.
10. Para cada simulação comparada, o id da anterior e, para baseline, simulado, diferença absoluta, diferença percentual, orçamento e meta de venda, o valor anterior, o atual e a variação (atual menos anterior). Valores monetários seguem comum.schema.json#/$defs/brl.
11. As três rotas respondem 401 sem sessão e 403 sem_permissao a quem não é auditor. O resumo responde 404 job_nao_encontrado para id inexistente. Parâmetro inválido responde 400 requisicao_invalida.

DEC-087

12. Acrescentar as três rotas à "Matriz HTTP vigente", permitidas só ao auditor.

Contexto técnico

• Entradas: o mockup da área do auditor (T-306 e T-332) e o modelo de dados.
• Saídas: as rotas especificadas e a matriz HTTP da DEC-087 atualizada.
• Componentes afetados: contracts/http/openapi.yaml, os exemplos do manifesto e docs/decisoes/dec-087.md.
• Restrições: nenhuma rota ou schema existente muda; nenhuma resposta traz binário de áudio, linhas por matrícula, prompt, resposta do modelo ou código.
• Referências: contract-change (.agents/skills/contract-change/SKILL.md), docs/database/modelo-dados.dbml, contracts/domain/comum.schema.json, contracts/domain/resultado-totais.schema.json, contracts/domain/conflitos-rodada.schema.json.

Critérios de aceitação

• As três rotas e os exemplos validam em python contracts/validar-exemplos.py.
• Um exemplo do painel mostra eventos de dois usuários com os contadores coerentes com os itens.
• Um exemplo do resumo mostra uma versão corrigida com uma parte alterada e uma simulação comparada com a anterior.
• A DEC-087 lista as três rotas como exclusivas do auditor.

Definição de concluído (DoD)

• Autorização registrada na issue antes da edição do contrato.
• Validação dos exemplos sem falha.
• PR revisado pelos responsáveis pela API e pelo frontend.