T-304 - Definir a política de acesso do auditor e o contrato da consulta de auditoria

• Componente: raiz (docs/decisoes/, contracts/http/openapi.yaml, docs/ARCHITECTURE.md), sujeito a autorização.
• Depende de: T-300, cujo schema da conclusão a resposta referencia.
• Data máxima: 06/11/2026
• Estimativa: 5 pontos (Fibonacci)

Entregável

• DEC-087 atualizada com a política de acesso do auditor e as decisões de conteúdo da consulta.
• GET /auditoria/jobs e GET /auditoria/jobs/{id} especificados em contracts/http/openapi.yaml, com schemas e exemplos.
• Textos da especificação e da arquitetura que citam GET /jobs/{id}/audit ou o acesso do auditor alinhados com a política.

Descrição

O auditor é um papel não operacional que averigua o que aconteceu num job. Hoje toda rota de job lhe responde 403 e não existe rota de auditoria. Esta tarefa define quem acessa o quê e o formato das duas rotas de leitura que a API implementa na T-305 e o frontend consome na T-307.

Contexto e decisões tomadas

• A DEC-087 diz que o auditor não acessa as rotas do profissional de RH e que o acesso dele a jobs de terceiros só ocorre por operações de auditoria explicitamente autorizadas. A especificação HTTP contradiz isso em dois trechos: na descrição do esquema de segurança, que diz que o papel auditor "autoriza consulta além da própria conta", e na rota de linhas da simulação, que diz que o solicitante deve ser dono do job ou ter o papel auditor. A API implementa a DEC-087.
• As rotas ficam em /auditoria/..., e não em /jobs/{id}/audit. Toda rota sob /jobs/** passa pelo interceptor de autorização da fatia job, que nega o handler sem a anotação @AutorizarJob, e essa anotação é privada da fatia. A consulta de auditoria é uma fatia própria da API, com a própria política.
• A consulta é só leitura e não confere posse. O auditor vê jobs de qualquer usuário.
• A resposta de um job é o nível 3 da explicabilidade (docs/ARCHITECTURE.md, seção de explicabilidade). Ela reúne, para o job, a procedência, as entradas, as versões da regra, as etapas da trilha, as chamadas ao modelo, os códigos, os resultados, as simulações, as transições, as ações, as rodadas de correção e as sugestões de meta.
• Decisões assumidas por esta tarefa e que dependem da PO, registradas no requisito 1:
  • o auditor vê o texto da entrada (transcrição ou texto digitado) e o conteúdo do formulário, porque os prompts de extração já o contêm;
  • o auditor ouve o áudio de cada entrada por voz, por uma rota própria (T-330), e não vê o detalhamento por matrícula (resultados_simulacao.linhas) nesta versão;
  • a tela do auditor mostra identificadores, versões e estados internos, porque a US04 exige o id da simulação, o horário e a versão exata da regra. A regra de não exibir lógica interna vale para as telas do profissional de RH.

Escopo

Dentro do escopo

• docs/decisoes/dec-087.md, contracts/http/openapi.yaml e as menções a GET /jobs/{id}/audit em docs/ARCHITECTURE.md.

Fora do escopo

• Implementação na API e no frontend.
• Filtros da listagem por usuário, período ou estado.
• A rota do áudio (T-330), o detalhamento por matrícula, as fontes dos dados da simulação (T-309) e o modelo da transcrição (T-312).

Requisitos

Decisões e autorização

1. Antes de editar, apresentar ao usuário as decisões assumidas listadas acima e pedir confirmação da PO. Em seguida, pedir autorização para a mudança de contrato conforme contract-change (.agents/skills/contract-change/SKILL.md), informando os arquivos, o consumidor (frontend), o produtor (API), a compatibilidade (rotas novas; nada existente muda) e as validações. Não editar antes das duas respostas.

DEC-087

2. Acrescentar à seção "Matriz HTTP vigente" as duas rotas novas, permitidas só ao auditor e sem conferência de posse, e registrar que o auditor continua negado em todas as rotas de /jobs/**, inclusive a de linhas da simulação.
3. Acrescentar uma seção com o conteúdo da consulta e as decisões confirmadas pela PO no requisito 1.

Especificação HTTP

4. GET /auditoria/jobs, paginada com pagina e tamanho como em GET /jobs, em ordem decrescente de criação, com jobs de todos os usuários. Cada item traz id, nome resolvido, estado, origem, competências, orçamento, meta de venda, criação, finalização, job_origem_id e o usuário dono (login e nome). O total é de todos os jobs, não de um usuário.
5. GET /auditoria/jobs/{id}, que devolve o registro de auditoria do job, com as seções abaixo. Cada seção é uma lista em ordem cronológica, e as referências entre seções são ids.
   • job: os campos do item da listagem, mais iniciado_em.
   • entradas: as submissões do job, de entrada inicial e de correção, com id, tipo, finalidade, criação, conteúdo do formulário, texto da entrada, formato do áudio e instante da transcrição. Sem o binário do áudio.
   • versoes: as versões da regra, com os campos de RegraVersionada mais regra_origem_id, hash, tentativa e parametros.
   • etapas: as linhas de trilhas_auditoria, com no, concluido_em, conclusao (referência a contracts/domain/trilha-conclusao.schema.json), regra_id, resultado_id, prompt_id, codigo_gerado_id, explicacao_id, simulacao_id e submissao_id. A descrição diz que a API deriva simulacao_id pelo código do resultado quando a linha não o traz, e submissao_id pela extração ou pela rodada de correção nas linhas de extração.
   • chamadas_modelo: os prompts com a resposta, com etapa, modelo (referência a modelo-llm.schema.json), texto do prompt, texto da resposta, consumo de tokens e criação.
   • codigos: id, versão da regra, linguagem, fonte, prompt e criação.
   • resultados: id, código, status, propósito, veredito, meta de venda, totais, asserções, decomposição, diagnóstico e criação, referenciando os schemas de domínio existentes. Sem linhas.
   • simulacoes: id, versão da regra, código, resultado vigente, flag de baixa rastreabilidade e criação.
   • transicoes, acoes, rodadas (referência ao schema Rodada), sugestoes_meta e explicacoes.
6. As duas rotas respondem 401 sem sessão, 403 sem_permissao para quem não é auditor e, na consulta de um job, 404 job_nao_encontrado. As descrições dizem que textos de prompt, resposta, código e entrada são dados não confiáveis e devem ser exibidos como texto.
7. Exemplos completos das duas respostas, coerentes com os exemplos de domínio existentes.
8. Na descrição do esquema keycloakOidc e na rota de linhas da simulação, retirar a autorização do auditor, conforme a DEC-087. Na nota de "fora do escopo" do início da especificação, retirar a consulta de auditoria.

Arquitetura

9. Em docs/ARCHITECTURE.md, trocar GET /jobs/{id}/audit por GET /auditoria/jobs/{id} e atualizar a frase que diz que a exposição da auditoria pertence à Sprint 3 para apontar a DEC-087.

Contexto técnico

• Entradas: DEC-087, especificação HTTP atual e o modelo de dados.
• Saídas: política de acesso registrada e contrato das duas rotas.
• Componentes afetados: documentação e contrato HTTP.
• Restrições: rotas novas só de leitura; nenhum campo existente muda; additionalProperties: false não é usado nas respostas.
• Referências: DEC-087 (docs/decisoes/dec-087.md), contracts/http/openapi.yaml, modelo de dados (docs/database/modelo-dados.dbml), contract-change (.agents/skills/contract-change/SKILL.md).

Critérios de aceitação

• A especificação valida e os exemplos das duas rotas passam em python contracts/validar-exemplos.py.
• Nenhum trecho da especificação concede ao auditor acesso a rota de /jobs/**.
• A resposta do job não tem campo para o binário do áudio nem para linhas.
• A DEC-087 registra as decisões confirmadas pela PO.

Definição de concluído (DoD)

• Confirmação da PO e autorização registradas antes da edição.
• python contracts/validar-exemplos.py e git diff --check sem falha.
• Gate dos quatro componentes verde, porque o diff toca contracts/.