RysePackage.Foundation.EntityFramework 1.1.1

MkG.Foundation

MkG.Foundation é o conjunto de pacotes base da plataforma MkG. Ele centraliza contratos, infraestrutura comum, persistência, observabilidade, resultados de aplicação e integração ASP.NET Core para que novos módulos sejam criados com uma estrutura consistente, testável e segura.

A Foundation não é um pacote de regras de negócio. Ela define padrões técnicos reutilizáveis para os projetos da plataforma.

Objetivos

• Padronizar a criação de novos módulos MkG.
• Reduzir duplicação de código estrutural.
• Garantir uma base consistente para multi-tenancy por OrganizationId.
• Padronizar auditoria, soft delete, physical delete explícito e concorrência.
• Padronizar retornos de aplicação com Result e Result<T>.
• Padronizar respostas HTTP, CorrelationId, envelopes e ProblemDetails.
• Garantir rastreabilidade com observabilidade estruturada.
• Separar claramente dados organizacionais, dados globais de referência e dados operacionais da plataforma.

Projetos

MkG.Foundation.Abstractions

Contratos fundamentais e desacoplados usados pelos demais pacotes.

Inclui:

• IExecutionContext
• IOrganizationScopedPoco
• IUnitScopedPoco
• IUnitOfWork

Este projeto não deve depender de ASP.NET Core, Entity Framework ou qualquer infraestrutura concreta.

MkG.Foundation.EntityFramework

Base comum para persistência com Entity Framework Core.

Inclui:

• BasePoco
• BasePocoConfiguration<TPoco>
• [PhysicalDelete]
• OrganizationDbContext<TContext>
• ReferenceDbContext<TContext>
• PlatformDbContext<TContext>
• extensions para consultas incluindo removidos
• UnitOfWork<TContext>

Tipos de DbContext

MkG.Foundation.Results

Modelo padronizado para retorno de operações da aplicação.

Inclui:

• Result
• Result<TValue>
• Error
• ErrorType
• ValidationError

Regras principais:

• Use Result para falhas tratáveis.
• Use Exception para falhas técnicas inesperadas.
• Quando uma Exception for associada a um Error, ela deve ser usada apenas internamente e nunca exposta em respostas HTTP.

MkG.Foundation.Observability

Base comum para eventos estruturados de observabilidade.

Inclui:

• IObservabilityRecorder
• eventos de processamento, jobs e controllers
• ICorrelationContext
• IErrorCodeTranslator
• política parametrizável de nível de log
• builders e extensions para reduzir verbosidade

Objetivo:

• Rastrear fluxos ponta a ponta por CorrelationId.
• Enriquecer eventos com OrganizationId, UserId, TraceId e SpanId.
• Padronizar error codes por enum.
• Evitar logs gigantes dentro dos services.

MkG.Foundation.AspNetCore

Integração da Foundation com APIs ASP.NET Core.

Inclui:

• HttpExecutionContext
• CorrelationIdMiddleware
• HttpCorrelationContext
• ApiResponse<T>
• AcceptedApiResponse
• MkGProblemDetails
• mapeamento de Result e Result<T> para IActionResult

Convenções principais de resposta HTTP:

Por decisão da plataforma, ausência de dado em uma consulta válida não é tratada como erro HTTP.

Getting Started

Requisitos

• .NET 10
• PostgreSQL para testes integrados de persistência
• Docker para execução de testes integrados com Testcontainers

Restaurar pacotes

dotnet restore

Build

dotnet build

Gerar pacotes NuGet

Os pacotes da Foundation seguem a família MkG.Foundation.* e usam os metadados comuns definidos em src/Foundation/Directory.Build.props.

dotnet pack ./src/Foundation/MkG.Foundation.Abstractions/MkG.Foundation.Abstractions.csproj --configuration Release --output ./artifacts/packages
dotnet pack ./src/Foundation/MkG.Foundation.Results/MkG.Foundation.Results.csproj --configuration Release --output ./artifacts/packages
dotnet pack ./src/Foundation/MkG.Foundation.Observability/MkG.Foundation.Observability.csproj --configuration Release --output ./artifacts/packages
dotnet pack ./src/Foundation/MkG.Foundation.EntityFramework/MkG.Foundation.EntityFramework.csproj --configuration Release --output ./artifacts/packages
dotnet pack ./src/Foundation/MkG.Foundation.AspNetCore/MkG.Foundation.AspNetCore.csproj --configuration Release --output ./artifacts/packages

Publicar pacotes NuGet

