From 7569986ffccedf28b50f4a9f7dcd72e5ed23467f Mon Sep 17 00:00:00 2001
From: Esdras Renan <monkeyesdras@gmail.com>
Date: Wed, 8 Oct 2025 21:42:40 -0300
Subject: [PATCH] docs(agents): add local dev guide, env examples, CI/deploy
 notes

---
 agents.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/agents.md b/agents.md
index 11966f9..3e1ea73 100644
--- a/agents.md
+++ b/agents.md
@@ -23,6 +23,70 @@
 5. `pnpm convex:dev`
 6. Em outro terminal: `pnpm dev`
 
+## Desenvolvimento local — boas práticas (atualizado)
+- Ambientes separados: mantenha seu `.env.local` só para DEV e o `.env` da VPS só para PROD. Nunca commitar arquivos `.env`.
+- Convex em DEV: rode `pnpm convex:dev` e aponte o front para `http://127.0.0.1:3210` via `NEXT_PUBLIC_CONVEX_URL`.
+- Banco local: por padrão `DATABASE_URL=file:./prisma/db.sqlite`. Se quiser isolar por projeto, use `db.dev.sqlite`.
+- Seeds em DEV: use `pnpm auth:seed` (usuários Better Auth) e acesse `/dev/seed` uma vez para dados de demonstração do Convex.
+- Seeds em PROD: só quando realmente necessário; não fazem parte do deploy automático.
+
+### Exemplo de `.env.local` (DEV)
+```
+# Base do app
+NODE_ENV=development
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+BETTER_AUTH_URL=http://localhost:3000
+BETTER_AUTH_SECRET=dev-only-long-random-string
+
+# Convex (DEV)
+NEXT_PUBLIC_CONVEX_URL=http://127.0.0.1:3210
+
+# Banco local (Prisma)
+DATABASE_URL=file:./prisma/db.sqlite
+
+# SMTP de desenvolvimento (ex.: Mailpit)
+SMTP_ADDRESS=localhost
+SMTP_PORT=1025
+SMTP_TLS=false
+SMTP_USERNAME=
+SMTP_PASSWORD=
+MAILER_SENDER_EMAIL="Dev <no-reply@localhost>"
+
+# (Opcional) OAuth DEV – não usado por padrão neste projeto
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+```
+
+Observações:
+- `COOKIE_DOMAIN` não é necessário em DEV neste projeto.
+- Variáveis de provisionamento de máquinas (`MACHINE_PROVISIONING_SECRET`, etc.) só se você for testar as rotas de máquinas/inventário.
+
+### Passo a passo local
+1) `pnpm install`
+2) `pnpm prisma:generate`
+3) `pnpm convex:dev` (terminal A)
+4) `pnpm dev` (terminal B)
+5) (Opcional) `pnpm auth:seed` e visitar `http://localhost:3000/dev/seed`
+
+## Deploy via GitHub Actions (produção)
+- Fluxo: `git push main` ⇒ runner self‑hosted na VPS sincroniza código e aplica o stack (Traefik/Swarm) sem derrubar o serviço (start-first).
+- Disparo do deploy web: apenas quando há mudanças em arquivos do app (src/, public/, prisma/, next.config.ts, package.json, pnpm-lock.yaml, tsconfig.json, middleware.ts, stack.yml).
+- Disparo do deploy Convex: apenas quando há mudanças em `convex/**`.
+- O `.env` da VPS é preservado; caches do servidor (`node_modules`, `.pnpm-store`) não são tocados.
+- Banco Prisma (SQLite) persiste em volume nomeado (`sistema_db`); não é recriado a cada deploy.
+
+## Bancos e seeds — DEV x PROD
+- DEV: use os seeds à vontade (usuários com `pnpm auth:seed`, dados demo do Convex em `/dev/seed`).
+- PROD: evite seeds automáticos; para criar um admin use `SEED_USER_*` e `pnpm auth:seed` em um container Node efêmero.
+- Alterações de schema: sempre via migrações (`prisma migrate`). O CI aplica `migrate deploy` no start do container web.
+
+## Dicas rápidas
+- Imagens em `public/`: trocou o arquivo → push. Para bust de cache, versionar o nome (ex.: `logo.v2.png`) ou usar query (`?v=sha`).
+- Problemas de permissão de build: garanta que `.next` pertence ao usuário do runner (se necessário, remover `.next` no host e rebuildar).
+- Se precisar inspecionar/backup do SQLite em PROD, prefira um bind dedicado (`/srv/apps/sistema-data:/app/data`) ou use `docker run -v sistema_db:/data` para copiar o arquivo.
+
 ## Checklist para novo computador
 1. Instale Node.js 20+ e habilite o Corepack (`corepack enable`) para usar o `pnpm`.
 2. Garanta o `pnpm` atualizado (`corepack prepare pnpm@latest --activate`) antes de clonar o repositório.