cassel/bi-agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update all documentation and add AI tooling configs

Browse Source 
- 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>
This commit is contained in:
Cassel
2026-03-19 13:29:03 -04:00
parent c5b377e788
commit 647cbec54f
3246 changed files with 479789 additions and 983 deletions
Download Patch File Download Diff File Expand all files Collapse all files

343
docs/GUIA-USUARIO.md
View File

@@ -1,18 +1,19 @@
# Guia do Usuario - BI Agentes
# Guia do Usuário — BI-CCC
Manual de uso do dashboard de transacoes para agentes CambioReal.
Manual de uso do sistema BI-CCC (Central Command Center) da CambioReal.
---
## Indice
## Índice
1. [Acessando o Sistema](#acessando-o-sistema)
2. [Visao Geral do Dashboard](#visao-geral-do-dashboard)
3. [Usando os Filtros](#usando-os-filtros)
4. [Entendendo os KPIs](#entendendo-os-kpis)
5. [Interpretando os Graficos](#interpretando-os-graficos)
6. [Tabela de Transacoes](#tabela-de-transacoes)
7. [Perguntas Frequentes](#perguntas-frequentes)
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)
---
@@ -20,253 +21,215 @@ Manual de uso do dashboard de transacoes para agentes CambioReal.
### Login
1. Abra o navegador e acesse o endereco fornecido pelo administrador
2. Na tela de login, digite:
- **E-mail**: Seu email cadastrado
- **Senha**: Sua senha pessoal
1. Abra o navegador e acesse o endereço fornecido pelo administrador
2. Digite seu **e-mail** e **senha**
3. Clique em **Entrar**
```
┌─────────────────────────────────┐
│ BI Agentes │
│ CambioReal - Dashboard │
│ │
│ E-mail: [_________________] │
│ │
│ Senha: [_________________] │
│ │
│ [ Entrar ] │
└─────────────────────────────────┘
```
**Dica:** Se aparecer a mensagem "E-mail ou senha incorretos", verifique se digitou corretamente. Caso persista, contate o administrador.
Após o login, você será direcionado automaticamente:
- **Admin** → Corporate Dashboard
- **Corporate** → Corporate Dashboard
- **Agente** → Dashboard pessoal
### Logout
Para sair do sistema, clique no botao **Sair** no canto superior direito do dashboard.
Clique no botão **Sair** no canto superior direito. A sessão expira automaticamente após 8 horas.
---
### Navegação
## Visao Geral do Dashboard
Apos o login, voce vera o dashboard com suas transacoes:
Admins acessam todas as páginas via navegação lateral (console nav) no lado direito da tela:
```
┌────────────────────────────────────────────────────────────────────┐
│ [Nome do Agente] - Agente [ID] [Ao vivo] [Sair] │
├────────────────────────────────────────────────────────────────────┤
│ De: [____] Ate: [____] Granulacao: [___] Fluxo: [___] [Aplicar] │
├────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ KPI 1 │ │ KPI 2 │ │ KPI 3 │ │ KPI 4 │ <- Indicadores │
│ └────────┘ └────────┘ └────────┘ └────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Grafico 1 │ │ Grafico 2 │ <- Graficos │
│ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────────────────────────────┐ │
│ │ Tabela de Transacoes │ <- Detalhes │
│ └─────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────┬───┐
│ │ 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
└──────────────────────────────────────────┴───┘
```
**Importante:** Voce ve apenas suas proprias transacoes. Outros agentes nao tem acesso aos seus dados.
---
## 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 |
---
## Usando os Filtros
## Corporate Dashboard
Os filtros ficam na barra abaixo do cabecalho. Use-os para refinar a visualizacao:
**Rota:** `/corporate`
**Role:** `admin`, `corporate`
### Periodo (De / Ate)
Visão executiva com KPIs consolidados dos três fluxos de câmbio.
Selecione a data inicial e final para ver transacoes em um periodo especifico.
### Funcionalidades
**Exemplo:** Para ver transacoes de janeiro:
- De: `2024-01-01`
- Ate: `2024-01-31`
### Granulacao
Escolha como agrupar os dados nos graficos:
| Opcao | Uso |
|-------|-----|
| **Dia** | Ver detalhes diarios (periodos curtos) |
| **Mes** | Visao mensal (padrao, recomendado) |
| **Ano** | Comparar anos inteiros |
### Fluxo
Filtre por tipo de operacao:
| Opcao | Significado |
|-------|-------------|
| **Todos** | BRL→USD e USD→BRL juntos |
| **BRL → USD** | Apenas envios (reais para dolares) |
| **USD → BRL** | Apenas recebimentos (dolares para reais) |
### Cliente
Selecione um cliente especifico ou deixe em "Todos" para ver todas as transacoes.
### Aplicar
**Importante:** Apos alterar os filtros, clique em **Aplicar** para atualizar a tela.
- 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)
---
## Entendendo os KPIs
## BI Executive
Os KPIs (Indicadores-Chave) mostram um resumo do periodo selecionado:
**Rota:** `/admin/bi`
**Role:** `admin`
### Transacoes
Quantidade total de operacoes realizadas.
Dashboard analítico completo para decisões estratégicas.
### Volume BRL
Soma de todos os valores em reais movimentados.
### Seções
**Exemplo:** Se teve 3 transacoes de R$ 10.000, R$ 20.000 e R$ 15.000, o volume e R$ 45.000.
| 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 |
### Volume USD
Soma de todos os valores em dolares movimentados.
### Filtros
### Taxa Media
Media ponderada da taxa de cambio cobrada (BRL/USD).
**Ponderada significa:** Transacoes maiores tem mais peso no calculo.
### Spread Medio
Porcentagem media de lucro sobre a taxa PTAX.
**O que e PTAX?** Taxa de cambio oficial do Banco Central.
**Exemplo:** Se a PTAX e 5,00 e voce cobra 5,05, o spread e 1% (0,05 / 5,00).
### IOF Total
Soma do IOF (Imposto sobre Operacoes Financeiras) recolhido.
### Ticket Medio
Valor medio em USD por operacao.
**Calculo:** Volume USD / Numero de Transacoes
### Clientes Ativos
Quantos clientes diferentes fizeram transacoes no periodo.
- Período customizado (data início / data fim)
- Granularidade: dia, mês, ano
---
## Interpretando os Graficos
## Client 360
### Volume BRL / USD por Periodo
**Rota:** `/admin/cliente`
**Role:** `admin`
Grafico de barras mostrando a evolucao do volume ao longo do tempo.
Visão completa e detalhada de cada cliente individual.
- **Barras verdes** = Volume em BRL (eixo esquerdo)
- **Barras azuis** = Volume em USD (eixo direito)
### Busca de Clientes
**Como ler:**
- Barras mais altas = mais volume naquele periodo
- Compare meses para identificar sazonalidade
- 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
### Volume por Cliente (Top 10)
### Profile do Cliente
Grafico horizontal mostrando os 10 maiores clientes por volume USD.
| 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 |
**Como usar:**
- Identifique seus clientes mais importantes
- Foque atencao nos maiores volumes
### Merchant Detection
### Taxa Cobrada vs PTAX
Grafico de linha comparando sua taxa com a taxa oficial.
- **Linha roxa** = Sua taxa cobrada (media ponderada)
- **Linha azul** = PTAX oficial
**O que observar:**
- A distancia entre as linhas e seu spread
- Quanto maior a distancia, maior sua margem
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
---
## Tabela de Transacoes
## Gestão de Usuários
A tabela mostra todas as transacoes individuais do periodo.
**Rota:** `/admin`
**Role:** `admin`
### Colunas
Administração de usuários do sistema.
| Coluna | Descricao |
|--------|-----------|
| **Data/Hora** | Quando a transacao foi realizada |
| **Cliente** | Nome do cliente |
| **Valor BRL** | Valor em reais |
| **Valor USD** | Valor em dolares |
| **IOF %** | Aliquota de IOF aplicada |
| **IOF R$** | Valor do IOF em reais |
| **PTAX** | Taxa oficial do BC no momento |
| **Taxa Cobrada** | Sua taxa de cambio |
| **Spread** | Diferenca entre taxa cobrada e PTAX |
| **Spread %** | Spread em porcentagem |
| **Status** | Situacao da operacao |
### Funcionalidades
### Organizacao
- 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)
As transacoes sao separadas por fluxo:
- **BRL → USD** (fundo roxo claro) - Envios
- **USD → BRL** (fundo azul claro) - Recebimentos
---
### Navegando
## Tema Dark/Light
- Use a barra de rolagem horizontal para ver todas as colunas
- A tabela ordena por data (mais antigas primeiro)
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 transacoes de outros agentes?
### Posso ver dados de outros agentes?
**Agentes** veem apenas seus próprios dados. **Admins** veem dados consolidados de todos.
**Nao.** Cada agente ve apenas suas proprias transacoes. O sistema garante isolamento total dos dados.
### 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.
### Os dados sao atualizados em tempo real?
### 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.
**Sim.** A cada vez que voce carrega o dashboard ou aplica filtros, os dados sao buscados diretamente do sistema.
### A sessão expira?
Sim, após 8 horas de inatividade.
### O que fazer se os graficos nao aparecerem?
### Funciona no celular?
Sim, o layout é responsivo, mas a experiência é melhor em telas maiores.
1. Verifique sua conexao com a internet (os graficos usam biblioteca externa)
2. Tente recarregar a pagina (F5)
3. Se persistir, contate o suporte tecnico
### O que é PTAX?
Taxa de câmbio oficial divulgada pelo Banco Central do Brasil, usada como referência para calcular o spread.
### Como exportar os dados?
*Em breve!* Estamos desenvolvendo funcionalidade de exportacao para Excel/CSV.
### A sessao expira?
**Sim.** Apos 8 horas de inatividade, voce precisara fazer login novamente.
### Posso acessar de celular?
**Sim.** O dashboard e responsivo e funciona em dispositivos moveis, porem a experiencia e melhor em telas maiores.
### O que significa PTAX?
PTAX e a taxa de cambio oficial divulgada pelo Banco Central do Brasil. E usada como referencia para calcular o spread das operacoes.
### 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 usuario e senha
2. Tente recarregar a pagina
1. Verifique usuário e senha
2. Recarregue a página (F5)
3. Contate o administrador do sistema
---
*CambioReal - BI Agentes v1.0*
*CambioReal — BI-CCC*