sistema-de-chamados/agents.md

Plano de Desenvolvimento — Sistema de Chamados

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 --dir web auth:seed após configurar .env.local. 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 web/convex/seed.ts.
• Com pnpm convex:dev rodando, acesse /dev/seed uma vez para popular dados quando necessário.

Setup local rápido

1. cd web && pnpm install
2. cp .env.example .env.local e ajuste NEXT_PUBLIC_CONVEX_URL apontando para o servidor Convex local.
3. pnpm --dir web auth:seed
4. pnpm --dir web convex:dev
5. Em outro terminal: pnpm --dir web 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 --dir "web" lint
• pnpm --dir "web" exec vitest run
• Revisar toasts/labels em PT-BR e ausência de segredos no diff.
• Adicionar coautor factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> quando aplicável.

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

• web/convex/ — queries e mutations (ex.: tickets.ts, users.ts).
• web/src/components/tickets/ — UI interna (dialog, listas, header, timeline).
• web/src/components/portal/ — formulários e fluxos do portal do cliente.
• web/scripts/ — seeds Better Auth e utilidades.
• web/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.