Guia de Desenvolvimento — 16/10/2025

Este documento consolida o estado atual do ambiente de desenvolvimento, descreve como rodar lint/test/build localmente (e no CI) e registra erros recorrentes com as respectivas soluções.

Resumo rápido

Node/PNPM: Node 20.9+ (alinhado ao requisito do Next 15) + pnpm 9 (habilite via corepack enable && corepack prepare pnpm@9 --activate).
Next.js 15.5.5: Projeto voltou para a versão estável (next@15.5.5) com Turbopack como bundler padrão e whitelist de domínios garantida pelo middleware.
Lint/Test/Build: pnpm lint, pnpm test, pnpm build. O script de testes usa vitest --run --passWithNoTests, eliminando o modo watch interativo.
Banco DEV: SQLite em prisma/prisma/db.dev.sqlite. Defina DATABASE_URL="file:./prisma/db.dev.sqlite" ao chamar CLI do Prisma.
Desktop (Tauri): fonte em apps/desktop. Usa Radix tabs + componentes shadcn-like, integra com os endpoints /api/machines/* e suporta atualização automática via GitHub Releases.
CI: Workflow Quality Checks roda lint/test/build para pushes e PRs na main, além do pipeline de deploy existente.

Banco de dados (Prisma)

Gere/atualize o schema local:

DATABASE_URL="file:./prisma/db.dev.sqlite" pnpm exec prisma db push
DATABASE_URL="file:./prisma/db.dev.sqlite" pnpm prisma:generate
DATABASE_URL="file:./prisma/db.dev.sqlite" pnpm auth:seed

Rode o app Next.js:
```
pnpm dev
```
Credenciais padrão (seed): admin@sistema.dev / admin123.

Por quê inline? Evitamos declarar DATABASE_URL em prisma/.env porque o Prisma lê também o .env da raiz (produção). O override inline garante isolamento do banco DEV.

Next.js 15 (estável)

Mantemos o projeto em next@15.5.5, priorizando estabilidade enquanto acompanhamos as novidades do 16.
React 18.2: voltamos para a versão suportada oficialmente pelo Next 15. Evite APIs exclusivas do React 19 (use(...), useActionState, etc.).
Turbopack segue como bundler padrão, sem flags experimentais adicionais.
Whitelist de hosts: o release estável 15.5 não aceita server.allowedHosts (vide invalid-next-config), portanto bloqueamos domínios exclusivamente via middleware.ts.

Comandos de qualidade

pnpm lint: executa ESLint (flat config) sobre os arquivos do projeto.
pnpm test: Vitest em modo não interativo (--run --passWithNoTests). Use pnpm test -- --watch somente quando quiser rodar em watch localmente. Inclui testes de API (rotas /api/machines/*) e utilitários de SMTP.
pnpm build: next build --turbopack.
pnpm prisma:generate: necessário antes do build quando o client Prisma muda.

Automação no CI

Arquivo: .github/workflows/quality-checks.yml

Etapas:

Instala dependências (pnpm install --frozen-lockfile).
pnpm prisma:generate.
pnpm lint.
pnpm test.
pnpm build.

O workflow dispara em todo push/pull_request para main e fornece feedback imediato sem depender do pipeline de deploy.

Desktop (Tauri)

Tabs Radix + estilos shadcn: apps/desktop/src/components/ui/tabs.tsx.
Painel principal: apps/desktop/src/main.tsx — abas Resumo/Inventário/Diagnóstico/Configurações, envio manual de inventário, seleção de persona (colaborador/gestor) e vínculo com usuário.
Coleta/hardware: apps/desktop/src-tauri/src/agent.rs.
Variáveis de build:
- VITE_APP_URL (URL Web).
- VITE_API_BASE_URL (API).

Build local

corepack enable && corepack prepare pnpm@9 --activate
pnpm -C apps/desktop install
VITE_APP_URL=http://localhost:3000 \
VITE_API_BASE_URL=http://localhost:3000 \
pnpm -C apps/desktop tauri build

Artefatos: apps/desktop/src-tauri/target/release/bundle/.

Atualizações OTA

Gere chaves (pnpm tauri signer generate).
Defina TAURI_SIGNING_PRIVATE_KEY (+ password) no ambiente de build.
Publique os pacotes e um latest.json em release GitHub.
O app verifica ao iniciar e pelo botão “Verificar atualizações”.

Erros recorrentes e soluções

Sintoma	Causa	Correção
`ERR_PNPM_OUTDATED_LOCKFILE` no pipeline	Dependências do desktop alteradas sem atualizar `pnpm-lock.yaml`	Rodar `pnpm install` na raiz e commitar o lockfile.
Prisma falha com `P2021` / tabelas Better Auth inexistentes	CLI leu `.env` da raiz (produção)	Usar `DATABASE_URL="file:./prisma/db.dev.sqlite"` nos comandos.
Vitest trava em modo watch	Script `pnpm test` sem `--run` e CI detecta TTY	Ajustado para `vitest --run --passWithNoTests`. Localmente, use `pnpm test -- --watch` se quiser.
Desktop não encontra updater	Falta `latest.json` ou assinatura inválida	Publicar release com `*.sig` e `latest.json` apontando para os pacotes corretos.

Referências úteis

Deploy (Swarm): veja docs/DEPLOY-RUNBOOK.md.
Plano do agente desktop / heartbeat: docs/plano-app-desktop-maquinas.md.
Histórico de incidentes: docs/historico-agente-desktop-2025-10-10.md.

Última revisão: 16/10/2025. Atualize este guia sempre que o fluxo de DEV ou automações mudarem.

Next.js 16 (beta): comportamento sujeito a mudanças. Antes de subir para stable, acompanhe o changelog oficial (quebra: revalidateTag com segundo argumento, params assíncronos, etc.). Já estamos compatíveis com os breaking changes atuais.

5.4 KiB Raw Blame History