[tecrodrigocastro]

Resumo

• /api/v1 via macro Route::apiV1() — prefixo e middleware group iguais em toda rota, raiz ou de módulo
• Envelope de erro único (code, message, errors, request_id) cobrindo validação, auth, authz, not found, method not allowed, rate limit e 500
• X-Request-Id: respeita o header do cliente ou gera UUID, propaga pro log e pra resposta
• Idempotency-Key: middleware idempotent opt-in pra rotas de pedido/cobrança (cache 24h da resposta)
• App\Http\Resources\ApiResource: money() (centavos + moeda) e isoDate() (ISO 8601 UTC)
• Scramble: doc agrupada por módulo (tag = namespace depois de PHPeste\), gate viewApiDocs restringe fora de local
• GET /api/v1/ping como referência mínima de ponta a ponta
• docs/api.md com a convenção completa

Test plan

• composer check (pint + phpstan nível 8 + rector --dry-run + pest, 32 testes) passa
• composer audit sem vulnerabilidades
• Teste garante que toda rota /api/v1 aparece no OpenAPI gerado pelo Scramble (DocsCoverageTest)
• Teste cobre o envelope de erro pra cada tipo de exceção (ApiErrorTest)
• Teste cobre o middleware de idempotência (header obrigatório + replay da mesma chave)