1 Bem-vindo ao Treinamento

Aprenda a usar a simulação de pagamentos FinoraQi CORE com ML em <1ms

info O que é o FinoraQi CORE?

O FinoraQi CORE é um ambiente de treinamento que simula processamento de pagamentos em tempo real, utilizando machine learning otimizado com Numba JIT para inferência em menos de 1 milissegundo.

⚡

ML Scoring <1ms

Modelo Numba compilado para código nativo

🔄

WebSocket Real-time

Updates de cada etapa do processamento

📊

Benchmark Integrado

Teste de performance com 100 iterações

🛡️

Anti-Fraude

Regras heurísticas + detecção de anomalias

target O que você vai aprender

  • Entender a estrutura do projeto no GitHub
  • Configurar o ambiente local (Docker ou manual)
  • Executar simulações de pagamento via interface
  • Consultar a API via código ou Swagger UI
  • Interpretar métricas de performance e scoring ML
  • Resolver problemas comuns e fazer deploy

2 Estrutura do Projeto

Entenda como os arquivos estão organizados no repositório

folder_tree Árvore de Diretórios

FinoraQi-website/ ├── public/ # Frontend estático │ ├── index.html # Landing page │ ├── dashboard.html # Dashboard do usuário │ ├── core.html ✅ # 🎯 SIMULAÇÃO DE PAGAMENTOS │ ├── crm_enterprise.html # Dashboard empresas │ └── onboarding.html # Tutorial inicial │ ├── backend-fastapi/ # Backend Python │ ├── app/ │ │ ├── main.py # Entry point FastAPI │ │ ├── api/v1/ │ │ │ └── payment.py ✅ # Endpoint /process │ │ ├── ml/ │ │ │ └── scoring.py ✅ # Modelo Numba JIT │ │ └── db/models.py # Schemas Pydantic │ ├── requirements.txt # Dependências Python │ └── Dockerfile │ ├── js/ │ ├── api.js # Cliente API frontend │ └── server.js # Server Node (opcional) │ ├── docker-compose.yml # Orquestração completa ├── .env.example # Template de config ├── vercel.json # Deploy frontend └── README.md # Documentação principal

link Links Importantes

code Repositório Principal no GitHub terminal Backend FastAPI + ML web Frontend (arquivos HTML) menu_book Documentação Completa (README)

3 Como Rodar o Projeto

Configure o ambiente local em 3 minutos

dns Pré-requisitos

Docker + Docker Compose
OU Python 3.10+ e Node.js 18+
Git instalado
Portas 8000 e 8080 livres
🐳 Opção 1: Com Docker (Recomendado) expand_more

Clone e suba os containers:

# 1. Clone o repositório git clone https://github.com/finoraqi-team/FinoraQi-website.git cd FinoraQi-website # 2. Copie template de variáveis cp .env.example .env # 3. Suba os containers docker-compose up -d # 4. Acesse no navegador: # 🎯 Simulação: http://localhost:8080/core.html # 📚 API Docs: http://localhost:8000/docs # 💚 Health: http://localhost:8000/health
🔧 Opção 2: Manual (Desenvolvimento) expand_more

Terminal 1 - Backend:

cd backend-fastapi python -m venv venv # Linux/Mac: source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Terminal 2 - Frontend:

# Na raiz do projeto: python -m http.server 8080 # OU com Node: npx serve public -p 8080

check_circle Verificação

Após iniciar, confirme que tudo está funcionando:

  • ✅ curl http://localhost:8000/health retorna {"status":"healthy"}
  • ✅ http://localhost:8000/docs abre o Swagger UI
  • ✅ http://localhost:8080/core.html carrega a simulação
  • ✅ Console do navegador mostra "✅ WebSocket conectado"

4 Usando a Simulação

Aprenda a processar pagamentos e interpretar resultados

payments Interface do core.html

