161 lines
9 KiB
Markdown
161 lines
9 KiB
Markdown
# Plano de Desenvolvimento — Sistema de Chamados
|
|
|
|
> **Diretriz máxima**: documentação, comunicação e respostas sempre em português brasileiro.
|
|
|
|
## Contatos
|
|
- **Esdras Renan** — monkeyesdras@gmail.com
|
|
|
|
## Credenciais padrão (Better Auth)
|
|
| Papel | Usuário | Senha |
|
|
| --- | --- | --- |
|
|
| Administrador | `admin@sistema.dev` | `admin123` |
|
|
| Painel telão | `suporte@rever.com.br` | `agent123` |
|
|
|
|
Os demais colaboradores reais são provisionados via **Convites & acessos**. Caso existam vestígios de dados demo, execute `node scripts/remove-legacy-demo-users.mjs` para limpá-los.
|
|
|
|
> Execute `pnpm auth:seed` após configurar `.env` para (re)criar os usuários acima (campos `SEED_USER_*` podem sobrescrever credenciais).
|
|
|
|
## Backend Convex
|
|
- Seeds de usuários/tickets demo: `convex/seed.ts`.
|
|
- Para DEV: rode `pnpm convex:dev` e acesse `/dev/seed` uma vez para popular dados realistas.
|
|
|
|
## Stack atual (18/10/2025)
|
|
- **Next.js**: `15.5.5` (Turbopack em produção + cache de filesystem em DEV).
|
|
- Whitelist de domínios em `src/config/allowed-hosts.ts` é aplicada pelo `middleware.ts`.
|
|
- **React / React DOM**: `18.2.0`.
|
|
- **Trilha de testes**: Vitest (`pnpm test`) sem modo watch por padrão (`--run --passWithNoTests`).
|
|
- **CI**: workflow `Quality Checks` (`.github/workflows/quality-checks.yml`) roda `pnpm install`, `prisma:generate`, `lint`, `test`, `build`. Variáveis críticas (`BETTER_AUTH_SECRET`, `NEXT_PUBLIC_APP_URL`, etc.) são definidas apenas no runner — não afetam a VPS.
|
|
- **Disciplina pós-mudanças**: sempre que fizer alterações locais, rode **obrigatoriamente** `pnpm lint`, `pnpm build` e `pnpm test` antes de entregar ou abrir PR. Esses comandos são mandatórios também para os agentes/automations, garantindo que o projeto continua íntegro.
|
|
- **Deploy**: pipeline `ci-cd-web-desktop.yml` (runner self-hosted). Build roda com pnpm 9, Node 20. Web é publicado em `/home/renan/apps/sistema` e o Swarm aponta `sistema_web` para essa pasta.
|
|
|
|
## Setup local (atualizado)
|
|
1. `pnpm install`
|
|
2. Copie `.env.example` → `.env.local`.
|
|
- Principais variáveis para DEV:
|
|
```
|
|
NODE_ENV=development
|
|
NEXT_PUBLIC_APP_URL=http://localhost:3000
|
|
BETTER_AUTH_URL=http://localhost:3000
|
|
BETTER_AUTH_SECRET=dev-only-long-random-string
|
|
NEXT_PUBLIC_CONVEX_URL=http://127.0.0.1:3210
|
|
DATABASE_URL=file:./prisma/db.dev.sqlite
|
|
```
|
|
3. `pnpm auth:seed`
|
|
4. (Opcional) `pnpm queues:ensure`
|
|
5. `pnpm convex:dev`
|
|
6. Em outro terminal: `pnpm dev`
|
|
7. Acesse `http://localhost:3000` e valide login com os usuários padrão.
|
|
|
|
### Banco de dados
|
|
- Local (DEV): `DATABASE_URL=file:./prisma/db.dev.sqlite` (guardado em `prisma/prisma/`).
|
|
- Produção: SQLite persistido no volume Swarm `sistema_sistema_db`. Migrations em PROD devem apontar para esse volume (ver `docs/DEPLOY-RUNBOOK.md`).
|
|
- Limpeza de legados: `node scripts/remove-legacy-demo-users.mjs` remove contas demo antigas (Cliente Demo, gestores fictícios etc.).
|
|
|
|
### Verificações antes de PR/deploy
|
|
```bash
|
|
pnpm lint
|
|
pnpm test
|
|
pnpm build
|
|
```
|
|
|
|
## Aplicativo Desktop (Tauri)
|
|
- Código-fonte: `apps/desktop` (Tauri v2 + Vite + React 19).
|
|
- URLs:
|
|
- Produção: `https://tickets.esdrasrenan.com.br`
|
|
- DEV: configure `apps/desktop/.env` (exemplo fornecido).
|
|
- Comandos:
|
|
- `pnpm -C apps/desktop tauri dev` — desenvolvimento (porta 1420).
|
|
- `pnpm -C apps/desktop tauri build` — gera instaladores.
|
|
- **Fluxo do agente**:
|
|
1. Coleta perfil da máquina (hostname, OS, MAC, seriais, métricas).
|
|
2. Provisiona via `POST /api/machines/register` usando `MACHINE_PROVISIONING_SECRET`, informando perfil de acesso (Colaborador/Gestor) + dados do colaborador.
|
|
3. Envia heartbeats periódicos (`/api/machines/heartbeat`) com inventário básico + estendido (discos SMART, GPUs, serviços, softwares, CPU window).
|
|
4. Realiza handshake em `APP_URL/machines/handshake?token=...&redirect=...` para receber cookies Better Auth + sessão (colaborador → `/portal`, gestor → `/dashboard`).
|
|
5. Token persistido no cofre do SO (Keyring); store guarda apenas metadados.
|
|
6. Envio manual de inventário via botão (POST `/api/machines/inventory`).
|
|
7. Updates automáticos: plugin `@tauri-apps/plugin-updater` consulta `latest.json` publicado nos releases do GitHub.
|
|
- **Admin ▸ Máquinas**: permite ajustar perfil/email associado, visualizar inventário completo e remover máquina.
|
|
|
|
### Sessão "machine" no frontend
|
|
- Ao autenticar como máquina, o front chama `/api/machines/session`, popula `machineContext` (assignedUser*, persona) e deriva role/`viewerId`.
|
|
- Mesmo quando `get-session` é `null` na WebView, o portal utiliza `machineContext` para saber o colaborador/gestor logado.
|
|
- UI remove opção "Sair" no menu do usuário quando detecta sessão de máquina.
|
|
- `/portal/debug` exibe JSON de `get-session` e `machines/session` (útil para diagnosticar cookies/bearer).
|
|
|
|
### Observações adicionais
|
|
- Planejamos usar um cookie `desktop_shell` no futuro para diferenciar acessos do desktop vs navegador (não implementado).
|
|
|
|
## Qualidade e testes
|
|
- **Lint**: `pnpm lint` (ESLint flat config).
|
|
- **Testes unitários/integrados (Vitest)**:
|
|
- Cobertura atual inclui utilitários (`tests/*.test.ts`), rotas `/api/machines/*` e `sendSmtpMail`.
|
|
- Executar `pnpm test -- --watch` apenas quando precisar de modo interativo.
|
|
- **Build**: `pnpm build` (`next build --turbopack`).
|
|
- **CI**: falhas mais comuns
|
|
- `ERR_PNPM_OUTDATED_LOCKFILE`: mantenha `pnpm-lock.yaml` atualizado (principalmente após alterar dependências do desktop).
|
|
- Variáveis Better Auth ausentes (`BETTER_AUTH_SECRET`): definidas no workflow (`Quality Checks`).
|
|
- Falha de host: confira `src/config/allowed-hosts.ts`; o middleware retorna 403 quando o domínio do Traefik não está listado.
|
|
|
|
## Produção / Deploy
|
|
- Runner self-hosted (VPS). Build roda fora de `/srv/apps/sistema` e rsync publica em `/home/renan/apps/sistema`.
|
|
- Swarm: `stack.yml` monta `/home/renan/apps/sistema.current` → `/app` (via symlink).
|
|
- Para liberar novo release manualmente:
|
|
```bash
|
|
ln -sfn /home/renan/apps/sistema.build.<novo> /home/renan/apps/sistema.current
|
|
docker service update --force sistema_web
|
|
```
|
|
- Resolver `P3009` (migration falhou) sempre no volume `sistema_sistema_db`:
|
|
```bash
|
|
docker service scale sistema_web=0
|
|
docker run --rm -it -e DATABASE_URL=file:/app/data/db.sqlite \
|
|
-v /home/renan/apps/sistema.current:/app \
|
|
-v sistema_sistema_db:/app/data -w /app \
|
|
node:20-bullseye bash -lc 'corepack enable; corepack prepare pnpm@9 --activate; pnpm i --no-frozen-lockfile; pnpm exec prisma migrate resolve --rolled-back <migration>; pnpm exec prisma migrate deploy'
|
|
docker service scale sistema_web=1
|
|
```
|
|
|
|
## Estado do portal / app web
|
|
- Autenticação Better Auth com `AuthGuard`.
|
|
- Sidebar inferior agrega avatar, link para `/settings` e logout (oculto em sessões de máquina).
|
|
- Formulários de ticket (novo/editar/comentários) usam editor rico + anexos; placeholders e validação PT-BR.
|
|
- Relatórios e painéis utilizam `AppShell` + `SiteHeader`.
|
|
- `usePersistentCompanyFilter` mantém filtro global de empresa em relatórios/admin.
|
|
- Exportações CSV: backlog, canais, CSAT, SLA, horas (rotas `/api/reports/*.csv`).
|
|
- PDF do ticket (`/api/tickets/[id]/export/pdf`).
|
|
- Play interno/externo com métricas por tipo.
|
|
- Admin > Empresas: cadastro + “Cliente avulso?”, horas contratadas, vínculos de usuários.
|
|
- Admin > Usuários: vincular colaborador à empresa.
|
|
- Dashboard: cards por fila e indicadores principais.
|
|
|
|
## Fluxos suportados
|
|
- **Equipe interna** (`admin`, `agent`, `collaborator`): cria/acompanha tickets, comenta, altera status/fila, gera relatórios.
|
|
- **Gestores** (`manager`): visualizam tickets da empresa, comentam publicamente, acessam dashboards.
|
|
- **Colaboradores** (`collaborator`): portal (`/portal`), tickets próprios, comentários públicos, editor rico, anexos.
|
|
- **Sessão Máquina**: desktop registra heartbeat/inventário e redireciona colaborador/gestor ao portal apropriado com cookies válidos.
|
|
|
|
## Backlog recomendado
|
|
1. E-mails automáticos quando uso de horas ≥ 90% do contratado.
|
|
2. Ações rápidas (status/fila) diretamente na lista de tickets.
|
|
3. Limites de anexos por tenant + monitoramento.
|
|
4. Layout do PDF do ticket alinhado ao visual da aplicação.
|
|
5. Experimentos com React Compiler (Next 16).
|
|
|
|
## Referências rápidas
|
|
- **Endpoints agent desktop**:
|
|
- `POST /api/machines/register`
|
|
- `POST /api/machines/heartbeat`
|
|
- `POST /api/machines/inventory`
|
|
- **Relatórios CSV**:
|
|
- Backlog: `/api/reports/backlog.csv?range=7d|30d|90d[&companyId=...]`
|
|
- Canais: `/api/reports/tickets-by-channel.csv?...`
|
|
- CSAT: `/api/reports/csat.csv?...`
|
|
- SLA: `/api/reports/sla.csv?...`
|
|
- Horas: `/api/reports/hours-by-client.csv?...`
|
|
- **Docs complementares**:
|
|
- `docs/DEV.md` — guia diário atualizado.
|
|
- `docs/STATUS-2025-10-16.md` — snapshot do estado atual e backlog.
|
|
- `docs/DEPLOY-RUNBOOK.md` — runbook do Swarm.
|
|
- `docs/admin-inventory-ui.md`, `docs/plano-app-desktop-maquinas.md` — detalhes do inventário/agente.
|
|
|
|
---
|
|
_Última atualização: 18/10/2025 (Next.js 15.5.5 estável, Turbopack, fluxos desktop + portal documentados)._
|