docs(projetos): runbook do upgrade de build do client (corte CI/tag, com janela de teste e rollback)

projetos/rx.scoreodonto.com-client/upgrade-build.md

@@ -0,0 +1,60 @@
+# rx.scoreodonto.com-client — Runbook do upgrade do build (corte para CI/tag)
+
+> Como migrar o client da forma antiga (webhook 9004 → `deploy-client.sh` no push) para a nova
+> (CI valida no push; **tag** builda com a versão da tag e publica). Plano geral: ver `plano-deploy.md`.
+> **Regra crítica:** o `latest.yml` em `updates/` é o que **TODOS os clients nas clínicas** leem — um arquivo errado quebra o auto-update de todos. Por isso: backup + teste num Windows ANTES de publicar.
+
+## Pré-requisitos
+- Fase 1 (versão no tray) + Fase 2 (`.gitea/workflows/build.yml`) prontas (hoje no working tree, não commitadas).
+- **Windows de teste** com o client instalado, para validar o auto-update.
+- Gitea Actions habilitado no repo do client.
+- SSH VPS4→VPS1 (o release usa `rsync`; já existe, o `deploy-client.sh` usa).
+- ⚠️ Desligar o serviço systemd `webhook-rx-client.service` **pode exigir sudo** — confirmar o acesso antes.
+
+## Ordem do corte (com janela de teste e rollback)
+
+### 0. Backup (rede de rollback)
+Na VPS1, copiar o `updates/` atual:
+```
+ssh deploy@10.99.0.1 'cp -a /home/deploy/stack/rx.scoreodonto.com/dental-server/updates \
+  /home/deploy/stack/rx.scoreodonto.com/dental-server/updates.bak_$(date +%Y%m%d_%H%M)'
+```
+
+### 1. Cortar o gatilho antigo (senão push dispara o build antigo)
+- `systemctl disable --now webhook-rx-client.service` (porta 9004).
+- No Gitea (repo client → Settings → Webhooks): desabilitar o webhook que aponta para a `:9004`.
+- Resultado: push no repo do client **não** dispara mais o `deploy-client.sh`.
+
+### 2. Habilitar o CI + subir o pipeline
+- Gitea → repo client → Settings → **Actions: habilitar**.
+- `git add -A && git commit && git push origin main` (build.yml + index.js da Fase 1).
+- O CI roda o job **build** (`electron-builder --publish never`) → confirma que **compila**. **Não publica**. Conferir CI verde.
+
+### 3. Validar o `.exe` num Windows ANTES de publicar
+- Pegar o `.exe` gerado pelo CI (artefato do runner / `dist/`) **ou** rodar o build na VPS4.
+- Instalar num **Windows de teste**: app abre, **"Versão v…"** no tray, captura/envio do sensor funciona, conecta ao server.
+- (Gate manual: só seguir para a tag se o `.exe` estiver ok — porque o passo 4 publica para todos.)
+
+### 4. Primeira release pela tag
+- Próxima versão (a atual é `1.3.8`): `git tag v1.3.9 && git push origin v1.3.9`.
+- O CI job **release**: `npm version 1.3.9` → build → `rsync` do `.exe`/`latest.yml` para a VPS1 `updates/`.
+- Conferir: `updates/latest.yml` = `1.3.9` e o `.exe` presente.
+
+### 5. Validar o auto-update em campo (1 client monitorado)
+- Num client de teste: "Verificar Atualizações" → detecta `1.3.9` → baixa → instala → reinicia → tray mostra **"Versão v1.3.9"**.
+- Observar: sem erro de update, app reconecta, envio volta.
+
+### 6. Rollback (se quebrar)
+- Restaurar o backup: `rsync`/`cp` do `updates.bak_*/` de volta para `updates/` → no próximo check os clients voltam à versão anterior.
+- O `index.js` já tem **anti-loop** de update (aborta após N tentativas) — ajuda se um `.exe` ruim foi instalado.
+
+## Riscos a tratar (antes/durante)
+- **Code signing** (SmartScreen): sem assinatura, o Windows alerta em **novas instalações** (não bloqueia o auto-update de quem já tem o app). Pendência antiga do RX.
+- **Versão crescente**: a tag (`1.3.9`) tem que ser **> a atual** (`1.3.8`), senão o electron-updater não atualiza.
+- **`latest.yml` único para todos** → o teste do passo 3 e o backup do passo 0 são obrigatórios.
+- **systemd/sudo** para desligar o webhook (passo 1).
+
+## Pós-corte (limpeza)
+- O **bump manual** do `package.json` deixa de existir (versão = tag).
+- O **`deploy-client.sh`** fica obsoleto (substituído pelo CI) → mover para `desuso/`.
+- Atualizar `plano-deploy.md` marcando Fases 3/4 como ✅.