# PrevGame no cPanel com Node.js

Este pacote preserva o jogo e acrescenta inicialização CommonJS em `app.js`,
carregamento dos módulos ESM e conexão explícita com Passenger. A pasta inteira
é a aplicação. Os arquivos web estão prontos em `dist/client` e o backend em
`dist/server`. Não é necessário compilar para instalar.

## Configurar pelo painel

1. No Gerenciador de Arquivos, envie e extraia o ZIP na pasta pessoal da conta.
   A pasta final deve conter `app.js`, `package.json`, `portable`, `dist` e `drizzle`.
2. Use um subdomínio dedicado e habilite seu certificado SSL/AutoSSL.
3. Abra **Setup Node.js App** e crie uma aplicação com os campos abaixo.
4. Cadastre as variáveis, salve e use **Start App / Restart**.

| Campo | Valor deste pacote |
|---|---|
| Node.js version | 24.x ou 22.x a partir de 22.13.0 |
| Application mode | Production |
| Application root | PrevGame_Jornada, relativo à pasta pessoal |
| Application URL | Seu subdomínio, com caminho `/` |
| Application startup file | app.js |

O diretório raiz da aplicação deve ficar fora de `public_html`. Se o provedor
permitir escolher separadamente o Document Root público, use `dist/client`.
Não exponha a pasta inteira como um diretório de arquivos do Apache. O domínio
precisa estar associado ao aplicativo Node.js, e não apenas a uma página HTML.

### Variáveis

| Nome | Valor |
|---|---|
| NODE_ENV | production |
| PUBLIC_URL | https://jogo.seudominio.com.br |
| ADMIN_PASSWORD | Senha exclusiva, com 16 ou mais caracteres |
| DATA_DIR | /home/SEU_USUARIO/PrevGame_Jornada/dados |
| OPENAI_API_KEY | Opcional; chave da entidade para gerar perguntas por IA |
| OPENAI_QUIZ_MODEL | Opcional; gpt-5-mini é o padrão |

Use seus caminhos e domínio reais. Não copie o texto de exemplo como senha.
PUBLIC_URL não deve conter subpastas. PORT e HOST não são necessários no cPanel:
a conexão é entregue ao Passenger. Não configure Nginx, Docker, PM2 ou systemd
adicionais para esta modalidade.

Alternativamente, copie `.env.example` para `.env` e preencha as variáveis ali.
O inicializador lê esse arquivo se existir; valores já definidos no ambiente do
processo têm prioridade. Prefira um único lugar para manter a configuração.
Nunca publique `.env` ou a pasta `dados`. Restrinja suas permissões à conta.

## Se o menu for Application Manager

Registre uma aplicação apontando para `/home/SEU_USUARIO/PrevGame_Jornada`, escolha
o domínio exclusivo, Base Application URL `/` e ambiente Production. O arquivo
`app.js` é o inicializador padrão. Cadastre as mesmas variáveis. Se as opções de
Node.js ou variáveis não aparecerem, o provedor precisa disponibilizá-las.

Não execute `npm start` ao mesmo tempo que a aplicação gerenciada pelo painel.
Para solicitar reinício, use o botão do painel ou regrave `tmp/restart.txt`.

## Verificar a instalação

- Abra `/login`, entre como `admin` e acesse `/admin`.
- Envie um regulamento PDF com texto ou TXT; confira o conteúdo extraído.
- Revise as regras e ative uma versão. Upload sozinho não altera os cálculos.
- Prepare perguntas manualmente ou configure a chave para gerar com IA.
- Saia da conta, crie um participante, conclua uma jornada e confira `/report`.
- Reinicie pelo cPanel e confirme que partida e documento continuam disponíveis.
- Confira controles e leitura no celular.

Os relatórios agregados aparecem com pelo menos cinco participantes distintos no
filtro. As contas são locais, com nome de acesso e senha; não verificam identidade
civil e não oferecem recuperação automática de senha por e-mail. O administrador
não deve compartilhar sua senha. Alterá-la nas variáveis e reiniciar invalida as
sessões administrativas existentes.

## Erros comuns

| Sintoma | O que conferir |
|---|---|
| Erro 503 na abertura | Log Passenger, variáveis obrigatórias, senha e versão do Node.js |
| ERR_REQUIRE_ESM | Startup deve ser app.js deste pacote; mantenha todos os package.json incluídos |
| No such built-in module: node:sqlite | Node.js antigo ou sem suporte a SQLite; selecionar 22.13+ ou 24 |
| Diretório ou arquivo não encontrado | Application root precisa conter app.js; evite uma pasta duplicada após extrair |
| Arquivos JS/CSS não carregam | Instalar em subdomínio com caminho `/`, sem subpasta |
| Origem não autorizada ou login não permanece | PUBLIC_URL deve coincidir com o domínio HTTPS, inclusive www se usado |
| Banco sem permissão | DATA_DIR precisa permitir escrita à conta cPanel, fora das pastas públicas |
| Upload grande falha | Limites do provedor: app aceita arquivo de até 10 MB; requisição multipart até 16 MB |
| IA não gera perguntas | Configurar OPENAI_API_KEY, conferir créditos e saída HTTPS e reiniciar |

A leitura de PDF/DOCX já está incluída. PDFs digitalizados exigem transcrição
conferida. O timeout da hospedagem precisa permitir a geração por IA, que pode
levar cerca de 90 segundos; isso é configurado pelo provedor se necessário.

## Dados, atualização e backup

O banco SQLite é criado na primeira inicialização, junto com o diretório de
uploads. Use disco local persistente; não use diretório temporário ou volume de
rede compartilhado entre servidores. Migrations são registradas e aplicadas uma
vez. O adaptador espera até cinco segundos por bloqueios de banco.

Este ZIP não traz contas, arquivos enviados ou partidas da versão no ChatGPT.
Para atualizar uma instalação própria já existente, mantenha o mesmo DATA_DIR e
faça backup antes. Pare a aplicação no painel, copie a pasta de dados inteira
(banco, arquivos auxiliares e uploads) e guarde as variáveis separadamente.
Nunca exclua a pasta de dados ao substituir os arquivos do aplicativo.

## Manutenção do código

A execução não necessita instalar pacotes: `dist` e os leitores de documentos já
estão completos. Caso o responsável altere os fontes, use o ambiente Node.js
selecionado no cPanel, execute `npm ci` e `npm run build`, depois reinicie. Não envie
uma pasta `node_modules` local: deixe o seletor da hospedagem gerenciar seu ambiente.

Verificação local incluída: `npm run test:cpanel`. Cobre inicialização CommonJS,
ligação Passenger simulada, permissões, jornadas, upload e persistência. A revisão
foi executada com Node.js 24.19.0; Node.js 22.13+ tem as APIs necessárias, mas não
foi executado neste ambiente. A configuração real do provedor deve ser conferida.

## Referências da hospedagem

- cPanel: https://docs.cpanel.net/knowledge-base/web-services/how-to-install-a-node.js-application/
- CloudLinux: https://docs.cloudlinux.com/cloudlinuxos/cloudlinux_os_components/
- Passenger: https://www.phusionpassenger.com/library/indepth/nodejs/reverse_port_binding.html
- Node.js 22.13: https://nodejs.org/en/blog/release/v22.13.0