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

Estado atual

• Autenticação Better Auth com guardas client-side (AuthGuard) bloqueando rotas protegidas.
• Menu de usuário no rodapé da sidebar com link para /settings e logout confiável.
• 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.
• Portal do cliente restringe visualização e criação ao próprio requester; clientes não atribuem responsáveis.
• Relatórios e dashboards utilizam AppShell, garantindo header/sidebar consistentes.

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.

Clientes

• Autenticam com cliente.demo@sistema.dev.
• Abrem tickets para si mesmos a partir do portal com assunto/descrição obrigatórios.
• Não visualizam campo de responsável nem tickets de outros usuários.

Próximos passos sugeridos

1. Finalizar redefinição de senha/auditoria de convites Better Auth.
2. Expandir cobertura de testes (vitest) para guardas de autenticação e criação de tickets.
3. Implementar ações rápidas (status/fila) diretamente na listagem de tickets.
4. Definir limites e monitoramento para anexos por tenant.

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.