refactor: quality workflow, docs, tests

docs/DEV.md

@@ -1,79 +1,68 @@
-# Guia de DEV — Banco (Prisma), Auth e Desktop (Tauri)
+# Guia de Desenvolvimento — 16/10/2025
 
-Este guia descreve o que foi corrigido, por quê e como seguir no DEV, incluindo como gerar o executável do Desktop (Tauri) localmente.
+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.
 
-## O que foi feito e por quê
+## Resumo rápido
 
-- Ajuste do Prisma no DEV (P2021)
-  - Problema: o Prisma CLI lia o `.env` da raiz (produção) e o banco local não tinha as tabelas do Better Auth (ex.: `AuthUser`, `AuthSession`).
-  - Decisão: evitar conflito entre `.env` (raiz) e `prisma/.env` — usamos `DATABASE_URL=...` inline nos comandos do Prisma, apontando para `./prisma/db.dev.sqlite` apenas no DEV.
-  - Resultado: banco `prisma/prisma/db.dev.sqlite` criado/sincronizado e seed de usuários executado.
+- **Node/PNPM**: Node 20 + pnpm 9 (habilite via `corepack enable && corepack prepare pnpm@9 --activate`).
+- **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.
 
-- Migração das abas do Desktop para shadcn/Radix
-  - O Tauri não roda Next.js. Para manter o visual consistente com o web, migramos as abas para um wrapper shadcn-like usando Radix Tabs e Tailwind (`apps/desktop/src/components/ui/tabs.tsx`).
-  - Incluímos badge de status equivalente ao web e o botão “Enviar inventário agora” (POST `/api/machines/inventory`).
+## Banco de dados (Prisma)
 
-- CI (GitHub Actions) e lockfile
-  - Erro resolvido: `ERR_PNPM_OUTDATED_LOCKFILE` em `apps/desktop`. Atualizamos o `pnpm-lock.yaml` para refletir as novas dependências do Desktop.
-  - O workflow do desktop usa `--frozen-lockfile`; manter o lockfile em sincronia evita falhas.
+1. Gere/atualize o schema local:
 
-## Fluxo de banco (DEV)
+   ```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
+   ```
 
-- Banco de DEV: `file:./prisma/db.dev.sqlite` (arquivo: `prisma/prisma/db.dev.sqlite`).
-- Comandos (forçar alvo de DEV no terminal atual):
+2. Rode o app Next.js:
 
-```
-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
-```
+   ```bash
+   pnpm dev
+   ```
 
-- Rodar app local (Next):
+3. Credenciais padrão (seed): `admin@sistema.dev / admin123`.
 
-```
-pnpm dev
-```
+> **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.
 
-- Login de teste (DEV): `admin@sistema.dev / admin123`
+## Comandos de qualidade
 
