FastPix - Sistema de Cobranças PIX

Sistema completo de geração e gerenciamento de cobranças PIX integrado com a plataforma Asaas, com autenticação via Keycloak e interface administrativa moderna.

🚀 Funcionalidades

• ✅ Criação de cobranças PIX com QR Code automático
• ✅ Gestão completa de cobranças (listagem, detalhes, estatísticas)
• ✅ Autenticação robusta (Keycloak SSO, JWT, API Key)
• ✅ Open Finance - Validação de capacidade financeira via Belvo
• ✅ Webhooks para notificações em tempo real da Asaas
• ✅ Interface administrativa responsiva com PrimeVue
• ✅ Observabilidade completa (Jaeger, Prometheus, Grafana)
• ✅ Testes BDD com SpecFlow e Gherkin
• ✅ API Gateway com Kong para rate limiting e segurança

📋 Arquitetura

Cliente/Browser
     │
     ▼
Kong Gateway (:8002)
  │   │   │
  │   │   └─► Keycloak SSO (:8081)
  │   │
  │   └─────► FastPix BFF API (:7000)
  │                │
  │                ├─► SQL Server (:1433)
  │                ├─► Asaas API (PIX)
  │                └─► Belvo API (Open Finance)
  │
  └─────────► Nuxt Admin (:3000)

Componentes

• FastPixBff: API BFF em ASP.NET Core 10.0 com Entity Framework Core
• fast-pix-nuxt: Interface administrativa em Nuxt 4 + TypeScript + PrimeVue
• Kong: API Gateway para roteamento, rate limiting e CORS
• Keycloak: Identity Provider (SSO) para autenticação centralizada
• SQL Server 2022: Banco de dados relacional
• Observabilidade: Jaeger (tracing), Prometheus (metrics), Grafana (dashboards)

🏃 Início Rápido

Pré-requisitos

• Docker e Docker Compose
• Tilt (recomendado)
• OU .NET 10.0 SDK + Node.js 18+

Opção 1: Tilt (Recomendado)

A forma mais simples de executar todo o ambiente:

# Subir toda a stack
tilt up

# Dashboard disponível em: http://localhost:10350

URLs disponíveis:

• 🌐 API + Swagger: http://localhost:7000/docs
• 🖥️ Web Admin: http://localhost:3000
• 📚 Documentação: http://localhost:8000
• 🔐 Keycloak: http://localhost:8081
• 🔍 Jaeger: http://localhost:16686
• 📊 Prometheus: http://localhost:9090
• 📈 Grafana: http://localhost:3001

Opção 2: Docker Compose

cd infra/dev
docker compose up --build

Opção 3: Desenvolvimento Local (sem containers)

API:

cd FastPixBff
dotnet restore
dotnet run
# API disponível em http://localhost:5180

Frontend:

cd fast-pix-nuxt
npm install
npm run dev
# Web disponível em http://localhost:3000

Documentação:

pip install -r requirements-docs.txt
mkdocs serve
# Docs disponíveis em http://localhost:8000

📖 Documentação

Para Desenvolvedores

• CONTEXT.md - Contexto completo do projeto para desenvolvedores e agentes de IA
• docs/ - Documentação completa em MkDocs
  • API.md - Referência de endpoints
  • USAGE.md - Guia de uso
  • TESTING.md - Guia de testes
  • TECHNICAL_SPEC.md - Especificação técnica
  • TRACEABILITY.md - Rastreabilidade
  • ERROR_CODES.md - Catálogo de erros

Documentação Online

Execute mkdocs serve e acesse http://localhost:8000 para navegação completa.

Para Agentes de IA

O arquivo CONTEXT.md foi criado especificamente para fornecer contexto completo do projeto para agentes de código. Ele inclui:

• Visão geral da arquitetura
• Estrutura de diretórios detalhada
• Componentes principais e suas responsabilidades
• Padrões de código e documentação
• Fluxos de autenticação e criação de cobranças
• Convenções e boas práticas

🧪 Testes

Testes BDD (SpecFlow)

cd FastPixBff.Specs
dotnet test

Testes de API (Postman/Newman)

newman run postman/FastPix.postman_collection.json \
  -e postman/FastPix.env.json

Testes de Carga (k6)

k6 run tests/load/fastpix.k6.js

🔐 Autenticação

O sistema suporta três mecanismos de autenticação:

1. Keycloak (Recomendado para Produção)

• OpenID Connect / OAuth 2.0
• SSO (Single Sign-On)
• Credenciais padrão de dev:
  • Usuário: fastpix-admin
  • Senha: fastpix

2. JWT Interno

Obter token via API:

curl -X POST http://localhost:7000/auth/token \
  -H "Content-Type: application/json" \
  -d '{"clientId":"seu-cliente","clientSecret":"seu-segredo"}'

3. API Key (Interno)

Para comunicação entre serviços:

curl -X GET http://localhost:8002/internal/stats \
  -H "x-consumer-key: fastpix-internal-key"

📊 Endpoints Principais

Cobranças

