Pipeline de CI/CD

Este documento descreve os fluxos de integração contínua, execução de testes e o processo de deploy manual do projeto.

1. Visão Geral

O repositório conta com dois workflows do GitHub Actions e um script de deploy manual via SSH. Não há Continuous Deployment automático — o deploy em produção é sempre iniciado manualmente.

Arquivo	Trigger	Jobs	Duração Estimada
`.github/workflows/ci.yml`	Push em `develop` ou `main`	type-check, lint, build	~3–5 min
`.github/workflows/tests.yml`	Push em `develop`/`main` (unit); PRs para `main` (unit + e2e)	unit, e2e	~5–8 min (unit) / ~12–18 min (e2e)
`scripts/deploy.bat`	Manual (desenvolvedor)	SSH + pm2 restart	~5–10 min

2. Workflow `ci.yml` — Integração Contínua

Executado a cada push nas branches develop e main. É a barreira de qualidade de código: se qualquer step falhar, o push é bloqueado de avançar no pipeline.

2.1 Steps Detalhados

Job: ci
Runs-on: ubuntu-latest
Node.js: 20 (cache: npm)

1. actions/checkout@v4
   └── Faz checkout do código do branch que disparou o push.

2. actions/setup-node@v4 (node-version: 20, cache: npm)
   └── Instala Node 20 e restaura o cache do node_modules
       baseado no package-lock.json (acelera execuções subsequentes).

3. npm ci
   └── Instalação limpa das dependências (usa package-lock.json).
       Falha se houver inconsistência entre package.json e lock file.

4. npx prisma generate
   └── Gera o Prisma Client a partir do schema.prisma.
       OBRIGATÓRIO antes de qualquer import de @/lib/db ou @prisma/client.
       Não requer DATABASE_URL (apenas lê o schema).

5. tsc --noEmit
   └── Type check completo do projeto sem gerar arquivos.
       Falha em qualquer erro de tipo, mesmo em arquivos não alterados.

6. eslint --max-warnings=200
   └── Linting com tolerância de até 200 warnings.
       Warnings acima de 200 ou qualquer erro → falha do job.
       O threshold 200 é temporário — reduzir progressivamente.

7. next build
   └── Build de produção completo.
       Falha se houver import inválido, variável de ambiente ausente
       marcada como obrigatória, ou erro de runtime em Server Components.

2.2 Variáveis de Ambiente Necessárias no CI

O step next build exige algumas variáveis para não falhar. Defina-as como secrets no repositório GitHub:

Variável	Obrigatória no Build?	Observação
`DATABASE_URL`	Não (Prisma generate não conecta)	Necessária apenas nos testes
`JWT_SECRET`	Sim (referenciada em código)	Qualquer valor de 32+ chars serve para build
`NEXTAUTH_URL`	Recomendado	Evita warnings no build
`NEXT_PUBLIC_GA4_ID`	Não	Build continua sem ela (feature fica desabilitada)
`NEXT_PUBLIC_CLARITY_ID`	Não	Idem

2.3 Como Interpretar Falhas

Falha	Causa Mais Comum	Ação
`tsc --noEmit` com erros	Tipo incorreto, import errado, `any` implícito	Corrigir os erros de tipo localmente antes do push
`eslint` com `Found X warnings, max allowed: 200`	Warnings acumulados	Corrigir warnings até ficar abaixo do threshold
`next build` — `Module not found`	Prisma Client não gerado ou path alias errado	Verificar se `npx prisma generate` roda antes
`next build` — `Environment variable not found`	Secret ausente no GitHub	Adicionar o secret em Settings → Secrets → Actions

3. Workflow `tests.yml` — Testes Automatizados

3.1 Job `unit` — Testes Unitários com Jest

Executado em todo push para develop e main, e também como pré-requisito do job e2e.

Job: unit
Runs-on: ubuntu-latest
Node.js: 20 (cache: npm)

