Cassel
647cbec54f
- Rewrite README.md with current architecture, features and stack - Update docs/API.md with all current endpoints (corporate, BI, client 360) - Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL - Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente) - Add docs/INDEX.md documentation index - Add PROJETO.md comprehensive project reference - Add BI-CCC-Implementation-Guide.md - Include AI agent configs (.claude, .agents, .gemini, _bmad) - Add netbird VPN configuration - Add status report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
236 lines
6.7 KiB
Markdown
236 lines
6.7 KiB
Markdown
# 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*
|