# Instalar o AquaPay no cPanel (backend + frontend)

> Não tive acesso a um cPanel real para testar. O backend, o `.env`, o SMTP, as cópias de segurança e o `app.cjs` estão testados localmente; o comportamento do Passenger/LiteSpeed do seu anfitrião tem de ser confirmado pelos testes do passo 8.

## 0. Requisitos
* cPanel com **"Setup Node.js App"** e **Node.js 22.13 ou superior** na lista de versões. O backend usa o SQLite incluído no Node 22 (`node:sqlite`). **Se o seu anfitrião só oferece Node 20 ou inferior**, peça-lhe que active o Node 22 ou use um VPS (Ubuntu + Node 22 + Caddy). Posso adaptar o backend a Node 20 (com `better-sqlite3`) se for preciso.
* Dois subdomínios com HTTPS: **`api.exemplo.co.mz`** (backend) e **`app.exemplo.co.mz`** (frontend). Crie-os em *Domains* e confirme o cadeado (AutoSSL, em *SSL/TLS Status*). Estar no mesmo domínio principal é importante: o cookie da sessão é `SameSite=Strict`.
* Active a **autenticação de dois factores** na sua conta cPanel e use uma senha forte: quem entra no cPanel tem acesso aos segredos do sistema.

## 1. Backend (API) — `api.exemplo.co.mz`
1. **Enviar os ficheiros:** em *File Manager*, na pasta pessoal (`/home/UTILIZADOR/`, **fora de `public_html`**), envie `aquapay-backend.zip` e extraia-o: fica `/home/UTILIZADOR/aquapay-backend`.
2. **Pasta de dados:** crie `/home/UTILIZADOR/aquapay-data` e `/home/UTILIZADOR/aquapay-backups` (permissões `700`).
3. **Segredos:** no seu computador, na pasta do backend, execute `node scripts/gen-secrets.js` e guarde o resultado num local seguro (cofre de senhas). **Faça cópia das chaves `SECRET_*`**: sem elas os NUIT/documentos cifrados e as senhas não se recuperam.
4. **Ficheiro `.env`:** em `/home/UTILIZADOR/aquapay-backend/.env` (permissões **`600`**) escreva:
```
NODE_ENV=production
APP_ORIGINS=https://app.exemplo.co.mz
PUBLIC_BASE_URL=https://api.exemplo.co.mz
TRUST_PROXY_HOPS=1
DATABASE_PATH=/home/UTILIZADOR/aquapay-data/aquapay.db
BACKUP_DIR=/home/UTILIZADOR/aquapay-backups

SECRET_PEPPER=...            # do gen-secrets
SECRET_WEBHOOK=...
SECRET_DATA_KEY=...
SECRET_BLIND_KEY=...

PAYMENTS_MODE=live
OTP_DELIVERY=smtp
SMTP_HOST=mail.exemplo.co.mz
SMTP_PORT=465
SMTP_SECURE=true
SMTP_USER=noreply@exemplo.co.mz
SMTP_PASS=...
SMTP_FROM="Frogodó AquaPay <noreply@exemplo.co.mz>"
```
   (Crie antes a conta de email `noreply@exemplo.co.mz` em *Email Accounts*.) As variáveis definidas no painel *Setup Node.js App* têm prioridade sobre o `.env`.
5. **Criar a aplicação:** *Setup Node.js App → Create Application*:
   * Node.js version: **22.x** (≥ 22.13) · Application mode: **Production**
   * Application root: `aquapay-backend` · Application URL: **`api.exemplo.co.mz`**
   * Application startup file: **`app.cjs`**
   * *Create* (não é preciso "Run NPM Install": o backend não tem dependências) e depois **Restart**.
6. **Criar o 1.º administrador:** no *Terminal* do cPanel (ou SSH), use o comando "enter to the virtual environment" que aparece na página da aplicação, e depois:
```
cd ~/aquapay-backend && npm run create-admin
```
   Mostra uma senha temporária **uma única vez**; será obrigado a trocá-la no primeiro login (e ela caduca em 7 dias). *Sem Terminal:* crie um *Cron Job* "uma vez" com `cd ~/aquapay-backend && ADMIN_PASSWORD='SenhaForte#2026x' node scripts/create-admin.js --name "O Seu Nome" --email eu@exemplo.co.mz --phone 84XXXXXXX` (use o caminho do Node do passo 7) e **apague o cron job logo a seguir**.
