feat(ui): versão vX.Y.Z fixa no canto inferior direito (todas as telas, lê /api/version)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/server.js

@@ -181,6 +181,41 @@ const BUILD_INFO = {
 };
 app.get('/api/version', (req, res) => res.json(BUILD_INFO));
 
+// Health check (público, sem auth) — status do backend + dependências.
+// Banco é crítico (down => HTTP 503); cache é opcional (down => "degraded", mas 200).
+app.get('/api/health', async (req, res) => {
+    const checks = {};
+    try {
+        const t = Date.now();
+        await pool.query('SELECT 1');
+        checks.database = { status: 'ok', latency_ms: Date.now() - t };
+    } catch {
+        checks.database = { status: 'down' };
+    }
+    try {
+        if (redis) {
+            const t = Date.now();
+            await redis.ping();
+            checks.cache = { status: 'ok', latency_ms: Date.now() - t };
+        } else {
+            checks.cache = { status: 'disabled' };
+        }
+    } catch {
+        checks.cache = { status: 'down' };
+    }
+    const dbOk = checks.database.status === 'ok';
+    const cacheDegraded = checks.cache.status === 'down';
+    const status = !dbOk ? 'down' : (cacheDegraded ? 'degraded' : 'ok');
+    res.status(dbOk ? 200 : 503).json({
+        status,
+        version: BUILD_INFO.version,
+        commit: BUILD_INFO.commit,
+        environment: BUILD_INFO.environment,
+        uptime_s: Math.round(process.uptime()),
+        checks,
+    });
+});
+
 // =============================================================================
 // SECURITY MIDDLEWARE: Tenant Guard
 // =============================================================================

doc/DEPLOY-PRODUCAO.md

@@ -1,33 +1,29 @@
 # Deploy & Versionamento — Runbook ScoreOdonto
 
-> Auditado contra o sistema em **17/jun/2026**. Cada item carrega seu **status real** — o doc
-> responde *"o que existe hoje?"*, não *"o que gostaríamos?"*.
+> Auditado contra o sistema em **17/jun/2026**. Cada item carrega seu **status real**.
 >
-> **Legenda de status (convenção do projeto):**
-> - ✅ **EM PRODUÇÃO** — está no ar em `scoreodonto.com` (VPS1), verificável agora.
-> - 🧪 **EM DEV** — implementado no working tree da VPS4 / `dev.scoreodonto.com`; **não commitado, não promovido**.
-> - 🎯 **ALVO** — desenhado/aprovado, **ainda não implementado**.
+> **Legenda:** ✅ EM PRODUÇÃO · 🧪 EM DEV (não promovido) · 🎯 ALVO (não implementado).
 >
-> **Produção AGORA:** `v1.0.15 · commit f2eb90c · 2026-06-17` (`curl https://scoreodonto.com/api/version`).
-> Os Passos 1/3/4 (versão em runtime) foram **promovidos a produção** em 17/jun (tag `v1.0.15`).
+> **Produção AGORA:** `v1.0.16 · commit 471c2c2 · 2026-06-17` (`curl https://scoreodonto.com/api/version`).
+> Modelo **Build Once → Promote → Deploy** completo — Passo 5 validado em v1.0.16. Tudo abaixo ✅.
 
 ---
 
-## 1. O modelo
+## 1. O modelo  ✅
 
-> **Push** na `main` produz imagem por **commit** no registry; a **tag `vX.Y.Z`** **promove** essa imagem para produção. **Produção nunca builda — só executa imagens.**
+> **Push** na `main` builda **uma vez** e publica por **commit**; a **tag `vX.Y.Z`** **re-tagueia** esse mesmo artefato (sem rebuild) e deploya. **Produção nunca builda — só executa imagens.**
 
 ```
  PUSH main (commit C)                 TAG vX.Y.Z (no commit C)
         │                                     │
         ▼                                     ▼
-   CI: build                           CI: deploy
-   publica :C, :<versão>, :latest      ✅ hoje: REBUILDA + promove + deploya
-        ▼                              🎯 alvo (Passo 5): só re-tag :C→:vX.Y.Z, SEM build
-   registry                                  ▼
-                                       VPS1: pull + up --no-build   ✅
-                                       APP_VERSION=tag em runtime    ✅ (Passo 3, em prod)
+   CI: build (1x)                       CI: promote (SEM build) ✅
+   publica :C + :latest                 re-tag :C → :vX.Y.Z (MESMO digest) + deploy
+        ▼                                     ▼
+   registry                             VPS1: pull :vX.Y.Z + up --no-build
+                                        APP_VERSION=tag injetada em runtime
 ```
