Checklist de code review para Pull Requests com padrões de qualidade

Crie um Checklist de Code Review completo para Pull Requests para:

Projeto: [NOME DO PROJETO]
Stack tecnológica: [EX: TypeScript/Node.js/React/PostgreSQL ou Python/FastAPI/Redis]
Ambiente: [SaaS / E-commerce / Fintech / HealthTech / etc.]
Tamanho do time: [NÚMERO] desenvolvedores
Processo atual de PR: [DESCREVA: ex. branch para main, 1 aprovação mínima]
Principais problemas históricos: [EX: bugs de null pointer, queries N+1, dados sensíveis em logs]

## ESTRUTURA DO CHECKLIST (para reviewer e author)

---

### PARTE A — CHECKLIST DO AUTHOR (antes de abrir o PR)

**Auto-review obrigatório:**
- [ ] Li todo o diff do PR antes de publicar
- [ ] O PR tem uma descrição clara: O QUÊ foi feito, POR QUÊ e COMO testar
- [ ] O PR tem tamanho adequado: < 400 linhas alteradas (se maior, justificar)
- [ ] Removi TODOs, console.logs, debuggers, código comentado sem explicação
- [ ] Não commitei credenciais, API keys, tokens ou dados sensíveis
- [ ] Adicionei ou atualizei testes para as mudanças feitas
- [ ] Os testes passam localmente (`pnpm test` / `pytest`)
- [ ] O build passa localmente (`pnpm build` / equivalente)
- [ ] Atualizei a documentação se a API ou interface mudou
- [ ] Não há conflitos com a branch base

**Template de descrição do PR (obrigatório):**
```markdown
## O que este PR faz
[Descrição clara em 1-3 frases]

## Por que esta mudança é necessária
[Contexto: ticket, bug, melhoria]

## Como testar
1. [Passo 1]
2. [Passo 2]
3. [O que verificar]

## Screenshots (se mudança visual)

## Checklist
- [ ] Testes adicionados/atualizados
- [ ] Documentação atualizada
- [ ] Breaking changes documentados
```

---

### PARTE B — CHECKLIST DO REVIEWER (ao fazer a revisão)

#### B1) CORREÇÃO E LÓGICA
- [ ] A lógica do código está correta para o caso principal?
- [ ] Casos edge foram tratados? (null, undefined, lista vazia, valor zero, string vazia)
- [ ] Condições de corrida (race conditions) foram consideradas em operações assíncronas?
- [ ] Tratamento de erros: exceções são capturadas e tratadas adequadamente?
- [ ] Rollback: em caso de falha parcial, o sistema fica em estado inconsistente?
- [ ] Os critérios de aceite do ticket foram atendidos?

#### B2) SEGURANÇA
- [ ] Inputs do usuário estão sendo validados e sanitizados antes de usar?
- [ ] Nenhum dado sensível é logado (senhas, tokens, CPF, cartão de crédito)
- [ ] Queries ao banco usam prepared statements ou ORM (sem SQL injection)
- [ ] APIs novas têm autenticação e autorização adequadas
- [ ] Não há secrets, API keys ou credenciais hardcoded
- [ ] Dependências novas adicionadas são confiáveis e atualizadas?
- [ ] Dados sensíveis são criptografados em repouso e em trânsito?
- [ ] CORS, CSP e headers de segurança estão configurados corretamente?

#### B3) PERFORMANCE
- [ ] Há queries N+1? (loop que faz queries individuais dentro de outro loop)
- [ ] Índices necessários foram adicionados para queries novas?
- [ ] Operações pesadas são assíncronas / não bloqueiam a thread principal?
- [ ] Caches são usados onde apropriado? (e invalidados corretamente?)
- [ ] Loops e algoritmos têm complexidade aceitável para o volume esperado?
- [ ] Grandes payloads são paginados ou transmitidos em streaming?
- [ ] Memory leaks: listeners, timers, subscriptions são removidos quando necessário?

