docs: documentação única da stack — deploy/infra/projetos + regras (LEIA-PRIMEIRO)

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

deploy/modelo.md

@@ -0,0 +1,20 @@
+# Deploy — Modelo (Build Once → Promote → Deploy)
+
+> Situação: **como o deploy funciona, em conceito.** Estado real verificado em 17/jun/2026.
+
+**Push** na `main` builda **uma vez** e publica a imagem por **commit**; a **tag `vX.Y.Z`** **re-tagueia** essa mesma imagem (sem rebuild) e deploya. **Produção nunca builda — só executa imagens prontas.**
+
+```
+ PUSH main (commit C)                 TAG vX.Y.Z (no commit C)
+        │                                     │
+        ▼                                     ▼
+   CI: build (1x)                       CI: promote (SEM build)
+   publica :C + :latest                 re-tag :C → :vX.Y.Z (MESMO digest) + deploy
+        ▼                                     ▼
+   registry (Gitea)                     produção: pull :vX.Y.Z + up --no-build
+```
+
+Garantia central: **a imagem em produção é byte-idêntica à que foi buildada e testada**. A tag é só um rótulo de release sobre um artefato imutável.
+
+- **Por que importa:** acaba a recompilação na promoção (que podia gerar imagem diferente da testada) e a colisão de tags. Implementação de referência: scoreodonto.com (`v1.0.18`).
+- Situações relacionadas: `subir-release.md`, `rollback.md`, `versionamento.md`; infra em `../infra/`.

deploy/rollback.md

@@ -0,0 +1,16 @@
+# Deploy — Rollback (reverter)
+
+> Situação: **a versão nova quebrou, quero voltar.**
+
+Por imagem, **sem rebuild** — na VPS1:
+```bash
+/home/deploy/stack/<projeto>/deploy-prod.sh <tag-ou-commit-anterior>   # pull + up --no-build
+```
+
+- A referência confiável é o **commit** (`:<sha>`) ou a **tag de release** (`:vX.Y.Z`) — no modelo Build Once, `:vX.Y.Z` é alias imutável do commit.
+- As migrações de banco são **aditivas** (só adicionam tabelas/colunas) → **voltar o código é seguro**, o schema extra fica inerte.
+- Restaurar o **dump do banco** só em caso extremo:
+  ```bash
+  pg_restore -d "postgresql://<user>:<senha>@10.99.0.3:5432/<banco>" --clean <arquivo>.dump
+  ```
+- Recuperação em **minutos** (só troca a imagem). Backups ficam em `/home/deploy/backups/`.

deploy/subir-release.md

@@ -0,0 +1,31 @@
+# Deploy — Subir um release
+
+> Situação: **quero colocar uma versão nova em produção.**
+
+⚠️ **Regra de ouro:** confirme **DEV ou PRODUÇÃO** antes de agir. `dev.<projeto>` = VPS4 (descartável). `<projeto>` sem `dev.` = VPS1 (real). **Nunca** `git push --force` na `main`. Push e tag exigem **autorização explícita do administrador**.
+
+```bash
+# 1) VPS4 — validar em DEV
+node --check backend/server.js
+docker compose build scoreodonto-backend scoreodonto-frontend
+docker compose up -d --force-recreate scoreodonto-backend scoreodonto-frontend   # conferir em dev.<projeto>
+
+# 2) commit + push → o CI builda 1x e publica :<commit> + :latest (NÃO deploya)
+git add -A && git commit -m "feat: <descrição>"
+git push origin main
+
+# 3) tag = "aprovado para produção" → o CI re-tagueia :<commit>→:vX.Y.Z (SEM rebuild) e deploya
+git tag -a vX.Y.Z -m "release vX.Y.Z" && git push origin vX.Y.Z
+
+# 4) verificar (sem SSH)
+curl -s https://<projeto>/api/version    # → vX.Y.Z · <commit> · PROD
+curl -s https://<projeto>/api/health     # → status ok
+```
+
+**Backup do banco de produção antes de releases sensíveis** (não há shell na VPS3; usar container):
+```bash
+docker run --rm -e PGPASSWORD=<senha> -v /home/deploy/backups:/b postgres:18 \
+  pg_dump -h 10.99.0.3 -U <user> -d <banco> -Fc -f /b/<banco>_$(date +%Y%m%d_%H%M).dump
+```
+
+> Pré-requisito do passo 3: o commit já tem que estar publicado no registry (passo 2). Se não estiver, o CI **falha de propósito** ("faça push antes da tag") — nunca builda na tag.

deploy/versionamento.md

@@ -0,0 +1,19 @@
+# Deploy — Versionamento e saúde
+
+> Situação: **como a versão é definida e onde ela aparece; como checar saúde.**
+
+## Versão
+- A versão é **definida pela tag git** (`vX.Y.Z`) — **não** se escreve versão à mão em arquivo (não existe mais `constants.ts`/`update-version.js`).
+- `commit`/`build` são carimbados no **build** da imagem (imutáveis); `version`/`environment` são **injetados no deploy em runtime** (a partir da tag).
+- Em **DEV** a versão aparece como `dev` (não há release); o número só existe em produção.
+
+## Onde a versão aparece (tudo em runtime, lendo `/api/version`)
+- **`vX.Y.Z` fixo no canto inferior direito** de toda página.
+- Tela de **Configurações → "Sobre o sistema"**.
+- O frontend **não embute** versão — consome `GET /api/version`. Fonte única = backend.
+
+## Endpoints
+- **`GET /api/version`** → `{ name, version, commit, build, environment }`.
+- **`GET /api/health`** → `{ status, version, commit, environment, uptime_s, checks }`.
+  - **banco** é crítico: se cair → `status: down` + **HTTP 503**.
+  - **cache** é opcional: se cair → `status: degraded` (HTTP 200); `disabled` se desligado.