# Guia do Usuário — BI-CCC

Manual de uso do sistema BI-CCC (Central Command Center) da CambioReal.

---

## Índice

1. [Acessando o Sistema](#acessando-o-sistema)
2. [Dashboard do Agente](#dashboard-do-agente)
3. [Corporate Dashboard](#corporate-dashboard)
4. [BI Executive](#bi-executive)
5. [Client 360](#client-360)
6. [Gestão de Usuários](#gestao-de-usuarios)
7. [Tema Dark/Light](#tema-darklight)
8. [Perguntas Frequentes](#perguntas-frequentes)

---

## Acessando o Sistema

### Login

1. Abra o navegador e acesse o endereço fornecido pelo administrador
2. Digite seu **e-mail** e **senha**
3. Clique em **Entrar**

Após o login, você será direcionado automaticamente:
- **Admin** → Corporate Dashboard
- **Corporate** → Corporate Dashboard
- **Agente** → Dashboard pessoal

### Logout

Clique no botão **Sair** no canto superior direito. A sessão expira automaticamente após 8 horas.

### Navegação

Admins acessam todas as páginas via navegação lateral (console nav) no lado direito da tela:

```
┌──────────────────────────────────────────┬───┐
│                                          │ H │  H = Home
│           Conteúdo da página             │ C │  C = Corporate
│                                          │ B │  B = BI Executive
│                                          │ 3 │  3 = Client 360
│                                          │ P │  P = Providers
│                                          │ U │  U = Usuários
└──────────────────────────────────────────┴───┘
```

---

## Dashboard do Agente

**Rota:** `/dashboard`
**Role:** `agente`

Dashboard pessoal do agente mostrando apenas suas próprias transações.

### KPIs Exibidos

| KPI | Descrição |
|-----|-----------|
| Transações | Quantidade total no período |
| Volume BRL | Soma em reais |
| Volume USD | Soma em dólares |
| Taxa Média | Média ponderada da taxa cobrada |
| Spread Médio | % médio sobre PTAX |
| IOF Total | Soma do IOF cobrado |
| Ticket Médio | USD médio por transação |
| Clientes Ativos | Clientes únicos no período |

### Gráficos

- **Volume por Período** — Barras duplas BRL/USD
- **Top 10 Clientes** — Barras horizontais por volume
- **Taxa vs PTAX** — Linha comparando taxa cobrada com PTAX oficial

### Filtros

| Filtro | Opções |
|--------|--------|
| Período | Data início / Data fim |
| Granulação | Dia, Mês, Ano |
| Fluxo | BRL→USD, USD→BRL, Todos |
| Cliente | Todos ou cliente específico |

---

## Corporate Dashboard

**Rota:** `/corporate`
**Role:** `admin`, `corporate`

Visão executiva com KPIs consolidados dos três fluxos de câmbio.

### Funcionalidades

- KPIs do período selecionado: volume, transações, ticket médio
- Comparativo com média 30 dias
- Gráficos de tendência
- Três fluxos separados: BRL→USD, USD→BRL, Balance
- Preset "Hoje" para visão rápida do dia
- Top 5 agentes por volume (7d, 30d, 90d)

---

## BI Executive

**Rota:** `/admin/bi`
**Role:** `admin`

Dashboard analítico completo para decisões estratégicas.

### Seções

| Seção | Descrição |
|-------|-----------|
| KPIs comparativos | Período atual vs anterior com variação % |
| Revenue Analytics | Receita por produto (CambioPay, CambioCheckout, Balance) com granularidade |
| Ranking de Agentes | Top agentes por volume e spread revenue |
| Top 10 Clientes | Maiores clientes por volume USD |
| Retenção | Clientes ativos, novos, inativos, em risco |
| BI Estratégico | Cohort retention, revenue expansion/contraction, cross-sell, maturidade |

### Filtros

- Período customizado (data início / data fim)
- Granularidade: dia, mês, ano

---

## Client 360

**Rota:** `/admin/cliente`
**Role:** `admin`

Visão completa e detalhada de cada cliente individual.

### Busca de Clientes

- Busca por nome (server-side)
- Lista os top 20 clientes por volume ao abrir a página
- Clique no card do cliente para ver detalhes

### Profile do Cliente

| Seção | Descrição |
|-------|-----------|
| Profile Card | Nome, lifetime stats, badge merchant (se aplicável) |
| 6 KPI Cards | Volume, transações, receita, ticket médio, ARPA, spread |
| Health Score | Score 0-100 baseado em volume + frequência + recência + crescimento |
| Churn Risk | Classificação: baixo / médio / alto / crítico com indicadores |
| Netting | Posição líquida BRL→USD vs USD→BRL |
| Revenue Intelligence | Receita mensal + MoM growth |
| Timeline | Volume + quantidade diária com granularidade D/W/M |
| Análise de Fluxo | Donut BRL↔USD + tendência de spread |
| Tabela de Transações | Ordenável, paginada, exportável CSV |
| Insights | Dia da semana preferido, ticket médio, providers usados |

### Merchant Detection

Clientes que são merchants CambioCheckout exibem badge roxo e seção dedicada:
- Volume checkout, payers, receita, operações
- Chart mensal volume + payers
- Top 10 pagadores clicáveis

---

## Gestão de Usuários

**Rota:** `/admin`
**Role:** `admin`

Administração de usuários do sistema.

### Funcionalidades

- Criar novo usuário (admin, corporate, agente)
- Editar dados do usuário
- Ativar/desativar usuários
- Reset de senha
- Vincular `agente_id` (para role agente)

---

## Tema Dark/Light

O sistema possui dois temas visuais:

| Tema | Estilo | Cores |
|------|--------|-------|
| **Dark** | Bloomberg terminal, monospace | Verde #00FF88, fundo escuro |
| **Light** | Institucional CambioReal | Roxo #7600be, verde #2E7D32 |

**Para alternar:** Clique no ícone de tema no header. A preferência é salva no navegador.

---

## Perguntas Frequentes

### Posso ver dados de outros agentes?
**Agentes** veem apenas seus próprios dados. **Admins** veem dados consolidados de todos.

### Os dados são em tempo real?
Os dados são buscados do banco a cada requisição, com cache de 5-15 minutos para performance.

### Como exportar dados?
Na tabela de transações (Client 360 e Dashboard do Agente), use o botão de exportação para baixar em CSV ou Excel.

### A sessão expira?
Sim, após 8 horas de inatividade.

### Funciona no celular?
Sim, o layout é responsivo, mas a experiência é melhor em telas maiores.

### O que é PTAX?
Taxa de câmbio oficial divulgada pelo Banco Central do Brasil, usada como referência para calcular o spread.

### O que é Health Score?
Score de 0 a 100 que avalia a "saúde" do cliente baseado em volume de transações, frequência, recência da última operação e crescimento.

---

## Suporte

Em caso de problemas:
1. Verifique usuário e senha
2. Recarregue a página (F5)
3. Contate o administrador do sistema

---

*CambioReal — BI-CCC*
