# 🌐 Interface Web - Robô de Balanceamento

## 📋 Visão Geral

A interface web `log_balanceamento.php` é um **dashboard de monitoramento em tempo real** para o robô de balanceamento de portfólio. Ela exibe:

- **Status do robô** (ativo/inativo)
- **Fase de operação** (construção ou balanceamento)
- **Valor total do portfólio** e ganhos
- **Saldos por moeda** com percentuais atuais vs. alvo
- **Histórico de operações** (trades realizados)
- **Eventos e alertas** do sistema

## 🚀 Instalação Rápida

### 1. Arquivos Necessários

```
/balanceamento/
├── log_balanceamento.php          ← Interface web (novo)
├── setup_db_balanceamento.php     ← Setup do banco (novo)
├── robobalanceamento/
│   ├── robo_balanceamento.py
│   ├── log_balanceamento.log      ← Log gerado pelo robô
│   └── portfolio_estado.json      ← Estado persistente
└── ...
```

### 2. Criar o Banco de Dados (Opcional)

Se desejar usar analytics no banco de dados:

```bash
# Abrir no navegador:
http://localhost/projetos/balanceamento/setup_db_balanceamento.php
```

Isso criará as tabelas:
- `portfolio_snapshots` - Snapshots diários
- `rebalancing_transactions` - Histórico de trades
- `coin_performance` - Métricas por moeda
- `daily_strategy_stats` - Estatísticas diárias
- `portfolio_events` - Eventos do sistema
- `configuration_history` - Histórico de mudanças

### 3. Acessar a Interface

```
http://localhost/projetos/balanceamento/log_balanceamento.php
```

## 📊 Componentes da Interface

### Header
- **Nome**: "Robô de Balanceamento"
- **Status Badge**: 
  - 🟢 **ATIVO** (verde) - Robô executado nos últimos 10 minutos
  - 🔴 **INATIVO** (laranja) - Robô não atualizado há mais de 10 minutos
- **Horário**: Data e hora atual

### Cards de Resumo (Grid 2×2)

#### 1. Fase Atual
- Exibe: "Construção" ou "Balanceamento"
- Cores: Vermelho para construção, teal para balanceamento
- Mostra: Número de moedas compradas vs. total

#### 2. Valor do Portfólio
- Exibe: Valor total em USDT
- Cor: Verde se positivo, vermelho se negativo
- Mostra: Capital inicial para comparação

#### 3. Ganho Total
- Exibe: Ganho em USDT e percentual
- Cor: Verde para ganho, vermelho para perda
- Sinal: Automático (+/-)

#### 4. Operações
- Exibe: Total de trades executados
- Inclui: Todas as operações (compra, venda, entrada)

### Tabela de Saldos

Coluna | Descrição
:--|--
**Moeda** | BTC, ETH, HBAR, etc. (badge destacado)
**Saldo** | Quantidade total da moeda
**Preço** | Preço atual no mercado
**Valor (USDT)** | Saldo × Preço
**% Atual** | Percentual atual no portfólio
**% Alvo** | Percentual-alvo configurado
**Diferença** | Variação com barra de progresso

**Cores da Diferença**:
- 🟢 Verde: Dentro da tolerância (±2%)
- 🔴 Vermelho: Acima do alvo (precisa vender)
- 🟡 Amarelo: Abaixo do alvo (precisa comprar)

**Barra de Progresso**: Visualiza graficamente o desvio

### Seção: Estado do Portfólio

Grid de 3 cards:
1. **Data de Início**: Quando o portfólio foi criado
2. **Moedas Compradas**: Lista de moedas ativas
3. **Moedas Pendentes**: Lista de moedas ainda não compradas

### Histórico de Trades

Tabela detalhada com:
- **Data/Hora**: Timestamp da operação
- **Moeda**: Qual moeda foi negociada
- **Tipo**: Compra (verde), Venda (vermelho), Entrada (azul)
- **Preço**: Preço de execução
- **Quantidade**: Quantidade negociada
- **Valor (USDT)**: Valor total da operação

Ordenado do mais recente para o mais antigo.

## 🎨 Design e Cores

### Tema Escuro
- Background: `#0a0e27` (azul muito escuro)
- Cards: `#1a2332` (azul escuro)
- Bordas: `#2a3f5f` (azul médio)
- Texto: `#e0e0e0` (cinza claro)

### Cores Semânticas
- 🟢 **Ganho/Positivo**: `#4caf50` (verde)
- 🔴 **Perda/Negativo**: `#f44336` (vermelho)
- 🟡 **Alerta/Pendente**: `#ffc107` (amarelo)
- 🔵 **Info/Principal**: `#64b5f6` (azul)

### Responsive
- Adapta-se para mobile e tablet
- Grid automático com `auto-fit` e `minmax()`
- Cards redimensionam conforme tela

## 📡 Dados Utilizados

### Origem dos Dados

1. **portfolio_estado.json** (Principal)
   - Moedas compradas e pendentes
   - Percentuais-alvo
   - Preços de compra
   - Histórico de trades
   - Data de início

2. **log_balanceamento.log** (Secundário)
   - Última seção do log entre separadores ("=====")
   - Extrai: fase, capital, valor total, ganhos, moedas
   - Saldos por moeda com percentuais

