esdrasrenan b5831d833a docs: refresh agents roadmap

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

2025-10-05 03:16:03 -03:00

18 KiB

Raw Blame History

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

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

Modelagem compartilhada
- Definir esquema Prisma para Ticket, TicketEvent, User (minimo), Queue/View.
- Publicar Zod schemas/Types para uso no frontend.
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).
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

Finalizar Auth placeholder e guardas de rota (Auth.js + middleware).
Implementar camada de dados real (Prisma Client + server actions) para tickets.
Adicionar formularios de criacao/edicao de ticket com validacao (React Hook Form + Zod).
Conectar timeline/comentarios a mutations otimizadas (UI otimista + websockets futuro).
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.
Comentários de supressão: prefira @ts-expect-error com justificativa curta para módulos gerados do Convex; evite @ts-ignore.

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)

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.

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

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

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-*.

Autenticação / Sessão (placeholder)

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

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.

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.

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.
tickets.updatePriority({ ticketId, priority, actorId }) — altera prioridade e registra PRIORITY_CHANGED.
tickets.remove({ ticketId, actorId }) — remove ticket, eventos e comentários (tenta excluir anexos do storage).
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.

Progresso recente (mar/2025)

Resumo do que foi implementado desde o último marco:

Rich text (Tiptap) com SSR seguro para comentários e descrição inicial do ticket
- Componente: web/src/components/ui/rich-text-editor.tsx
- Comentários: web/src/components/tickets/ticket-comments.rich.tsx (visibilidade Público/Interno, anexos tipados)
- Novo ticket (Dialog + Página): campos de descrição usam rich text; primeiro comentário é registrado quando houver conteúdo.
Tipagem estrita (remoção de any) no front e no Convex
- Uso consistente de Id<> e Doc<> (Convex) e schemas Zod (record tipado em v4).
- Queries useQuery com "skip" quando necessário; mapeadores atualizados.
Filtros server-side
- tickets.list agora escolhe o melhor índice (por status, queueId ou tenant) e só então aplica filtros complementares.
UI do detalhe do ticket (Header)
- Prioridade como dropdown-badge translúcida: web/src/components/tickets/priority-select.tsx (nova Convex tickets.updatePriority).
- Seleção de responsável com avatar no menu.
- Ação de exclusão com modal (ícones, confirmação): web/src/components/tickets/delete-ticket-dialog.tsx (Convex tickets.remove).
Correções e DX
- Tiptap: immediatelyRender: false + setContent({ emitUpdate: false }) para evitar mismatch de hidratação.
- Validação de assunto no Dialog “Novo ticket” (trim + setError) para prevenir ZodError em runtime.

Arquivos principais tocados:

Convex: web/convex/schema.ts, web/convex/tickets.ts (novas mutations + tipagem Doc/Id).
UI: ticket-summary-header.tsx, ticket-detail-view.tsx, ticket-comments.rich.tsx, new-ticket-dialog.tsx, play-next-ticket-card.tsx.
Tipos e mapeadores: web/src/lib/schemas/ticket.ts, web/src/lib/mappers/ticket.ts.

Guia de layout/UX aplicado

Header do ticket
- Ordem: #ref • PrioritySelect (badge) • Status (badge/select) • Ações (Excluir)
- Tipografia: título forte, resumo como texto auxiliar, metadados em texto pequeno.
- Combos de Categoria/ Subcategoria exibidos como selects dependentes com salvamento automático (sem botões dedicados).
Comentários
- Composer com rich text + Dropzone; seletor de visibilidade.
- Lista com avatar, nome, carimbo relativo e conteúdo rich text.
Prioridades (labels)
- LOW (cinza), MEDIUM (azul), HIGH (âmbar), URGENT (vermelho) — badge translúcida no trigger do select.

Próximos passos sugeridos (UI/Funcionais)

Curto prazo (incremental):

Transformar Status em dropdown-badge (mesmo padrão de Prioridade).
Estados vazios com Empty (ícone, título, descrição, CTA) na lista de comentários e tabela.
Edição inline no header (Assunto/Resumo) com botões Reset/Salvar (mutations dedicadas).
Polir cards (bordas/padding/sombra) nas telas Play/Tickets para padronizar com Header/Conversa.

Médio prazo:

Combobox (command) para responsável com busca.
Paginação/ordenção server-side em tickets.list.
Unificar mensagens de timeline e payloads (sempre actorName/actorAvatar).
Testes Vitest para mapeadores e smoke tests básicos das páginas.

Como validar manualmente

