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.

---

Próximas Entregas (Roadmap detalhado)

1. UX/Visual (shadcn/ui)

• Padronizar cartões em todas as telas (Play, Visualizações) com o mesmo padrão aplicado em Conversa/Detalhes/Timeline (bordas, sombra, paddings).
• Aplicar microtipografia consistente: headings H1/H2, tracking, tamanhos, cores em PT‑BR.
• Skeletons de carregamento nos principais painéis (lista de tickets, recentes, play next).
• Melhorar tabela: estados hover/focus, ícones de canal, largura de colunas previsível e truncamento.

2. Comentários e anexos

• Dropzone também no “Novo ticket” (já implementado) com registro de comentário inicial e anexos.
• Grid de anexos com miniaturas e legenda; manter atributo download com o nome original.
• Preview em modal para imagens (feito) e suporte a múltiplas linhas no grid.
• Botão para copiar link de arquivo (futuro, usar URL do storage).

3. Timeline e eventos

• Mensagens amigáveis em PT‑BR (feito para CREATED/STATUS/ASSIGNEE/QUEUE).
• Incluir sempre actorName/actorAvatar no payload; evitar JSON cru na UI.
• Exibir avatar e nome do ator nas entradas (parcialmente feito).

4. Dados e camada Convex

• Sempre retornar datas como number (epoch) e converter no front via mappers Zod.
• Padronizar import do Convex com @/convex/_generated/api (alias criado).
• Evitar useQuery com args vazios — proteger chamadas (gates) e, quando necessário, fallback de mock para IDs ticket-*.

5. Autenticação / Sessão (placeholder)

• Cookie demoUser e bootstrap de usuário no Convex (feito). Trocar por Auth.js/Clerk quando for o momento.

6. Testes

• Vitest configurado; adicionar casos para mapeadores (já iniciado) e smoke tests básicos de páginas.
• Não usar Date em assertions de payload — sempre comparar epoch ou instanceof Date após mapeamento.

7. Acessibilidade e internacionalização

• Labels e mensagens 100% em PT‑BR; evitar termos como QUEUE_CHANGED na UI.
• Navegação por teclado em Dialogs/Selects; aria-labels em botões de ação.

8. Observabilidade (posterior)

• Logs de evento estruturados no Convex; traces simples no client para ações críticas.

---

Endpoints Convex (resumo)

• tickets.list({ tenantId, status?, priority?, channel?, queueId?, search?, limit? })
• tickets.getById({ tenantId, id })
• tickets.create({ tenantId, subject, summary?, priority, channel, queueId?, requesterId })
• tickets.addComment({ ticketId, authorId, visibility, body, attachments?[] })
• tickets.updateStatus({ ticketId, status, actorId }) — gera evento com toLabel e actorName.
• tickets.changeAssignee({ ticketId, assigneeId, actorId }) — gera evento com assigneeName.
• tickets.changeQueue({ ticketId, queueId, actorId }) — gera evento com queueName.
• tickets.playNext({ tenantId, queueId?, agentId }) — atribui ticket e registra evento.
• queues.summary({ tenantId })
• files.generateUploadUrl() — usar via useAction.
• users.ensureUser({ tenantId, email, name, avatarUrl?, role?, teams? })

Observações:

• Não retornar Date nas funções Convex; usar number e converter na UI com os mappers em src/lib/mappers.
• Evitar passar {} para useQuery — args devem estar definidos ou a query não deve ser invocada.

---

Padrões de Código

• UI: shadcn/ui (Field, Dialog, Select, Badge, Table, Spinner) + Tailwind.
• Dados: Zod para validação; mappers para converter server→UI (epoch→Date, null→undefined).
• Texto: PT‑BR em labels, toasts e timeline.
• UX: updates otimistas + toasts (status, assignee, fila, comentários).
• Imports do Convex: sempre @/convex/_generated/api.

---

Como abrir PR

• Crie uma branch descritiva (ex.: feat/tickets-attachments-grid).
• Preencha a descrição com: contexto, mudanças, como testar (pnpm scripts), screenshots quando útil.
• Checklist:
  • Sem Date no retorno Convex.
  • Labels PT‑BR.
  • Skeleton/Loading onde couber.
  • Mappers atualizados se tocar em payloads.
  • AGENTS.md atualizado se houver mudança de padrões.