CnabAnalizeScore 0.1.1

🏦 CnabAnalizeScore

Biblioteca .NET para análise e validação de layouts CNAB (Centro Nacional de Automação Bancária) com algoritmos de similaridade inteligente para mapeamento automático de campos.

📋 Índice

• Sobre
• Características
• Instalação
• Uso Rápido
• Conceitos
• Exemplos Avançados
• Layouts Disponíveis
• API
• Contribuindo

🎯 Sobre

CnabAnalizeScore é uma biblioteca que facilita a integração e validação de arquivos CNAB, permitindo que você:

• 🔍 Analise layouts CNAB comparando campos de entrada com templates pré-configurados
• 🎯 Calcule scores de similaridade entre nomes de campos usando múltiplos algoritmos (Levenshtein, similaridade textual, compatibilidade de tipos)
• 📊 Obtenha relatórios detalhados com percentuais de match e compatibilidade
• 🔄 Compare múltiplos layouts automaticamente e escolha o melhor match

Ideal para sistemas que precisam importar dados de diferentes fontes (Excel, CSV, APIs) e mapeá-los para o formato CNAB de forma inteligente e automática.

✨ Características

• ✅ Matching inteligente de campos usando algoritmos de similaridade textual
• ✅ Suporte a múltiplos layouts CNAB (400, 444, etc.)
• ✅ Cálculo automático de score de compatibilidade
• ✅ Validação de tipos de dados (texto, número, decimal)
• ✅ Análise de múltiplos layouts simultaneamente
• ✅ Relatórios detalhados com estatísticas de match
• ✅ Extensível - fácil adicionar novos layouts e algoritmos

📦 Instalação

Via NuGet Package Manager

Install-Package CnabAnalizeScore

Via .NET CLI

dotnet add package CnabAnalizeScore

Via PackageReference (no .csproj)

<PackageReference Include="CnabAnalizeScore" Version="1.0.0" />

🚀 Uso Rápido

Exemplo Básico

using CnabAnalizeScore.Core.CnabAnalize;
using CnabAnalizeScore.Core.CnabTemplates;

// 1. Definir os campos de entrada (vindos do seu Excel, CSV, API, etc.)
var camposEntrada = new[]
{
    "Seu Numero",
    "Numero Documento",
    "Data Vencimento",
    "Valor do Titulo",
    "Nome do Sacado",
    "CPFCNPJ"
};

// 2. Criar o template do layout CNAB que deseja analisar
var cnab400 = Cnab400Template.Create();

// 3. Criar o analisador e executar
var matcher = new CnabLayoutMatcher();
var resultado = matcher.AnalisarLayout(cnab400, camposEntrada);

// 4. Verificar compatibilidade
if (resultado.IsCompativel)
{
    Console.WriteLine($"✅ Layout compatível!");
    Console.WriteLine($"📊 Percentual de match: {resultado.PercentualMatch:P1}");
    Console.WriteLine($"⭐ Score médio: {resultado.ScoreMedio:P1}");
    
    // Listar campos mapeados
    foreach (var field in resultado.Fields)
    {
        Console.WriteLine($"  {field.NomeCampoOrigem} ← {field.NomeCampoDestino} ({field.Score:P0})");
    }
}
else
{
    Console.WriteLine("❌ Layout não compatível");
}

Saída Exemplo

✅ Layout compatível!
📊 Percentual de match: 85.7%
⭐ Score médio: 92.3%
  SeuNumero ← Seu Numero (100%)
  NumeroDocumento ← Numero Documento (100%)
  DataVencimento ← Data Vencimento (100%)
  ValorTitulo ← Valor do Titulo (95%)
  NomeSacado ← Nome do Sacado (98%)
  CPF_CNPJ ← CPFCNPJ (90%)

💡 Conceitos

Score de Similaridade

O score varia de 0.0 a 1.0 (0% a 100%) e indica o quão similar é o nome do campo de entrada com o campo do layout CNAB. O cálculo considera:

1. Similaridade Textual: Compara as strings usando distância de Levenshtein
2. Palavras-chave: Verifica sinônimos e variações pré-configuradas
3. Compatibilidade de Tipo: Valida se os tipos de dados são compatíveis

Score de Rejeição

Cada layout possui um score de rejeição (padrão: 0.3 ou 30%). Campos com score abaixo deste valor são descartados do resultado.

// Exemplo: Layout com score de rejeição de 40%
var layout = Cnab400Template.Create(); // ScoreRejeicao = 0.3 (30%)

Resultado da Análise

O objeto LayoutMatchResult contém:

📚 Exemplos Avançados

Analisar Múltiplos Layouts

Quando você não sabe qual layout usar, pode analisar vários e obter o melhor match:

