feat: timeline 'Comentário adicionado' com autor; skeletons na página de detalhe; skeleton nas filas; alias de Convex já padronizado; mutation addComment inclui authorName/avatar

agents.md

@@ -124,3 +124,83 @@ Este repositório foi atualizado para usar Convex como backend em tempo real par
 - [ ] 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.