FinanceProcessor - Documentação Técnica

📋 Visão Geral

FinanceProcessor é uma solução completa para processamento de arquivos CNAB (Centro Nacional de Automação Bancária), desenvolvida com .NET 10 e .NET Aspire. A aplicação permite que usuários façam upload de arquivos CNAB, visualizem transações extraídas, gerenciem arquivos enviados e acompanhem estatísticas em tempo real através de um dashboard intuitivo.

🏗️ Arquitetura do Sistema

O FinanceProcessor é uma aplicação distribuída construída com .NET Aspire, que orquestra múltiplos serviços de forma integrada:

Componentes Principais

1. API REST (FinanceProcessor.API)

Serviço responsável por fornecer os endpoints HTTP que alimentam a aplicação web. Construído com ASP.NET Core, oferece:

• Endpoints de Upload: Recebe arquivos CNAB, valida seu conteúdo e persiste no armazenamento
• Endpoints de Transações: Fornece acesso paginado às transações processadas com cálculo de totais
• Endpoints de Gerenciamento de Arquivos: Lista e detalha arquivos salvos com metadados
• Endpoint de Dashboard: Retorna estatísticas agregadas do sistema (total de arquivos, transações, valor total, etc.)

Todos os endpoints seguem padrões RESTful com respostas padronizadas e tratamento robusto de erros.

2. Aplicação Web (FinanceProcessor.Web)

Interface moderna construída com Blazor (renderizada interativamente no servidor), oferecendo:

• Dashboard: Visualização de estatísticas principais do sistema em cards informativos
• Upload de Arquivos: Interface intuitiva para envio de arquivos CNAB com validação client-side
• Listagem de Transações: Tabela paginada mostrando valor total de todas as transações
• Gerenciamento de Arquivos: Visualize histórico completo de uploads com detalhes técnicos (hash SHA-256, tamanho, data)

A aplicação usa Bootstrap 5 para styling profissional e Bootstrap Icons para uma experiência visual coerente.

3. Worker de Processamento (FinanceProcessor.Worker.DataImporter)

Serviço em background que processa arquivos de forma assíncrona através de filas Kafka:

• Consumo de Mensagens: Monitora continuamente a fila de importação de dados
• Parsing de CNAB: Extrai transações dos arquivos usando regras de validação específicas
• Persistência de Dados: Armazena transações no banco de dados relacional
• Processamento Resiliente: Implementa retry logic e tratamento de exceções para garantir processamento confiável

Este worker desacopla o upload do processamento, permitindo que uploads sejam rápidos enquanto o processamento acontece em segundo plano.

🛠️ Stack Tecnológico

Backend

• .NET 10: Framework base de toda a aplicação
• .NET Aspire: Orquestração e configuração de serviços distribuídos
• ASP.NET Core: Framework web para API REST
• Entity Framework Core: ORM para acesso aos dados
• Kafka: Message broker para processamento assíncrono
• Azure Blob Storage / Local Storage: Armazenamento de arquivos

Frontend

• Blazor: Framework interativo com C# no servidor
• Bootstrap 5: Framework CSS para design responsivo
• Bootstrap Icons: Ícones SVG para interface
• JavaScript Interop: Integração com JavaScript quando necessário

Infraestrutura

• .NET Aspire AppHost: Orquestração de containers e serviços
• SQL Server: Banco de dados relacional principal
• Docker: Containerização de serviços (quando usado localmente ou em produção)

📊 Fluxo de Dados

Usuário
   ↓
[Upload CNAB] → API (Validação) → Armazenamento
                                      ↓
                             Mensagem Kafka
                                      ↓
                             Worker (Processamento)
                                      ↓
                           Banco de Dados (Transações)
                                      ↓
                             Web (Dashboard)
                                      ↓
                              Visualização

1. Upload: Usuário envia arquivo CNAB através da web
2. Validação: API valida formato e estrutura do arquivo
3. Armazenamento: Arquivo é salvo no blob storage e metadados no BD
4. Fila: Mensagem de importação é publicada no Kafka
5. Processamento: Worker consome mensagem e processa transações
6. Persistência: Transações são inseridas no banco de dados
7. Visualização: Dashboard e listagens são atualizadas com novos dados

🚀 Como Executar

Pré-requisitos

• .NET 10 SDK instalado (download)
• .NET Aspire instalado (dotnet workload install aspire)
• Docker Desktop instalado (para executar dependências como Kafka, SQL Server)
• Visual Studio 2026 ou Visual Studio Code com extensões C#

Setup Inicial

1. Execute o AppHost

cd src/FinanceProcessor.AppHost
dotnet run

O AppHost abrirá uma página no navegador com todos os serviços inicializados e suas respectivas URLs de acesso:

• 🖥️ API REST
• 🌐 Web Blazor
• 📨 Kafka
• 🗄️ Banco de Dados
• 🔄 Worker de processamento

🔒 Segurança e Validação

• Validação de Entrada: Todos os arquivos são validados antes do processamento
• Hash de Integridade: SHA-256 calculado para cada arquivo
• Tratamento de Erros: Exceções capturadas e reportadas com mensagens amigáveis
• Isolamento de Processos: Worker processa em background sem afetar a API

📈 Performance e Escalabilidade

• Paginação: Todos os endpoints de listagem implementam paginação
• Processamento Assíncrono: Kafka desacopla upload de processamento
• Cache de Respostas: Stateless API permite horizontal scaling
• Banco de Dados Indexado: Índices em chaves de busca frequentes

📖 API Swagger/OpenAPI

A API REST está totalmente documentada via Swagger/OpenAPI com versionamento /api/v1/.

Após executar a aplicação, acesse: https://localhost:7123/swagger/index.html

🧪 Testes de Integração com .NET Aspire

O projeto inclui testes de integração automatizados usando MSTest com .NET Aspire Testing. Os testes validam os endpoints da API em um ambiente controlado, garantindo funcionalidade e robustez.

Para executar:

dotnet test test/FinanceProcessor.Tests

📚 Recursos Adicionais

• CNAB Specification: Banco Central do Brasil
• .NET Aspire Documentation: Microsoft Docs
• .NET Aspire Testing: Microsoft Docs
• Blazor Documentation: Microsoft Docs
• Entity Framework Core: Microsoft Docs