Estratégia de Qualidade e Diretrizes de Code Review

1. Os 3 Pilares da Garantia da Qualidade no e-SUS AF

A estratégia de qualidade do e-SUS AF é sustentada por três pilares complementares e sucessivos que garantem a integridade do produto desde a escrita das primeiras linhas de código até a publicação oficial da release:

flowchart TD
    subgraph P1["1. Testes Automatizados da Engenharia"]
        direction TB
        T_UNIT["Testes Unitários
• Regras de negócio isoladas
• Services, DTOs e Helpers"]
        T_E2E["Testes E2E & Integração (BDD)
• Fluxo Básico (Happy Path)
• Fluxos Alternativos & Exceções"]
    end

    subgraph P2["2. Revisão Técnica & Governança"]
        direction TB
        CR_PEER["Revisão por Pares (Peer Review)
• Qualidade, legibilidade e padrões
• Disseminação de conhecimento"]
        CR_TL["Aprovação do Tech Lead
• Gatekeeper arquitetural
• Segurança, OneFlow e impacto sistêmico"]
    end

    subgraph P3["3. Homologação & Estabilização"]
        direction TB
        QA_REG["Testes de Regressão (QA)
• Suites automatizadas e manuais
• Verificação na Sprint de Estabilização"]
        PO_HOM["Homologação Negocial (PO/Negócio)
• Validação de critérios de aceite
• Aprovação formal da release oficial"]
    end

    P1 -->|CI/CD Verde| P2
    P2 -->|Aprovado e Mergeado na main| P3

1.1. Pilar 1: Testes Automatizados da Engenharia (Unitários e E2E orientados a BDD)

Os testes automatizados constituem a primeira e mais rápida linha de defesa contra regressões. No e-SUS AF, a automação é parte intrínseca da atividade de desenvolvimento de qualquer funcionalidade (feature), melhoria ou correção de defeito (bugfix / hotfix).

• Testes Unitários:

  • Objetivo: Validar unidades atômicas de lógica de forma isolada, rápida e sem dependências externas reais (banco de dados, rede ou APIs de terceiros).
  • Escopo Principal: Métodos de serviço (Services no NestJS), entidades de domínio, objetos de transferência de dados (DTOs e validações do class-validator), funções utilitárias e componentes isolados de interface (React).
  • Mocks e Stubs: Uso criterioso de dublês de teste para repositórios e serviços externos, garantindo tempos de execução em milissegundos.

• Testes E2E (End-to-End) e de Integração orientados a BDD:

  • Objetivo: Validar fluxos completos da aplicação integrando controladores, serviços, persistência em banco de dados e contratos de API, simulando o comportamento do usuário final.
  • Estruturação BDD (Behavior-Driven Development): Os cenários de teste E2E devem refletir diretamente os critérios de aceite descritos na Issue/História de Usuário no formato Gherkin (Dado / Quando / Então ou Given / When / Then).
  • Cobertura Obrigatória de Fluxos: Todo PR deve conter obrigatoriamente testes automatizados que cubram tanto o Fluxo Básico (Caminho Feliz / Happy Path) quanto os Fluxos Alternativos e de Exceção.

Exemplo Prático: Mapeamento de Testes E2E para Funcionalidade

Considerando a funcionalidade de negócio "Manter Localização Física de Medicamentos", a matriz de testes automatizados deve contemplar:

1.2. Pilar 2: Revisão de Código por Pares e Aprovação do Líder Técnico

A revisão de código (Code Review) é um processo colaborativo e técnico que visa elevar a qualidade do software, manter a consistência arquitetural, prevenir vulnerabilidades de segurança e promover a troca contínua de conhecimento entre os membros da equipe.

1. Revisão por Pares (Peer Review):
   • Realizada por pelo menos um desenvolvedor do time de Engenharia.
   • Avalia legibilidade, clareza lógica, conformidade com os padrões de desenvolvimento (NestJS, React, TypeORM), robustez dos testes e modularidade.
2. Aprovação do Líder Técnico (Tech Lead):
   • Atua como a autoridade arquitetural final antes do merge na branch main.
   • Avalia o impacto do PR no ecossistema e-SUS AF, riscos de desempenho, integridade do modelo de dados, aderência à governança OneFlow e mitigação de vulnerabilidades de segurança (OWASP).

1.3. Pilar 3: Homologação Negocial e Testes de Regressão (Sprint de Estabilização)

O terceiro pilar garante que o software não apenas foi bem construído tecnicamente, mas atende com exatidão às necessidades dos profissionais de saúde e gestores do SUS.

• Contexto no Release Train (2+1): Este pilar é executado predominantemente durante a Sprint de Estabilização e Homologação (1 a 2 semanas), após o Code Freeze na branch main e o corte da branch temporária release/vX.Y.0.
• Testes de Regressão (QA):
  • O time de Qualidade executa baterias abrangentes de testes de regressão (automatizados e exploratórios manuais) para garantir que as novas funcionalidades não degradaram módulos pré-existentes.
• Homologação Negocial (Product Owner e Analistas de Negócio):
  • Conduzida no ambiente de Homologação (HML) com dados representativos de produção.
  • Validação formal de que os critérios de aceite definidos durante os refinamentos foram plenamente satisfeitos.
  • Em caso de inconformidade negocial crítica que não possa ser sanada no prazo da estabilização, aplica-se a Feature Drop Policy, revertendo a alteração na branch de release para não comprometer o cronograma de entrega.

2. Macrofluxo do Processo de Code Review

O fluxo a seguir ilustra o ciclo de vida completo de uma alteração no código-fonte, desde a criação da branch de trabalho até a incorporação na branch main:

flowchart TD
    START(["Início: Tarefa do Backlog / Issue"]) --> BRANCH["Criar Branch Temporária a partir da main
(feature/*, bugfix/* ou hotfix/*)"]

    BRANCH --> DEV["Desenvolvimento da Solução
+ Escrita de Testes Unitários e E2E (BDD)"]
    DEV --> PRE_CHECK["Checklist de Pré-Submissão do Autor
(Lint, Testes Locais, Auto-Review)"]

    PRE_CHECK --> PR["Abrir Pull Request (PR) contra a main
(Preencher Template de PR)"]

    subgraph CI_PIPELINE["Esteira de Integração Contínua (CI/CD)"]
        direction TB
        CI_LINT["Lint & Code Formatting"] --> CI_BUILD["Build & Type Checking"]
        CI_BUILD --> CI_UNIT["Execução dos Testes Unitários"]
        CI_UNIT --> CI_E2E["Execução dos Testes E2E"]
        CI_E2E --> CI_SAST["Análise Estática de Segurança (SAST)"]
    end

    PR --> CI_PIPELINE
    CI_PIPELINE --> Q_CI{"CI/CD Passou
100% Verde?"}

    Q_CI -->|"Não (Falha)"| FIX_CI["Autor Corrige Erros & Realiza Novo Push"]
    FIX_CI --> CI_PIPELINE

    Q_CI -->|"Sim (Sucesso)"| PEER_REV["Revisão por Pares (Peer Review)"]

    PEER_REV --> Q_PEER{"Apontamentos
Bloqueadores?"}
    Q_PEER -->|"Sim"| ADDR_FEEDBACK["Autor Implementa Ajustes Solicitados"]
    ADDR_FEEDBACK --> CI_PIPELINE

    Q_PEER -->|"Não / Aprovado"| TL_REV["Revisão do Líder Técnico (Tech Lead)"]

    TL_REV --> Q_TL{"Tech Lead
Aprovou?"}
    Q_TL -->|"Solicitar Mudanças"| TL_FEEDBACK["Autor Ajusta Conforme Orientação do TL"]
    TL_FEEDBACK --> CI_PIPELINE

    Q_TL -->|"Aprovado"| MERGE["Merge na branch main via PR (--no-ff)
& Remoção da Branch Temporária"]

    MERGE --> STABILIZATION["Disponível para a Sprint de Estabilização
& Homologação Negocial (PO/QA)"]
    STABILIZATION --> END(["Fim do Ciclo de Integração"])

3. Checklist do Revisor de PR

Ao analisar um Pull Request, o revisor (par ou Tech Lead) deve inspecionar criticamente as cinco dimensões técnicas detalhadas na tabela abaixo:

4. Checklist de Submissão do Autor do PR

Antes de submeter um Pull Request para revisão da equipe, o desenvolvedor autor da alteração deve cumprir rigorosamente o seguinte checklist de auto-avaliação:

### Checklist do Autor antes de abrir o Pull Request:

- [ ] 1. Branch atualizada com a `main` mais recente (via `git rebase main` ou `git merge main` sem conflitos pendentes).
- [ ] 2. Bateria completa de testes automatizados locais executada com 100% de sucesso (`npm run test` e `npm run test:e2e`).
- [ ] 3. Validação de linting e formatação executada sem erros ou avisos (`npm run lint` e `npm run format`).
- [ ] 4. Build da aplicação concluído com sucesso localmente (`npm run build`).
- [ ] 5. Auto-review realizado no GitLab/GitHub: inspeção minuciosa de todo o diff de arquivos alterados antes de solicitar revisão aos pares.
- [ ] 6. Remoção de todos os logs temporários de depuração (`console.log`, `print_r`), comentários de rascunho e arquivos não relacionados.
- [ ] 7. Template de Pull Request preenchido integralmente, incluindo número da Issue, contexto de negócio, cenários BDD e evidências de teste.

Template Oficial de Pull Request (PR)

Todo Pull Request aberto nos repositórios do e-SUS AF deve utilizar o template padronizado abaixo:

## 📌 Descrição da Alteração
<!-- Resumo claro e conciso do que foi implementado, corrigido ou refatorado -->
Resolve a issue: #[Número_da_Issue]

## 🛠️ Tipo de Mudança
- [ ] 🚀 Nova Funcionalidade (`feat`)
- [ ] 🐛 Correção de Bug (`fix` / `bugfix`)
- [ ] 🚑 Hotfix Emergencial de Produção (`hotfix`)
- [ ] ♻️ Refatoração / Débito Técnico (`refactor`)
- [ ] 🧪 Testes Automatizados (`test`)
- [ ] 📚 Documentação (`docs`)

## 🧪 Cobertura de Testes Automatizados (BDD)
- [ ] Testes Unitários adicionados/atualizados
- [ ] Testes E2E cobrindo o **Fluxo Básico (Caminho Feliz)**
- [ ] Testes E2E cobrindo os **Fluxos Alternativos e de Exceção**

**Cenários BDD cobertos:**
1. *Dado* [contexto], *Quando* [ação], *Então* [resultado esperado].
2. *Dado* [contexto de exceção], *Quando* [ação inválida], *Então* [erro esperado tratado].

## 📸 Evidências de Validação Manual
<!-- Insira capturas de tela (screenshots), gravações em vídeo/gif ou trechos de logs comprovando o funcionamento -->

## 📋 Checklist de Auto-Avaliação
- [ ] Minha branch está sincronizada com a `main`.
- [ ] Os testes locais passaram com sucesso.
- [ ] O linter e o build passaram sem erros.
- [ ] Realizei o auto-review do meu próprio diff no repositório.
- [ ] Removi `console.log` e comentários desnecessários.

5. Cultura e Boas Práticas de Revisão

O processo de Code Review deve ser encarado como uma oportunidade de aprendizado contínuo, colaboração e fortalecimento da cultura técnica da equipe, e não como uma etapa punitiva ou burocrática.

5.1. Taxonomia Padronizada de Comentários

Para evitar ambiguidades, ruídos de comunicação e discussões desnecessárias, os revisores devem prefixar seus comentários utilizando as seguintes etiquetas padronizadas:

5.2. Prazos e SLAs de Code Review

Para manter o fluxo contínuo de entrega e evitar que Pull Requests fiquem represados, a equipe adota os seguintes acordos de nível de serviço (SLA) para a realização de revisões:

5.3. Dimensão e Atomicidade dos Pull Requests

• Tamanho Ideal de um PR: Recomenda-se fortemente que Pull Requests contenham até 300 a 400 linhas de código alteradas (excluindo arquivos de lock e fixtures geradas automaticamente).
• Vantagens de PRs Pequenos e Atômicos:
  • Revisões mais profundas, ágeis e atentas por parte dos revisores;
  • Redução drástica do risco de introdução de bugs sutis;
  • Facilidade na identificação da causa raiz em eventuais operações de git bisect;
  • Menor probabilidade de conflitos de merge (merge conflicts) com a branch main.
• Grandes Funcionalidades: Devem ser decompostas em entregas menores e incrementais, utilizando feature toggles (ou feature flags) quando necessário para integrar o código com segurança na main antes da ativação completa da funcionalidade.

5.4. Resolução de Impasses Técnicos

Caso haja discordância técnica entre o autor e o revisor sobre a melhor abordagem para um determinado trecho de código:

1. Comunicação Síncrona: Se a discussão em comentários ultrapassar 3 iterações, os envolvidos devem realizar um alinhamento síncrono rápido (áudio/vídeo) para encontrar um consenso.
2. Mediação do Líder Técnico: Caso o impasse persista, o caso é escalado para o Líder Técnico (Tech Lead), que atuará como árbitro final com base nas diretrizes arquiteturais e nos padrões estabelecidos no Onboarding do projeto.