# Plano de Desenvolvimento — Sistema de Chamados

> **Diretriz máxima:** todas as respostas, comunicações e documentações devem ser redigidas em português brasileiro.

## Contato principal
- **Esdras Renan** — monkeyesdras@gmail.com

## Credenciais padrão (Better Auth)
- Administrador: `admin@sistema.dev` / `admin123`
- Agente Demo: `agente.demo@sistema.dev` / `agent123`
- Cliente Demo: `cliente.demo@sistema.dev` / `cliente123`
> Execute `pnpm auth:seed` após configurar `.env`. O script atualiza as contas acima ou cria novas conforme variáveis `SEED_USER_*`.

## Sincronização com Convex
- Usuários e tickets demo são garantidos via `convex/seed.ts`.
- Após iniciar `pnpm convex:dev`, acesse `/dev/seed` uma vez por ambiente local para carregar dados reais de demonstração no banco do Convex.

## Setup local rápido
1. `pnpm install`
2. Ajuste `.env` (ou crie a partir do exemplo) e confirme `NEXT_PUBLIC_CONVEX_URL` apontando para o Convex local.
3. `pnpm auth:seed`
4. (Opcional) `pnpm queues:ensure`
5. `pnpm convex:dev`
6. Em outro terminal: `pnpm dev`

## Estado atual
- Autenticação Better Auth com guardas client-side (`AuthGuard`) bloqueando rotas protegidas.
- Menu de usuário no rodapé da sidebar com link para `/settings` e logout confiável.
- Formulários de novo ticket (dialog, página e portal) com seleção de responsável, placeholders claros e validação obrigatória de assunto/descrição/categorias.
- Portal do cliente restringe visualização e criação ao próprio requester; clientes não atribuem responsáveis.
- Relatórios e dashboards utilizam `AppShell`, garantindo header/sidebar consistentes.

## Entregas recentes relevantes
- Correção do redirecionamento após logout evitando retorno imediato ao dashboard.
- Validações manuais dos formulários de rich text para eliminar `ZodError` durante edição.
- Dropdown de responsáveis na criação de tickets com preenchimento automático pelo autor e evento inicial de comentário.
- Indicadores visuais de campos obrigatórios e botão "Novo ticket" funcional no cabeçalho do detalhe.
- Seeds (Better Auth e Convex) ampliados para incluir agente e cliente de teste.

## Fluxos suportados

### Equipe interna (admin/agent/collaborator)
- Criar tickets com categorias, responsável inicial e anexos.
- Abrir novos tickets diretamente a partir do detalhe via dialog reutilizável.
- Acessar `/settings` para ajustes pessoais e efetuar logout pelo menu.

### Clientes
- Autenticam com `cliente.demo@sistema.dev`.
- Abrem tickets para si mesmos a partir do portal com assunto/descrição obrigatórios.
- Não visualizam campo de responsável nem tickets de outros usuários.

## Próximos passos sugeridos
1. Finalizar redefinição de senha/auditoria de convites Better Auth.
2. Expandir cobertura de testes (`vitest`) para guardas de autenticação e criação de tickets.
3. Implementar ações rápidas (status/fila) diretamente na listagem de tickets.
4. Definir limites e monitoramento para anexos por tenant.

## Rotina antes de abrir PR
- `pnpm lint`
- `pnpm exec vitest run`
- Revisar toasts/labels em PT-BR e ausência de segredos no diff.
- Adicionar coautor `factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>` quando aplicável.

## Convenções
- Convex deve retornar apenas tipos primitivos; converta datas via mappers em `src/lib/mappers`.
- Manter textos em PT-BR e evitar comentários supérfluos no código.
- Reutilizar componentes shadcn existentes e seguir o estilo do arquivo editado.
- Validações client-side críticas devem sinalizar erros inline e exibir toast.

## Estrutura útil
- `convex/` — queries e mutations (ex.: `tickets.ts`, `users.ts`).
- `src/components/tickets/` — UI interna (dialog, listas, header, timeline).
- `src/components/portal/` — formulários e fluxos do portal do cliente.
- `scripts/` — seeds Better Auth e utilidades.
- `src/components/auth/auth-guard.tsx` — proteção de rotas client-side.

## Histórico resumido
- Scaffold Next.js + Turbopack configurado com Better Auth e Convex.
- Portal do cliente entregue com isolamento por `viewerId`.
- Fluxo de convites e painel administrativo operacionais.
- Iteração atual focada em UX de criação de tickets, consistência de layout e guardas de sessão.