// Criar lista de layouts para testar
var layouts = new List<BaseTemplate>
{
    Cnab400Template.Create(),
    Cnab444Template.Create()
};

// Analisar todos e retornar o melhor
var matcher = new CnabLayoutMatcher();
var melhorResultado = matcher.AnalisarMelhoresLayouts(layouts, camposEntrada);

Console.WriteLine($"🏆 Melhor layout: {melhorResultado.TypeLayout}");
Console.WriteLine($"📊 Score: {melhorResultado.ScoreMedio:P1}");

Filtrar Campos por Score

var resultado = matcher.AnalisarLayout(cnab400, camposEntrada);

// Obter apenas matches com score acima de 80%
var matchesAltos = resultado.Fields
    .Where(f => f.Score >= 0.8f)
    .OrderByDescending(f => f.Score)
    .ToList();

foreach (var match in matchesAltos)
{
    Console.WriteLine($"✅ {match.NomeCampoDestino} → {match.NomeCampoOrigem} " +
                      $"(Score: {match.Score:P1})");
}

Identificar Campos Não Mapeados

var resultado = matcher.AnalisarLayout(cnab400, camposEntrada);

// Campos de entrada que não foram mapeados
var camposNaoMapeados = camposEntrada
    .Where(campo => !resultado.Fields.Any(f => f.NomeCampoDestino == campo))
    .ToList();

if (camposNaoMapeados.Any())
{
    Console.WriteLine("⚠️  Campos não mapeados:");
    foreach (var campo in camposNaoMapeados)
    {
        Console.WriteLine($"  • {campo}");
    }
}

Validar Compatibilidade Mínima

const float PERCENTUAL_MINIMO = 0.7f; // 70%

var resultado = matcher.AnalisarLayout(cnab400, camposEntrada);

if (resultado.PercentualMatch >= PERCENTUAL_MINIMO)
{
    Console.WriteLine("✅ Layout validado! Pode prosseguir com a importação.");
}
else
{
    Console.WriteLine($"❌ Layout incompatível. Necessário {PERCENTUAL_MINIMO:P0}, " +
                      $"encontrado apenas {resultado.PercentualMatch:P0}");
}

📋 Layouts Disponíveis

CNAB 400

Layout CNAB 400 - Remessa

var cnab400 = Cnab400Template.Create();
// Score de rejeição: 30%
// Template genérico CNAB 400 - Remessa
// Campos: SeuNumero, NumeroDocumento, NossoNumero, DataEmissao, 
//         DataVencimento, ValorTitulo, CPF_CNPJ, NomeSacado, etc.

Campos principais:

• SeuNumero: Número de controle do participante
• NumeroDocumento: Número do documento de cobrança
• NossoNumero: Identificação do título no banco
• DataEmissao / DataVencimento: Datas em formato DDMMAA
• ValorTitulo: Valor nominal (decimal com 2 casas)
• CPF_CNPJ: Documento do sacado
• NomeSacado: Nome do pagador
• Endereco, Numero, Bairro, Cidade, UF, CEP
• ValorJurosDia, ValorMulta, DiasProtesto
• Mensagem1, Mensagem2: Instruções/observações

CNAB 444

Layout CNAB 444 - Remessa - Cessão de Crédito / FIDC

var cnab444 = Cnab444Template.Create();
// Score de rejeição: 35%
// Template CNAB 444 - Cessão de Crédito / FIDC
// Campos: SeuNumero, NumeroTitulo, ChaveNFe, NumeroNFe, etc.

Campos principais:

• SeuNumero: Número de controle do participante
• NumeroTitulo: Número do título/duplicata
• ChaveNFe: Chave de acesso da NF-e (44 dígitos)
• NumeroNFe, SerieNFe: Dados da nota fiscal
• DataEmissaoNFe: Data de emissão da NF-e (DDMMAAAA)
• ValorNFe: Valor total da nota fiscal
• DataVencimento: Data de vencimento (DDMMAAAA)
• ValorNominal: Valor nominal do título
• CPF_CNPJ_Sacado, RazaoSocial: Dados do sacado
• CPF_CNPJ_Cedente: Documento do cedente

Criar seu Próprio Layout

public class MeuLayoutCustom : BaseTemplate
{
    private MeuLayoutCustom() : base("MeuLayout", scoreRejeicao: 0.3f)
    {
        InitializeFields();
    }

    public static MeuLayoutCustom Create() => new MeuLayoutCustom();

    private void InitializeFields()
    {
        var fields = new List<FieldCnab>();
        
        fields.Add(new FieldCnab(
            name: "CodigoCliente",
            typeField: "NUMERO",
            startPosition: 1,
            endPosition: 10,
            length: 10,
            similarity: new FieldSimilarity(new[] { 
                "Codigo Cliente", 
                "CodCliente", 
                "Id Cliente" 
            }),
            description: "Código único do cliente"
        ));
        
        // Adicionar mais campos...
        
        fieldCnabs = fields;
    }
}

