sistema-de-chamados/agents.md

Plano de Desenvolvimento — Sistema de Chamados

Diretriz máxima: todas as respostas, comunicações e documentações devem ser redigidas em português brasileiro.

Contato principal

• Esdras Renan — monkeyesdras@gmail.com

Credenciais padrão (Better Auth)

• Administrador: admin@sistema.dev / admin123
• Agente Demo: agente.demo@sistema.dev / agent123
• Cliente Demo: cliente.demo@sistema.dev / cliente123

Execute pnpm auth:seed após configurar .env. O script atualiza as contas acima ou cria novas conforme variáveis SEED_USER_*.

Sincronização com Convex

• Usuários e tickets demo são garantidos via convex/seed.ts.
• Após iniciar pnpm convex:dev, acesse /dev/seed uma vez por ambiente local para carregar dados reais de demonstração no banco do Convex.

Setup local rápido

1. pnpm install
2. Ajuste .env (ou crie a partir do exemplo) e confirme NEXT_PUBLIC_CONVEX_URL apontando para o Convex local.
3. pnpm auth:seed
4. (Opcional) pnpm queues:ensure
5. pnpm convex:dev
6. Em outro terminal: pnpm dev

App Desktop (Agente de Máquinas)

• Código: apps/desktop (Tauri v2 + Vite).
• Padrões de URL:
  • Produção: usa https://tickets.esdrasrenan.com.br por padrão (fallback em release).
  • Desenvolvimento: use apps/desktop/.env (ver .env.example).
• Comandos úteis:
  • pnpm -C apps/desktop tauri dev — dev completo (abre WebView em 1420 + backend Rust).
  • pnpm -C apps/desktop build — build do frontend (dist).
  • pnpm -C apps/desktop tauri build — gera instaladores (bundle) por SO.
• Saída dos pacotes: apps/desktop/src-tauri/target/release/bundle/.
• Fluxo atualizado:
  1. Coleta perfil (hostname/OS/MAC/seriais/métricas).
  2. Provisiona via POST /api/machines/register com MACHINE_PROVISIONING_SECRET, solicitando o perfil de acesso (Colaborador ou Gestor) e os dados do usuário associado. O backend garante a vinculação única da máquina ao colaborador ou gestor informado.
  3. Envia heartbeats a cada 5 min para /api/machines/heartbeat com inventário básico + estendido (discos, GPUs, serviços, softwares).
  4. Abre APP_URL/machines/handshake?token=...&redirect=... para autenticar a sessão: colaboradores são direcionados ao portal (/portal), gestores ao painel completo (/dashboard). A rota de handshake é pública no middleware para permitir a criação da sessão sem login prévio.
• Segurança: token salvo no cofre do SO (Keyring). Store guarda apenas metadados não sensíveis.
• Endpoint extra: POST /api/machines/inventory (atualiza inventário por token ou provisioningSecret).
• Atualizações automáticas: o plugin @tauri-apps/plugin-updater verifica latest.json nos releases do GitHub. Publicar uma nova release com manifestos atualiza os clientes sem reinstalação manual.
• Ajustes administrativos: em Admin ▸ Máquinas é possível vincular ou alterar o perfil (colaborador/gestor) e e-mail associado através do botão “Ajustar acesso”.

Sessão "machine" no frontend

• Ao autenticar como machine, o frontend consulta /api/machines/session e popula machineContext (assignedUserId, email, name, persona).
• Mesmo quando /api/auth/get-session retorna null na WebView, o portal passa a derivar a role a partir do machineContext e utiliza assignedUserId como viewerId — assim o colaborador consegue abrir chamados via desktop.
• Na UI interna, o menu do usuário (canto inferior do sidebar) oculta o botão "Encerrar sessão" quando a sessão é de máquina (ou quando machineContext está presente).
• Página de diagnóstico: /portal/debug exibe o status/JSON de get-session e machines/session com os mesmos cookies da aba.

Sinalizador de desktop (opcional – futuro)

• Podemos adicionar um cookie (ex.: desktop_shell=1) no handshake para diferenciar acessos do app desktop de acessos web convencionais.
• Esse cookie permitiria customizações de UI específicas (ex.: ocultar "Sair" apenas no desktop) sem depender de heurísticas do ambiente.

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.
• Smoke de provisionamento (/api/machines/register + heartbeat) roda só se RUN_MACHINE_SMOKE=true (default: desativado para evitar quedas em caso de instabilidade).
• 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.
3. Clone o projeto: git clone git@github.com:esdrasrenan/sistema-de-chamados.git e entre na pasta.
4. Copie o arquivo .env já configurado do computador atual para a raiz do repositório (nunca faça commit desse arquivo).
5. Instale as dependências com pnpm install.
6. Gere os clientes locais necessários: pnpm prisma:generate.
7. Semeie as credenciais Better Auth: pnpm auth:seed.
8. Se for trabalhar com filas padrão, execute pnpm queues:ensure.
9. Inicie o backend Convex em um terminal (pnpm convex:dev) e, em outro, suba a aplicação Next.js (pnpm dev).
10. Acesse http://localhost:3000 e teste login com os usuários padrão listados acima antes de continuar o desenvolvimento.

Estado atual

