esdras/sistema-de-chamados
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sistema-de-chamados/docs/desktop/handshake-troubleshooting.md

4.6 KiB
Raw Permalink Blame History

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