> ⚠️ 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.

---

# 🚀 Fluxo de Deploy Multi-VPS (VPS 1, VPS 3 e VPS 4)

Este guia descreve detalhadamente o fluxo GitOps e despacho de arquivos compilados entre os servidores do ecossistema NewWhats.

---

## 🗺️ Mapa de Papéis dos Servidores

```
  [ VPS 4: Builder ]  ───(git push)───►  [ VPS 3: Git/DB ]
          │                                      ▲
          │                                      │
   (rsync compiles)                       (DB Connections)
          │                                      │
          ▼                                      │
  [ VPS 1: Produção ] ───────────────────────────┘
```

| Servidor | IP VPN | Função Principal | Fluxo de Código |
|---|---|---|---|
| **VPS 1 (App Server)** | `10.99.0.1` | Execução em Produção | Recebe os arquivos compilados da VPS 4 |
| **VPS 3 (Data Server)** | `10.99.0.3` | Banco PostgreSQL & Gitea | Centraliza o Git e o banco de dados |
| **VPS 4 (Build Server)**| `10.99.0.4` | Desenvolvimento & Compilação | Compila a plataforma e despacha via Rsync |

---

## 🔄 Fluxo de Deploy Passo a Passo

O ciclo de deploy adota o modelo **Builder-to-Host** para garantir que servidores de execução de produção (VPS 1) não consumam recursos excessivos de CPU com compilações pesadas de Webpack/Next.js e TypeScript.

```mermaid
sequenceDiagram
    participant Dev as Desenvolvedor (VPS 4)
    participant Gitea as Gitea (VPS 3)
    participant Builder as Build Process (VPS 4)
    participant Prod as Produção Docker (VPS 1)

    Dev->>Gitea: git push origin main
    Dev->>Builder: Executa deploy-prod-builder.sh
    Builder->>Gitea: git fetch & reset --hard
    Builder->>Builder: Incrementa versão (update-version.js)
    Builder->>Builder: Compila Backend, Plugins & Frontend
    Builder->>Prod: rsync /dist e /node_modules
    Builder->>Prod: ssh restart containers
    Builder->>Gitea: git push (version bump)
```

---

## 🖥️ Detalhamento por Máquina

### 1️⃣ VPS 4 — O Motor de Compilação (Build / Builder)
Todas as modificações de código e atualizações são criadas e validadas nesta máquina.
1. O desenvolvedor realiza as alterações no código local.
2. Faz o commit e envia para a VPS 3:
   ```bash
   git add .
   git commit -m "feat: minha nova funcionalidade"
   git push origin main
   ```
3. Executa o script centralizador de deploy:
   ```bash
   bash /home/deploy/stack/clube67/deploy-prod-builder.sh
   ```
   * *O script limpa e reseta a pasta local para bater com a origin/main.*
   * *Roda `update-version.js` para incrementar o build (ex: `v1.0.9 (build #9)`).*
   * *Compila o backend, gera tipos Prisma, compila plugins e roda `next build`.*

4. **Sincronizar o incremento de versão no Gitea (Obrigatório):**
   Após o deploy com sucesso, os arquivos de versão estarão alterados localmente. É vital comitá-los para não apagar o contador de deploys no Gitea na próxima execução:
   ```bash
   git add deploys.json version.json frontend/public/deploys.json frontend/public/version.json
   git commit -m "chore(deploy): bump version"
   git push origin main
   ```

### 2️⃣ VPS 3 — O Orquestrador e Repositório (Git & Banco de Dados)
A VPS 3 é o coração dos dados do ecossistema. Ela roda o banco PostgreSQL diretamente no host e serve o Gitea.
* **Recebimento de Alterações (Push):** Quando a VPS 4 faz `git push`, a VPS 3 valida a autenticação de chaves SSH ou JWT e atualiza o branch `main`.
* **Disponibilização (Pull):** Durante o deploy automático, a VPS 4 executa `git fetch` e `git reset` apontando de volta para a VPS 3 para garantir consistência.

### 3️⃣ VPS 1 — O Servidor de Produção (App Server)
A VPS 1 roda os containers Docker `newwhats-backend-prod` e `newwhats-frontend-prod`.
* **Sem Compilação Local:** Ela nunca roda `npm run build` ou instala dependências de desenvolvimento.
* **Recebimento de Binários:** O script da VPS 4 envia apenas as pastas `/dist`, `/node_modules`, `package.json` e os arquivos do frontend prontos (`.next/`, `/public/`) via **rsync** de alta velocidade.
* **Reinício de Containers:** Após os arquivos serem transferidos para a pasta local da VPS 1, a VPS 4 faz um comando SSH seguro que dispara:
   ```bash
   docker compose restart newwhats-backend-prod newwhats-frontend-prod
   ```

---

## 🚦 Boas Práticas e Resolução de Conflitos
* **Nunca altere código diretamente na VPS 1:** Qualquer edição em produção será apagada no próximo deploy, pois o `rsync --delete` substitui todos os arquivos pelos compilados na VPS 4.
* **Commite antes de Buildar:** Lembre-se sempre de subir suas alterações para o Gitea (`git push`) antes de rodar o deploy-prod-builder.sh, pois o script reseta a árvore de diretórios local para bater com o Git remoto.