🔧 API

CnabLayoutMatcher

Classe principal para análise de layouts.

Métodos

AnalisarLayout(BaseTemplate layout, string[] camposEntrada)

• Analisa um único layout CNAB
• Parâmetros:
  • layout: Template do layout (ex: Cnab400Template.Create())
  • camposEntrada: Array com nomes dos campos a comparar
• Retorna: LayoutMatchResult com o resultado completo
• Exceções:
  • ArgumentNullException: Se layout for nulo
  • ArgumentException: Se camposEntrada for nulo ou vazio

AnalisarMelhoresLayouts(List<BaseTemplate> layouts, string[] camposEntrada)

• Analisa múltiplos layouts e retorna o melhor match
• Parâmetros:
  • layouts: Lista de templates para analisar
  • camposEntrada: Array com nomes dos campos a comparar
• Retorna: LayoutMatchResult do layout mais compatível
• Exceções:
  • ArgumentException: Se layouts for nulo ou vazio

LayoutMatchResult

Resultado da análise de um layout.

Propriedades

FieldMatchResult

Resultado do match de um campo específico.

Propriedades

BaseTemplate

Classe base para todos os layouts CNAB.

Propriedades

FieldCnab

Estrutura que representa um campo no layout CNAB.

Construtor

FieldCnab(
    string name,
    string typeField,        // "TEXTO", "NUMERO", "DECIMAL"
    int startPosition,
    int endPosition,
    int length,
    FieldSimilarity similarity,
    string description = ""
)

FieldSimilarity

Define sinônimos e variações para o campo.

new FieldSimilarity(new[] { 
    "Nome Principal",
    "Variacao 1",
    "Variação 2",
    "Nome_Alternativo"
})

🛠️ Casos de Uso

1. Importação de Planilhas Excel

// Ler cabeçalhos da planilha
var colunas = ObterColunasExcel("arquivo.xlsx");

// Validar compatibilidade com CNAB
var matcher = new CnabLayoutMatcher();
var resultado = matcher.AnalisarLayout(Cnab400Template.Create(), colunas);

if (resultado.IsCompativel)
{
    // Criar mapeamento para importação
    var mapeamento = resultado.Fields.ToDictionary(
        f => f.NomeCampoDestino,  // Coluna do Excel
        f => f.NomeCampoOrigem     // Campo do CNAB
    );
    
    // Usar mapeamento para importar dados
    ImportarDados(mapeamento);
}

2. Validação de APIs de Integração

// Receber JSON de API externa
var camposApi = JsonSerializer.Deserialize<string[]>(jsonResponse);

// Verificar se a API retorna os campos necessários
var resultado = matcher.AnalisarLayout(cnab400, camposApi);

if (resultado.PercentualMatch < 0.8f)
{
    throw new InvalidOperationException(
        $"API incompatível. Necessário 80%, encontrado {resultado.PercentualMatch:P0}"
    );
}

3. Detecção Automática de Layout

// Quando não sabe qual layout usar
var todosLayouts = new List<BaseTemplate>
{
    Cnab400Template.Create(),
    Cnab444Template.Create(),
    // ... outros layouts
};

var melhor = matcher.AnalisarMelhoresLayouts(todosLayouts, camposUsuario);

Console.WriteLine($"Layout detectado automaticamente: {melhor.TypeLayout}");

🤝 Contribuindo

Contribuições são bem-vindas! Para adicionar novos layouts ou melhorias:

1. Fork o repositório
2. Crie uma branch para sua feature (git checkout -b feature/NovoLayout)
3. Implemente suas mudanças
4. Adicione testes
5. Commit suas mudanças (git commit -am 'Adiciona novo layout CNAB XXX')
6. Push para a branch (git push origin feature/NovoLayout)
7. Abra um Pull Request

Adicionando um Novo Layout

1. Crie uma nova classe herdando de BaseTemplate
2. Implemente o método InitializeFields()
3. Defina todos os campos com suas respectivas similaridades
4. Adicione testes unitários
5. Atualize a documentação

📄 Licença

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.

📞 Suporte

• 🐛 Issues: GitHub Issues
• 📧 Email: suporte@example.com
• 💬 Discussões: GitHub Discussions

🙏 Agradecimentos

• Baseado nas especificações oficiais FEBRABAN
• Inspirado nas necessidades reais de integração bancária
• Desenvolvido para a comunidade .NET brasileira

Feito com ❤️ para facilitar integrações CNAB no Brasil