Uh oh!
There was an error while loading. Please reload this page.
feat(api): versiona documentação openapi - #234
Conversation
…ode-Community#230) ## Linear Issue: PAV-119 Closes PAV-119 ## Branch flow - [ ] Este PR é uma feature/fix/chore destinada a `develop`. - [x] Este é um PR de release com origem `develop` e destino `master`. - [x] Este PR não pula o fluxo obrigatório entre `develop` e `master`. ## Objetivo Promover para `master` a implementação do lock distribuído do scraper, garantindo no máximo uma execução ativa do pipeline entre diferentes origens de disparo. ## Resumo das Alterações - Implementa lock distribuído no Valkey compartilhado por cron, execução manual administrativa e cache miss de `/scrape`. - Utiliza aquisição atômica com `SET NX PX`, TTL e renovação periódica. - Protege renovação e liberação por ownership/token. - Implementa comportamento fail-closed quando o Valkey não confirma a aquisição. - Cancela a execução de forma segura em caso de perda do lock. - Adiciona estado operacional com `runId`, origem, início e expiração sem expor o token proprietário. - Adiciona contratos HTTP para execução concorrente e indisponibilidade do run lock. - Alinha os defaults de `SCRAPER_RUN_LOCK_TTL` e `SCRAPER_RUN_LOCK_RENEW_INTERVAL` à semântica fail-fast definida anteriormente. - Adiciona cobertura de testes para concorrência, ownership, configuração, renovação, liberação e cenários de falha. - Atualiza documentação e configuração do Docker Compose. ## Arquivos e Módulos Afetados - Scraper Go - Run lock / Valkey - Scheduler e pipeline do scraper - Backend administrativo - Configuração do scraper - Docker Compose - Testes Go e backend - Documentação operacional ## Validação - [x] Implementação revisada contra o escopo da PAV-119. - [x] Ajustes solicitados no code review aplicados. - [x] Semântica fail-fast das configurações do run lock validada. - [x] Nenhuma alteração de frontend incluída no escopo. - [ ] CI final do PR de release validado. ## Observações Este PR promove alterações já integradas e revisadas em `develop`. Não realizar squash ou alterações adicionais diretamente em `master` fora do fluxo de release.
hltav
left a comment
There was a problem hiding this comment.
PR fora do padrão de contribuição do projeto.
Por favor, ajuste a descrição conforme o template/documentação do repositório, incluindo card relacionado, objetivo, resumo das alterações, módulos afetados e validações executadas.
Após a adequação, a revisão técnica será retomada.
hltav
left a comment
There was a problem hiding this comment.
A implementação atende parcialmente ao escopo da PAV-32, porém a documentação OpenAPI entregue ainda não contempla integralmente os requisitos definidos no card.
Há divergência entre a cobertura/documentação atualmente validada e o nível de contrato previsto para os endpoints principais, incluindo os critérios relacionados a schemas, exemplos e respostas da API.
Revise a implementação e os testes considerando todo o escopo e os critérios definidos na PAV-32 antes de solicitar uma nova revisão.
Jovinull
commented
Aug 29, 2026
Atualização aplicada em resposta ao review da PAV-32.
Validação:
|
hltav
left a comment
There was a problem hiding this comment.
As pendências levantadas na revisão anterior foram atendidas.
A especificação OpenAPI agora apresenta cobertura adequada dos principais contratos da API, incluindo schemas, exemplos, autenticação e respostas de erro, e os testes foram ampliados para validar esses contratos de forma mais efetiva.
As inconsistências de documentação legada também foram removidas e o versionamento /api/v1 está coerente com o escopo da PAV-32.
Pode seguir para merge.
Card
Objetivo e escopo
/api/v1para os endpoints da API e documentar a versão no Swagger.O que foi feito
GET /api/v1/healthcom o mesmo comportamento deGET /health./api/v1, acrescenta schemas e documenta os principais endpoints.Módulos afetados
backend/src/app.tsbackend/src/swagger.tsbackend/src/routes/jobs.routes.tsbackend/tests/unit/app.test.tsbackend/tests/unit/swagger.test.tsREADME.mdValidação
npm exec --workspace=backend vitest run tests/unit/app.test.ts tests/unit/swagger.test.ts- 2 arquivos e 31 testes aprovados.GET /api/v1/health,GET /api/v1/jobs/searche a especificação Swagger da v1.npm run lint --workspace=frontend- concluído sem erros.npm run build --workspace=frontend- concluído com sucesso.Riscos e observações
/api/v1pode ser feita de forma gradual.