Sufficit.EFData 1.26.909.1815

<h1> Sufficit.EFData <a href="https://github.com/sufficit"><img src="https://avatars.githubusercontent.com/u/66928451?s=200&v=4" alt="Sufficit Logo" width="80" align="right"></a> </h1>

Worktrees (padrão Sufficit): toda árvore de trabalho deste projeto (humanos ou agentes de IA) deve ser criada dentro da pasta do próprio projeto: git worktree add .worktrees/<nome>. A pasta .worktrees/ é ignorada pelo git (.gitignore → **/.worktrees/) e nunca deve ser versionada ou criada fora da raiz do repositório.

Entity Framework Data Providers for Sufficit Ecosystem

A comprehensive .NET library that provides Entity Framework-based data access providers for the Sufficit platform. This library implements the Provider Architecture Pattern with extension methods for optimal performance and maintainability.

📋 Table of Contents

• About
• Features
• Architecture
• Installation
• Usage
• Modules
• Configuration
• Database migrations
• Development
• Contributing
• License

📖 About

Sufficit.EFData is a core component of the Sufficit ecosystem, providing standardized data access patterns using Entity Framework Core. The library implements a consistent provider architecture that ensures:

• Multi-target Framework Support: Compatible with .NET 7, .NET 9, and .NET 10
• Provider Pattern: Clean separation between data access logic and business logic
• Extension Methods: Convenient query methods without additional abstraction layers
• Dependency Injection: Seamless integration with Microsoft.Extensions.DependencyInjection
• Database Agnostic: Support for multiple database providers (MySQL, SQL Server, etc.)

Key Principles

1. Single Responsibility: Each provider handles one specific domain
2. Extension Methods: Business logic extensions without repository overhead
3. Scoped Contexts: Proper DbContext lifecycle management
4. Consistent API: Uniform interface across all providers

✨ Features

🔧 Core Features

• Multi-Framework Targeting: Supports .NET 7, .NET 9, and .NET 10
• Provider Architecture: Clean separation of data access concerns
• Extension Methods: Fluent API for complex queries
• Dependency Injection: Native support for IServiceCollection
• Database Providers: MySQL, SQL Server, and PostgreSQL support
• Migration Tools: Built-in database migration utilities

📊 Domain Modules

• Exchange: Email tracking, message templates, and communication logs
• Identity: User management and authentication data
• Contacts: Customer and contact information management
• Telephony: Call records, CDR data, and telephony operations
• Finance: Billing, payments, and financial transactions
• Statistics: Analytics and reporting data
• Storage: File and media storage management
• Tasks: Background job and task management

🛠️ Developer Experience

• IntelliSense Support: Full IDE integration
• Comprehensive Documentation: Detailed API documentation
• Code Examples: Practical usage samples
• Migration Tools: Database schema management
• Testing Support: Unit testing utilities

🏗️ Architecture

Provider Pattern Implementation

Sufficit.EFData/
├── EFProvider<TContext>          # Abstract base provider
├── ScopedProvider               # Scoped service management
├── Extension Methods            # Query extensions
└── DbContext Implementations    # Database contexts

Key Components

EFProvider Base Class

public abstract class EFProvider<DBContext> : ScopedProvider
    where DBContext : Microsoft.EntityFrameworkCore.DbContext
{
    protected EFProvider(IServiceScopeFactory serviceScopeFactory)
        : base(serviceScopeFactory) { }

    protected DBContext CreateDbContext(IServiceScope scope)
        => scope.ServiceProvider.GetRequiredService<DBContext>();
}

Extension Methods Pattern

public static class EFMessageTemplateProviderExtensions
{
    public static async Task<MessageTemplate?> GetByTitleAsync(
        this EFMessageTemplateProvider provider,
        string title,
        CancellationToken cancellationToken = default)
    {
        return await provider.Search(new MessageTemplateSearchParameters
        {
            Title = title
        }).FirstOrDefaultAsync(cancellationToken);
    }
}

Database Context Management

• Scoped Lifetime: DbContext instances are properly scoped
• Connection Pooling: Efficient database connection management
• Transaction Support: ACID transaction handling
• Migration Support: Automatic schema updates

