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.

web/convex/tickets.ts

@@ -256,10 +256,11 @@ export const addComment = mutation({
       createdAt: now,
       updatedAt: now,
     });
+    const author = await ctx.db.get(args.authorId);
     await ctx.db.insert("ticketEvents", {
       ticketId: args.ticketId,
       type: "COMMENT_ADDED",
-      payload: { authorId: args.authorId },
+      payload: { authorId: args.authorId, authorName: author?.name, authorAvatar: author?.avatarUrl },
       createdAt: now,
     });
     // bump ticket updatedAt

web/src/components/tickets/ticket-detail-view.tsx

@@ -7,6 +7,9 @@ import { api } from "@/convex/_generated/api";
 import { DEFAULT_TENANT_ID } from "@/lib/constants";
 import { mapTicketWithDetailsFromServer } from "@/lib/mappers/ticket";
 import { getTicketById } from "@/lib/mocks/tickets";
+import { Card, CardContent } from "@/components/ui/card";
+import { Separator } from "@/components/ui/separator";
+import { Skeleton } from "@/components/ui/skeleton";
 import { TicketComments } from "@/components/tickets/ticket-comments";
 import { TicketDetailsPanel } from "@/components/tickets/ticket-details-panel";
 import { TicketSummaryHeader } from "@/components/tickets/ticket-summary-header";
@@ -21,7 +24,34 @@ export function TicketDetailView({ id }: { id: string }) {
   } else if (isMockId) {
     ticket = getTicketById(id) ?? null;
   }
-  if (!ticket) return <div className="px-4 py-8 text-sm text-muted-foreground">Carregando ticket...</div>;
+  if (!ticket) return (
+    <div className="flex flex-col gap-6 px-4 lg:px-6">
+      <Card className="rounded-xl border bg-card shadow-sm">
+        <CardContent className="space-y-3 p-6">
+          <div className="flex items-center gap-2"><Skeleton className="h-5 w-24" /><Skeleton className="h-5 w-20" /></div>
+          <Skeleton className="h-7 w-2/3" />
+          <Skeleton className="h-4 w-1/2" />
+        </CardContent>
+      </Card>
+      <div className="grid gap-6 lg:grid-cols-[2fr_1fr]">
+        <Card className="rounded-xl border bg-card shadow-sm">
+          <CardContent className="space-y-4 p-6">
+            {Array.from({ length: 3 }).map((_, i) => (
+              <div key={i} className="space-y-2">
+                <div className="flex items-center gap-2"><Skeleton className="h-4 w-28" /><Skeleton className="h-3 w-24" /></div>
+                <Skeleton className="h-16 w-full" />
+              </div>
+            ))}
+          </CardContent>
+        </Card>
+        <Card className="rounded-xl border bg-card shadow-sm">
+          <CardContent className="space-y-3 p-6">
+            {Array.from({ length: 5 }).map((_, i) => (<Skeleton key={i} className="h-3 w-full" />))}
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  );
   return (
     <div className="flex flex-col gap-6 px-4 lg:px-6">
       <TicketSummaryHeader ticket={ticket as any} />

web/src/components/tickets/ticket-queue-summary.tsx

@@ -14,8 +14,20 @@ interface TicketQueueSummaryProps {
 }
 
 export function TicketQueueSummaryCards({ queues }: TicketQueueSummaryProps) {
-  const fromServer = useQuery(api.queues.summary, { tenantId: DEFAULT_TENANT_ID }) ?? []
-  const data: TicketQueueSummary[] = (queues ?? fromServer) as any
+  const fromServer = useQuery(api.queues.summary, { tenantId: DEFAULT_TENANT_ID })
+  const data: TicketQueueSummary[] = (queues ?? fromServer ?? []) as any
+  if (!queues && fromServer === undefined) {
+    return (
+      <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-3">
+        {Array.from({ length: 3 }).map((_, i) => (
+          <div key={i} className="rounded-xl border bg-card p-4">
+            <div className="h-4 w-24 animate-pulse rounded bg-muted" />
+            <div className="mt-4 h-3 w-full animate-pulse rounded bg-muted" />
+          </div>
+        ))}
+      </div>
+    )
+  }
   return (
     <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-3">
       {data.map((queue) => {

web/src/components/tickets/ticket-timeline.tsx

@@ -75,6 +75,7 @@ export function TicketTimeline({ ticket }: TicketTimelineProps) {
                   if (entry.type === "ASSIGNEE_CHANGED" && (p.assigneeName || p.assigneeId)) message = `Responsável alterado${p.assigneeName ? ` para ${p.assigneeName}` : ""}`
                   if (entry.type === "QUEUE_CHANGED" && (p.queueName || p.queueId)) message = `Fila alterada${p.queueName ? ` para ${p.queueName}` : ""}`
                   if (entry.type === "CREATED" && (p.requesterName)) message = `Criado por ${p.requesterName}`
+                  if (entry.type === "COMMENT_ADDED" && (p.authorName || p.authorId)) message = `Comentário adicionado${p.authorName ? ` por ${p.authorName}` : ""}`
                   if (!message) return null
                   return (
                     <div className="rounded-lg border border-dashed bg-card px-3 py-2 text-sm text-muted-foreground">