T-078 - Implementar `GET /jobs` com histórico paginado

[pedro-fs-garcia]

T-078 - Implementar GET /jobs com histórico paginado

• Componente: api
• Estimativa: 3
• Depende de: T-042
• Data máxima: 2026-09-22 (ter)

Descrição

Implementar GET /jobs, devolvendo os jobs do usuário paginados e ordenados por data decrescente, com filtro por estado.

A lista das regras já processadas. É o que sustenta o cenário 2 da US-007: sair da tela sem escolher uma ação não descarta o trabalho, porque o job vive na api e é reencontrado aqui.

Também é a porta de entrada do reprocessamento: o usuário acha a regra arquivada nesta lista antes de reprocessá-la.

Escopo

Dentro do escopo

• GET /jobs devolvendo os jobs do usuário, paginados e ordenados por data de criação decrescente.
• Cada item com competência, veredito, estado atual e a referência para abrir o relatório.
• Filtro por estado, para separar arquivados de em andamento.
• Autorização: cada usuário vê os próprios jobs, salvo papel que autorize o contrário.

Fora do escopo

• Tela de histórico (T-082).
• Reprocessamento (T-079), que é uma ação sobre um item da lista.
• Consulta unitária (T-042), que é outra rota.
• Busca por texto ou por parâmetro da regra.

Requisitos

• A paginação é obrigatória desde já: uma lista sem limite quebra quando o volume de demonstração crescer.
• Job arquivado continua aparecendo - arquivar preserva, não exclui.
• Os campos exibidos vêm gravados; a api não recalcula veredito nem diferença para montar a lista.
• A ordenação padrão é por data de criação decrescente, e é estável entre páginas.

Contexto técnico

• Entradas: token validado; parâmetros de paginação e filtro.
• Saídas: página de jobs conforme o openapi.yaml.
• Componentes afetados: api/ (fatia de histórico).
• Restrições: a resposta segue o contrato HTTP; campo ausente significa "ainda não há", nunca null.
• Referências: ARCHITECTURE.md §3.2 (histórico) e §3.1 (tela de histórico); US-007 cenários 2 e 3.

Critérios de aceitação

• GET /jobs devolve os jobs do usuário paginados, ordenados por data decrescente.
• Cada item traz competência, veredito, estado e a referência do relatório.
• O filtro por estado separa arquivados dos demais.
• Jobs de outro usuário não aparecem para papel sem autorização.
• A ordenação é estável entre páginas, sem item repetido nem omitido.
• A resposta valida contra o openapi.yaml.

Definição de concluído (DoD)

• Todos os critérios de aceitação foram atendidos.
• Testes automatizados foram adicionados ou atualizados quando aplicável.
• Os testes existentes passam.
• O código segue as convenções e padrões de qualidade do projeto.
• Documentação, migrações, contratos ou configurações exigidos foram atualizados.
• Nenhuma regressão conhecida ou problema não resolvido foi introduzido pela tarefa.
• As alterações foram confirmadas e estão prontas para revisão/mesclagem.
• A implementação foi verificada no ambiente apropriado.

Observações / Decisões

Fronteira com T-042: GET /jobs/{id} é a consulta unitária, com resultado e decomposição completos; GET /jobs é a listagem, com o mínimo para reconhecer e escolher um item. Trazer o resultado inteiro em cada linha da lista seria desperdício e tornaria a paginação inútil.

Efeito cascata: destrava T-082. É a tarefa mais independente da US-007 e pode correr em paralelo com o fim do worker.