# TG15 On — edição para cPanel

Pacote de preparação para implantação, com PHP 8.2+ e MySQL/MariaDB. O protótipo HTML anterior permanece separado. Esta edição requer validação no servidor antes de receber dados reais.

## O que está incluído

- Login por e-mail e senha; contas criadas exclusivamente pelo administrador.
- Painel em `admin.php`: criar e editar usuários; alterar nome, e-mail e perfil; ativar/desativar; redefinir a senha. Desativar preserva os registros.
- Perfis administrador e usuário comum. O painel não exibe os registros de saúde de outros usuários. O administrador também pode usar seu próprio diário.
- Redefinição administrativa de senha; recuperação por e-mail opcional, com link de uso único por 30 minutos.
- Salvamento no banco por usuário, com controle de revisão para impedir sobrescrita silenciosa entre dispositivos/abas.
- Aplicações, estoque, frascos, peso, bem-estar e edição dos registros, aproveitando o app atual.
- Exportação JSON e importação dos registros anteriores, com validação no servidor. Importar substitui os registros da conta; exporte antes.
- Sessões com cookies Secure/HttpOnly/SameSite, proteção CSRF, consultas preparadas, limitação de tentativas, senhas com hash e registro de ações administrativas.
- Sessões encerradas após 30 minutos de inatividade, limite absoluto de 12 horas e invalidação de sessões antigas ao alterar/desativar uma conta.

## 1. Preparar a hospedagem

1. Em **MultiPHP Manager** / **Select PHP Version**, selecione PHP **8.2 ou superior** mantido pelo provedor. Ative `PDO`, `pdo_mysql`, `session` e `json` (algumas extensões já são incorporadas). Argon2id é usado quando disponível; caso contrário, o algoritmo padrão do PHP.
2. Crie o subdomínio **`tg15on.wellbits.com.br`** e ative o certificado SSL/AutoSSL. O app exige HTTPS. O endereço foi definido para esta implantação; sua criação no cPanel e no DNS ainda precisa ser executada e validada.
3. Extraia o pacote em uma pasta fora da raiz pública, por exemplo `/home/SUA_CONTA/tg15/`.
4. Configure a raiz documental do subdomínio para **`/home/SUA_CONTA/tg15/public`**. Somente `public/` pode ser acessível pela web. As pastas `private/`, `database/` e `tests/` ficam fora da raiz documental. Não coloque o pacote inteiro dentro de `public_html`.
5. Se o plano não permitir essa raiz documental, mantenha as mesmas pastas irmãs fora da raiz pública e peça ao provedor o ajuste do subdomínio. Não mova `config.php` para uma pasta pública.

O cPanel precisa informar o IP do servidor para criar o registro **A** de `tg15on` no DNS de `wellbits.com.br` (se a zona não for gerenciada automaticamente no próprio cPanel). Não use um IP presumido. Após o DNS apontar ao servidor, emita/verifique o AutoSSL. Se houver proxy, confirme com o provedor que o PHP recebe HTTPS corretamente.

## 2. Criar o banco

Na tela enviada: **Database Wizard** (ou **Manage My Databases**):

1. Crie o banco MySQL/MariaDB e um usuário exclusivo para ele. Anote os nomes completos com o prefixo do cPanel.
2. Associe o usuário ao banco. Importe `database/schema.sql` pelo **phpMyAdmin**, dentro do banco novo.
3. Para o usuário de execução do aplicativo, mantenha somente `SELECT`, `INSERT`, `UPDATE` e `DELETE` neste banco. As tabelas já foram criadas pela importação. Se precisar alterar o esquema futuramente, use o usuário de manutenção no cPanel.
4. Confirme o endereço do servidor do banco com o provedor; geralmente é `localhost`. PostgreSQL não é utilizado nesta edição.

## 3. Configuração privada

1. Copie `private/config.example.php` para `private/config.php`.
2. A `base_url` já está definida como **`https://tg15on.wellbits.com.br`**. Preencha host, porta, nome do banco, usuário e senha; mantenha a URL sem barra final.
3. Crie **duas chaves diferentes e aleatórias**, com pelo menos 32 caracteres: `app_key` e `setup_key`. No Terminal do cPanel, se disponível, use duas vezes:

   `php -r 'echo bin2hex(random_bytes(32)), PHP_EOL;'`

4. Use permissões restritas para `config.php` (preferencialmente 600, conforme exigências do PHP do provedor). Nunca envie senha do banco ou essas chaves pelo chat.
5. Deixe `mail_enabled` como `false` inicialmente. O administrador poderá redefinir senhas pelo painel.
6. Os exemplos não incluem credenciais prontas, contas predefinidas ou senhas padrão.

## Endereços após a instalação

- Login: https://tg15on.wellbits.com.br/
- Aplicativo: https://tg15on.wellbits.com.br/app.php
- Administração: https://tg15on.wellbits.com.br/admin.php
- Instalação inicial: https://tg15on.wellbits.com.br/setup.php

Esses endereços são os caminhos configurados; sua disponibilidade deve ser confirmada após a instalação.

## 4. Criar o primeiro administrador