3. **configuracoes_balanceamento.json** (Leitura)
   - Parâmetros do sistema
   - Não exibido direto, mas validado

### Processamento

```
log_balanceamento.log
      ↓
Extrair última seção (entre "=====")
      ↓
Parse com Regex (timestamps, valores, percentuais)
      ↓
Mesclar com portfolio_estado.json
      ↓
Renderizar na interface
```

## 🔄 Atualização de Dados

### Frescor dos Dados

- **Saldos**: Extrait do log_balanceamento.log (atualizado a cada ciclo do robô)
- **Histórico**: Lido de portfolio_estado.json (atualizado em tempo real)
- **Página**: Carrega dados toda vez que é acessada

### Atualizar Manualmente

Pressione **F5** ou **Ctrl+R** para recarregar a página e ver dados mais recentes.

### Auto-Refresh (Opcional)

Adicione ao final do `<head>`:
```html
<meta http-equiv="refresh" content="60">
```
Para atualizar a página a cada 60 segundos.

## 🐛 Troubleshooting

### Problema: Interface mostra "INATIVO"
**Causa**: Robô parou de atualizar log há mais de 10 minutos.

**Solução**:
1. Verifique se `python robobalanceamento.py` está rodando
2. Verifique permissões do arquivo log_balanceamento.log
3. Verifique se o diretório `robobalanceamento/` existe

### Problema: Tabela de saldos vazia
**Causa**: Portfolio_estado.json vazio ou não criado.

**Solução**:
1. Rode o robô em fase construção (Phase 1)
2. Aguarde primeira compra de moeda
3. Verifique se portfolio_estado.json foi criado

### Problema: Histórico de trades não aparece
**Causa**: Sem arquivos de estado do robô.

**Solução**:
1. Verifique se files existem em `robobalanceamento/`
2. Rode `python exemplos_portofolios.py` para carregar template
3. Execute robô com `python robo_balanceamento.py`

### Problema: Erro de leitura de JSON
**Causa**: Arquivo corrompido ou com encoding inválido.

**Solução**:
1. Verifique JSON com: `cat portfolio_estado.json | python -m json.tool`
2. Se corrompido, delete e deixe robô recriar
3. Verifique encoding: UTF-8 sem BOM

### Problema: Percentuais não somam 100%
**Causa**: Portfólio em construção (nem todas moedas compradas).

**Solução**: Normal durante fase 1. Aguarde conclusão da fase construção.

## 📈 Recursos Avançados

### Integração com Banco de Dados

Se você rodou `setup_db_balanceamento.php`, pode estender a interface para:

1. **Histórico de múltiplos dias** (query em `portfolio_snapshots`)
2. **Gráficos de performance** (Chart.js com `coin_performance`)
3. **Análise de rebalanceamentos** (`rebalancing_transactions`)
4. **Eventos e alertas** (`portfolio_events`)

### Exemplo de Query para Gráfico

```php
// Ganho nos últimos 7 dias
$sql = "SELECT data, ganho_percentual FROM portfolio_snapshots 
        WHERE data >= DATE_SUB(CURDATE(), INTERVAL 7 DAY) 
        ORDER BY data";
```

### Exemplo de Query para Alertas

```php
// Últimos 5 eventos críticos
$sql = "SELECT * FROM portfolio_events 
        WHERE severidade = 'critico' 
        ORDER BY data_hora DESC 
        LIMIT 5";
```

## 🔐 Segurança

### Restrições

1. **Frontend apenas**: A interface é read-only (não modifica dados)
2. **JSON local**: Usa arquivos JSON, não expõe API keys
3. **Sem autenticação**: Implante .htaccess para proteger:

```apache
# .htaccess
AuthType Basic
AuthName "Acesso Restrito"
AuthUserFile /path/to/.htpasswd
Require valid-user
```

### Proteção de Dados

- Não exibe API keys (nunca lê de configuracoes_balanceamento.json)
- Não permite execução de comandos
- Não tem formulários para entrada (read-only)

## 📱 Responsividade

| Dispositivo | Comportamento |
|--|--|
| **Desktop** (>1024px) | Grid 2×2 / 3 colunas completo |
| **Tablet** (768-1024px) | Grid 1×2 / 2 colunas |
| **Mobile** (< 768px) | Grid 1×1 / 1 coluna, scroll horizontal em tabelas |

## 🎯 Próximos Passos

1. **Adicionar Gráficos**: Integre Chart.js para gráficos históricos
2. **Banco de Dados**: Configure MySQL e armazene histórico diário
3. **Alertas**: Implemente sistema de notificações (email, webhooks)
4. **API REST**: Crie endpoints para integração com outros sistemas
5. **Mobile App**: Transforme em Progressive Web App (PWA)

## 📞 Suporte

Se encontrar problemas:

1. Verifique o `php_error_balanceamento.log`
2. Verifique o `robobalanceamento/log_balanceamento.log`
3. Valide JSON: `python -m json.tool arquivo.json`
4. Rode `python validar_balanceamento.py` para diagnóstico completo

---

**Versão**: 1.0  
**Última atualização**: 2024  
**Compatibilidade**: PHP 7.4+, MySQL 5.7+ (opcional)