feat: add Scalar API documentation

[teuzowebdeveloper9]

Contexto

Este PR adiciona documentacao interativa com Scalar para facilitar a avaliacao e o uso da mini-API do desafio FURY Click Hero.

Por que Scalar

• O desafio nao pede front-end, mas uma documentacao interativa ajuda o avaliador a testar a API sem precisar ler todo o codigo primeiro.
• Scalar consome uma especificacao OpenAPI padrao, gerada pelo NestJS via @nestjs/swagger, mantendo o contrato da API versionavel e independente da UI.
• A documentacao deixa claros os payloads, enums, respostas esperadas, erros 400 de validacao e o endpoint de consulta de jobs.
• A URL base do deploy agora aponta para os endpoints disponiveis, e /docs entrega a referencia interativa da API.

O que mudou

• Adiciona @nestjs/swagger e @scalar/nestjs-api-reference.
• Cria setupOpenApiDocs para expor /docs e /openapi.json.
• Documenta POST /webhook/violation, GET /jobs/:id, GET / e GET /health.
• Adiciona DTOs de documentacao para request, response, erros de validacao e not found.
• Atualiza o README com a documentacao Scalar e o racional da decisao.

Como validar

• npm run typecheck
• npm run lint
• npm test -- --runInBand
• npm run build
• Iniciar localmente e validar:
  • GET http://localhost:3002/docs
  • GET http://localhost:3002/openapi.json
  • GET http://localhost:3002/

Resultado esperado

• /docs renderiza a API Reference do Scalar.
• /openapi.json expõe a especificacao OpenAPI.
• A rota raiz lista os endpoints principais, incluindo docs e OpenAPI.

Trade-off

A documentacao foi adicionada sem criar front-end ou alterar o fluxo funcional do desafio. O objetivo e melhorar descobribilidade, testabilidade manual e clareza do contrato sem aumentar desnecessariamente o escopo.

[teuzowebdeveloper9]

AI-assisted code review (Codex)

Findings

No blocking issues found in this PR.

What I reviewed

• Scalar integration through @scalar/nestjs-api-reference.
• OpenAPI document generation through @nestjs/swagger.
• Public routes exposed by this branch: /docs, /openapi.json, /, and /health.
• Documentation DTOs for webhook payloads, enqueue responses, job status, validation errors, and not found responses.
• README updates explaining the Scalar documentation and why it was added.
• Security impact of the adjusted Helmet CSP.

Validation performed

• npm run typecheck
• npm run lint
• npm test -- --runInBand
• npm run build
• Local smoke checks:
  • GET /docs -> 200
  • GET /openapi.json -> 200
  • GET / -> 200

Notes

• The Scalar addition is scoped to documentation and does not change the webhook, BullMQ, Redis, worker, retry, or idempotency flow.
• The global CSP now allows inline scripts/styles and jsDelivr so Scalar can render. This is acceptable for this no-auth technical challenge, but in a production app I would consider isolating docs behind a stricter route-specific policy or internal access control.
• The PR improves evaluator experience: reviewers can inspect request/response contracts and manually test endpoints without reading the implementation first.

Verdict

Looks good to merge after CI passes.