AuditLog.Abstractions 0.5.0

AuditLog

Biblioteca de auditoria automática para EF Core com Source Generators Roslyn.

Pacotes

AuditLog — Auditoria de Entidades

1. Defina um configurador

[GenerateAuditLog]
public sealed class PacienteAuditConfigurator : AuditConfigurator<Paciente>
{
    public PacienteAuditConfigurator()
    {
        For(x => x.Id).Key();
        For(x => x.Nome).HasMaxLength(200).IsRequired();
        For(x => x.Cpf).Sensitive().HasMaxLength(11);
        For(x => x.DataAtualizacao).Ignore();
    }
}

2. Adicione o interceptor no DbContext

public class AppDbContext : DbContext
{
    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.AddInterceptors(new AuditSaveInterceptor());
    }
}

3. O generator produz automaticamente

• PacienteAuditLog — tabela de auditoria com snapshot dos dados
• PacienteAuditLogDescriptor — mapeia Paciente → PacienteAuditLog
• PacienteAuditLogEntityMap — EF Core configuration (column types, max length)
• ServiceCollectionExtensions.AddGeneratedAuditLogs() — DI registration

AuditLog.Historico — Histórico Legível

A tabela *AuditLog gerada por [GenerateAuditLog] guarda um snapshot textual cru de cada revisão (CamposAlteradosJson + colunas) — ótimo pra auditoria/consulta técnica, mas não pra mostrar direto ao usuário final: FK aparece como Id, enum como Enum.ToString(), data sem formatação fixa, booleano como "True"/"False". O AuditLog.Historico lê esse snapshot e resolve os campos alterados pra texto legível — o material pronto pra uma tela de "ver histórico" de um registro.

Instalação

<ItemGroup>
  <PackageReference Include="AuditLog.Historico" Version="1.0.0" />
</ItemGroup>

1. Configure os campos com AuditHistoricoConfigurator

var mapper = new AuditHistoricoMapper<ProdutoAuditLog>(cfg =>
{
    cfg.For(x => x.Nome).HasLabel("Nome");
    cfg.For(x => x.CategoriaId).HasLabel("Categoria").ResolveGuidLookup(categoriaPorId);
    cfg.For(x => x.Status).HasLabel("Status").ResolveEnum<StatusProduto>();
    cfg.For(x => x.Ativo).HasLabel("Ativo").ResolveBool();
    cfg.For(x => x.AtualizadoEm).HasLabel("Atualizado em").ResolveData();
    cfg.For(x => x.FotoId).HasLabel("Foto").IsArquivo();
});

For(x => x.Campo) é o ponto de entrada — mesma pegada do AuditConfigurator<T>.For do AuditLog.Abstractions, de propósito, pra ficar familiar pra quem já configura auditoria com esse pacote. Campo nunca configurado aqui ainda aparece no histórico, só que com o nome cru da propriedade como rótulo e sem nenhuma resolução no valor.

Métodos do AuditCampoBuilder<TLog> retornado por For:

2. Resolvers prontos

• ResolveData() (usa DateResolver.ToDisplayDate internamente) — pra campos de data/hora gravados sem cultura/formato explícito pelo AuditLog.Generator. O parse roda sob a mesma CultureInfo.CurrentCulture do processo vigente na leitura; como nem a gravação (AuditSaveInterceptor) nem este resolver fixam cultura explícita, as duas rodam sob a mesma cultura do processo, o que torna o round-trip seguro independente de qual cultura seja essa.
• ResolveEnum<TEnum>() (usa EnumDisplayResolver.ToDisplayName internamente) — resolve o nome do membro (Enum.ToString()) pro [Display(Name=...)]; sem esse atributo, tenta [Description]; sem nenhum dos dois, mantém o valor cru.

Campo sem nenhum resolver configurado aparece no histórico com o valor exatamente como foi persistido na tabela *AuditLog, sem nenhuma transformação — retornar o próprio valor de entrada é o fallback seguro nesse caso.

3. Monte o histórico com AuditHistoricoMapper<TLog>

IReadOnlyList<AuditHistoricoEntrada<ProdutoAuditLog>> entradas = mapper.Mapear(logs);

TLog precisa seguir a convenção fixa que o AuditLog.Generator sempre produz nos tipos *AuditLog: propriedades Id (long), Operacao (AuditOperation), OcorridoEm (DateTimeOffset), UsuarioId/CorrelationId/CamposAlteradosJson (string?) e AuditLogAnteriorId (long?). Se TLog não seguir essa convenção, o construtor do mapper falha cedo com uma mensagem indicando qual propriedade está faltando, em vez de deixar o mapeamento silenciosamente incompleto.

Mapear espera o lote completo de revisões relevantes: a revisão "anterior" de cada log é resolvida via AuditLogAnteriorId dentro do próprio lote passado, sem nenhuma consulta adicional. Só entradas com Operacao == AuditOperation.Modified têm CamposAlterados preenchido — Added/Deleted retornam lista vazia.

Resultado, um AuditHistoricoEntrada<TLog> por log:

E cada AuditHistoricoCampo:

Exemplo completo

// ProdutoAuditLog é gerado por [GenerateAuditLog] a partir de um AuditConfigurator<Produto>.
var logs = await db.Set<ProdutoAuditLog>()
    .AsNoTracking()
    .Where(log => log.ProdutoId == produtoId)
    .ToListAsync(ct);

// Lookup construído só com os IDs de categoria que aparecem no lote — nunca a tabela inteira.
var categoriaIds = logs
    .SelectMany(l => new[] { l.CategoriaId })
    .Where(v => Guid.TryParse(v, out _))
    .Select(v => Guid.Parse(v!))
    .Distinct()
    .ToList();