• Autenticação Better Auth com guardas client-side (AuthGuard) bloqueando rotas protegidas.
• Menu de usuário (rodapé da sidebar) concentra acesso às configurações ("Meu perfil" → /settings) e logout. Removemos o item redundante "Configurações" do menu lateral.
• Formulários de novo ticket (dialog, página e portal) com seleção de responsável, placeholders claros e validação obrigatória de assunto/descrição/categorias.
• Relatórios, dashboards e páginas administrativas utilizam AppShell, garantindo header/sidebar consistentes.
  • Use SiteHeader no header do AppShell para título/lead e ações.
  • O conteúdo deve ficar dentro de <div className="mx-auto w-full max-w-6xl px-4 pb-12 lg:px-6">.
  • Persistir filtro global de empresa com usePersistentCompanyFilter (localStorage) para manter consistência entre relatórios.

Entregas recentes

• Exportações CSV (Backlog, Canais, CSAT, SLA e Horas por cliente) com parâmetros de período.
• PDF do ticket (via pdfkit standalone), com espaçamento e traduções PT-BR.
• Play interno/externo com somatório por tipo por ticket e relatório por cliente.
• Admin > Empresas & clientes: cadastro/edição, Cliente avulso? e Horas contratadas/mês.
• Admin > Usuários: vincular colaborador à empresa.
• Dashboard: cards de filas (Chamados/Laboratório/Visitas) e indicadores principais.
• Lista de tickets: filtro por Empresa, coluna Empresa, alinhamento vertical e melhor espaçamento entre colunas.

Entregas recentes relevantes

• Sessão de máquina confiável no desktop: CORS com credenciais habilitado, aplicação de múltiplos cookies via NextResponse.cookies.set(...), fallback no portal para usar machineContext quando get-session for null.
• Portal (cliente): esconder Fila/Prioridade, listar apenas tickets do solicitante, editor rico + anexos nos comentários, botão “Sair” oculto no desktop.
• Convex: permissão de comentário para solicitante corrigida (primeiro comentário público após criação do ticket).
• Desktop (Windows): fallback para preencher extended.windows.osInfo via sysinfo quando o PowerShell retornar vazio.
• Correção do redirecionamento após logout evitando retorno imediato ao dashboard.
• Validações manuais dos formulários de rich text para eliminar ZodError durante edição.
• Dropdown de responsáveis na criação de tickets com preenchimento automático pelo autor e evento inicial de comentário.
• Indicadores visuais de campos obrigatórios e botão "Novo ticket" funcional no cabeçalho do detalhe.
• Seeds (Better Auth e Convex) ampliados para incluir agente e cliente de teste.

Fluxos suportados

Equipe interna (admin/agent/collaborator)

• Criar tickets com categorias, responsável inicial e anexos.
• Abrir novos tickets diretamente a partir do detalhe via dialog reutilizável.
• Acessar /settings para ajustes pessoais e efetuar logout pelo menu.

Papéis

• Papéis válidos: admin, manager, agent, collaborator (papel customer removido).
• Colaboradores acessam o portal (/portal) e visualizam apenas os próprios tickets; gestores herdam a visão completa da empresa mesmo quando autenticados via agente desktop.
• Gestores veem os tickets da própria empresa e só podem registrar comentários públicos.

Próximos passos sugeridos

1. Disparo de e-mails automáticos quando uso de horas ≥ 90% do contratado.
2. Ações rápidas (status/fila) diretamente na listagem de tickets.
3. Limites e monitoramento para anexos por tenant.
4. PDF do ticket com layout idêntico ao app (logo/cores/fontes).

Referências de endpoints úteis

• Backlog CSV: /api/reports/backlog.csv?range=7d|30d|90d[&companyId=...]
• Canais CSV: /api/reports/tickets-by-channel.csv?range=7d|30d|90d[&companyId=...]
• CSAT CSV: /api/reports/csat.csv?range=7d|30d|90d
• SLA CSV: /api/reports/sla.csv
• Horas por cliente CSV: /api/reports/hours-by-client.csv?range=7d|30d|90d

Referências de inventário de máquinas

• UI (Admin > Máquinas): filtros, pesquisa, inventário enriquecido (GPUs, discos, serviços) e exclusão de máquina — ver docs/admin-inventory-ui.md
• Endpoints do agente:
  • POST /api/machines/register
  • POST /api/machines/heartbeat
  • POST /api/machines/inventory

Rotina antes de abrir PR

• pnpm lint
• pnpm build --turbopack
• pnpm exec vitest run
• Revisar toasts/labels em PT-BR e ausência de segredos no diff.

Convenções

• Convex deve retornar apenas tipos primitivos; converta datas via mappers em src/lib/mappers.
• Manter textos em PT-BR e evitar comentários supérfluos no código.
• Reutilizar componentes shadcn existentes e seguir o estilo do arquivo editado.
• Validações client-side críticas devem sinalizar erros inline e exibir toast.

Estrutura útil

• convex/ — queries e mutations (ex.: tickets.ts, users.ts).
• src/components/tickets/ — UI interna (dialog, listas, header, timeline).
• src/components/portal/ — formulários e fluxos do portal do cliente.
• scripts/ — seeds Better Auth e utilidades.
• src/components/auth/auth-guard.tsx — proteção de rotas client-side.

Histórico resumido

• Scaffold Next.js + Turbopack configurado com Better Auth e Convex.
• Portal do cliente entregue com isolamento por viewerId.
• Fluxo de convites e painel administrativo operacionais.
• Iteração atual focada em UX de criação de tickets, consistência de layout e guardas de sessão.