# Desktop (Tauri) — Handshake, Sessão de Dispositivo 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 dispositivo”, 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 dispositivo (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 dispositivo”)
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 dispositivo).
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 dispositivo, dados persistidos junto ao executável e DevTools habilitado.