+Prova (v1.0.16): `:v1.0.16` tem **digest idêntico** a `:471c2c2` — a tag é só um rótulo sobre a imagem já testada.
 
 ---
 
@@ -37,15 +33,14 @@
 |---|---|---|
 | Infra VPS1/3/4 + Docker rootless | ✅ | Mapa na §3 |
 | Registry (`git.clube67.com/ruicesar/...`) | ✅ | Ver `REGISTRY.md` |
-| CI: `act_runner` "vps4-builder" builda+publica em push | ✅ | `.gitea/workflows/build.yml`; runner systemd na VPS4 |
-| Deploy por tag (job `deploy` SSH VPS4→VPS1) | ✅ | `deploy-prod.sh` na VPS1 |
+| CI: job `build` publica por **commit** em push (sem `APP_VERSION`) | ✅ | `.gitea/workflows/build.yml` (runner `vps4-builder`) |
+| Job `promote` por tag: re-tag `:<commit>→:vX.Y.Z` (sem rebuild) + deploy | ✅ | validado em v1.0.16 (`:v1.0.16` == `:471c2c2`) |
+| Validação de integridade no promote (commit existe? digest igual? front+back mesmo commit) | ✅ | falha se o commit não foi pushado |
 | Produção não builda (`image:` + `pull` + `up --no-build`) | ✅ | `docker-compose.prod.yml` |
 | Banco DEV isolado em `pgdev`; prod no Postgres da VPS3 | ✅ | Ver `BANCO-DEV-ESTRATEGIA.md` |
-| `GET /api/version` responde (de `process.env`) | ✅ | No ar: v1.0.15 · f2eb90c · PROD |
-| **Versão exibida em Configurações → "Sobre o sistema"** | ✅ | Passo 1 (promovido em v1.0.15; saiu do Sidebar) |
-| **Front/telas consomem `/api/version` (`useAppVersion`); app não usa `APP_VERSION`** | ✅ | Passos 1/4 (em prod desde v1.0.15) |
-| **Deploy injeta `APP_VERSION`/`APP_ENV` em runtime (`environment`)** | ✅ | Passo 3 (`compose.prod`/`deploy-prod.sh` em prod) |
-| **Tag promove sem rebuild + validação de integridade** | 🎯 | Passo 5 (§7) — único item pendente |
+| Versão em runtime (`/api/version`) → Configurações + telas públicas | ✅ | `useAppVersion()`; sem `APP_VERSION` manual |
+| `APP_VERSION`/`APP_ENV` injetados no deploy em runtime | ✅ | `compose.prod` `environment` |
+| Versão **nasce da tag git** (`constants.ts`/`update-version.js` removidos) | ✅ | Passo 5 |
 
 ---
 
@@ -53,90 +48,70 @@
 
 | Onde | Host | Papel | Docker |
 |---|---|---|---|
-| VPS1 | `10.99.0.1` | **Produção** (Traefik + apps) | rootless (`unix:///run/user/1000/docker.sock`) |
+| VPS1 | `10.99.0.1` | **Produção** (Traefik + apps) | rootless |
 | VPS3 | `10.99.0.3` | Postgres (prod) + Gitea + registry | — |
 | VPS4 | `10.99.0.4` | **Dev + Builder** (código; runner CI; `pgdev`) | rootless |
 
-- Repo (fonte da verdade): `ssh://git@10.99.0.3/ruicesar/scoreodonto.com.git`.
-- Project Compose: `scoreodontocom`. Diretório nas duas máquinas: `/home/deploy/stack/scoreodonto.com`.
+- Repo: `ssh://git@10.99.0.3/ruicesar/scoreodonto.com.git`. Project Compose: `scoreodontocom`.
 
 ---
 
-## 4. De onde vem a versão (contrato `/api/version`)
+## 4. De onde vem a versão (`/api/version`)
 
 ```json
-{ "name": "ScoreOdonto API", "version": "v1.0.15", "commit": "f2eb90c",
-  "build": "2026-06-17 03:37 UTC", "environment": "PROD" }
+{ "name": "ScoreOdonto API", "version": "v1.0.16", "commit": "471c2c2",
+  "build": "2026-06-17 10:35 UTC", "environment": "PROD" }
 ```
