sistema-de-chamados/README.md

Sistema de Chamados

Aplicacao Next.js 16 (App Router) com React 19, Convex e Better Auth para gestao de tickets da Rever. A stack ainda inclui Prisma 7 (PostgreSQL), Tailwind e Turbopack como bundler padrao (webpack permanece disponivel como fallback). Todo o codigo-fonte fica na raiz do monorepo seguindo as convencoes do App Router.

Requisitos

• Bun >= 1.3 (recomendado 1.3.1). Após instalar via script oficial, adicione export PATH="$HOME/.bun/bin:$PATH" ao seu shell (ex.: .bashrc) para ter bun disponível globalmente.
• Node.js >= 20 (necessário para ferramentas auxiliares como Prisma CLI e Next.js em modo fallback).
• CLI do Convex (bunx convex dev instalará automaticamente no primeiro uso, se ainda não estiver presente).
• GitHub Actions/autodeploy dependem dessas versões e do CLI do Convex disponível; use npx convex --help para confirmar.

Configuração rápida

1. Instale as dependências:

   bun install
   

2. Ajuste o arquivo .env (ou crie a partir de .env.example) e confirme os valores de:
   • NEXT_PUBLIC_CONVEX_URL (gerado pelo Convex Dev)
   • BETTER_AUTH_SECRET, BETTER_AUTH_URL, DATABASE_URL (PostgreSQL, ex: postgresql://postgres:dev@localhost:5432/sistema_chamados)
3. Aplique as migrações e gere o client Prisma:

   bunx prisma migrate deploy
   bun run prisma:generate
   

4. Popule usuários padrão do Better Auth:

   bun run auth:seed
   

   Sempre que trocar de máquina ou quiser “zerar” o ambiente local, basta repetir os passos 3 e 4 com a mesma DATABASE_URL.

Resetar rapidamente o ambiente local

1. Suba um PostgreSQL local (Docker recomendado):

   docker run -d --name postgres-dev -p 5432:5432 -e POSTGRES_PASSWORD=dev -e POSTGRES_DB=sistema_chamados postgres:18
   

2. Aplique as migracoes:

   bunx prisma migrate deploy
   

3. Recrie/garanta as contas padrao de login:

   bun run auth:seed
   

4. Suba o servidor normalmente com bun run dev.

Subir serviços locais

• (Opcional) Para re-sincronizar manualmente as filas padrão, execute bun run queues:ensure.
• Em um terminal, rode o backend em tempo real do Convex com bun run convex:dev:bun (ou bun run convex:dev para o runtime Node).
• Em outro terminal, suba o frontend Next.js (Turbopack) com bun run dev:bun (bun run dev:webpack serve como fallback).
• Com o Convex rodando, acesse http://localhost:3000/dev/seed uma vez para popular dados de demonstração (tickets, usuários, comentários).

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.

Documentação

• Índice de docs: docs/README.md
• Operações (produção): docs/OPERATIONS.md (versão EN) e docs/OPERACAO-PRODUCAO.md (PT-BR)
• Guia de DEV: docs/DEV.md
• Testes automatizados (Vitest/Playwright): docs/testes-vitest.md
• Stack Swarm: stack.yml (roteado por Traefik, rede traefik_public).

Variáveis de ambiente

• Exemplo na raiz: .env.example — copie para .env e preencha segredos.
• App Desktop: apps/desktop/.env.example — copie para apps/desktop/.env e ajuste VITE_APP_URL.
• Nunca faça commit de arquivos .env com valores reais (já ignorados em .gitignore).

Guia de DEV (Prisma, Auth e Desktop/Tauri)

Para fluxos detalhados de desenvolvimento — banco de dados local (PostgreSQL/Prisma), seed do Better Auth, ajustes do Prisma CLI no DEV e build do Desktop (Tauri) — consulte docs/DEV.md.

Scripts úteis

• 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 (bun run convex:dev mantém o fluxo antigo usando Node).
• bun run build:bun / bun run start:bun — build e serve com Bun usando Turbopack (padrão atual).
• bun run dev:webpack — fallback do Next.js em modo desenvolvimento (webpack).
• 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 run build — executa next build --turbopack (runtime Node, caso prefira evitar o --bun).
• bun run build:webpack — executa next build --webpack como fallback oficial.
• bun run auth:seed — atualiza/cria contas padrao do Better Auth (credenciais em agents.md).
• bunx prisma migrate deploy — aplica migracoes ao banco PostgreSQL.
• bun run convex:dev — roda o Convex em modo desenvolvimento com Node, gerando tipos em convex/_generated.

Transferir dispositivo entre colaboradores

Quando uma dispositivo trocar de responsável:

1. Abra Admin > Dispositivos, selecione o equipamento e clique em Resetar agente.
2. No equipamento, execute o reset local do agente (rever-agent reset ou reinstale o serviço) e reprovisione com o código da empresa.
3. Após o agente gerar um novo token, associe a dispositivo ao novo colaborador no painel.

Sem o reset de agente, o Convex reaproveita o token anterior e o inventário continua vinculado ao usuário antigo.

Estrutura principal

• app/ dentro de src/ — rotas e layouts do Next.js (App Router).
• components/ — componentes reutilizáveis (UI, formulários, layouts).
• convex/ — queries, mutations e seeds do Convex.
• prisma/ — schema e migracoes do Prisma (PostgreSQL).
• scripts/ — utilitários em Node para sincronização e seeds adicionais.
• agents.md — guia operacional e contexto funcional (em PT-BR).
• PROXIMOS_PASSOS.md — backlog de melhorias futuras.

Credenciais de demonstração

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

Consulte PROXIMOS_PASSOS.md para acompanhar o backlog funcional e o progresso das iniciativas planejadas.

Executar com Bun

• bun install é o fluxo padrão (o arquivo bun.lock deve ser versionado; use bun install --frozen-lockfile em CI).
• bun run dev:bun, bun run convex:dev:bun, bun run build:bun e bun run start:bun já estão configurados; internamente executam bun run --bun <script> para usar o runtime do Bun sem abrir mão dos scripts existentes. O cross-env garante os valores esperados de NODE_ENV (development/production).
• O bundler padrão é o Turbopack; se precisar comparar/debugar com webpack, use bun run build:webpack.
• bun test utiliza o test runner do Bun. O teste de snapshot de screenshot é automaticamente ignorado quando o matcher não está disponível; testes de navegador completos continuam via bun run test:browser (Vitest + Playwright).

Diagnóstico de sessão da dispositivo (Desktop)

• Quando o portal for aberto via app desktop, use a página https://seu-app/portal/debug para validar cookies e contexto:
  • /api/auth/get-session deve idealmente mostrar user.role = "machine" (em alguns ambientes WebView pode retornar null, o que não é bloqueante).
  • /api/machines/session deve retornar 200 com assignedUserId/assignedUserEmail.
• O frontend agora preenche machineContext mesmo que get-session retorne null, e deriva o papel efetivo a partir desse contexto.
• Se machines/session retornar 401/403, revise CORS/credenciais e o fluxo de handshake documentados em docs/OPERACAO-PRODUCAO.md.