📦 Installation

NuGet Package

# Install via NuGet
dotnet add package Sufficit.EFData

# Or via Package Manager
Install-Package Sufficit.EFData

Package Reference

<PackageReference Include="Sufficit.EFData" Version="1.0.0" />

Prerequisites

• .NET 7, .NET 9, or .NET 10
• Entity Framework Core packages
• Database Provider (MySQL, SQL Server, etc.)

The legacy netstandard2.0 target was retired because its EF Core 3.1 MySQL provider required Newtonsoft.Json. Sufficit.EFData standardizes JSON handling on System.Text.Json and rejects Newtonsoft dependencies during build and test.

🚀 Usage

Basic Setup

// Program.cs or Startup.cs
using Microsoft.Extensions.DependencyInjection;
using Sufficit.EFData;

public void ConfigureServices(IServiceCollection services)
{
    // Add database context
    services.AddDbContext<ExchangeDbContext>(options =>
        options.UseMySql(connectionString,
            new MySqlServerVersion(new Version(8, 0, 21))));

    // Register providers
    services.AddSufficitEFData();
}

Using Providers

public class MessageService
{
    private readonly EFMessageTemplateProvider _provider;

    public MessageService(EFMessageTemplateProvider provider)
    {
        _provider = provider;
    }

    public async Task<MessageTemplate?> GetTemplateAsync(string title)
    {
        // Using extension method
        return await _provider.GetByTitleAsync(title);
    }

    public async Task<IEnumerable<MessageTemplate>> SearchTemplatesAsync(
        string? searchTerm = null,
        int page = 1,
        int pageSize = 20)
    {
        // Using base Search method
        return await _provider.Search(new MessageTemplateSearchParameters
        {
            Title = searchTerm,
            Paging = new PagingParameters { Page = page, PageSize = pageSize }
        }).ToListAsync();
    }
}

Advanced Queries

public async Task<IEnumerable<MessageTemplate>> GetActiveTemplatesAsync()
{
    return await _provider.Search(new MessageTemplateSearchParameters
    {
        IsActive = true,
        Sorting = new SortingParameters
        {
            SortBy = "CreatedAt",
            SortDirection = SortDirection.Descending
        }
    }).ToListAsync();
}

📚 Modules

Exchange Module

Handles email templates, message tracking, and communication logs.

// Usage
public class EmailService
{
    private readonly EFMessageTemplateProvider _templateProvider;
    private readonly EFEMailTrackingProvider _trackingProvider;

    public async Task SendTemplatedEmailAsync(string templateTitle, string recipient)
    {
        var template = await _templateProvider.GetByTitleAsync(templateTitle);
        if (template == null) return;

        // Send email logic here
        await _trackingProvider.TrackEmailAsync(template.Id, recipient);
    }
}

Identity Module

Manages user authentication and authorization data.

// Register Identity providers
services.AddSufficitIdentityProviders();

// Usage
public class UserService
{
    private readonly EFIdentityProvider _identityProvider;

    public async Task<User?> AuthenticateAsync(string username, string password)
    {
        return await _identityProvider.AuthenticateAsync(username, password);
    }
}

Telephony Module

Handles call records, CDR data, and telephony operations.

// Register Telephony providers
services.AddSufficitTelephonyProviders();

// Usage
public class CallService
{
    private readonly EFCallRecordProvider _callProvider;

    public async Task<IEnumerable<CallRecord>> GetRecentCallsAsync(string extension)
    {
        return await _callProvider.Search(new CallRecordSearchParameters
        {
            Extension = extension,
            DateRange = new DateTimeRange
            {
                Start = DateTime.UtcNow.AddDays(-7),
                End = DateTime.UtcNow
            }
        }).ToListAsync();
    }
}

⚙️ Configuration

Connection Strings

{
  "ConnectionStrings": {
    "ExchangeDb": "Server=localhost;Database=exchange;User=user;Password=password;",
    "IdentityDb": "Server=localhost;Database=identity;User=user;Password=password;",
    "TelephonyDb": "Server=localhost;Database=telephony;User=user;Password=password;"
  }
}

Service Registration