-- **commit / build** = carimbados no **build** da imagem (imutáveis — identidade do artefato). ✅
-- **version / environment** = **injetados no deploy em runtime** (a partir da tag) via `environment` do `compose.prod` ✅ (Passo 3, em prod) — a mesma imagem pode ser promovida sob qualquer tag sem rebuild.
-- **Frontend** = lê tudo de `/api/version` via `useAppVersion()`; **não embute mais a versão** ✅ (Passos 1/4, em prod). Fonte única = backend.
+- **commit / build** = carimbados no **build** (imutáveis — identidade do artefato).
+- **version / environment** = **injetados no deploy em runtime** (a partir da tag). A mesma imagem é promovida sob qualquer tag, sem rebuild.
+- **Frontend** lê tudo de `/api/version` (`useAppVersion()`); não embute versão. Fonte única = backend.
 
 ---
 
-## 5. Runbook — subir um release (fluxo ATUAL ✅)
+## 5. Runbook — subir um release ✅
 
-> ⚠️ **Regra de ouro:** confirme **DEV ou PRODUÇÃO** antes de agir. `dev.scoreodonto.com` = VPS4 (banco `pgdev`, descartável). `scoreodonto.com` = VPS1 (real). **Nunca** `git push --force` na `main`. Push/tag exigem autorização explícita.
+> ⚠️ **Regra de ouro:** confirme **DEV ou PRODUÇÃO**. `dev.scoreodonto.com` = VPS4 (banco `pgdev`). `scoreodonto.com` = VPS1 (real). **Nunca** `git push --force` na `main`. Push/tag exigem autorização explícita.
 
 ```bash
-# 1) VPS4: validar em DEV (build local do container de dev)
+# 1) VPS4: validar em DEV
 cd /home/deploy/stack/scoreodonto.com
 node --check backend/server.js
 docker compose build scoreodonto-backend scoreodonto-frontend
-docker compose up -d --force-recreate scoreodonto-backend scoreodonto-frontend
-# conferir em https://dev.scoreodonto.com
+docker compose up -d --force-recreate scoreodonto-backend scoreodonto-frontend   # https://dev.scoreodonto.com
 
-# 2) ⚠️ transitório (até Passo 5): a TAG precisa casar com frontend/constants.ts
-node update-version.js          # bump (ex. V1.0.14 → V1.0.15)
-
-# 3) commit + push → CI builda e publica :<commit> + :<versão> + :latest (NÃO deploya)
-git add -A && git commit -m "feat: <descrição> (vX.Y.Z)"
+# 2) commit + push → CI builda 1x e publica :<commit> + :latest (NÃO deploya)
+git add -A && git commit -m "feat: <descrição>"
 git push origin main
 
-# 4) tag = "aprovado p/ produção" → CI (hoje REBUILDA ✅) promove + deploya na VPS1
-git tag v1.0.15 && git push origin v1.0.15
+# 3) tag = "aprovado p/ produção" → job PROMOTE re-tagueia :<commit>→:vX.Y.Z (SEM rebuild) + deploya
+#    (o número da versão é livre — não precisa casar com nenhum arquivo)
+git tag -a vX.Y.Z -m "release vX.Y.Z" && git push origin vX.Y.Z
 
-# 5) verificar SEM SSH:
-curl -s https://scoreodonto.com/api/version     # → version/commit/environment
+# 4) verificar (sem SSH)
+curl -s https://scoreodonto.com/api/version     # → vX.Y.Z · <commit> · PROD
 ```
 
-**Backup do banco de PRODUÇÃO antes de releases sensíveis** (migrações rodam no boot; aditivas/idempotentes):
+**Backup do banco de PRODUÇÃO antes de releases sensíveis** (via container, pois não há shell na VPS3):
 ```bash
-ssh deploy@10.99.0.3 'pg_dump -Fc scoreodonto -f ~/backups/scoreodonto_$(date +%Y%m%d_%H%M).dump'
+docker run --rm -e PGPASSWORD=<senha> -v /home/deploy/backups:/b postgres:18 \
+  pg_dump -h 10.99.0.3 -U scoreodonto_user -d scoreodonto -Fc -f /b/scoreodonto_$(date +%Y%m%d_%H%M).dump
 ```
 
-> ### ⚠️ Fase transitória — por que `APP_VERSION`/`constants.ts` ainda existem
-> Estamos entre o **modelo antigo** (versão escrita à mão em `constants.ts`) e o **novo**
-> (identidade pelo **commit**; tags só promovem). Até o **Passo 5**, o CI ainda lê `APP_VERSION`
-> para nomear a imagem → o bump manual continua **necessário para evitar colisão de tags no
-> registry** (republicar `:vX.Y.Z` com outro código quebraria *"uma tag = um artefato"*).
-> **Após o Passo 5:** `constants.ts` e `update-version.js` são removidos, a identidade passa a
-> ser o commit, e tags apenas **promovem** artefatos já construídos.
-
 ---
 
 ## 6. Rollback ✅
 