7. **Cópias de segurança diárias:** *Cron Jobs* → 1 vez por dia: `cd /home/UTILIZADOR/aquapay-backend && /home/UTILIZADOR/nodevenv/aquapay-backend/22/bin/node scripts/backup.js >> /home/UTILIZADOR/aquapay-backups/backup.log 2>&1` (confirme o caminho do Node na página da aplicação). Descarregue as cópias regularmente para fora do servidor e guarde as chaves do `.env` **separadas** das cópias.
8. **Testar:**
   * Abra `https://api.exemplo.co.mz/api/health` → deve mostrar `{"status":"ok"}`.
   * **IP real dos clientes:** depois de um pedido, veja o log da aplicação (ficheiro `stderr.log`/`stdout.log` na pasta da aplicação ou em `~/logs`): o campo `ip` tem de mostrar o IP do visitante. Se aparecer vazio ou sempre o mesmo, os limites de tentativas ficam partilhados por todos: ajuste `TRUST_PROXY_HOPS` (0, 1 ou 2) até aparecer o IP certo.

## 2. Frontend — `app.exemplo.co.mz`
1. No seu computador, na pasta `aquapay` (frontend), crie `.env.production` com:
```
VITE_API_URL=https://api.exemplo.co.mz
```
2. `npm install` e `npm run build` → cria a pasta **`dist`** (já inclui o `.htaccess` com HTTPS forçado e cabeçalhos de segurança).
3. Em *File Manager*, abra a pasta do subdomínio (`/home/UTILIZADOR/app.exemplo.co.mz` ou `public_html`, conforme criou) e envie **todo o conteúdo de `dist`** (incluindo `.htaccess`; active "Show Hidden Files").
4. Abra `https://app.exemplo.co.mz` e entre com o administrador. Não precisa de regras de reescrita: a aplicação usa rotas com `#`.
5. Confirme que `https://app.exemplo.co.mz/.env` e `.../.git` dão erro 404/403.

## 3. Depois de instalar
* **Pagamentos online (M-Pesa, e-Mola, mKesh, cartão):** com `PAYMENTS_MODE=live` respondem "integração não configurada" até serem ligados às operadoras (`src/services/providers`). Tudo o resto (facturas, pagamentos no escritório, contratos, relatórios) funciona.
* **SMS:** opcional. Para além do email pode usar `OTP_DELIVERY=smtp,webhook` com `MESSAGING_URL` (gateway de SMS). Sem SMS, a senha inicial do cliente (= telefone) é só comunicada por email e o cliente recebe aviso por email.
* **Actualizar:** faça uma cópia de segurança, envie os ficheiros novos **sem apagar `.env` nem a pasta de dados**, clique **Restart** no *Setup Node.js App*. As migrações da base de dados correm sozinhas no arranque.
* **Não** use várias instâncias/cluster (os limites de tentativas estão em memória; uma instância basta para uma operadora local).

## 4. Problemas comuns
| Sintoma | O que ver |
|---|---|
| A aplicação não arranca | `stderr.log`: "Node.js 22.13…" → mude a versão; "Configuração insegura: …" → corrija o `.env` conforme a mensagem |
| Erro de rede/CORS no frontend | `APP_ORIGINS` tem de ser **exactamente** `https://app.exemplo.co.mz` (sem `/` no fim); ambos em HTTPS |
| Entra mas a sessão cai ao recarregar | Cookie bloqueado: os dois subdomínios têm de estar no mesmo domínio principal e em HTTPS |
| 503/502 | Reinicie a aplicação; confirme memória/limites (LVE) do plano |
| "Demasiadas tentativas" para toda a gente | IP errado nos logs: ajuste `TRUST_PROXY_HOPS` (passo 8) |
| Não chegam emails | Teste o `SMTP_*` com um cliente de email; confirme a porta 465 e que `SMTP_FROM` usa o mesmo domínio da conta |
