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

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-17 17:31:50 +02:00
commit c0ca88c028
14 changed files with 582 additions and 0 deletions
@@ -0,0 +1,45 @@
+> ⚠️ EM DESUSO desde 2026-06-17 — consolidado em /home/deploy/stack/documentos-unicos/ (ver LEIA-PRIMEIRO.md). Mantido só como histórico; NÃO usar como referência.
+
+---
+
+# 🔢 Contador de Versões e Painel de Deploy
+
+O NewWhats conta com um sistema de versionamento automatizado e monitoramento integrado diretamente no painel administrativo (Admin settings).
+
+---
+
+## 1. Funcionamento do Versionamento Automático (`v1.+1`)
+
+A cada ciclo de build executado na **VPS 4 (Build Server)**, o script `deploy-prod-builder.sh` incrementa automaticamente as versões e constrói o histórico de deploys:
+
+1. Executa o script auxiliar `update-version.js` na raiz do projeto.
+2. Esse script lê o histórico em `deploys.json`.
+3. Incrementa o contador de builds (Ex: `#7` -> `#8`).
+4. Incrementa a versão semântica de forma menor, ex: `v1.0.7` -> `v1.0.8`.
+5. Registra metadados cruciais do commit atual do Git:
+   * Código de Hash do Commit.
+   * Mensagem do último commit.
+   * Autor do Deploy.
+   * Carimbo de data/hora exato do deploy.
+6. Grava arquivos finais:
+   * `version.json` e `deploys.json` (usados pelo Backend).
+   * `frontend/public/version.json` e `frontend/public/deploys.json` (consumidos pelo Frontend).
+
+---
+
+## 2. A Interface do Usuário (Painel de Deploys)
+
+Integrado perfeitamente nas Configurações do Administrador, adicionamos uma aba dedicada a **Versões**, que exibe com design moderno e premium (gradientes vibrantes e micro-animações):
+
+* **Versão Ativa**: Exibe a versão ativa atual (ex: `v1.0.8`) com o respectivo número de build (`build #8`).
+* **Último Commit**: Mostra o hash abreviado e a mensagem do último commit que disparou o deploy atual.
+* **Histórico de Deploys**: Uma tabela organizada exibindo o histórico cronológico de todos os deploys efetuados, seus status, data/hora e mensagem explicativa.
+* **Disparo Manual Webhook**: Um botão "Verificar atualizações" que consome o endpoint `/deploys/trigger` do backend, disparando de forma assíncrona o webhook de deploy automático na VPS 4 com pooling de progresso dinâmico na tela.
+
+---
+
+## 3. Segurança e Sincronização GitOps
+
+Para garantir total consistência e impedir perda de dados:
+* O script de build executa `git fetch` e `git reset --hard origin/main` antes de compilar.
+* **Regra Fundamental**: Qualquer alteração para entrar em produção deve ser primeiramente comitada localmente e empurrada para o repositório Gitea (`git push origin main`). O script de deploy puxará as alterações atualizadas do servidor Git de forma automatizada e segura!