1. Acesse `https://tg15on.wellbits.com.br/setup.php` por HTTPS.
2. Digite a `setup_key` definida no arquivo privado e informe seu nome, e-mail e senha (12 a 72 bytes; acentos usam mais de um byte).
3. Ao concluir, será aberto o painel administrativo. A instalação é bloqueada automaticamente no banco e `setup.php` passa a retornar 404.
4. Remova `public/setup.php` depois de confirmar a primeira conta, como limpeza da instalação.
5. Crie os usuários no painel. O administrador pode redefinir uma senha; comunique-a ao titular por um canal apropriado. Senhas não são enviadas automaticamente por e-mail.

## 5. Recuperação por e-mail (opcional)

- Configure uma caixa/remetente no seu domínio e confirme com o provedor que a função PHP `mail()` está habilitada.
- Ajuste `mail_from` e, só depois, `mail_enabled=true`.
- Teste recebimento e pasta de spam; configure SPF/DKIM pelo cPanel. A implementação não usa SMTP autenticado diretamente. Se `mail()` não funcionar nesse plano, mantenha o recurso desativado até integrar o SMTP apropriado.
- Links têm token aleatório com hash no banco, expiram em 30 minutos e só podem ser usados uma vez. Redefinir a senha invalida sessões anteriores. O token só segue para o e-mail da conta; não aparece em logs da aplicação nem no painel.

## 6. Migrar os registros

1. No app anterior, use **Exportar meus dados** no navegador onde os registros foram feitos.
2. Entre na conta correspondente na edição cPanel.
3. Use **Importar registros** e selecione o JSON exportado. A importação substitui os registros apenas dessa conta, após confirmação.
4. Confira saldos, aplicações, peso e validade. O pacote não contém os dados do protótipo nem dados fictícios de teste.
5. Dados novos não ficam em `localStorage` nesta edição. O aplicativo precisa de conexão com o servidor para salvar. O protótipo hospedado separadamente continua usando seu comportamento anterior.

## 7. Validação obrigatória antes do uso real

Foram feitas análise sintática, compilação em PHP 8.3.33 (WebAssembly), 17 verificações de validação de dados e 7 verificações de senha/e-mail. A lógica de estoque também foi verificada com os testes do protótipo. O MySQL/MariaDB da WellBits e o envio real de e-mail não estavam disponíveis durante a preparação. Execute em um ambiente de homologação com dados fictícios:

- Criar administrador; repetir setup deve falhar; tentar setup com chave errada deve falhar.
- Criar dois usuários, acessar cada um e confirmar que os dados e exportações são diferentes. Tentar abrir `admin.php` com usuário comum deve retornar 403.
- Tentar API sem login, POST sem CSRF, e alteração com revisão antiga: devem ser negados.
- Testar login correto/incorreto, limite de tentativas, logout, expiração, desativação e mudança de senha (sessões antigas devem ser invalidadas).
- Testar cadastro/edição de estoque, aplicações vinculadas e exclusão: o saldo deve ser mantido sem duplicação ou valores negativos.
- Testar importação/exportação e acesso em dois dispositivos. Em conflito, a alteração não pode sobrescrever a revisão mais recente.
- Se ativado, testar o ciclo de recuperação de senha, expiração e reutilização do link.
- Confirmar que as URLs de `private/config.php` e `database/schema.sql` não estão acessíveis pela web; somente `public/` é raiz do site.
- Configurar backups protegidos do banco e das chaves, com restauração testada. Definir a política de privacidade, retenção e atendimento aos titulares com a WellBits antes de abrir o acesso a terceiros.

No Terminal do cPanel, se disponível, execute dentro da pasta do pacote:

```sh
php tests/check-environment.php
php tests/data-test.php
php tests/credentials-test.php
```

O primeiro comando apenas verifica o ambiente e a leitura das tabelas; não cria contas nem altera os registros. Os demais usam valores fictícios e não acessam o banco.

## Arquitetura e manutenção

`public/` contém as páginas e assets. `private/` contém autenticação, sessão, validação e configuração. `database/` contém o esquema. `build.py` gera a edição cPanel a partir do protótipo `dist/` quando executado no repositório completo; não é necessário na hospedagem.

O diário é salvo como um documento JSON por usuário, com revisão, para preservar o modelo do app atual. Usuários, sessões invalidadas, recuperação de senha e auditoria têm controle no servidor. Não há endpoint para um administrador ler o diário de terceiros. Não há exclusão definitiva de contas pelo painel nesta versão.

Se surgir conflito entre abas/dispositivos, o app bloqueia a sobrescrita e mantém o formulário aberto. Recarregar descarta campos ainda não salvos: anote-os antes. Uma alteração só é confirmada depois da resposta do servidor; se a conexão cair, confirme o último estado ao entrar novamente.

Para limpeza periódica, o administrador do banco pode executar (fora de horário de pico):

```sql
DELETE FROM tg15_rate_limits WHERE window_started < UNIX_TIMESTAMP() - 86400;
DELETE FROM tg15_password_resets WHERE expires_at < UNIX_TIMESTAMP();
```

Limites iniciais: 2 MB por salvamento/importação; 5.000 registros por coleção; 100 unidades físicas por item de estoque; listagem administrativa de até 1.000 contas. Estes limites devem ser revistos conforme o uso.

Referências técnicas: https://www.php.net/manual/en/function.password-hash.php ; https://www.php.net/manual/en/pdo.prepare.php ; https://www.php.net/manual/en/session.security.ini.php