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

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

• 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).
• 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

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.