# Manual de instalação

Este manual descreve como instalar o **Business Intelligence (BI)** da CEBI em um **Windows Server**. Ele se destina à equipe de infraestrutura (TI).

## Visão geral

O BI tem duas partes obrigatórias, publicadas no **IIS** do mesmo servidor, e uma parte opcional para demonstrações:

| Parte | Pasta no pacote | Porta padrão | Função |
|---|---|---|---|
| **API do BI** | `api/` | **5080** | Conversa com o banco Oracle, busca os dados das fontes e atende a tela. |
| **Tela (frontend)** | `frontend/` | **5173** | A aplicação que os usuários abrem no navegador. |
| APIs de demonstração | `api-demo/` | 8092 e 8093 | Dados fictícios para apresentações (opcional). |

> **Importante:** a tela procura a API **no mesmo servidor, na porta 5080** (se a tela abre em `http://servidor:5173`, ela chama `http://servidor:5080/api`). Para usar outro servidor ou outra porta para a API, é preciso gerar a tela de novo — fale com a equipe do BI.

### Conteúdo do pacote

```
BI-2026.10.7.1/
├── INSTALAR.bat          → instalação automática (recomendada)
├── Instalar-BI.ps1       → script executado pelo INSTALAR.bat
├── api/                  → API do BI (.NET 8), já compilada
├── frontend/             → tela do BI (arquivos estáticos), já compilada
├── api-demo/             → APIs de demonstração (Node.js)
└── README-INSTALACAO.md  → este guia, em texto
```

## 1. Pré-requisitos

| Item | Observação |
|---|---|
| **Windows Server 2016 ou mais novo** | 2019 ou 2022 recomendados. |
| **IIS** | O instalador instala sozinho, se faltar (inclui *Application Initialization*). |
| **.NET 8 – ASP.NET Core Hosting Bundle** | https://dotnet.microsoft.com/download/dotnet/8.0 → coluna *ASP.NET Core Runtime* → Windows → **Hosting Bundle**. Deve ser instalado **depois** do IIS (se o IIS for instalado depois, rode o instalador do Hosting Bundle de novo e escolha *Reparar*). |
| **IIS URL Rewrite** | https://www.iis.net/downloads/microsoft/url-rewrite |
| **Node.js 18+ (LTS)** | https://nodejs.org — somente para as APIs de demonstração. |
| **Acesso ao Oracle** | O servidor precisa alcançar o banco (padrão `192.168.4.2`, porta `1521`, serviço `bi`). |
| **Usuário no Oracle** | Schema próprio do BI com permissão para **criar tabelas** e quota no tablespace — a API cria as tabelas sozinha na primeira inicialização. |
| **Portas livres** | 5080 e 5173 (BI) e 8092/8093 (demonstração). |

> O driver do Oracle já vem dentro da API — **não** é preciso instalar o Oracle Client no servidor.

## 2. Instalação automática (recomendada)

1. Instale os pré-requisitos acima (Hosting Bundle, URL Rewrite e Node.js).
2. Copie o `BI-2026.10.7.1.zip` para o servidor e **extraia o zip inteiro**.
3. Dê dois cliques em **`INSTALAR.bat`**. Ele pede permissão de administrador sozinho.
4. Responda às perguntas:
   - **Oracle:** servidor, porta, serviço, usuário e senha (o instalador testa a conexão);
   - **Administrador inicial do BI:** nome, e-mail e senha.
5. Aguarde a etapa **8/8 – Testando**. Ao final aparece **"BI INSTALADO COM SUCESSO"** e o endereço de acesso para os usuários.

### O que o instalador faz

| Etapa | Ação |
|---|---|
| 1/8 | Confere Windows, IIS, Hosting Bundle, URL Rewrite, Node.js e se as portas estão livres. Instala o IIS, se faltar. |
| 2/8 | Pede os dados do Oracle (e testa o acesso) e do administrador inicial. |
| 3/8 | Copia a aplicação para **`C:\BI`** (`api`, `frontend`, `api-demo`). |
| 4/8 | Cria `C:\BI\api\appsettings.Production.json` com uma **chave de segurança aleatória** e os endereços do servidor liberados; o arquivo fica legível só por administradores e pela própria API. |
| 5/8 | Publica no IIS os sites **BI-API** (porta 5080) e **BI-Web** (porta 5173). A API fica **sempre ligada** (tem rotina de atualização automática das fontes) e guarda as chaves de criptografia em `C:\BI\dados\chaves`. |
| 6/8 | Libera as portas 5080 e 5173 no firewall do Windows. |
| 7/8 | APIs de demonstração: cadastra os nomes `api.saneamento.cebi` e `api.os.cebi` e cria tarefas agendadas que as deixam ligadas sozinhas, inclusive após reiniciar o servidor. |
| 8/8 | Testa a API, a tela e as APIs de demonstração e mostra os endereços de acesso. |

### Opções do instalador

Executar pelo PowerShell como administrador:

| Opção | Uso |
|---|---|
| `.\Instalar-BI.ps1 -InstallDir D:\BI` | Instala em outra pasta. |
| `.\Instalar-BI.ps1 -SemDemo` | Não configura as APIs de demonstração. |
| `.\Instalar-BI.ps1 -UrlsExtras "http://bi.cebi.local:5173"` | Libera um endereço extra (por exemplo, um nome cadastrado no DNS). |

O log de cada execução fica em `C:\ProgramData\BI-instalacao-<data>.log` (as senhas digitadas não são gravadas).

