# Manual de Instalação — XML Monitor

Instalação pelo navegador, **sem precisar de terminal**. Leva cerca de 20 minutos.

---

## Antes de começar

Tenha em mãos:

- Acesso ao **cPanel** da hospedagem
- O arquivo **`xml-monitor.zip`** (o pacote que acompanha este manual)
- O domínio ou subdomínio onde o sistema vai ficar

---

## Passo 1 — Conferir o PHP

No cPanel, abra **Select PHP Version**.

1. Em **PHP Version**, selecione **8.3** ou superior.
2. Clique na aba **Extensions** e marque todas estas:

```
bcmath    curl     dom      fileinfo   gd
intl      json     libxml   mbstring   openssl
pdo_mysql simplexml soap    zip        zlib
```

3. Clique em **Save**.

> **A extensão `soap` é a mais importante.** Sem ela não há comunicação com a
> SEFAZ e o sistema não baixa XML nenhum. Se ela não aparecer na lista, abra um
> chamado no suporte da hospedagem pedindo a ativação **antes** de continuar.

---

## Passo 2 — Criar o banco de dados

No cPanel, abra **MySQL® Databases**.

1. Em *Create New Database*, digite `xmlmonitor` e clique em **Create Database**.
   O cPanel vai criar com o prefixo da sua conta, algo como `seuusuario_xmlmonitor`.
2. Em *Add New User*, crie um usuário e uma senha. **Anote os dois.**
3. Em *Add User To Database*, selecione o usuário e o banco, clique em **Add**.
4. Na tela seguinte, marque **ALL PRIVILEGES** e clique em **Make Changes**.

Anote estes três dados — você vai usá-los no Passo 5:

| Dado | Exemplo |
|---|---|
| Nome do banco | `seuusuario_xmlmonitor` |
| Usuário | `seuusuario_xmladmin` |
| Senha | *(a que você criou)* |

---

## Passo 3 — Enviar os arquivos

No cPanel, abra **File Manager**.

1. Entre na pasta **`/home/seuusuario`** (a raiz da sua conta, **não** o `public_html`).
2. Clique em **Upload** e envie o `xml-monitor.zip`.
3. Volte ao File Manager, clique com o botão direito no arquivo e escolha **Extract**.
4. Confirme que apareceu a pasta **`app-xmlmonitor`**.

Agora mova os arquivos públicos:

5. Entre em `app-xmlmonitor/public`.
6. Selecione **tudo** que está lá dentro (`index.php`, `.htaccess`, `build`, `robots.txt`).
7. Clique em **Move** e informe o destino **`/public_html`**.

> Se o `public_html` já tiver um `index.html` ou `index.php` de outro site,
> apague-os antes — senão o servidor abre o arquivo errado.

### Estrutura final

```
/home/seuusuario/
├── app-xmlmonitor/          ← o sistema (fora da web, protegido)
│   ├── app/  config/  storage/  vendor/  ...
│   └── .env
└── public_html/             ← o que o navegador enxerga
    ├── index.php
    ├── .htaccess
    └── build/
```

> **Por que separado:** os certificados digitais dos seus clientes ficam dentro de
> `app-xmlmonitor/storage`. Se o sistema estivesse no `public_html`, qualquer pessoa
> poderia baixar esses certificados pela URL — e emitir nota em nome deles.

---

## Passo 4 — Ajustar permissões

Ainda no File Manager, dentro de `app-xmlmonitor`:

1. Clique com o botão direito na pasta **`storage`** → **Change Permissions**.
2. Marque **775** e ative **Recurse into subdirectories**. Confirme.
3. Repita para a pasta **`bootstrap/cache`**.

E deixe o arquivo de configuração gravável:

4. No topo do File Manager, clique em **Settings** e marque **Show Hidden Files (dotfiles)**.
5. Localize o arquivo **`.env`** dentro de `app-xmlmonitor`.
6. Botão direito → **Change Permissions** → **664**.

> Se o `.env` não existir, copie o `.env.example`: botão direito → **Copy** →
> destino `/home/seuusuario/app-xmlmonitor/.env`.

---

## Passo 5 — Instalar pelo navegador

Abra no navegador:

```
https://seudominio.com.br/instalar
```

### Tela 1 — Verificação do servidor

Mostra 26 itens conferidos automaticamente.

- **Tudo verde** → clique em **Continuar**.
- **Algum item em vermelho** → o próprio item explica como resolver. A maioria se
  corrige no Passo 1 (extensões) ou no Passo 4 (permissões). Corrija e clique em
  **Verificar de novo**.

