f5b3abd277
- Add docs/README.md as index - Consolidate ops in docs/operations.md; mark legacy runbooks as archive - Create docs/desktop/ and docs/admin/ structure and move relevant docs - Update root README to link docs index - Keep historical and planning notes under docs/archive/
71 lines
4.5 KiB
Markdown
71 lines
4.5 KiB
Markdown
# Desktop (Tauri) — Handshake, Sessão de Máquina e Antivírus
|
||
|
||
Este documento consolida as orientações e diagnósticos sobre o fluxo do agente desktop, handshake na web e possíveis interferências de antivírus.
|
||
|
||
## Sintomas observados
|
||
- Ao clicar em “Registrar máquina”, o antivírus aciona (ex.: ATC.SuspiciousBehavior) e o processo é interrompido.
|
||
- Após o registro, ao abrir a UI web: cabeçalho mostra “Cliente / Sem e‑mail definido” e o Portal não permite abrir chamados.
|
||
- No passado, mesmo quando o app “entrava direto”, o Portal não refletia o colaborador/gestor vinculado (sem assignedUser); receio de repetir o problema.
|
||
|
||
## Causas prováveis
|
||
1) O antivírus interrompe o processo durante o handshake
|
||
- O app salva token/config, inicia heartbeat e abre `GET /machines/handshake?token=...&redirect=...` para gravar cookies de sessão.
|
||
- Se o processo cai neste momento, os cookies não são gravados e a UI fica sem sessão “machine”.
|
||
|
||
2) Endpoint de contexto sem ler a sessão adequadamente
|
||
- O Portal preenche o colaborador/gestor via `GET /api/machines/session`.
|
||
- Em alguns ambientes, é mais estável rodar esse endpoint no runtime `nodejs` para ler `cookies()` do Next sem inconsistências.
|
||
|
||
## O que já foi aplicado no projeto
|
||
- Middleware permite `GET /machines/handshake` sem exigir login (rota pública).
|
||
- Frontend preenche `machineContext` chamando `GET /api/machines/session` (assignedUserId/email/nome/persona) e usa esse ID ao abrir chamados.
|
||
- UI oculta “Sair” quando a sessão é de máquina (portal e shell interno).
|
||
- DevTools habilitado no desktop (F12, Ctrl+Shift+I ou botão direito com Ctrl/Shift).
|
||
- Desktop salva dados em `C:\\Raven\\data\\machine-agent.json` (ou equivalente ao lado do executável), com fallback para AppData se a pasta do app não permitir escrita.
|
||
|
||
## Validação rápida (após “Registrar máquina”)
|
||
1) No executável, com DevTools:
|
||
```js
|
||
fetch('/api/machines/session').then(r => r.status).then(console.log)
|
||
// Esperado: 200
|
||
fetch('/api/machines/session').then(r => r.json()).then(console.log)
|
||
// Deve conter: persona (collaborator|manager), assignedUserEmail/nome/Id
|
||
```
|
||
2) Na UI (Portal/Topo):
|
||
- Mostrar nome/e‑mail do colaborador/gestor (não “Cliente / Sem e‑mail definido”).
|
||
- Sem botão “Sair” (sessão de máquina).
|
||
3) No Portal, o formulário “Abrir chamado” deve habilitar normalmente (usa `machineContext.assignedUserId`).
|
||
|
||
Se `GET /api/machines/session` retornar 403:
|
||
- Verificar se o antivírus barrou o processo na hora do handshake.
|
||
- Adicionar exceção para `C:\\Raven\\appsdesktop.exe` e `C:\\Raven\\data\\`.
|
||
- Opcional: forçar `export const runtime = 'nodejs'` no endpoint de sessão para leitura consistente de cookies (Next `cookies()`).
|
||
|
||
## Fluxo atual do desktop
|
||
- Antes de registrar: tela de onboarding (sem “Abrir sistema”).
|
||
- Após registrar: salva token/config, inicia heartbeat e mostra as abas com “Abrir sistema” e “Reprovisionar”.
|
||
- Auto‐abrir: o app já tenta abrir o sistema quando detecta token; pode ser reforçado chamando `openSystem()` ao fim do `register()`.
|
||
|
||
## Melhorias opcionais
|
||
- Auto‑abrir imediatamente após `register()` (reforça o comportamento atual e reduz a janela para interferência do AV).
|
||
- Diagnóstico no desktop: exibir caminho completo do arquivo de dados e botão “Abrir pasta de dados”.
|
||
- Forçar `nodejs` no `GET /api/machines/session` para estabilidade total na leitura de cookies.
|
||
|
||
## Notas sobre antivírus
|
||
- Apps Tauri não assinados com certificado de code signing do Windows são frequentemente marcados como “desconhecidos”.
|
||
- A assinatura Minisign (updater) não substitui o code signing do executável.
|
||
- Recomendações:
|
||
- Adicionar exceções para o executável e a pasta de dados.
|
||
- Avaliar aquisição de um certificado de code signing (EV/OV) para distribuição ampla sem alertas.
|
||
|
||
## Checklist quando “não mudou nada” após registro
|
||
- Confirmar `GET /api/machines/session` (status 200 + JSON contendo assignedUser). Caso 403, tratar AV/endpoint runtime.
|
||
- Verificar cookies no navegador (DevTools → Application → Cookies): presença da sessão e `machine_ctx`.
|
||
- Validar que o Portal mostra o colaborador/gestor e permite abrir chamado.
|
||
- Conferir arquivo de dados:
|
||
- Preferencial: `C:\\Raven\\data\\machine-agent.json`.
|
||
- Fallback: AppData local do usuário (buscar por `machine-agent.json`).
|
||
|
||
---
|
||
|
||
Última atualização: automatização do handshake no middleware, ocultação de “Sair” em sessão de máquina, dados persistidos junto ao executável e DevTools habilitado.
|