dotnet nuget push ./artifacts/packages/*.nupkg --api-key <NUGET_API_KEY> --source https://api.nuget.org/v3/index.json

As credenciais de publicação e do Elasticsearch devem ser fornecidas por fonte segura e nunca versionadas.

Observabilidade 1.1

O pacote RysePackage.Foundation.Observability pode enviar eventos diretamente ao Elasticsearch por uma fila limitada em memória. O envio é assíncrono, não grava arquivos e qualquer falha do destino é descartada sem interferir na aplicação.

APIs ASP.NET Core devem registrar os componentes e o pipeline nesta ordem:

builder.Services.AddMkGFoundationObservability(builder.Configuration);
builder.Services.AddMkGFoundationAspNetCore();

app.UseMkGCorrelationId();
app.UseMkGHttpObservability();

A configuração fica em MkG:Foundation:Observability. Senhas e API keys devem vir de variáveis de ambiente ou cofre de segredos.

Executar testes

dotnet test

Com cobertura:

dotnet test --collect:"XPlat Code Coverage"

Uso básico em uma API

Registrar Foundation ASP.NET Core e Observability

builder.Services.AddMkGFoundationAspNetCore();
builder.Services.AddMkGFoundationObservability(builder.Configuration);

Registrar middleware de correlação

var app = builder.Build();

app.UseMkGCorrelationId();

app.MapControllers();

app.Run();

Exemplo de controller usando Result mapping

[HttpGet("{id:guid}")]
public async Task<IActionResult> GetById(Guid id, CancellationToken cancellationToken)
{
    var result = await _productAppService.GetByIdAsync(id, cancellationToken);

    return result.ToQueryActionResult(_correlationContext);
}

[HttpPost]
public async Task<IActionResult> Create(ProductCreateRequestDto request, CancellationToken cancellationToken)
{
    var result = await _productAppService.CreateAsync(request, cancellationToken);

    return result.ToCreatedActionResult(
        _correlationContext,
        locationFactory: id => $"/api/v1/products/{id}",
        successMessage: "Produto criado com sucesso.");
}

[HttpPut("{id:guid}")]
public async Task<IActionResult> Update(Guid id, ProductUpdateRequestDto request, CancellationToken cancellationToken)
{
    var result = await _productAppService.UpdateAsync(id, request, cancellationToken);

    return result.ToCommandActionResult(
        _correlationContext,
        successMessage: "Atualização aceita com sucesso.");
}

Regras de implementação

• Services devem retornar Result ou Result<T>.
• Controllers devem usar os mappers padronizados do MkG.Foundation.AspNetCore.
• Entidades persistentes devem herdar de BasePoco.
• Entidades organizacionais devem implementar IOrganizationScopedPoco.
• Dados globais de referência devem usar ReferenceDbContext<TContext>.
• Dados de gestão da plataforma devem usar PlatformDbContext<TContext>.
• Dados operacionais da organização devem usar OrganizationDbContext<TContext>.
• Não usar DateTime.Now; usar TimeProvider.GetUtcNow().
• Não expor Exception, StackTrace, tokens, secrets ou payloads sensíveis em respostas HTTP.
• Não usar IgnoreQueryFilters() em dados organizacionais sem reaplicar OrganizationId.
• Não retornar POCOs persistentes diretamente em controllers; usar DTOs.

Documentação complementar

Documentações técnicas específicas foram geradas para:

• MkG.Foundation.Abstractions
• MkG.Foundation.EntityFramework
• MkG.Foundation.Results
• MkG.Foundation.Observability
• MkG.Foundation.AspNetCore
• Manual de implementação dos três modelos de DbContext
• Contexto roteável do projeto
• Grafo de dependências
• Configuração de observabilidade
• Changelog

Build and Test

O projeto possui testes unitários e integrados cobrindo:

• contratos base
• auditoria e filtros globais dos DbContexts
• soft delete e physical delete
• transações e rollback
• observabilidade e política de logs
• tradução de error codes
• Result, Error e ValidationError
• CorrelationId
• envelopes HTTP
• ProblemDetails
• mapeamento de Result para IActionResult

Executar todos os testes:

dotnet test

Contribuição

Ao contribuir com a Foundation:

1. Preserve a separação de responsabilidades entre os pacotes.
2. Não adicione dependências de infraestrutura em Abstractions.
3. Não coloque regras de negócio específicas na Foundation.
4. Inclua testes unitários para qualquer novo contrato ou comportamento.
5. Inclua testes integrados quando houver comportamento real de infraestrutura.
6. Atualize a documentação correspondente.
7. Mantenha compatibilidade com as convenções de Result, observabilidade e respostas HTTP.

Decisão arquitetural

A MkG.Foundation é a base para novos projetos da plataforma MkG.

Ela estabelece padrões para:

persistência
auditoria
multi-tenancy
observabilidade
resultados de aplicação
respostas HTTP
correlação
tratamento de erros

Com isso, novos módulos podem ser implementados com uma estrutura previsível, segura e alinhada às decisões arquiteturais da plataforma.