> **Segurança:** a senha inicial do administrador é **apagada** do arquivo de configuração ao final de uma instalação bem-sucedida — ela só é usada na primeira inicialização. Troque essa senha no primeiro acesso.

## 3. APIs de demonstração

São usadas nas apresentações: a fonte de dados é cadastrada **ao vivo** no BI. Como quem busca os dados é a **API do BI** (no servidor, não no navegador), elas precisam rodar **no mesmo servidor da API do BI**.

O `INSTALAR.bat` já as configura. Para instalar ou atualizar **somente** as APIs de demonstração, use o pacote pequeno **`BI-demo-2026.10.7.1.zip`**: extraia e dê dois cliques em **`INSTALAR-DEMO.bat`**.

| API | Endereço para cadastrar no BI |
|---|---|
| Água/Esgoto | `http://api.saneamento.cebi:8092/v1/ligacoes` |
| Ordens de Serviço | `http://api.os.cebi:8093/v1/ordens` |

- Os nomes `api.saneamento.cebi` e `api.os.cebi` são cadastrados no arquivo `hosts` do próprio servidor (apontando para ele mesmo). Como alternativa, podem ser cadastrados no **DNS da empresa**.
- As portas 8092/8093 **não** precisam ser liberadas no firewall.
- No servidor, as APIs aparecem no Agendador de Tarefas como **"BI - API Demo Agua"** e **"BI - API Demo Ordens de Servico"**.
- **Plano B (sem Node.js):** a API do BI já traz dados fictícios embutidos: `http://localhost:5080/api/demo/vendas`.

## 4. Verificar a instalação

1. No navegador, acesse `http://<servidor>:5173`.
2. Entre com o e-mail e a senha do administrador.
3. Em **Fontes de Dados → + Nova Fonte**, cadastre `http://api.saneamento.cebi:8092/v1/ligacoes`, clique em **Testar conexão** e confirme a mensagem **"Conexão OK"**.
4. O rodapé da tela mostra a versão instalada (ex.: *Versão: 2026.10.7.1*).

## 5. Solução de problemas

| Sintoma | Causa provável | Solução |
|---|---|---|
| Instalador para em **"Falta o .NET 8 – ASP.NET Core Hosting Bundle"** | Hosting Bundle ausente ou instalado antes do IIS. | Instale (ou *Repare*) o Hosting Bundle e rode o `INSTALAR.bat` de novo. |
| **"A API não respondeu"** na etapa 8/8 | Oracle inacessível ou usuário/senha incorretos. | Conferir `C:\BI\api\appsettings.Production.json` e o acesso ao Oracle. Detalhes: *Visualizador de Eventos → Logs do Windows → Aplicativo* (origem *IIS AspNetCore Module V2*). |
| Ao cadastrar fonte: **"No such host is known (api.saneamento.cebi…)"** | Os nomes das APIs de demonstração não estão cadastrados no servidor. | Rodar o `INSTALAR-DEMO.bat` (ou o `INSTALAR.bat`) no **servidor da API do BI**. |
| Ao cadastrar fonte: **conexão recusada** | A API de demonstração não está ligada. | Conferir as tarefas "BI - API Demo…" no Agendador de Tarefas e se o Node.js está instalado. |
| Aviso **"CONFLITO: a porta … já é usada por …"** | Outro sistema do servidor usa a porta. | Avisar a equipe do BI para gerar o pacote com outra porta. |
| Tela abre, mas mostra **"Não foi possível conectar ao servidor"** | A API (porta 5080) está parada ou bloqueada no firewall. | Conferir o site **BI-API** no Gerenciador do IIS e a regra de firewall "BI - API (5080)". |

## 6. Instalação manual (sem o instalador)

Use apenas se não for possível executar o `INSTALAR.bat`.

1. **API:** copie a pasta `api/` para o servidor. Copie `appsettings.Production.example.json` para **`appsettings.Production.json`** e preencha:
   - `ConnectionStrings:Oracle` — usuário, senha e endereço do Oracle;
   - `Jwt:Key` — chave secreta com **no mínimo 32 caracteres**, única deste servidor;
   - `Seed:AdminEmail` / `Seed:AdminPassword` — administrador inicial (criado só se o banco não tiver usuários);
   - `Frontend:BaseUrl` — endereço(s) da tela, separados por vírgula (ex.: `http://servidor:5173`);
   - `DataProtection:KeysPath` — pasta fixa para as chaves de criptografia (ex.: `C:\BI\dados\chaves`), com permissão de escrita para a API.
2. Publique a pasta `api/` no IIS (porta 5080), com pool de aplicativos **sem código gerenciado**, **sempre ligado** (*AlwaysRunning*, *idle timeout* 0) e *preload* habilitado. O `web.config` já está pronto.
3. **Tela:** publique a pasta `frontend/` no IIS (porta 5173). O `web.config` incluído já configura as rotas (requer o URL Rewrite).
4. Libere as portas 5080 e 5173 no firewall.

> Na primeira inicialização, a API cria as tabelas no Oracle e o usuário administrador automaticamente.

## 7. Segurança

- **Troque a senha inicial** do administrador no primeiro acesso.
- Não compartilhe o `appsettings.Production.json`: ele contém a senha do Oracle e a chave de segurança.
- Mantenha `Auth:ReturnDevLinks` como `false` em produção.
- Avalie publicar com **HTTPS** (certificado no IIS).
- Se o servidor usar o **mesmo banco Oracle** de outro ambiente do BI, painéis e usuários são mantidos, mas fontes de dados com senha/token precisam ter essa senha informada de novo (cada servidor tem as próprias chaves de criptografia).