# Criar cobrança PIX
POST /api/charges/pix
Authorization: Bearer {token}
Content-Type: application/json
{
  "name": "João Silva",
  "cpfCnpj": "12345678900",
  "email": "joao@example.com",
  "mobilePhone": "11999999999",
  "amount": 100.00,
  "description": "Pedido #123"
}

# Listar cobranças
GET /api/charges/list?page=1&pageSize=20&status=PENDING

# Buscar cobrança por ID
GET /api/charges/{id}

# Estatísticas do dia
GET /api/charges/stats

Open Finance

# Validar capacidade financeira
POST /api/open-finance/validate-capacity
Authorization: Bearer {token}
Content-Type: application/json
{
  "linkId": "link-id-belvo",
  "claimedAmount": 5000.00
}

Health Checks

# Liveness probe
GET /health/live

# Readiness probe
GET /health/ready

🛠️ Configuração

Variáveis de Ambiente - API

# Asaas
Asaas__AccessToken=SEU_TOKEN
Asaas__WebhookToken=SEU_TOKEN_WEBHOOK

# Keycloak
Keycloak__Authority=http://keycloak:8080/realms/fastpix
Keycloak__Audience=fastpix-api

# Database
ConnectionStrings__DefaultConnection=Server=localhost,1433;Database=FastPixDb;...

# Belvo (Open Finance)
Belvo__UseMock=false
Belvo__SecretId=SEU_SECRET_ID
Belvo__SecretPassword=SEU_SECRET_PASSWORD

Variáveis de Ambiente - Frontend

NUXT_PUBLIC_API_BASE_URL=http://localhost:8002
NUXT_PUBLIC_KEYCLOAK_URL=http://localhost:8081
NUXT_PUBLIC_KEYCLOAK_REALM=fastpix
NUXT_PUBLIC_KEYCLOAK_CLIENT_ID=fastpix-admin

🏗️ Estrutura do Projeto

fast-pix/
├── FastPixBff/              # API Backend (.NET 10)
│   ├── Auth/                # Autenticação (JWT, Keycloak, API Key)
│   ├── Data/                # Entity Framework Core
│   ├── Entities/            # Modelos de domínio
│   ├── Models/              # DTOs
│   ├── Services/            # Lógica de negócio
│   └── Program.cs           # Configuração e endpoints
├── FastPixBff.Specs/        # Testes BDD (SpecFlow)
├── fast-pix-nuxt/           # Frontend (Nuxt 4)
│   ├── composables/         # Lógica reutilizável
│   ├── pages/               # Rotas
│   ├── stores/              # Estado global (Pinia)
│   └── middleware/          # Guards de autenticação
├── docs/                    # Documentação MkDocs
├── infra/                   # Infraestrutura (Docker, K8s)
├── tests/                   # Testes (carga, integração)
├── postman/                 # Coleções Postman
├── scripts/                 # Scripts utilitários
├── CONTEXT.md               # Contexto para agentes de IA
├── README.md                # Este arquivo
└── Tiltfile                 # Configuração Tilt

🤝 Contribuindo

1. Fork o projeto
2. Crie sua feature branch: git checkout -b feature/minha-feature
3. Siga os padrões de código e documentação
4. Adicione testes para novas funcionalidades
5. Execute os testes: dotnet test && npm test
6. Commit suas mudanças: git commit -m 'feat: adiciona nova funcionalidade'
7. Push para a branch: git push origin feature/minha-feature
8. Abra um Pull Request

Padrões de Documentação

• C#: Use XML documentation (/// <summary>)
• TypeScript: Use JSDoc (/** @param */)
• Markdown: Siga estrutura hierárquica com exemplos

Consulte CONTEXT.md para padrões detalhados.

📈 Performance

O sistema foi otimizado para alta performance:

• ⚡ Thread pool configurado para 200 threads mínimos
• ⚡ Connection pooling otimizado (EF Core)
• ⚡ Response compression (Gzip/Brotli)
• ⚡ Rate limiting configurável
• ⚡ Circuit breaker para APIs externas
• ⚡ Caching de respostas quando aplicável

Consulte docs/BENCHMARK.md para detalhes de performance.

🔒 Segurança

• 🔐 Autenticação multi-camada (Keycloak, JWT, API Key)
• 🔐 Validação de payload com FluentValidation
• 🔐 Headers de segurança (HSTS, X-Frame-Options, CSP)
• 🔐 Rate limiting por IP e endpoint
• 🔐 Logs estruturados sem dados sensíveis
• 🔐 Webhook com validação de token
• 🔐 CORS configurado por ambiente

📝 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

👥 Time

Desenvolvido por ktfth

📞 Suporte

• 📧 Email: suporte@fastpix.com
• 🐛 Issues: GitHub Issues
• 📖 Documentação: http://localhost:8000 (desenvolvimento)

---

Nota: Este README fornece uma visão geral do projeto. Para informações detalhadas sobre arquitetura, componentes e padrões de código, consulte CONTEXT.md e a documentação completa em docs/.