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
- [x] Scaffold Next.js + Tailwind + shadcn/ui.
- [x] Ajustar layout shell (dashboard + sidebar) com tema solicitado.
- [x] Criar modulos base de dominio (schemas Prisma/Zod) ainda com dados mockados.
- [x] Preparar estrutura de paginas: `/tickets`, `/tickets/[id]`, `/play`.
- [x] Implementar Auth placeholder (cookie + middleware).
- [x] 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.