# OPACC — GUIA DE IMPLEMENTAÇÃO E PUBLICAÇÃO (DEPLOYMENT GUIDE)
**Projeto:** OPACC — Gestão Cadastral (`opacc.cv`)  
**Documento:** `OPACC_CADASTRO_DEPLOYMENT_GUIDE.md`  
**Versão:** 1.0.0  
**Data:** 19 de novembro de 2026  

---

## 1. Arquitetura de Publicação Recomendada

A aplicação foi concebida para correr de forma **totalmente autónoma** do site WordPress `opacc.cv`, num subdomínio institucional dedicado — por exemplo:

- **Endereço recomendado:** `https://cadastro.opacc.cv`
- **Ligação a partir do site atual (`opacc.cv`):** Inserir botão/banner/link institucional no WordPress apontando para `https://cadastro.opacc.cv` (sem instalar plugins pesados nem alterar a base de dados WordPress).

Um único processo Node.js serve tanto a **API REST (`/api/v1/*`)** como o **Frontend SPA compilado (`frontend/dist`)**, simplificando radicalmente a operação, manutenção, backups e SSL.

---

## 2. Pré-requisitos do Servidor

- **Node.js:** v22.13+ ou **v24 LTS** (recomendado v24.x — inclui módulo nativo `node:sqlite`, sem necessidade de compiladores C/C++).
- **Memória RAM:** Mínimo 512 MB (recomendado 1 GB+).
- **Disco:** Mínimo 2 GB livres (base de dados + backups diários).
- **TLS / HTTPS:** Certificado SSL válido (Let's Encrypt / cPanel AutoSSL).

---

## 3. Instalação Passo-a-Passo (Ambiente de Testes ou Produção)

### Passo 1 — Copiar a aplicação
Transferir o diretório `opacc-gestao-cadastral/` para o servidor (ex.: `/var/www/opacc-gestao-cadastral`).

### Passo 2 — Configurar variáveis de ambiente
```bash
cd opacc-gestao-cadastral
cp .env.example .env
```
Editar `.env` com valores reais do ambiente:
```env
NODE_ENV=production
PORT=3080
HOST=127.0.0.1
APP_BASE_URL=https://cadastro.opacc.cv
CORS_ORIGIN=https://cadastro.opacc.cv
TRUST_PROXY=1
HTTPS_ENABLED=true

# Gerar com: node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
JWT_SECRET=<CHAVE_ALEATORIA_FORTE_96_CHARS>
CHALLENGE_SECRET=<CHAVE_ALEATORIA_FORTE_96_CHARS>

# Email institucional OPACC (OrangeHost / mail.opacc.cv)
SMTP_HOST=mail.opacc.cv
SMTP_PORT=465
SMTP_SECURE=true
SMTP_USER=cadastro@opacc.cv
SMTP_PASS=<PASSWORD_CONTA_EMAIL>
SMTP_FROM="OPACC — Gestão Cadastral <cadastro@opacc.cv>"
```

### Passo 3 — Instalar dependências e compilar o Frontend
```bash
npm --prefix backend install --omit=dev
npm --prefix frontend install
npm --prefix frontend run build
```

### Passo 4 — Inicializar Base de Dados Nova e Vazia (§5)
```bash
npm run db:init
```
> **Importante antes da entrada em produção:** Se o ambiente foi utilizado anteriormente para demonstração com dados `[TESTE DEMO]`, executar `npm run db:reset-empty` para garantir **0 membros e 0 submissões** antes da abertura oficial aos membros.

### Passo 5 — Executar a Suite de Verificação
```bash
npm test
```
Confirmar saída: `RESULTADO FINAL: 22 / 22 TESTES APROVADOS COM SUCESSO!`.

---

## 4. Opções de Alojamento

### Opção A — Servidor VPS Linux (Nginx + systemd / PM2) — *Recomendada*
1. Configurar serviço `systemd` ou `pm2`:
   ```bash
   pm2 start backend/src/server.js --name opacc-cadastro
   pm2 save && pm2 startup
   ```
2. Configurar proxy reverso **Nginx** com HTTPS (Certbot / Let's Encrypt):
   ```nginx
   server {
       listen 443 ssl http2;
       server_name cadastro.opacc.cv;

       ssl_certificate /etc/letsencrypt/live/cadastro.opacc.cv/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/cadastro.opacc.cv/privkey.pem;

       location / {
           proxy_pass http://127.0.0.1:3080;
           proxy_http_version 1.1;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
       }
   }
   ```

### Opção B — Alojamento Atual OrangeHost (cPanel — Setup Node.js App)
1. Criar subdomínio `cadastro.opacc.cv` no cPanel e ativar AutoSSL.
2. Em **Setup Node.js App**, selecionar Node.js 24 (se disponível no servidor OrangeHost; caso apenas Node 20/22 sem `node:sqlite`, recomenda-se Opção A VPS ou container Node 24).
3. Definir *Application startup file* como `backend/src/server.js` e adicionar variáveis de ambiente.

---

## 5. Procedimento de Backup e Recuperação

- **Backup automático diário (cron Linux, ex. 03:00):**
  ```cron
  0 3 * * * cd /var/www/opacc-gestao-cadastral && /usr/bin/node backend/src/db/backup.js >> /var/log/opacc-backup.log 2>&1
  ```
- **Backup / Restauro via Interface:** Aceder como Superadministrador em `/admin/configuracoes` → secção *Cópias de Segurança e Recuperação*.
- **Restauro seguro:** Antes de substituir a base de dados ativa, o motor verifica o checksum SHA-256 do ficheiro de backup e cria automaticamente um snapshot preventivo da base atual.

---

## 6. Ligação no Site WordPress Atual (`opacc.cv`)

Apenas **após autorização expressa da OPACC** (§20), adicionar no portal WordPress:
- Menu / Destaque principal: **"Atualização Cadastral (Circular n.º 27/CDIR/2026)"** → `https://cadastro.opacc.cv` (`target="_blank" rel="noopener"`).