┌─────────────────────────────────────┐ │ 🏦 FinoraQi • CORE REAL TIME [❓] 👤│ ├─────────────────────────────────────┤ │ │ │ [📝 Formulário de Pagamento] │ │ • ID Usuário: [user_demo_001 ] │ │ • Valor (R$): [150.00 ] │ │ • Descrição: [Compra marketplace]│ │ • Tipo: [📉 Despesa ▼ ] │ │ • Método: [✨ PIX ▼ ] │ │ │ │ [⚡ Processar com ML (1ms)] │ │ [🚀 Rodar Benchmark (100x)] │ │ │ │ [🔄 Painel de Processamento] │ │ [📊] Timer: 0.847ms │ │ [▓▓▓▓▓░░░░] 60% │ │ [✓] Recebido → Validação → ML → │ │ [✓] Anti-Fraude → [⚡] Aprovado │ │ │ │ [✅ Resultado] │ │ • ID: tx_abc123 • Status: ✅ │ │ • Risk: 🟢 Baixo • ML: 94.2% │ │ │ │ [📈 Gráfico: Últimas 20 trans.] │ └─────────────────────────────────────┘

step Passo a Passo

  1. Preencha o formulário:
    Use valores válidos. ID do usuário pode ser qualquer string única.
  2. Clique em "⚡ Processar com ML":
    O frontend envia POST para a API e abre conexão WebSocket.
  3. Acompanhe os steps em tempo real:
    Cada etapa é atualizada via WebSocket com latência em ms.
  4. Analise o resultado:
    Status, risk_score, métricas do modelo e breakdown detalhado.
  5. Teste o benchmark:
    Clique em "Rodar Benchmark" para ver performance em 100 iterações.

data_object Campos do Formulário

Campo Tipo Obrigatório Exemplo
user_id string Sim user_demo_001
amount number > 0 Sim 150.00
description string Sim "Compra marketplace"
category enum Não expense|income|investment|transfer
payment_method enum Não pix|credit_card|debit_card

5 API Reference

Endpoints disponíveis e como consumir programaticamente

post_add POST /api/v1/payment/process

Endpoint principal para processamento de pagamentos.

POST http://localhost:8000/api/v1/payment/process Content-Type: application/json { "user_id": "user_demo_001", "amount": 150.00, "description": "Compra marketplace", "category": "expense", "payment_method": "pix" }

Resposta de sucesso (200):

{ "transaction_id": "tx_abc123xyz", "status": "approved", "amount": 150.00, "processing_time_ms": 0.847, "risk_level": "low", "ml_score": 0.942, "metadata": { "ml_latency_ms": 0.432, "features_used": 14, "is_anomaly": false, "user_trust": 0.94, "model_version": "v2.1.0-numba" } }

websocket WebSocket /ws/payment/{user_id}

Conexão bidirecional para updates em tempo real do processamento.

// Conectar const ws = new WebSocket( 'ws://localhost:8000/ws/payment/user_demo_001' ); // Enviar dados ws.send(JSON.stringify({ type: 'process_payment', data: { /* mesmos campos do POST */ } })); // Receber updates ws.onmessage = (event) => { const data = JSON.parse(event.data); if (data.type === 'progress') { console.log(`Stage: ${data.stage}, Progress: ${data.progress_percent}%`); } if (data.type === 'result') { console.log('Resultado final:', data); } };

health_and_safety Endpoints Adicionais

Endpoint Método Descrição
/health GET Health check do serviço
/api/v1/benchmark?iterations=100 GET Teste de performance com N iterações
/docs GET Swagger UI interativo
/openapi.json GET Especificação OpenAPI 3.0
open_in_new Testar APIs no Swagger UI (localhost)

6 Como Funciona o ML Scoring

Entenda a mágica por trás da inferência em <1ms

psychology Arquitetura do Modelo

[Dados de Entrada] ↓ [Pré-processamento] → Normalização de features ↓ [Numba JIT @jit(nopython=True)] ← Compilação para código nativo ↓ [Weighted Scoring] → Cálculo do risk_score (0.0 a 1.0) ↓ [Clamp & Output] → Retorna score final ↓ [Tempo Total: ~0.4ms] ⚡

