sistema-de-chamados/agents.md

Plano de Desenvolvimento - Sistema de Chamados

Meta imediata

Construir o nucleo de tickets compartilhado entre web e desktop (Tauri), garantindo base solida para canais, SLAs e automacoes futuras.

Fase A - Fundamentos da plataforma

1. Scaffold e DX
   • Criar projeto Next.js (App Router) com Typescript, ESLint, Tailwind, shadcn/ui.
   • Configurar alias de paths, lint/prettier opinativo.
   • Ajustar globals.css para tokens de cor/tipografia conforme layout base.
2. Design system inicial
   • Importar componentes dashboard-01 e sidebar-01 via shadcn.
   • Ajustar paleta (tons de cinza + destaque primario) e tipografia (Inter/Manrope).
   • Implementar layout shell (sidebar + header) reutilizavel.
3. Autenticacao placeholder
   • Configurar stub de sessao (cookie + middleware) para navegacao protegida.

Status da fase

• OK Scaffold Next.js + Tailwind + shadcn/ui criado em web/.
• OK Layout base atualizado (sidebar, header, cards, grafico) com identidade da aplicacao.
• OK Auth placeholder via cookie + middleware e bootstrap de usuario no Convex.

Fase B - Nucleo de tickets

1. Modelagem compartilhada
   • Definir esquema Prisma para Ticket, TicketEvent, User (minimo), Queue/View.
   • Publicar Zod schemas/Types para uso no frontend.
2. Fluxo principal
   • Pagina tickets com tabela (TanStack) suportando filtros basicos.
   • Pagina de ticket com timeline de eventos/comentarios (dados mockados).
   • Implementar modo play preliminar (simula proxima tarefa da fila).
3. Mutations
   • Formulario de criacao/edicao com validacao.
   • Comentarios publico/privado (UX + componentes).

Status parcial

• OK prisma/schema.prisma criado com entidades centrais (User, Team, Ticket, Comment, Event, SLA).
• OK Schemas Zod e mocks compartilhados em src/lib/schemas e src/lib/mocks.
• OK Paginas /tickets, /tickets/[id] e /play prontas com componentes dedicados (filtros, tabela, timeline, modo play).
• OK Integração com backend Convex (consultas/mutações + file storage). Prisma mantido apenas como referência.

Fase C - Servicos complementares (posterior)

• SLAs (BullMQ + Redis), notificacoes, ingest de e-mail, portal cliente, etc.

Backlog imediato

• Scaffold Next.js + Tailwind + shadcn/ui.
• Ajustar layout shell (dashboard + sidebar) com tema solicitado.
• Criar modulos base de dominio (schemas Prisma/Zod) ainda com dados mockados.
• Preparar estrutura de paginas: /tickets, /tickets/[id], /play.
• Implementar Auth placeholder (cookie + middleware).
• Conectar APIs/mutations reais (Convex) e sincronizar tipos no frontend.

Proximas entregas sugeridas

1. Finalizar Auth placeholder e guardas de rota (Auth.js + middleware).
2. Implementar camada de dados real (Prisma Client + server actions) para tickets.
3. Adicionar formularios de criacao/edicao de ticket com validacao (React Hook Form + Zod).
4. Conectar timeline/comentarios a mutations otimizadas (UI otimista + websockets futuro).
5. Preparar testes basicos (unit + e2e mockados) e pipeline de CI inicial.

Acompanhamento

Atualizar este arquivo a cada marco relevante (setup concluido, nucleo funcional, etc.).

---

Guia do Projeto (para agentes e contribuidores)

Este repositório foi atualizado para usar Convex como backend em tempo real para o núcleo de tickets. Abaixo, um guia prático conforme o padrão de AGENTS.md para orientar contribuições futuras.

Decisões técnicas atuais

• Backend: Convex (funções + banco + storage) em web/convex/.
  • Esquema: web/convex/schema.ts.
  • Tickets API: web/convex/tickets.ts (list/getById/create/addComment/updateStatus/playNext).
  • Upload de arquivos: web/convex/files.ts (Convex Storage).
  • Filas: web/convex/queues.ts (resumo por fila).
  • Seed/bootstrap: web/convex/seed.ts, web/convex/bootstrap.ts.
• Auth placeholder: cookie + middleware
  • Login: web/src/app/login/page.tsx
  • Middleware: web/middleware.ts
  • Provider: web/src/lib/auth-client.tsx (garante usuário no Convex)
• Frontend (Next.js + shadcn/ui)
  • Páginas principais: /tickets, /tickets/[id], /tickets/new, /play.
  • UI ligada ao Convex com convex/react.
  • Toasts: sonner via Toaster em web/src/app/layout.tsx.
• Mapeamento/validação de dados
  • Convex retorna datas como number (epoch). A UI usa Date.
  • Sempre converter/validar via Zod em web/src/lib/mappers/ticket.ts.
  • Não retornar Date a partir de funções do Convex.
• Prisma: mantido apenas como referência de domínio (não é fonte de dados ativa).

Como rodar

• Pré‑requisitos: Node LTS + pnpm.
• Passos:
  • cd web && pnpm i
  • pnpm convex:dev (mantém gerando tipos e rodando backend dev)
  • Criar .env.local com NEXT_PUBLIC_CONVEX_URL=<url exibida pelo convex dev>
  • Em outro terminal: pnpm dev
  • Login em /login; seed opcional em /dev/seed.

Convenções de código

• Não use Date em payloads do Convex; use number (epoch ms).
• Normalize dados no front via mappers Zod antes de renderizar.
• UI com shadcn/ui; priorize componentes existentes e consistência visual.
• Labels e mensagens em PT‑BR (status, timeline, toasts, etc.).
• Atualizações otimistas com rollback em erro + toasts de feedback.

Estrutura útil

• web/convex/* — API backend Convex.
• web/src/lib/mappers/* — Conversores server→UI com Zod.
• web/src/components/tickets/* — Tabela, filtros, detalhe, timeline, comentários, play.

Scripts (pnpm)

• pnpm convex:dev — Convex (dev + geração de tipos)
• pnpm dev — Next.js (App Router)
• pnpm build / pnpm start — build/produção

Backlog imediato (próximos passos)

• Form “Novo ticket” em Dialog shadcn + React Hook Form + Zod + toasts.
• Atribuição/transferência de fila no detalhe (selects com update otimista).
• Melhorias de layout adicionais no painel “Detalhes” (quebras, largura responsiva) e unificação de textos PT‑BR.
• Testes unitários dos mapeadores com Vitest.

Checklist de PRs

• Funções Convex retornam apenas tipos suportados (sem Date).
• Dados validados/convertidos via Zod mappers antes da UI.
• Textos/labels em PT‑BR.
• Eventos de UI com feedback (toast) e rollback em erro.
• Documentação atualizada se houver mudanças em fluxo/env.