docs: reorganize and simplify

- 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/
2025-10-20 16:24:16 -03:00 · 2025-10-20 16:24:16 -03:00 · f5b3abd277
commit f5b3abd277
parent 0dd0e67458
15 changed files with 190 additions and 11 deletions
--- a/docs/desktop/build.md
+++ b/docs/desktop/build.md
@ -0,0 +1,52 @@
+# Build do App Desktop (Tauri)
+
+Guia rápido para gerar instaladores do app desktop em cada sistema operacional.
+
+## Pré‑requisitos
+- Node.js 20+ e pnpm (Corepack habilitado):
+  - `corepack enable && corepack prepare pnpm@9 --activate`
+- Rust toolchain (stable) instalado.
+- Dependências nativas por SO:
+  - Linux (Debian/Ubuntu):
+    ```bash
+    sudo apt update && sudo apt install -y \
+      libwebkit2gtk-4.1-dev build-essential curl wget file \
+      libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
+    ```
+  - Windows: Visual Studio Build Tools + WebView2 Runtime.
+  - macOS: Xcode Command Line Tools.
+
+## Configuração de URLs
+- Produção: por padrão o app usa `https://tickets.esdrasrenan.com.br`.
+- Desenvolvimento: crie `apps/desktop/.env` a partir de `apps/desktop/.env.example` e ajuste:
+  ```
+  VITE_APP_URL=http://localhost:3000
+  VITE_API_BASE_URL=
+  ```
+
+## Comandos de build
+- Linux/macOS/Windows (rodar no próprio sistema):
+  ```bash
+  pnpm -C apps/desktop tauri build
+  ```
+- Apenas frontend (Vite):
+  ```bash
+  pnpm -C apps/desktop build
+  ```
+
+Saída de artefatos: `apps/desktop/src-tauri/target/release/bundle/`.
+
+## Dicas
+- Primeira compilação do Rust pode demorar (download de crates e linkedição).
+- Se o link‑editor for lento no Linux, considere instalar `lld` e usar:
+  ```bash
+  RUSTFLAGS="-Clink-arg=-fuse-ld=lld" pnpm -C apps/desktop tauri build
+  ```
+- Para logs detalhados em dev, rode `pnpm -C apps/desktop tauri dev`.
+
+## Diagnóstico de sessão (Desktop → Portal)
+- Durante testes, navegue até `/portal/debug` (o desktop pode redirecionar automaticamente) para ver:
+  - `/api/auth/get-session` — pode ser `null` na WebView; não é bloqueante.
+  - `/api/machines/session` — precisa retornar `200` com `assignedUserId/email`.
+- Produção: as rotas de sessão/handshake enviam `Access-Control-Allow-Credentials: true` e aplicam cookies com `NextResponse.cookies.set(...)` para confiabilidade em navegadores/embeds.
+- O desktop mantém a navegação top‑level via `/machines/handshake` para maximizar a aceitação de cookies.
--- a/docs/desktop/handshake-troubleshooting.md
+++ b/docs/desktop/handshake-troubleshooting.md
@ -0,0 +1,71 @@
+# 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.
--- a/docs/desktop/updater.md
+++ b/docs/desktop/updater.md
@ -0,0 +1,111 @@
+# Checklist de Publicação — Updater do Agente Desktop
+
+Este guia consolida tudo o que precisa ser feito para que o auto-update do Tauri funcione em cada release.
+
+---
+
+## 1. Preparação (uma única vez)
+
+1. **Gerar o par de chaves** (Linux ou WSL)  
+   ```bash
+   pnpm -C apps/desktop tauri signer generate -w ~/.tauri/raven.key
+   ```
+   - Privada: `~/.tauri/raven.key` (nunca compartilhar)  
+   - Pública: `~/.tauri/raven.key.pub` (cole em `tauri.conf.json > plugins.updater.pubkey`)
+   - Se for buildar em outra máquina (ex.: Windows), copie os dois arquivos para `C:\Users\<usuario>\.tauri\raven.key(.pub)`.
+
+2. **Verificar o `tauri.conf.json`**
+   ```json
+   {
+     "bundle": { "createUpdaterArtifacts": true },
+     "plugins": {
+       "updater": {
+         "active": true,
+         "endpoints": ["https://.../latest.json"],
+         "pubkey": "<conteúdo da raven.key.pub>"
+       }
+     }
+   }
+   ```
+
+---
+
+## 2. Antes de cada release
+
+1. **Sincronizar versão** (mesmo número nos três arquivos):
+   - `apps/desktop/package.json`
+   - `apps/desktop/src-tauri/tauri.conf.json`
+   - `apps/desktop/src-tauri/Cargo.toml`
+
+2. **Build do front (gera `dist/` para o Tauri)**  
+   ```bash
+   pnpm -C apps/desktop build
+   ```
+
+3. **Exportar variáveis do assinador** (no mesmo shell em que vai buildar):
+   ```bash
+   export TAURI_SIGNING_PRIVATE_KEY="$(cat ~/.tauri/raven.key)"
+   export TAURI_SIGNING_PRIVATE_KEY_PASSWORD="<senha-da-chave>"
+   ```
+   > No PowerShell, use `setx` para persistir ou execute `set`/`$env:` no terminal atual.
+
+4. **Gerar os instaladores + `.sig`**  
+   ```bash
+   pnpm -C apps/desktop tauri build
+   ```
+   Os artefatos ficam em `apps/desktop/src-tauri/target/release/bundle/`:
+
+   | SO       | Bundle principal                            | Assinatura gerada                       |
+   |----------|----------------------------------------------|-----------------------------------------|
+   | Windows  | `nsis/Raven_0.X.Y_x64-setup.exe`             | `nsis/Raven_0.X.Y_x64-setup.exe.sig`    |
+   | Linux    | `appimage/Raven_0.X.Y_amd64.AppImage`        | `appimage/Raven_0.X.Y_amd64.AppImage.sig` |
+   | macOS    | `macos/Raven.app.tar.gz`                     | `macos/Raven.app.tar.gz.sig`            |
+
+---
+
+## 3. Publicar no GitHub
+
+1. **Criar/atualizar release** (ex.: `v0.1.7`) anexando todos os instaladores e seus `.sig`.
+2. **Atualizar `latest.json`** (no próprio repo ou em um gist público) com algo como:
+   ```json
+   {
+     "version": "0.1.7",
+     "notes": "Novidades do release",
+     "pub_date": "2025-10-12T08:00:00Z",
+     "platforms": {
+       "windows-x86_64": {
+         "signature": "<conteúdo de Raven_0.1.7_x64-setup.exe.sig>",
+         "url": "https://github.com/esdrasrenan/sistema-de-chamados/releases/download/v0.1.7/Raven_0.1.7_x64-setup.exe"
+       },
+       "linux-x86_64": {
+         "signature": "<conteúdo de Raven_0.1.6_amd64.AppImage.sig>",
+         "url": "https://github.com/esdrasrenan/sistema-de-chamados/releases/download/v0.1.6/Raven_0.1.6_amd64.AppImage"
+       },
+       "darwin-x86_64": {
+         "signature": "<conteúdo de Raven.app.tar.gz.sig>",
+         "url": "https://github.com/esdrasrenan/sistema-de-chamados/releases/download/v0.1.6/Raven.app.tar.gz"
+       }
+     }
+   }
+   ```
+   - Pegue o link **Raw** do `latest.json` e mantenha igual ao usado no `tauri.conf.json`.
+
+---
+
+## 4. Validar rapidamente
+
+1. Instale a versão anterior (ex.: 0.1.5) e abra.
+2. O agente deve avisar sobre a nova versão e reiniciar automaticamente ao concluir a instalação.
+3. Caso queira forçar manualmente, abra a aba **Configurações → Verificar atualizações**.
+
+---
+
+## 5. Resumo rápido
+
+1. `pnpm -C apps/desktop build`
+2. `export TAURI_SIGNING_PRIVATE_KEY=...` / `export TAURI_SIGNING_PRIVATE_KEY_PASSWORD=...`
+3. `pnpm -C apps/desktop tauri build`
+4. Upload dos bundles + `.sig` → atualizar `latest.json`
+5. Testar o instalador antigo para garantir que atualiza sozinho
+
+Com isso, os usuários sempre receberão a versão mais recente assim que abrirem o agente desktop.