-Reverter o **código** é seguro (migrações só adicionam). Por imagem, **sem rebuild**:
+Por imagem, **sem rebuild** — na VPS1:
 ```bash
-ssh deploy@10.99.0.1
-/home/deploy/stack/scoreodonto.com/deploy-prod.sh v1.0.13   # tag anterior → pull + up --no-build
+/home/deploy/stack/scoreodonto.com/deploy-prod.sh <tag-ou-commit-anterior>   # pull + up --no-build
 ```
-Restaurar o dump do banco só em caso extremo (`pg_restore --clean`).
+⚠️ A referência confiável é o **commit** (`:<sha>`). Tags `:vX.Y.Z` antigas (pré-Passo 5) podem ter sido republicadas com código diferente — a partir do Passo 5, `:vX.Y.Z` é sempre um alias imutável do commit. Migrações são aditivas (voltar o código é seguro). Dump em `/home/deploy/backups/` só em extremo.
 
 ---
 
-## 7. Passo 5 — "tag promove, não builda" 🎯
+## 7. Follow-ups (não bloqueiam)  🎯
+- `GET /api/health` (monitoramento/diagnóstico).
+- **Política de retenção** do registry (uma imagem `:<commit>` por push acumula).
+- Reconciliar o repo na VPS1 (working tree sujo, não afeta o deploy por imagem).
 
-Desenho **aprovado (17/jun/2026), não aplicado**. Refina o CI existente para Build Once → Promote → Deploy:
-- `build.yml` → 2 jobs por ref: **build** (só push; publica `:<commit>`+`:latest`, sem `APP_VERSION`); **promote** (só tag; re-tag `:<commit>→:vX.Y.Z` via `docker buildx imagetools create`, sem rebuild) → deploy.
-- **Validação de integridade antes do deploy:** existe `backend:<C>` e `frontend:<C>`? digests válidos? alias `:vX.Y.Z` == digest de `:<C>`? front e back do **mesmo commit**? Só então deploy (evita deploy parcial).
-- Decisões fechadas: manter **`:<commit>`** (sem prefixo); **falhar** se o commit não foi pushado (nunca buildar na tag); **`:latest`** só conveniência.
-- Eliminar `update-version.js` + `frontend/constants.ts` (a versão passa a nascer da **tag git**).
-- Follow-ups: `GET /api/health`; **política de retenção** do registry.
-
-Racional completo em `deploy.md` e na memória `project-cicd-tag-promove-nao-rebuilda`.
-
----
-
-> **Sequência acordada para fechar o drift:** (1) doc honesta com status ✅/🧪/🎯 [este doc] → (2) commitar Passos 1/3/4 → (3) promover → (4) confirmar `/api/version` → (5) elevar `VERDADE-HOJE.md` a doc principal (com esta convenção e precedência) → (6) Passo 5 → (7) atualizar docs. À medida que cada item 🧪 for promovido, vira ✅ aqui.
+Racional do modelo em `deploy.md`; histórico em `project-cicd-tag-promove-nao-rebuilda` (memória).

doc/VERDADE-HOJE.md

@@ -9,8 +9,8 @@
 ### 1. Onde está o código?
 - **Fonte da verdade:** Gitea na **VPS3**, repo `ruicesar/scoreodonto.com`.
 - **Dev (trabalho):** VPS4 em `/home/deploy/stack/scoreodonto.com`.
-- **Produção:** VPS1 roda **imagens versionadas do registry** (não código-fonte). No ar: **v1.0.15 · commit `f2eb90c`**.
-- **Documentação:** centralizada em `scoreodonto.com/documentação/`.
+- **Produção:** VPS1 roda **imagens versionadas do registry** (não código-fonte). No ar: **v1.0.16 · commit `471c2c2`**.
+- **Documentação:** centralizada em `scoreodonto.com/doc/` (pasta única).
 
 ### 2. Onde está o banco?
 - **Produção:** PostgreSQL no host da **VPS3** (`10.99.0.3:5432`), banco `scoreodonto`, user `scoreodonto_user`.
