esdras/sistema-de-chamados
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: atualizar instrucoes para bun e convex self-hosted

Browse source
This commit is contained in:
Esdras Renan 2025-11-05 19:39:44 -03:00
parent aec9b1ff85
commit fb17882dad
5 changed files with 35 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

18
README.md
View file

@ -20,16 +20,16 @@ Aplicação **Next.js 16 (App Router)** com **React 19**, **Convex** e **Better
- `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `DATABASE_URL` - `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `DATABASE_URL`
3. Aplique as migrações e gere o client Prisma: 3. Aplique as migrações e gere o client Prisma:
```bash ```bash
pnpm prisma migrate deploy bunx prisma migrate deploy
pnpm prisma:generate bun run prisma:generate
``` ```
4. Popule usuários padrão do Better Auth: 4. Popule usuários padrão do Better Auth:
```bash ```bash
pnpm auth:seed bun run auth:seed
``` ```
5. (Opcional) Para re-sincronizar manualmente as filas padrão, execute: 5. (Opcional) Para re-sincronizar manualmente as filas padrão, execute:
```bash ```bash
pnpm queues:ensure bun run queues:ensure
``` ```
6. Em um terminal, execute o backend em tempo real do Convex: 6. Em um terminal, execute o backend em tempo real do Convex:
```bash ```bash
@ -40,7 +40,7 @@ Aplicação **Next.js 16 (App Router)** com **React 19**, **Convex** e **Better
```bash ```bash
bun run dev:bun bun run dev:bun
``` ```
> Fallback: `pnpm dev` (Node) ou `bun run dev:webpack` caso o Turbopack acione alguma incompatibilidade. > Fallback: `bun run dev:webpack` caso o Turbopack acione alguma incompatibilidade.
8. Com o Convex ativo, acesse `http://localhost:3000/dev/seed` uma vez para popular dados de demonstração (tickets, usuários, comentários) diretamente no banco do Convex. 8. Com o Convex ativo, acesse `http://localhost:3000/dev/seed` uma vez para popular dados de demonstração (tickets, usuários, comentários) diretamente no banco do Convex.
> Se o CLI perguntar sobre configuração do projeto Convex, escolha criar um novo deployment local (opção padrão) e confirme. As credenciais são armazenadas em `.convex/` automaticamente. > Se o CLI perguntar sobre configuração do projeto Convex, escolha criar um novo deployment local (opção padrão) e confirme. As credenciais são armazenadas em `.convex/` automaticamente.
@ -64,9 +64,9 @@ Para fluxos detalhados de desenvolvimento — banco de dados local (SQLite/Prism
## Scripts úteis ## Scripts úteis
- `bun run dev:bun` — padrão atual para o Next.js com runtime Bun (`pnpm dev` usa Node como fallback). - `bun run dev:bun` — padrão atual para o Next.js com runtime Bun (`bun run dev:webpack` permanece como fallback).
- `bun run convex:dev:bun` — runtime Bun para o Convex (`pnpm convex:dev` mantém o fluxo antigo). - `bun run convex:dev:bun` — runtime Bun para o Convex (`bun run convex:dev` mantém o fluxo antigo usando Node).
- `bun run build:bun` / `bun run start:bun` — build e serve com Bun; use `pnpm build`/`pnpm start` se quiser ficar no Node. - `bun run build:bun` / `bun run start:bun` — build e serve com Bun; `bun run build` mantém o fallback Node.
- `bun run dev:webpack` / `bun run build:webpack` — fallback oficial caso Turbopack apresente problemas. - `bun run dev:webpack` / `bun run build:webpack` — fallback oficial caso Turbopack apresente problemas.
- `bun run lint` — ESLint com as regras do projeto. - `bun run lint` — ESLint com as regras do projeto.
- `bun test` — suíte de testes unitários usando o runner do Bun (o teste de screenshot fica automaticamente ignorado se o matcher não existir). - `bun test` — suíte de testes unitários usando o runner do Bun (o teste de screenshot fica automaticamente ignorado se o matcher não existir).
@ -97,7 +97,7 @@ Sem o reset de agente, o Convex reaproveita o token anterior e o inventário con
## Credenciais de demonstração ## Credenciais de demonstração
Após executar `pnpm auth:seed`, as credenciais padrão ficam disponíveis conforme descrito em `agents.md` (seção “Credenciais padrão”). Ajuste variáveis `SEED_USER_*` se precisar sobrepor usuários ou senhas durante o seed. Após executar `bun run auth:seed`, as credenciais padrão ficam disponíveis conforme descrito em `agents.md` (seção “Credenciais padrão”). Ajuste variáveis `SEED_USER_*` se precisar sobrepor usuários ou senhas durante o seed.
## Próximos passos ## Próximos passos

34
agents.md
View file

@ -13,23 +13,23 @@
Os demais colaboradores reais são provisionados via **Convites & acessos**. Caso existam vestígios de dados demo, execute `node scripts/remove-legacy-demo-users.mjs` para limpá-los. Os demais colaboradores reais são provisionados via **Convites & acessos**. Caso existam vestígios de dados demo, execute `node scripts/remove-legacy-demo-users.mjs` para limpá-los.
> Execute `pnpm auth:seed` após configurar `.env` para (re)criar os usuários acima (campos `SEED_USER_*` podem sobrescrever credenciais). > Execute `bun run auth:seed` após configurar `.env` para (re)criar os usuários acima (campos `SEED_USER_*` podem sobrescrever credenciais).
## Backend Convex ## Backend Convex
- Seeds de usuários/tickets demo: `convex/seed.ts`. - Seeds de usuários/tickets demo: `convex/seed.ts`.
- Para DEV: rode `pnpm convex:dev` e acesse `/dev/seed` uma vez para popular dados realistas. - Para DEV: rode `bun run convex:dev:bun` e acesse `/dev/seed` uma vez para popular dados realistas.
## Stack atual (18/10/2025) ## Stack atual (18/10/2025)
- **Next.js**: `15.5.5` (Turbopack em produção + cache de filesystem em DEV). - **Next.js**: `15.5.5` (Turbopack em produção + cache de filesystem em DEV).
- Whitelist de domínios em `src/config/allowed-hosts.ts` é aplicada pelo `middleware.ts`. - Whitelist de domínios em `src/config/allowed-hosts.ts` é aplicada pelo `middleware.ts`.
- **React / React DOM**: `18.2.0`. - **React / React DOM**: `18.2.0`.
- **Trilha de testes**: Vitest (`pnpm test`) sem modo watch por padrão (`--run --passWithNoTests`). - **Trilha de testes**: Vitest (`bun test`) sem modo watch por padrão (`--run --passWithNoTests`).
- **CI**: workflow `Quality Checks` (`.github/workflows/quality-checks.yml`) roda `pnpm install`, `prisma:generate`, `lint`, `test`, `build`. Variáveis críticas (`BETTER_AUTH_SECRET`, `NEXT_PUBLIC_APP_URL`, etc.) são definidas apenas no runner — não afetam a VPS. - **CI**: workflow `Quality Checks` (`.github/workflows/quality-checks.yml`) roda `bun install`, `bun run prisma:generate`, `bun run lint`, `bun test`, `bun run build:bun`. Variáveis críticas (`BETTER_AUTH_SECRET`, `NEXT_PUBLIC_APP_URL`, etc.) são definidas apenas no runner — não afetam a VPS.
- **Disciplina pós-mudanças**: sempre que fizer alterações locais, rode **obrigatoriamente** `pnpm lint`, `pnpm build` e `pnpm test` antes de entregar ou abrir PR. Esses comandos são mandatórios também para os agentes/automations, garantindo que o projeto continua íntegro. - **Disciplina pós-mudanças**: sempre que fizer alterações locais, rode **obrigatoriamente** `bun run lint`, `bun run build:bun` e `bun test` antes de entregar ou abrir PR. Esses comandos são mandatórios também para os agentes/automations, garantindo que o projeto continua íntegro.
- **Deploy**: pipeline `ci-cd-web-desktop.yml` (runner self-hosted). Build roda com pnpm 9, Node 20. Web é publicado em `/home/renan/apps/sistema` e o Swarm aponta `sistema_web` para essa pasta. - **Deploy**: pipeline `ci-cd-web-desktop.yml` (runner self-hosted). Build roda com Bun 1.3 + Node 20. Web é publicado em `/home/renan/apps/sistema` e o Swarm aponta `sistema_web` para essa pasta.
## Setup local (atualizado) ## Setup local (atualizado)
1. `pnpm install` 1. `bun install`
2. Copie `.env.example` → `.env.local`. 2. Copie `.env.example` → `.env.local`.
- Principais variáveis para DEV: - Principais variáveis para DEV:
``` ```
@ -40,10 +40,10 @@ Os demais colaboradores reais são provisionados via **Convites & acessos**. Cas
NEXT_PUBLIC_CONVEX_URL=http://127.0.0.1:3210 NEXT_PUBLIC_CONVEX_URL=http://127.0.0.1:3210
DATABASE_URL=file:./prisma/db.dev.sqlite DATABASE_URL=file:./prisma/db.dev.sqlite
``` ```
3. `pnpm auth:seed` 3. `bun run auth:seed`
4. (Opcional) `pnpm queues:ensure` 4. (Opcional) `bun run queues:ensure`
5. `pnpm convex:dev` 5. `bun run convex:dev:bun`
6. Em outro terminal: `pnpm dev` 6. Em outro terminal: `bun run dev:bun`
7. Acesse `http://localhost:3000` e valide login com os usuários padrão. 7. Acesse `http://localhost:3000` e valide login com os usuários padrão.
### Banco de dados ### Banco de dados
@ -53,9 +53,9 @@ Os demais colaboradores reais são provisionados via **Convites & acessos**. Cas
### Verificações antes de PR/deploy ### Verificações antes de PR/deploy
```bash ```bash
pnpm lint bun run lint
pnpm test bun test
pnpm build bun run build:bun
``` ```
## Aplicativo Desktop (Tauri) ## Aplicativo Desktop (Tauri)
@ -86,11 +86,11 @@ pnpm build
- Planejamos usar um cookie `desktop_shell` no futuro para diferenciar acessos do desktop vs navegador (não implementado). - Planejamos usar um cookie `desktop_shell` no futuro para diferenciar acessos do desktop vs navegador (não implementado).
## Qualidade e testes ## Qualidade e testes
- **Lint**: `pnpm lint` (ESLint flat config). - **Lint**: `bun run lint` (ESLint flat config).
- **Testes unitários/integrados (Vitest)**: - **Testes unitários/integrados (Vitest)**:
- Cobertura atual inclui utilitários (`tests/*.test.ts`), rotas `/api/machines/*` e `sendSmtpMail`. - Cobertura atual inclui utilitários (`tests/*.test.ts`), rotas `/api/machines/*` e `sendSmtpMail`.
- Executar `pnpm test -- --watch` apenas quando precisar de modo interativo. - Executar `bun test -- --watch` apenas quando precisar de modo interativo.
- **Build**: `pnpm build` (`next build --turbopack`). - **Build**: `bun run build:bun` (`next build --turbopack`).
- **CI**: falhas mais comuns - **CI**: falhas mais comuns
- `ERR_PNPM_OUTDATED_LOCKFILE`: mantenha `pnpm-lock.yaml` atualizado (principalmente após alterar dependências do desktop). - `ERR_PNPM_OUTDATED_LOCKFILE`: mantenha `pnpm-lock.yaml` atualizado (principalmente após alterar dependências do desktop).
- Variáveis Better Auth ausentes (`BETTER_AUTH_SECRET`): definidas no workflow (`Quality Checks`). - Variáveis Better Auth ausentes (`BETTER_AUTH_SECRET`): definidas no workflow (`Quality Checks`).

10
docs/OPERACAO-PRODUCAO.md
View file

@ -11,7 +11,7 @@ Nota: este documento foi substituído por `docs/operations.md` e permanece aqui
- Banco Prisma (SQLite) persistente via volume `sistema_db` (mapeado em `/app/data`). - Banco Prisma (SQLite) persistente via volume `sistema_db` (mapeado em `/app/data`).
- Estado do Convex persistente via volume `convex_data`. - Estado do Convex persistente via volume `convex_data`.
- Seeds prontos (Better Auth e dados demo Convex). - Seeds prontos (Better Auth e dados demo Convex).
- Seeds Better Auth automáticos: o container do web executa `pnpm auth:seed` após `prisma migrate deploy`, garantindo usuários padrão em toda inicialização (sem resetar senha existente por padrão). - Seeds Better Auth automáticos: o container do web executa `bun run auth:seed` após `prisma migrate deploy`, garantindo usuários padrão em toda inicialização (sem resetar senha existente por padrão).
### Sessão de dispositivo (Desktop/Tauri) ### Sessão de dispositivo (Desktop/Tauri)
- A rota `GET /machines/handshake?token=...&redirect=/portal|/dashboard` é pública no middleware para permitir a criação da sessão "machine" a partir do agente desktop, mesmo sem login prévio. - A rota `GET /machines/handshake?token=...&redirect=/portal|/dashboard` é pública no middleware para permitir a criação da sessão "machine" a partir do agente desktop, mesmo sem login prévio.
@ -249,7 +249,7 @@ O pipeline executa um teste rápido após o deploy do Web:
- Usuários (Better Auth): - Usuários (Better Auth):
``` ```
CONTAINER=$(docker ps --format '{{.ID}} {{.Names}}' | grep sistema_web | awk '{print $1}' | head -n1) CONTAINER=$(docker ps --format '{{.ID}} {{.Names}}' | grep sistema_web | awk '{print $1}' | head -n1)
docker exec -it "$CONTAINER" bash -lc 'cd /app && pnpm auth:seed' docker exec -it "$CONTAINER" bash -lc 'cd /app && bun run auth:seed'
``` ```
- Apenas um admin (em produção): - Apenas um admin (em produção):
``` ```
@ -259,9 +259,9 @@ docker exec -it "$CONTAINER" bash -lc 'cd /app && \
SEED_USER_PASSWORD="suaSenhaForte" \ SEED_USER_PASSWORD="suaSenhaForte" \
SEED_USER_NAME="Seu Nome" \ SEED_USER_NAME="Seu Nome" \
SEED_USER_ROLE="admin" \ SEED_USER_ROLE="admin" \
pnpm auth:seed' bun run auth:seed'
``` ```
- Filas padrão: `docker exec -it "$CONTAINER" bash -lc 'cd /app && pnpm queues:ensure'` - Filas padrão: `docker exec -it "$CONTAINER" bash -lc 'cd /app && bun run queues:ensure'`
## Atualizações (sem CI) ## Atualizações (sem CI)
- App (Next.js): - App (Next.js):
@ -337,4 +337,4 @@ Benefícios
- Scripts (package.json): - Scripts (package.json):
- `dev`: `next dev --turbopack` - `dev`: `next dev --turbopack`
- `build`: `next build --turbopack` - `build`: `next build --turbopack`
- O workflow de CI executa `pnpm build` (que já chama Turbopack via script), e a stack utiliza `pnpm start` sobre o artefato gerado. - O workflow de CI executa `bun run build:bun` (que já chama Turbopack via script), e a stack utiliza `bun run start:bun` sobre o artefato gerado.

6
docs/OPERATIONS.md
View file

@ -141,9 +141,9 @@ Depois disso, o job “Deploy Convex functions” funciona em modo não interati
## 7) Testes, Build e Lint ## 7) Testes, Build e Lint
- Local - Local
- `pnpm build` (Next + typecheck) - `bun run build:bun` (Next + typecheck)
- `pnpm lint` - `bun run lint`
- `pnpm test` - `bun test`
- CI garante build, lint e testes antes do deploy. - CI garante build, lint e testes antes do deploy.

3
scripts/deploy-from-git.sh
View file

@ -42,7 +42,7 @@ if echo "$CHANGED" | grep -q '^convex/'; then
-v "$APP_DIR":/app \ -v "$APP_DIR":/app \
-w /app \ -w /app \
--env-file .ci.env \ --env-file .ci.env \
node:20-bullseye bash -lc "corepack enable && corepack prepare pnpm@10.20.0 --activate && pnpm install --frozen-lockfile --prod=false && pnpm exec convex deploy" node:20-bullseye bash -lc "corepack enable && corepack prepare pnpm@10.20.0 --activate && pnpm install --no-frozen-lockfile --prod=false && pnpm exec convex deploy"
else else
echo "[deploy] convex/ changed but .ci.env missing; skip Convex deploy" echo "[deploy] convex/ changed but .ci.env missing; skip Convex deploy"
fi fi
@ -51,4 +51,3 @@ else
fi fi
echo "[deploy] Done." echo "[deploy] Done."