sistema-de-chamados/agents.md

# 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`

## App Desktop (Agente de Máquinas)
- Código: `apps/desktop` (Tauri v2 + Vite).
- Padrões de URL:
  - Produção: usa `https://tickets.esdrasrenan.com.br` por padrão (fallback em release).
  - Desenvolvimento: use `apps/desktop/.env` (ver `.env.example`).
- Comandos úteis:
  - `pnpm -C apps/desktop tauri dev` — dev completo (abre WebView em 1420 + backend Rust).
  - `pnpm -C apps/desktop build` — build do frontend (dist).
  - `pnpm -C apps/desktop tauri build` — gera instaladores (bundle) por SO.
- Saída dos pacotes: `apps/desktop/src-tauri/target/release/bundle/`.
- Fluxo atualizado:
  1) Coleta perfil (hostname/OS/MAC/seriais/métricas).
  2) Provisiona via `POST /api/machines/register` com `MACHINE_PROVISIONING_SECRET`, solicitando o **perfil de acesso** (Colaborador ou Gestor) e os dados do usuário associado. O backend garante a vinculação única da máquina ao colaborador ou gestor informado.
  3) Envia heartbeats a cada 5 min para `/api/machines/heartbeat` com inventário básico + estendido (discos, GPUs, serviços, softwares).
  4) Abre `APP_URL/machines/handshake?token=...&redirect=...` para autenticar a sessão: colaboradores são direcionados ao portal (`/portal`), gestores ao painel completo (`/dashboard`).
- Segurança: token salvo no cofre do SO (Keyring). Store guarda apenas metadados não sensíveis.
- Endpoint extra: `POST /api/machines/inventory` (atualiza inventário por token ou provisioningSecret).
- Atualizações automáticas: o plugin `@tauri-apps/plugin-updater` verifica `latest.json` nos releases do GitHub. Publicar uma nova release com manifestos atualiza os clientes sem reinstalação manual.
- Ajustes administrativos: em **Admin ▸ Máquinas** é possível vincular ou alterar o perfil (colaborador/gestor) e e-mail associado através do botão “Ajustar acesso”.

## Desenvolvimento local — boas práticas (atualizado)
- Ambientes separados: mantenha seu `.env.local` só para DEV e o `.env` da VPS só para PROD. Nunca commitar arquivos `.env`.
- Convex em DEV: rode `pnpm convex:dev` e aponte o front para `http://127.0.0.1:3210` via `NEXT_PUBLIC_CONVEX_URL`.
- Banco local: por padrão `DATABASE_URL=file:./prisma/db.sqlite`. Se quiser isolar por projeto, use `db.dev.sqlite`.
- Seeds em DEV: use `pnpm auth:seed` (usuários Better Auth) e acesse `/dev/seed` uma vez para dados de demonstração do Convex.
- Seeds em PROD: só quando realmente necessário; não fazem parte do deploy automático.

### Exemplo de `.env.local` (DEV)
```
# Base do app
NODE_ENV=development
NEXT_PUBLIC_APP_URL=http://localhost:3000
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=dev-only-long-random-string

# Convex (DEV)
NEXT_PUBLIC_CONVEX_URL=http://127.0.0.1:3210

# Banco local (Prisma)
DATABASE_URL=file:./prisma/db.sqlite

# SMTP de desenvolvimento (ex.: Mailpit)
SMTP_ADDRESS=localhost
SMTP_PORT=1025
SMTP_TLS=false
SMTP_USERNAME=
SMTP_PASSWORD=
MAILER_SENDER_EMAIL="Dev <no-reply@localhost>"

# (Opcional) OAuth DEV – não usado por padrão neste projeto
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
```

Observações:
- `COOKIE_DOMAIN` não é necessário em DEV neste projeto.
- Variáveis de provisionamento de máquinas (`MACHINE_PROVISIONING_SECRET`, etc.) só se você for testar as rotas de máquinas/inventário.

### Passo a passo local
1) `pnpm install`
2) `pnpm prisma:generate`
3) `pnpm convex:dev` (terminal A)
4) `pnpm dev` (terminal B)
5) (Opcional) `pnpm auth:seed` e visitar `http://localhost:3000/dev/seed`

## Deploy via GitHub Actions (produção)
- Fluxo: `git push main` ⇒ runner self‑hosted na VPS sincroniza código e aplica o stack (Traefik/Swarm) sem derrubar o serviço (start-first).
- Disparo do deploy web: apenas quando há mudanças em arquivos do app (src/, public/, prisma/, next.config.ts, package.json, pnpm-lock.yaml, tsconfig.json, middleware.ts, stack.yml).
- Disparo do deploy Convex: apenas quando há mudanças em `convex/**`.
- O `.env` da VPS é preservado; caches do servidor (`node_modules`, `.pnpm-store`) não são tocados.
- Smoke de provisionamento (`/api/machines/register` + heartbeat) roda só se `RUN_MACHINE_SMOKE=true` (default: desativado para evitar quedas em caso de instabilidade).
- Banco Prisma (SQLite) persiste em volume nomeado (`sistema_db`); não é recriado a cada deploy.