#### B4) MANUTENIBILIDADE E LEGIBILIDADE
- [ ] O código é autoexplicativo sem comentários excessivos?
- [ ] Funções têm responsabilidade única (SRP)?
- [ ] Nomes de variáveis, funções e classes são descritivos e seguem a convenção do projeto?
- [ ] Código duplicado foi extraído em funções/módulos reutilizáveis?
- [ ] Magic numbers e strings têm constantes nomeadas?
- [ ] Comentários existentes são precisos (não desatualizados)?
- [ ] Complexidade ciclomática: funções com > 10 branches merecem refatoração
- [ ] O código segue os padrões do projeto (linter, formatter passam)?

#### B5) TESTES
- [ ] Há testes para o caminho feliz (happy path)?
- [ ] Há testes para casos de erro (unhappy path)?
- [ ] Há testes para casos edge identificados?
- [ ] Os testes são determinísticos (não dependem de tempo, randomness, ordem)?
- [ ] Mocks/stubs são usados adequadamente (não mockando o que está sendo testado)?
- [ ] Cobertura de código: novas linhas críticas estão cobertas?
- [ ] Os testes são legíveis: arrange/act/assert é claro?

#### B6) ARQUITETURA E DESIGN
- [ ] A mudança segue os padrões arquiteturais do projeto?
- [ ] Dependências entre módulos estão na direção correta (sem circular dependencies)?
- [ ] APIs públicas (endpoints, interfaces) seguem o contrato estabelecido?
- [ ] Breaking changes são sinalizados e versionados corretamente?
- [ ] A mudança é extensível sem exigir reescrita futura? (Open/Closed Principle)
- [ ] Novos endpoints têm idempotência para operações que devem ser idempotentes?

#### B7) OBSERVABILIDADE
- [ ] Logs adequados em pontos críticos (início, fim, erros)?
- [ ] Nível de log correto (debug, info, warn, error)?
- [ ] Métricas/traces adicionados para operações novas de alto impacto?
- [ ] Erros têm contexto suficiente para debugging (sem stack trace cru para o usuário)?

#### B8) DADOS E BANCO DE DADOS
- [ ] Migrations são reversíveis (têm rollback)?
- [ ] Alterações de schema não quebram a versão atual do código (backward compatible)?
- [ ] Não há deleção de dados sem soft delete ou backup?
- [ ] Transações são usadas quando múltiplas operações devem ser atômicas?
- [ ] Locks de banco de dados não causam deadlocks?

---

### PARTE C — PROCESSO DE REVIEW

**SLA de revisão:**
- PRs marcados como [URGENTE]: review em < 4 horas
- PRs normais: review em < 1 dia útil
- PRs > 400 linhas: author deve agendar sessão de pair review

**Tom do feedback:**
- Comentários de bloqueio (BLOCK): problema crítico que impede merge
- Comentários de sugestão (NIT/SUGGESTION): melhoria opcional
- Comentários de pergunta (QUESTION): para entender decisão do author
- Elogios (PRAISE): reconhecer boas práticas explicitamente

**Exemplos de comentários bem escritos:**
- BOM: "BLOCK: Esta query pode retornar N+1 quando há muitos pedidos. Sugiro usar `include` aqui: [exemplo]"
- RUIM: "Isso está errado, refaz"

**Aprovação:**
- Mínimo de aprovações para merge: [NÚMERO]
- Quem pode aprovar em cada área: [REGRAS DO TIME]
- Auto-merge permitido: [SIM/NÃO] com quais condições?

---

## CONFIGURAÇÃO NO GITHUB/GITLAB

- CODEOWNERS: definir donos por área/arquivo
- Branch protection rules: impedir push direto na main
- Required status checks: CI deve passar antes de merge
- PR template: adicionar ao `.github/pull_request_template.md`
- Labels padrão: bug, feature, refactor, docs, breaking-change, wip

Formato: checklist completo em markdown (pronto para adicionar ao repositório), processo de review e configurações de repositório.