code Código do Scoring (simplificado)

Arquivo: backend-fastapi/app/ml/scoring.py

from numba import jit, float64 import numpy as np # Decorator Numba: compila para código nativo @jit(nopython=True, cache=True) def calculate_risk_score( amount: float64, user_trust: float64, transaction_freq: float64, time_of_day: float64, # ... +10 features ) -> float64: # Normalização norm_amount = np.log1p(amount) / 10.0 # Weighted scoring base_score = ( 0.25 * user_trust + 0.20 * (1 - norm_amount) + 0.15 * transaction_freq + # ... mais pesos 0.0 ) # Garante entre 0 e 1 return np.clip(base_score, 0.0, 1.0)

bolt Por que é tão rápido?

Técnica Benefício
Numba JIT Compila Python → código nativo na primeira execução
cache=True Reusa código compilado entre requests (sem recompilar)
NumPy vetorial Operações em batch, sem loops Python lentos
Features pré-calculadas Evita computação redundante no scoring
Sem I/O no scoring Tudo em memória, zero acesso a disco/rede

7 Benchmark & Performance

Meça e otimize a performance do sistema

speed Como Rodar o Benchmark

Na interface core.html, clique em "🚀 Rodar Benchmark (100 iterações)".

# Ou via curl: curl http://localhost:8000/api/v1/benchmark?iterations=100

analytics Interpretando os Resultados

Exemplo de output:

{ "min_ms": 0.0234, "max_ms": 2.1456, "mean_ms": 0.8912, "p50_ms": 0.8234, "p95_ms": 1.4521, "p99_ms": 1.9876, "std_ms": 0.3421, "target_achieved": true }
Métrica O que significa Target
P99 99% das requests respondem em ≤ este valor < 2ms
Média Tempo médio de resposta < 1ms
target_achieved % de requests abaixo de 1ms ≥ 90% true
std (desvio) Consistência da performance Quanto menor, melhor

trending_up Dicas de Otimização

  • Primeira request é lenta (~2s): Normal! É o Numba compilando. Requests seguintes são <1ms.
  • Use cache=True: Garante que a compilação seja reutilizada entre reinicializações.
  • Evite I/O no scoring: Mantenha o modelo puramente computacional.
  • Monitore em produção: Adicione logs de latência para detectar degradação.

8 Deploy & Troubleshooting

Coloque em produção e resolva problemas comuns

🚀 Deploy em Produção expand_more

Vercel (Frontend):

npm i -g vercel vercel login vercel --prod # Configure API_BASE_URL nas vars de ambiente

Railway/Render (Backend):

# railway.toml [build] builder = "nixpacks" [deploy] startCommand = "uvicorn app.main:app --host 0.0.0.0 --port $PORT" [env] PYTHON_VERSION = "3.10" DATABASE_URL = "${{ secrets.DATABASE_URL }}"
🔧 Problemas Comuns expand_more
Problema Solução
API não responde em :8000 docker-compose logs -f backend para ver erros
WebSocket não conecta Verifique CORS no backend: allow_origins=["*"] para dev
ML scoring lento (>5ms) Confirme @jit(nopython=True) e cache=True
Frontend 404 em assets Verifique vercel.json servindo public/**/*
🔐 Variáveis de Ambiente expand_more

.env.production (obrigatórias):

ENV=production SECRET_KEY=gerar_com_openssl_rand_base64_32 DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/db REDIS_URL=redis://user:pass@host:6379/0 JWT_SECRET_KEY=outra_chave_forte_aqui CORS_ORIGINS=https://seu-frontend.vercel.app

⚠️ Nunca commitar .env no Git! Use .gitignore e variáveis da plataforma de deploy.

support_agent Suporte & Contribuição

🐛

Reportar Bug

Abrir Issue no GitHub

💡

Sugerir Feature

Discussions no GitHub

🤝

Contribuir

Fork → Branch → PR. Veja CONTRIBUTING.md

📧

Contato Direto

finoraqi.finance@gmail.com