var categoriaPorId = await db.Categorias
    .AsNoTracking()
    .Where(c => categoriaIds.Contains(c.Id))
    .ToDictionaryAsync(c => c.Id, c => c.Nome, ct);

var mapper = new AuditHistoricoMapper<ProdutoAuditLog>(cfg =>
{
    cfg.For(x => x.Nome).HasLabel("Nome");
    cfg.For(x => x.CategoriaId).HasLabel("Categoria").ResolveGuidLookup(categoriaPorId);
    cfg.For(x => x.Status).HasLabel("Status").ResolveEnum<StatusProduto>();
    cfg.For(x => x.Ativo).HasLabel("Ativo").ResolveBool();
    cfg.For(x => x.AtualizadoEm).HasLabel("Atualizado em").ResolveData();
});

var entradas = mapper.Mapear(logs);

Uma entrada resultante (simplificada):

new AuditHistoricoEntrada<ProdutoAuditLog>(
    Id: 42,
    Operacao: AuditOperation.Modified,
    OcorridoEm: DateTimeOffset.Parse("2026-08-10T14:32:00-03:00"),
    UsuarioId: "3f2a1c4e-7b21-4e9a-9c31-2a8f0b1d5e6a",
    CorrelationId: "9b7e2f31-...",
    CamposAlterados:
    [
        new AuditHistoricoCampo("Categoria", ValorAnterior: "Descartáveis", ValorNovo: "Insumos", EhArquivo: false),
        new AuditHistoricoCampo("Ativo", ValorAnterior: "Sim", ValorNovo: "Não", EhArquivo: false),
        new AuditHistoricoCampo("Atualizado em", ValorAnterior: "10/08/2026 11:00:00", ValorNovo: "10/08/2026 14:32:00", EhArquivo: false)
    ],
    Log: /* a linha ProdutoAuditLog original */);

Cabe ao consumidor (controller, DTO de aplicação) projetar AuditHistoricoEntrada<TLog> pro formato exposto na API — o pacote não define esse contrato de saída de propósito, porque cada aplicação tem seus próprios campos de exibição (ex: nome do usuário resolvido a partir de UsuarioId, descrição textual da operação).

Relação com o resto da suíte

• Depende só de AuditLog.Abstractions (usa AuditOperation) — sem dependência de EF Core nem de nenhum framework web.
• Consome as tabelas *AuditLog produzidas por [GenerateAuditLog] (AuditLog.Generator) — não gera nem grava nada, só lê e resolve o que já foi persistido.
• Mapear recebe qualquer IEnumerable<TLog> já carregado — a origem das linhas (EF Core, outra fonte) é responsabilidade do chamador.

SoftDelete — Exclusão Lógica

Dois pacotes complementares:

Instalação

<ItemGroup>
  <PackageReference Include="AuditLog.EntityFrameworkCore.SoftDelete" Version="1.0.0" />
  <PackageReference Include="AuditLog.Generator.SoftDelete" Version="1.0.0" />
</ItemGroup>

1. Implemente ISoftDeleteEntity nas entidades

public class Paciente : ISoftDeleteEntity
{
    public Guid Id { get; set; }
    public string Nome { get; set; }

    // Obrigatório para soft delete
    public bool IsDeleted { get; set; }
    public DateTime? DeletedAt { get; set; }

    // Relacionamentos (Fluent API configurada no DbContext)
    public List<Notificacao> Notificacoes { get; set; } = [];
}

2. Marque o DbContext com [GenerateSoftDelete]

using AuditLog.EntityFrameworkCore.SoftDelete;

[GenerateSoftDelete]
public class AppDbContext : DbContext
{
    public DbSet<Paciente> Pacientes { get; set; }
    public DbSet<Notificacao> Notificacoes { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Paciente>(e =>
        {
            e.HasMany(x => x.Notificacoes)
                .WithOne(x => x.Paciente)
                .HasForeignKey(x => x.PacienteId)
                .OnDelete(DeleteBehavior.Cascade);
        });

        modelBuilder.ApplySoftDeleteQueryFilter();
    }
}

3. Registre na DI

// Com o source generator (handlers tipados)
var registry = new SoftDeleteHandlerRegistry();
registry.AddGeneratedSoftDeleteHandlers();
services.AddSoftDelete(registry);

// Ou sem o generator (fallback via reflection)
services.AddSoftDelete();

4. Use normalmente

db.Pacientes.Remove(paciente);
await db.SaveChangesAsync();
// → IsDeleted = true, DeletedAt = now
// → Cascade: Notificacoes também são marcadas como deletadas
// → Query filter global: db.Pacientes retorna apenas não-deletados

Comportamentos por FK

Convenções (quando OnDelete não é especificado)

Consultas

// Query filter automático — só não-deletados
db.Pacientes.ToList();

// Incluir deletados
db.Pacientes.IgnoreQueryFilters().ToList();

Suporte a herança indireta de IEntityTypeConfiguration<T>

O gerador detecta entity maps que implementam IEntityTypeConfiguration<T> através de toda a cadeia de herança, incluindo casos como AuditEntityMap<T> → IContextEntityMap<T> → IEntityTypeConfiguration<T>. Isso funciona tanto com ApplyConfiguration(new ConcreteEntityMap()) quanto com ApplyConfigurationsFromAssembly().

Descoberta de entidades sem DbSet<T>

O gerador descobre entidades mesmo quando o DbContext não possui propriedades DbSet<T>, desde que as entidades sejam registradas via modelBuilder.Entity<T>() no OnModelCreating ou via ApplyConfiguration/ApplyConfigurationsFromAssembly com entity maps que implementam IEntityTypeConfiguration<T>.