-- Prisma Studio (DEV):
+- `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.
+- `pnpm build`: `next build --turbopack`.
+- `pnpm prisma:generate`: necessário antes do build quando o client Prisma muda.
 
-```
-DATABASE_URL="file:./prisma/db.dev.sqlite" pnpm exec prisma studio
-```
+### Automação no CI
 
-Observação: evitar `prisma/.env` nesse setup, pois causa conflito com o `.env` da raiz (o Prisma acusa conflitos e falha o comando). Manter o override inline é a forma mais segura de isolar DEV sem tocar produção.
+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)
 
-- Onde foram feitas as mudanças principais:
-  - `apps/desktop/src/components/ui/tabs.tsx` (Tabs Radix + estilos shadcn-like)
-  - `apps/desktop/src/main.tsx` (layout com abas: Resumo/Inventário/Diagnóstico/Configurações; status badge; botão “Enviar inventário agora”; seleção do perfil de acesso colaborador/gestor e sincronização do usuário vinculado).
-  - `apps/desktop/src-tauri/src/agent.rs` (coleta e normalização de hardware, discos, GPUs e inventário estendido por SO).
+- 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).
 
-- Variáveis de ambiente do Desktop (em tempo de build):
-  - `VITE_APP_URL` e `VITE_API_BASE_URL` — por padrão, use a URL da aplicação web.
+### Build local
 
-### Atualizações automáticas (GitHub)
-
-1. Gere o par de chaves do updater (`pnpm tauri signer generate -- -w ~/.tauri/raven.key`) e configure as variáveis de ambiente `TAURI_SIGNING_PRIVATE_KEY` e `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` antes de rodar `pnpm -C apps/desktop tauri build`.
-2. Garanta que `bundle.createUpdaterArtifacts` esteja habilitado (já configurado) para gerar os pacotes `.nsis`/`.AppImage` e os arquivos `.sig`.
-3. Publique os artefatos de cada SO em um release do GitHub e atualize o `latest.json` público (ex.: no próprio repositório ou em um gist) com `version`, `notes`, `pub_date` e as entradas por plataforma (`url` e `signature`).
-4. O agente já consulta o updater ao iniciar e também possui o botão “Verificar atualizações” na aba Configurações. Ao detectar nova versão o download é feito em segundo plano e o app reinicia automaticamente após o `downloadAndInstall`.
-
-### Build do executável localmente
-
-Você pode gerar o executável local sem precisar da VPS. O que muda é apenas o sistema operacional alvo (Linux/Windows/macOS). O Tauri recomenda compilar em cada SO para obter o bundle nativo desse SO. Em produção, o GitHub Actions já faz isso em matriz.
-
-1) Pré-requisitos gerais
-   - Node 20 + pnpm 9 (via Corepack)
-   - Rust (stable) — `rustup` instalado
-   - Dependências do sistema (Linux):
-     - `libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libxdo-dev libssl-dev build-essential curl wget file`
-
-2) Instalar deps do desktop e buildar
-
-```
+```bash
 corepack enable && corepack prepare pnpm@9 --activate
 pnpm -C apps/desktop install
 VITE_APP_URL=http://localhost:3000 \
@@ -81,27 +70,28 @@ VITE_API_BASE_URL=http://localhost:3000 \
 pnpm -C apps/desktop tauri build
 ```
 
-3) Saída do build
-   - Os artefatos ficam em: `apps/desktop/src-tauri/target/release/bundle/`
-   - No Linux: `.AppImage`/`.deb`/`.rpm` (conforme target)
-   - No Windows/macOS: executável/instalador específicos do SO (para assinatura, usar chaves/AC, se desejado)
-   - Para liberar atualizações OTA, publique release no GitHub com artefatos e `latest.json` — o plugin de updater verifica a URL configurada em `tauri.conf.json`.
+Artefatos: `apps/desktop/src-tauri/target/release/bundle/`.
 
-### Build na VPS x Local
+### Atualizações OTA
 
-- Não há diferença funcional além do SO alvo e de possíveis chaves de assinatura. Use a VPS apenas se quiser gerar pacotes Linux em ambiente isolado. Para Windows/macOS, é preferível buildar nesses SOs ou usar a matriz do GitHub Actions (já configurada).
+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”.
 
-## CI/CD — Observações
+## Erros recorrentes e soluções
 
-- `desktop-release.yml` (Tauri): instala dependências, faz build por SO e publica artefatos. Mantendo o `pnpm-lock.yaml` atualizado, o passo `--frozen-lockfile` passa.
-- `ci-cd-web-desktop.yml`: já usa `pnpm install --no-frozen-lockfile` no web, evitando falhas em pipelines de integração.
-  - Smoke de provisionamento pode ser desligado definindo `RUN_MACHINE_SMOKE=false` (default); quando quiser exercitar o fluxo complete register/heartbeat, defina `RUN_MACHINE_SMOKE=true`.
+| 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. |
 
-## Troubleshooting
+## Referências úteis
 
-- Sign-in 500 após `db push`/seed:
-  - Verifique o terminal do app e confirme a existência da tabela `AuthUser` no Prisma Studio (alvo DEV).
+- **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`.
 
-- `ERR_PNPM_OUTDATED_LOCKFILE` no Desktop:
-  - Atualize `pnpm-lock.yaml` no root após alterar dependências de `apps/desktop/package.json`.
-  - Alternativa: usar `--no-frozen-lockfile` (não recomendado para releases reproduzíveis).
+> Última revisão: 16/10/2025. Atualize este guia sempre que o fluxo de DEV ou automações mudarem.