Rich text: comentar em /tickets/[id] com formatação, anexos e alternando visibilidade.
Prioridade: alterar no cabeçalho; observar evento de timeline e toasts.
Exclusão: acionar modal no cabeçalho e confirmar; conferir redirecionamento para /tickets.
Novo ticket: usar Dialog; assunto com menos de 3 chars deve bloquear submit com erro no campo.

Atualizações recentes (abr/2025)

Resumo do que foi integrado nesta rodada para o núcleo de tickets e UX:

Header do ticket
- Status como dropdown‑badge (padrão visual alinhado às badges existentes).
- Edição inline de Assunto/Resumo com Cancelar/Salvar e toasts.
- Ação de Play/Pause (toggle de atendimento) com eventos WORK_STARTED/WORK_PAUSED na timeline.
- Layout dos campos reorganizado: labels acima e controles abaixo (evita redundância do valor + dropdown lado a lado).
Tabela e comentários
- Empty states padronizados com Empty + CTA de novo ticket.
Notificações
- Toaster centralizado no rodapé (bottom‑center) com estilo consistente.
Título do app
- Atualizado para “Sistema de chamados”.

Backend Convex

ickets.updateSubject e ickets.updateSummary adicionadas para edição do cabeçalho.
ickets.toggleWork adicionada; campo opcional working no schema de ickets.

Próximos passos sugeridos

Status dropdown‑badge também na tabela (edição rápida opcional com confirmação).
Combobox (command) para busca de responsável no select.
Tokens de cor: manter badges padrão do design atual; quando migração completa para paleta Rever estiver definida, aplicar via globals.css para herdar em todos os componentes.
Testes (Vitest): adicionar casos de mappers e smoke tests de páginas.

Observações de codificação

Evitar any; usar TicketStatus/TicketPriority e Id<>/Doc<> do Convex.
Não retornar Date do Convex; sempre epoch (number) e converter via mappers Zod.

Atualizações recentes (out/2025)

Cabeçalho de ticket agora persiste automaticamente mudanças de categoria/subcategoria, mostrando toasts e bloqueando os selects enquanto a mutação é processada.
Normalização de nomes de fila/time aplicada também ao retorno de tickets.playNext, garantindo rótulos "Chamados"/"Laboratório" em todos os fluxos.
ESLint ignora convex/_generated/** e supressões migradas para @ts-expect-error com justificativa explícita.
Mutação tickets.remove não requer mais actorId; o diálogo de exclusão apenas envia ticketId.

Atualizações recentes (nov/2025)

Dialog de novo ticket redesenhado: duas colunas com botão “Criar” no cabeçalho, dropzone mais compacta, categorias primária/secundária empilhadas e rótulos explícitos.
Validação do assunto relaxada para evitar ZodError prematuro; verificação manual permanece na submissão.
Placeholder cinza claro "Escreva um comentário..." aplicado ao editor Tiptap e seção renomeada para “Comentários”.
Linhas da tabela de tickets agora são totalmente clicáveis (mouse e teclado), reforçando acessibilidade e atalho de navegação.
Toasts e layouts refinados para manter consistência entre criação, listagem e detalhe dos tickets.

Próximos passos estratégicos

Produto / Experiência

Unificar revisão visual do modal de novo ticket com microinterações (estado de salvamento, validações inline).
Implementar filtros salváveis e quick actions na listagem (ex.: alterar status diretamente).
Exibir indicadores de anexos na tabela e nos cartões de “tickets recentes”.

Técnica

Corrigir configuração do postcss.config.mjs (plugin inválido impede execução do Vitest) e restaurar cobertura de testes automatizados.
Formalizar camada de autenticação (Auth.js ou Clerk) com refresh de sessão e proteção de rotas no Convex (auth.getUserIdentity).
Mapear RBAC inicial (admin/agente/visualização) e refletir nas mutations do Convex.
Configurar ambientes staging/production do Convex com variáveis (.env) versionadas via doppler/1Password.
Automatizar lint/test/build no CI (GitHub Actions) e bloquear merge sem execução.

Administrativa / Operacional

Inventariar acessos: quem possui permissão no Convex, GitHub e futuros serviços (Redis, email, armazenamento S3?).
Criar checklists de onboarding/offboarding de agentes (criação de usuário, associação a filas, provisionamento de avatar).
Definir plano de capacidade para armazenamento de anexos (quotas por tenant, política de retenção) e alertas.
Preparar mock de integrações externas (e-mail entrante, WhatsApp) para futuras etapas.
Documentar fluxo de suporte interno (quem revisa PRs, janelas de deploy, rollback).

Manter este arquivo atualizado ao concluir cada item estratégico ou quando surgirem novas dependências administrativas.

18 KiB Raw Blame History Unescape Escape