1. checkout + setup-node + npm ci + prisma generate
2. jest --ci --coverage --coverageThreshold='{"global":{"lines":60}}'
   └── Executa todos os testes (__tests__/**).
       Falha se coverage de linhas cair abaixo de 60%.
       --ci desativa watch mode e trata warnings como erros.
3. actions/upload-artifact@v4
   └── Faz upload do relatório coverage/lcov-report/ como artifact.
       Disponível por 7 dias na aba Actions do repositório.

Variáveis de ambiente necessárias para os testes unitários:

DATABASE_URL=mysql://root:root@localhost:3306/ljvemas_test
JWT_SECRET=test-secret-for-ci-at-least-32-characters

3.2 Job `e2e` — Testes End-to-End com Playwright

Executado apenas em Pull Requests para main, e somente após o job unit ser concluído com sucesso.

Job: e2e
Needs: unit
If: github.event_name == 'pull_request' && github.base_ref == 'main'
Runs-on: ubuntu-latest

1. checkout + setup-node + npm ci + prisma generate
2. npx playwright install chromium
   └── Instala apenas o browser Chromium (economia de ~400MB vs instalar todos).
3. Sobe banco de dados MySQL via Docker
   └── docker run -d -p 3306:3306 mysql:8
       Aguarda healthcheck antes de continuar.
4. npx prisma migrate deploy
   └── Aplica todas as migrations no banco de testes.
5. npm run db:seed
   └── OBRIGATÓRIO antes dos testes E2E.
       O login helper dos testes depende do usuário admin seedado.
6. npm run test:e2e
   └── Playwright com retries: 2 e workers: 1 (para evitar race conditions).

3.3 Diagrama de Dependência dos Jobs

3.4 Configuração do Playwright

O arquivo playwright.config.ts define:

Browser: Chromium apenas
Retries: 2 (falhas intermitentes não bloqueiam o PR)
Workers: 1 em CI (evita conflitos no banco de dados)
Base URL: http://localhost:3000
Timeout: 30s por teste

4. Deploy Manual

O deploy em produção não é automatizado. O processo atual utiliza o script scripts/deploy.bat que realiza a implantação via SSH no servidor Hostinger.

4.1 Pré-requisitos

Acesso SSH configurado ao servidor Hostinger (chave SSH no agente ou arquivo ~/.ssh/config)
Variáveis de ambiente de produção configuradas no servidor
PM2 instalado globalmente no servidor: npm install -g pm2

4.2 Processo de Deploy

scripts/deploy.bat
│
Conecta ao servidor via SSH
git pull origin main  (atualiza o código no servidor)
npm ci --omit=dev     (instala dependências de produção)
npx prisma generate   (regenera o Prisma Client)
npx prisma migrate deploy  (aplica migrations pendentes)
next build            (gera o build de produção)
pm2 restart ljvemasearomas  (reinicia a aplicação)

4.3 Verificação Pós-Deploy

Após o deploy, verificar manualmente:

pm2 status — processo ljvemasearomas está online
pm2 logs ljvemasearomas --lines 50 — sem erros de inicialização
Acessar a URL de produção e verificar que a loja carrega
Testar login no admin panel
Verificar que o último pedido/produto está presente (sem regressão de dados)

5. Secrets Necessários no GitHub

Os secrets abaixo precisam ser configurados em Settings → Secrets and variables → Actions do repositório. Atualmente nenhum está configurado — isso precisa ser feito antes de os workflows poderem rodar em ambiente limpo.

Secret	Uso	Como Obter	Onde Configurar
`JWT_SECRET`	Build e testes	`openssl rand -hex 32`	GitHub → Settings → Secrets → Actions
`DATABASE_URL`	Testes unitários e E2E	Connection string do MySQL de CI	GitHub → Settings → Secrets → Actions
`NEXTAUTH_URL`	Build sem warnings	URL do ambiente (ex.: `http://localhost:3000`)	GitHub → Settings → Secrets → Actions
`SSH_PRIVATE_KEY`	Deploy via `deploy.bat` (futuro)	Chave privada do servidor Hostinger	GitHub → Settings → Secrets → Actions
`SSH_HOST`	Deploy via `deploy.bat` (futuro)	IP ou hostname do servidor	GitHub → Settings → Secrets → Actions
`HYPERDX_API_KEY`	Telemetria em produção	Dashboard HyperDX	Servidor (não no CI)

Atenção: para o deploy manual atual via scripts/deploy.bat, os secrets do GitHub não são necessários — o script usa as credenciais SSH do desenvolvedor. Os secrets SSH_PRIVATE_KEY e SSH_HOST seriam necessários apenas se o deploy fosse automatizado via GitHub Actions no futuro.

6. Como Adicionar um Novo Workflow

6.1 Template Mínimo

# .github/workflows/meu-workflow.yml
name: Meu Workflow

on:
  push:
    branches: [develop, main]

jobs:
  meu-job:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Instalar dependências
        run: npm ci

      - name: Gerar Prisma Client
        run: npx prisma generate

      - name: Executar tarefa
        run: npm run minha-tarefa
        env:
          JWT_SECRET: ${{ secrets.JWT_SECRET }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}

6.2 Checklist para Novo Workflow

Usa actions/checkout@v4 (não versões antigas)
Usa node-version: 20 com cache: npm
Roda npm ci (não npm install)
Roda npx prisma generate antes de qualquer import de Prisma
Variáveis de ambiente sensíveis são lidas de secrets, não hardcoded
Nome do workflow e dos jobs é descritivo em inglês
Trigger é restrito às branches necessárias (não usar on: push sem filtro)

7. Solução de Problemas de CI

7.1 Erros de Type Check

Sintoma: tsc --noEmit falha com erros de tipo.

Causa: Tipos incompatíveis, imports incorretos ou any implícito introduzido em um PR.

Solução: Executar localmente antes do push:

npx tsc --noEmit

Corrigir todos os erros antes de fazer push.

7.2 Lint com Excesso de Warnings

Sintoma: Found 215 warnings (max: 200).

Causa: Warnings de lint acumulados ultrapassaram o threshold de 200.

Solução:

npx eslint . --max-warnings=200 2>&1 | grep "warning" | head -30

Corrigir pelo menos 15 warnings (os mais fáceis primeiro: variáveis não usadas, imports desnecessários).

7.3 Testes E2E sem Banco de Dados

Sintoma: Testes E2E falham com P1001: Can't reach database server.

Causa: O step de subir o MySQL via Docker não foi aguardado ou a DATABASE_URL está incorreta.

Solução: Verificar no workflow se o healthcheck do container MySQL está configurado e se DATABASE_URL aponta para localhost:3306 com as credenciais corretas do container.

7.4 Playwright sem Browsers Instalados

Sintoma: Error: browserType.launch: Executable doesn't exist at .../chromium.

Causa: O step npx playwright install chromium não foi executado no job.

Solução: Garantir que o workflow inclui o step de instalação antes de rodar os testes:

npx playwright install chromium

7.5 Seed Falha com Timeout no CI

Sintoma: npm run db:seed falha com P1001 ou timeout.

Causa: O Prisma não consegue conectar ao banco porque o container MySQL ainda não está pronto, ou a DATABASE_URL está incorreta no step.

Solução: Adicionar um sleep ou healthcheck antes do seed:

- name: Aguardar MySQL
  run: |
    for i in $(seq 1 30); do
      mysqladmin ping -h 127.0.0.1 -u root -proot && break
      sleep 2
    done

- name: Seed do banco
  run: npm run db:seed
  env:
    DATABASE_URL: mysql://root:root@localhost:3306/ljvemas_test

1. Visão Geral​

2. Workflow ci.yml — Integração Contínua​

2.1 Steps Detalhados​

2.2 Variáveis de Ambiente Necessárias no CI​

2.3 Como Interpretar Falhas​

3. Workflow tests.yml — Testes Automatizados​

3.1 Job unit — Testes Unitários com Jest​

3.2 Job e2e — Testes End-to-End com Playwright​

3.3 Diagrama de Dependência dos Jobs​

3.4 Configuração do Playwright​

4. Deploy Manual​

4.1 Pré-requisitos​

4.2 Processo de Deploy​

4.3 Verificação Pós-Deploy​

5. Secrets Necessários no GitHub​

6. Como Adicionar um Novo Workflow​

6.1 Template Mínimo​

6.2 Checklist para Novo Workflow​

7. Solução de Problemas de CI​

7.1 Erros de Type Check​

7.2 Lint com Excesso de Warnings​

7.3 Testes E2E sem Banco de Dados​

7.4 Playwright sem Browsers Instalados​

7.5 Seed Falha com Timeout no CI​