public void ConfigureServices(IServiceCollection services)
{
    // Database contexts
    services.AddDbContext<ExchangeDbContext>(options =>
        options.UseMySql(Configuration.GetConnectionString("ExchangeDb"),
            new MySqlServerVersion(new Version(8, 0, 21))));

    services.AddDbContext<IdentityDbContext>(options =>
        options.UseSqlServer(Configuration.GetConnectionString("IdentityDb")));

    // Providers
    services.AddSufficitEFData();
}

🗄️ Database migrations

All database migrations are maintained in the dedicated migrations project. Runtime code under src/ contains contexts, mappings and providers; do not add versioned SQL scripts or generated migration classes there. An architectural unit test rejects migration artifacts placed anywhere outside the dedicated project.

• migrations/src/<Domain>/: Entity Framework factories, migration classes and model snapshots using Sufficit.EFData.<Domain>.Migrations.
• migrations/sql/<Domain>/: reviewed, versioned SQL migrations and data seeds, optionally grouped by subdomain.
• migrations/docs/<Domain>/: migration-specific decisions, preconditions and validation records.

Use a sortable yyyyMMddHHmm-description prefix for SQL and documentation artifacts. Prefer additive and idempotent scripts, state the target schema explicitly, validate with a transaction/rollback when possible, and never commit credentials. Schema changes must be applied deliberately through the migrations host or an explicitly reviewed SQL artifact—not automatically from application startup.

See migrations/README.md for the workflow and commands.

💻 Development

Project Structure

Sufficit.EFData/
├── src/
│   ├── EFProvider.cs              # Base provider class
│   ├── ScopedProvider.cs          # Scoped service management
│   ├── DEFAULT.cs                 # Constants and utilities
│   ├── Exchange/                  # Exchange domain providers
│   ├── Identity/                  # Identity domain providers
│   ├── Telephony/                 # Telephony domain providers
│   ├── Contacts/                  # Contacts domain providers
│   ├── Finance/                   # Finance domain providers
│   └── Extensions/                # Extension methods
├── tests/                         # Unit tests
├── docs/                          # Documentation
└── migrations/                    # Dedicated migration host and artifacts
    ├── Sufficit.EFData.Migrations.csproj
    ├── src/                       # EF migrations grouped by domain/namespace
    │   ├── Finance/
    │   ├── Telephony/
    │   └── Gateway/WhatsApp/
    ├── sql/                       # SQL grouped by domain and subdomain
    │   ├── Finance/
    │   ├── Sales/
    │   └── Telephony/
    └── docs/                      # Documentation grouped by domain

Building the Project

# Restore dependencies
dotnet restore

# Build for all target frameworks
dotnet build --configuration Release

# Run tests
dotnet test

# Create NuGet package
dotnet pack --configuration Release

Testing

// Example unit test
[Fact]
public async Task GetByTitleAsync_ReturnsCorrectTemplate()
{
    // Arrange
    var options = new DbContextOptionsBuilder<ExchangeDbContext>()
        .UseInMemoryDatabase(databaseName: "TestDb")
        .Options;

    using var context = new ExchangeDbContext(options);
    var provider = new EFMessageTemplateProvider(context);

    // Act
    var result = await provider.GetByTitleAsync("Welcome Email");

    // Assert
    Assert.NotNull(result);
    Assert.Equal("Welcome Email", result.Title);
}

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Development Setup

1. Fork the repository

2. Clone your fork

   git clone https://github.com/yourusername/sufficit-efdata.git
   cd sufficit-efdata
   

3. Create a feature branch

   git checkout -b feature/new-provider
   

4. Make your changes

5. Add tests for new functionality

6. Ensure all tests pass

   dotnet test
   

7. Submit a pull request

Code Standards

• Follow C# coding conventions
• Use meaningful variable and method names
• Add XML documentation comments
• Write unit tests for new features
• Ensure code coverage > 80%

Commit Messages

Use conventional commit format:

feat: add new email tracking provider
fix: resolve connection timeout issue
docs: update API documentation
test: add unit tests for message templates

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Developed by Sufficit Soluções em Tecnologia da Informação

For more information, visit our GitHub repository or contact development@sufficit.com.br.