From a1436ea7293ffe5f5ddca190a529ec6c0baa3139 Mon Sep 17 00:00:00 2001
From: Esdras Renan <monkeyesdras@gmail.com>
Date: Wed, 19 Nov 2025 21:44:55 -0300
Subject: [PATCH] docs: add runbook steps forbetter-sqlite3 rebuild + login

---
 docs/OPERATIONS.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
index c451c2d..b553804 100644
--- a/docs/OPERATIONS.md
+++ b/docs/OPERATIONS.md
@@ -153,6 +153,20 @@ Depois disso, o job “Deploy Convex functions” funciona em modo não interati
   - Certifique‑se de que `/srv/apps/sistema/convex.json` existe (rodar wizard `npx convex dev --once --configure=new`).
   - Não usar `CONVEX_DEPLOYMENT` com `CONVEX_SELF_HOSTED_URL` + `CONVEX_SELF_HOSTED_ADMIN_KEY`.
 
+- Login quebrando com erro de `better_sqlite3` (NODE_MODULE_VERSION)
+  - Sintoma: HTTP 500 em `/api/auth/sign-in/email` e logs do `sistema_web` com “Could not locate the bindings file” ou “compiled against NODE_MODULE_VERSION 115”.
+  - Causa: o `better-sqlite3` precisa ser recompilado para a versão de Node em uso (rodamos Node 22 dentro do container).
+  - Correção (uma vez, após trocar versão de Node/Bun ou limpar `node_modules`):
+    ```
+    docker run --rm -v /apps/sistema:/app sistema_web:node22-bun \
+      bash -lc "cd /app && npm rebuild better-sqlite3"
+    docker service update --force sistema_web
+    ```
+    Isso grava o binário em `/apps/sistema/node_modules/.bun/better-sqlite3@11.10.0/...` (path montado pelo serviço).
+  - Flags no serviço (stack.yml):
+    - `SKIP_APT_BOOTSTRAP=true` evita apt-get no boot (imagem já tem toolchain).
+    - `SKIP_SQLITE_REBUILD=true` deixa o boot rápido; deixe como `true` depois de recompilar manualmente como acima.
+
 - “Schema validation failed” (campo extra `provisioningCode`)
   - Atualize o schema do Convex no servidor para incluir `provisioningCode?: string` em `companies`.
   - Refaça o deploy.