## Bancos e seeds — DEV x PROD
- DEV: use os seeds à vontade (usuários com `pnpm auth:seed`, dados demo do Convex em `/dev/seed`).
- PROD: evite seeds automáticos; para criar um admin use `SEED_USER_*` e `pnpm auth:seed` em um container Node efêmero.
- Alterações de schema: sempre via migrações (`prisma migrate`). O CI aplica `migrate deploy` no start do container web.

## Dicas rápidas
- Imagens em `public/`: trocou o arquivo → push. Para bust de cache, versionar o nome (ex.: `logo.v2.png`) ou usar query (`?v=sha`).
- Problemas de permissão de build: garanta que `.next` pertence ao usuário do runner (se necessário, remover `.next` no host e rebuildar).
- Se precisar inspecionar/backup do SQLite em PROD, prefira um bind dedicado (`/srv/apps/sistema-data:/app/data`) ou use `docker run -v sistema_db:/data` para copiar o arquivo.

## Checklist para novo computador
1. Instale Node.js 20+ e habilite o Corepack (`corepack enable`) para usar o `pnpm`.
2. Garanta o `pnpm` atualizado (`corepack prepare pnpm@latest --activate`) antes de clonar o repositório.
3. Clone o projeto: `git clone git@github.com:esdrasrenan/sistema-de-chamados.git` e entre na pasta.
4. Copie o arquivo `.env` já configurado do computador atual para a raiz do repositório (nunca faça commit desse arquivo).
5. Instale as dependências com `pnpm install`.
6. Gere os clientes locais necessários: `pnpm prisma:generate`.
7. Semeie as credenciais Better Auth: `pnpm auth:seed`.
8. Se for trabalhar com filas padrão, execute `pnpm queues:ensure`.
9. Inicie o backend Convex em um terminal (`pnpm convex:dev`) e, em outro, suba a aplicação Next.js (`pnpm dev`).
10. Acesse `http://localhost:3000` e teste login com os usuários padrão listados acima antes de continuar o desenvolvimento.

## Estado atual
- Autenticação Better Auth com guardas client-side (`AuthGuard`) bloqueando rotas protegidas.
- Menu de usuário (rodapé da sidebar) concentra acesso às configurações ("Meu perfil" → `/settings`) e logout. Removemos o item redundante "Configurações" do menu lateral.
- 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.
- Relatórios, dashboards e páginas administrativas utilizam `AppShell`, garantindo header/sidebar consistentes.
  - Use `SiteHeader` no `header` do `AppShell` para título/lead e ações.
  - O conteúdo deve ficar dentro de `<div className="mx-auto w-full max-w-6xl px-4 pb-12 lg:px-6">`.
  - Persistir filtro global de empresa com `usePersistentCompanyFilter` (localStorage) para manter consistência entre relatórios.

## Entregas recentes
- Exportações CSV (Backlog, Canais, CSAT, SLA e Horas por cliente) com parâmetros de período.
- PDF do ticket (via pdfkit standalone), com espaçamento e traduções PT-BR.
- Play interno/externo com somatório por tipo por ticket e relatório por cliente.
- Admin > Empresas & clientes: cadastro/edição, `Cliente avulso?` e `Horas contratadas/mês`.
- Admin > Usuários: vincular colaborador à empresa.
- Dashboard: cards de filas (Chamados/Laboratório/Visitas) e indicadores principais.
- Lista de tickets: filtro por Empresa, coluna Empresa, alinhamento vertical e melhor espaçamento entre colunas.

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

### Papéis
- Papéis válidos: `admin`, `manager`, `agent`, `collaborator` (papel `customer` removido).
- Colaboradores acessam o portal (`/portal`) e visualizam apenas os próprios tickets; gestores herdam a visão completa da empresa mesmo quando autenticados via agente desktop.
- Gestores veem os tickets da própria empresa e só podem registrar comentários públicos.

## Próximos passos sugeridos
1. Disparo de e-mails automáticos quando uso de horas ≥ 90% do contratado.
2. Ações rápidas (status/fila) diretamente na listagem de tickets.
3. Limites e monitoramento para anexos por tenant.
4. PDF do ticket com layout idêntico ao app (logo/cores/fontes).

## Referências de endpoints úteis
- Backlog CSV: `/api/reports/backlog.csv?range=7d|30d|90d[&companyId=...]`
- Canais CSV: `/api/reports/tickets-by-channel.csv?range=7d|30d|90d[&companyId=...]`
- CSAT CSV: `/api/reports/csat.csv?range=7d|30d|90d`
- SLA CSV: `/api/reports/sla.csv`
- Horas por cliente CSV: `/api/reports/hours-by-client.csv?range=7d|30d|90d`
 
## Referências de inventário de máquinas
- UI (Admin > Máquinas): filtros, pesquisa, inventário enriquecido (GPUs, discos, serviços) e exclusão de máquina — ver docs/admin-inventory-ui.md
- Endpoints do agente:
  - `POST /api/machines/register`
  - `POST /api/machines/heartbeat`
  - `POST /api/machines/inventory`

## Rotina antes de abrir PR
- `pnpm lint`
- `pnpm build --turbopack`
- `pnpm exec vitest run`
- Revisar toasts/labels em PT-BR e ausência de segredos no diff.

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