### Tela 2 — Banco de dados

Preencha com o que você anotou no Passo 2:

| Campo | O que colocar |
|---|---|
| Nome do sistema | Como quiser chamar. Dá para trocar depois |
| Endereço do site | `https://seudominio.com.br` |
| Servidor | `127.0.0.1` |
| Porta | `3306` |
| Nome do banco | `seuusuario_xmlmonitor` |
| Usuário do banco | `seuusuario_xmladmin` |
| Senha do banco | A senha criada |

Clique em **Testar conexão e criar tabelas**.

O instalador testa a conexão **antes** de gravar qualquer coisa. Se algo estiver
errado, ele diz exatamente o quê — banco inexistente, senha incorreta, falta de
permissão — e nada é alterado.

### Tela 3 — Usuário master

É a sua conta de administrador da plataforma.

- **Nome** — como preferir
- **E-mail** — será o seu login; use um e-mail que você acessa
- **Senha** — mínimo de 8 caracteres, com letras e números

Clique em **Criar conta e concluir**.

> A partir daqui o endereço `/instalar` fica **permanentemente fechado**.
> Ninguém consegue reinstalar por cima do seu sistema.

### Tela 4 — Concluído

Mostra o comando do cron. **Copie esse comando** — é o Passo 6.

---

## Passo 6 — Criar o agendamento (obrigatório)

**Sem este passo nenhum XML é baixado.** É o que faz o sistema funcionar sozinho.

No cPanel, abra **Cron Jobs**.

1. Em *Common Settings*, escolha **Once Per Minute (`* * * * *`)**.
2. Em *Command*, cole o comando que apareceu na Tela 4. Algo assim:

```
* * * * * /opt/cpanel/ea-php83/root/usr/bin/php /home/seuusuario/app-xmlmonitor/artisan schedule:run >/dev/null 2>&1
```

3. Clique em **Add New Cron Job**.

É **uma única entrada**. Ela cuida do monitor de XML, da fila de processamento e
da limpeza automática.

> Se o caminho do PHP não funcionar, peça ao suporte da hospedagem o caminho do
> **binário do PHP 8.3 para linha de comando**. Costuma ser
> `/opt/cpanel/ea-php83/root/usr/bin/php` ou `/usr/local/bin/ea-php83`.

---

## Passo 7 — Primeiro acesso

Entre em `https://seudominio.com.br/entrar` com o e-mail e a senha do Passo 5.

Depois:

1. **Configurações do site** — nome, cor, logo, favicon, textos da tela de login e
   seus dados de desenvolvedor.
2. **Empresas → Nova empresa** — cadastre o primeiro cliente e o administrador dele.
3. **Certificados** — instale o certificado digital A1 (arquivo `.pfx` ou `.p12`)
   da empresa. Ou peça ao cliente que envie pelo painel dele.
4. Pronto. O monitor começa sozinho no próximo ciclo. Para não esperar, use o
   botão **Sincronizar** na tela da empresa.

---

## Se algo der errado

| O que acontece | O que fazer |
|---|---|
| Site abre sem cores nem formatação | A pasta `build` não foi movida para o `public_html` (Passo 3) |
| "500 Server Error" | Permissões da `storage`. Refaça o Passo 4 |
| `/instalar` mostra "Não encontrado" | O sistema já foi instalado. Use `/entrar` |
| Erro "Access denied" no banco | Usuário ou senha incorretos, ou faltou dar ALL PRIVILEGES |
| "Class SoapClient not found" | A extensão `soap` está desativada. Volte ao Passo 1 |
| Nenhum XML chega depois de horas | O cron não foi criado, ou está com o PHP errado. Refaça o Passo 6 |
| "419 Page Expired" no login | O domínio está sem HTTPS. Ative o AutoSSL no cPanel |
| Página em branco | Peça ao suporte o *error log* do PHP e envie para análise |

---

## Duas coisas para nunca esquecer

**1. Guarde uma cópia do arquivo `.env`.**
Dentro dele está a `APP_KEY`, a chave que criptografa as senhas dos certificados
digitais. Se ela for perdida, cada cliente terá de reenviar o certificado.

**2. Faça backup do banco e da pasta `storage/app/xmls`.**
A lei exige a guarda dos XMLs por **5 anos**. O sistema não apaga nada, mas ele
não substitui backup. Use o *Backup Wizard* do cPanel periodicamente.

---

## Instalação por terminal

Se você tiver acesso ao *Terminal* do cPanel ou SSH, existe um caminho mais
rápido. Consulte o arquivo `INSTALACAO.md`, dentro da pasta do sistema.