# 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+ (Next.js 16 exige essa versão mínima) + pnpm 9 (habilite via `corepack enable && corepack prepare pnpm@9 --activate`).
- **Next.js 16 (beta)**: Projeto já está em `next@16.0.0-beta.0`, com Turbopack como bundler padrão e cache de filesystem habilitado em `next.config.ts` (além de `server.allowedHosts` configurado para os domínios via Traefik).
- **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)

1. Gere/atualize o schema local:

   ```bash
   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
   ```

2. Rode o app Next.js:

   ```bash
   pnpm dev
   ```

3. 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 16 (beta)

- Comportamento sujeito a mudanças; acompanhe o changelog antes da GA. Breaking changes relevantes já mitigados: `params`/`searchParams` assíncronos, `cookies()`/`headers()` com await e `revalidateTag` aguardando novo perfil (não utilizamos).
- **Turbopack** é o bundler padrão. Mantemos `experimental.turbopackFileSystemCacheForDev = true` no `next.config.ts` para acelerar reinicializações do `pnpm dev`.
- **React Compiler (opcional)**: habilite com `reactCompiler: true` no `next.config.ts` e instale `babel-plugin-react-compiler`. Use apenas para experiências controladas (a compilação fica mais lenta).
- **Caching APIs**: considere `updateTag()`/`refresh()` em novas Server Actions. Atualmente não usamos `revalidateTag`.

## 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:

1. Instala dependências (`pnpm install --frozen-lockfile`).
2. `pnpm prisma:generate`.
3. `pnpm lint`.
4. `pnpm test`.
5. `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

```bash
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

1. Gere chaves (`pnpm tauri signer generate`).
2. Defina `TAURI_SIGNING_PRIVATE_KEY` (+ password) no ambiente de build.
3. Publique os pacotes e um `latest.json` em release GitHub.
4. 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.