@@ -25,12 +25,12 @@
 ### 4. Quem faz deploy?
 - **CI/CD por tag (Gitea Actions).** Push na `main` → o runner `act_runner` "vps4-builder" (VPS4, rootless) builda e **publica no registry** (NÃO deploya). `git tag vX.Y.Z && git push` → CI + job `deploy` promove para a VPS1 (`deploy-prod.sh`).
 - **Produção consome imagem** (`pull` + `up -d --no-build`).
-- ⚠️ Hoje a **tag rebuilda** antes de promover; o **Passo 5** mudará para a tag apenas **re-taguear** o artefato já construído por commit.
+- ✅ **Build Once → Promote (Passo 5, validado em produção):** push builda 1× e publica por **commit** (`:<sha>`); a **tag re-tagueia** esse artefato como `:vX.Y.Z` (sem rebuild — digest idêntico) e deploya. Provado em v1.0.16 (`:v1.0.16` == `:471c2c2`, mesmo digest).
 
 ### 5. Como versiona?
-- A versão exibida vem do **backend em runtime**: `GET /api/version` (de `process.env`), mostrada em **Configurações → "Sobre o sistema"** e nas telas públicas (o frontend consome via `useAppVersion()`, não embute mais a versão). No ar: **v1.0.15 · `f2eb90c` · PROD**.
-- No deploy, `APP_VERSION` (= tag) e `APP_ENV=PROD` são **injetados em runtime**; `commit`/`build` vêm carimbados na imagem.
-- ⚠️ **Legado transitório:** `frontend/constants.ts` (`APP_VERSION`) + `update-version.js` ainda existem **só** para o CI nomear a imagem (bump manual evita colisão de tag). Serão **eliminados no Passo 5** (a versão nascerá da tag git).
+- A versão exibida vem do **backend em runtime**: `GET /api/version` (de `process.env`), mostrada em **Configurações → "Sobre o sistema"** e nas telas públicas (o frontend consome via `useAppVersion()`, não embute mais a versão). No ar: **v1.0.16 · `471c2c2` · PROD**.
+- A versão **nasce da tag git** e é **injetada no deploy em runtime** (`APP_VERSION`=tag, `APP_ENV=PROD`); `commit`/`build` vêm carimbados na imagem.
+- ✅ **`constants.ts`/`update-version.js` foram removidos** (Passo 5) — não há mais versão manual.
 
 ### 6. Como volta uma versão (rollback)?
 - **Por imagem, sem rebuild:** na VPS1, `./deploy-prod.sh <ref-anterior>` → `pull` + `up -d --no-build`.
@@ -39,4 +39,4 @@
 ---
 
 ## Veredito de uma linha
-> O código vive no Gitea (VPS3); a **produção (VPS1) roda imagens versionadas do registry** (hoje **v1.0.15**), sem buildar; o **DEV está isolado no `pgdev`** (não toca o banco de produção). **CI/CD por tag ativo**, com **versão visível em runtime** (`/api/version` → Configurações). Pendência técnica principal: **Passo 5** (tag promove sem rebuild; eliminar o `APP_VERSION` manual).
+> O código vive no Gitea (VPS3); a **produção (VPS1) roda imagens versionadas do registry** (hoje **v1.0.16**), sem buildar; o **DEV está isolado no `pgdev`** (não toca o banco de produção). **CI/CD por tag ativo** no modelo **Build Once → Promote → Deploy** (push builda por commit; tag re-tagueia sem rebuild e deploya — validado em v1.0.16), com **versão visível em runtime** (`/api/version` → Configurações) nascendo da tag git.

frontend/App.tsx

@@ -8,6 +8,7 @@ import {
 } from 'lucide-react';
 
 import { ToastContainer } from './components/Toast.tsx';
+import { useAppVersion } from './buildInfo.ts';
 
 import { Dashboard } from './views/Dashboard.tsx';
 import { LeadsView } from './views/LeadsView.tsx';
@@ -265,6 +266,7 @@ const MobileBottomNav: React.FC<{
 
 // ------- App -------
 const App: React.FC = () => {
+  const ver = useAppVersion();
   const [isSidebarOpen, setSidebarOpen] = useState(false);
   const [, forcePwRerender] = useState(0); // re-avalia o modal de troca obrigatória de senha
   const currentRole = HybridBackend.getCurrentRole();
@@ -577,6 +579,10 @@ const App: React.FC = () => {
         </main>
       </div>
       <ToastContainer />
+      {/* Versão sempre visível no canto inferior direito (lê /api/version; não bloqueia cliques) */}
+      <div className="fixed bottom-1.5 right-2 z-40 pointer-events-none select-none text-[10px] font-mono text-gray-400/70">
+        {ver.version}
+      </div>
     </>
   );
 };