Tooark.Entities 4.0.1

Tooark.Entities

Biblioteca com entidades base para aplicações .NET, incluindo suporte a identificadores únicos, auditoria, controle de versão e exclusão lógica.

📦 Conteúdo do Pacote

Entidades

Value Objects usados nas entidades

As entidades recebem Value Objects do pacote Tooark.ValueObjects — CreatedBy, UpdatedBy, DeletedBy, RestoredBy, FileStorage e Title — e guardam o valor já convertido. O que entra é o objeto de valor (CreatedBy); o que a entidade expõe é o Guid (CreatedById).

🔧 Instalação

dotnet add package Tooark.Entities

⚙️ Configuração

Não há configuração adicional.

Como as operações de escrita reagem a valor inválido

Os métodos Set* lançam BadRequestException e não deixam notificação na entidade. Uma chamada recusada não altera nada: a entidade segue íntegra e a chamada seguinte, se correta, é aceita normalmente.

using Tooark.Entities;
using Tooark.Exceptions;

public static class Exemplo
{
  public static void Excluir(AuditableEntity entidade, Guid usuario)
  {
    try
    {
      // Recusada: o identificador é vazio
      entidade.SetDeleted(Guid.Empty);
    }
    catch (BadRequestException)
    {
      // A entidade não guardou nada da chamada recusada e segue íntegra
    }

    // Aceita normalmente
    entidade.SetDeleted(usuario);
  }
}

A exceção do valor ausente é diferente da do valor inválido: null produz Field.Required;<campo>, e valor presente mas reprovado produz Field.Invalid;<campo>.

O SetId do BaseEntity é a única exceção: ele acumula notificação em vez de lançar, porque roda no construtor. Verifique IsValid depois de construir uma entidade com identificador informado.

Já ValidateNotDeleted() acumula notificação de propósito — é o método para checar sem interromper o fluxo. Quem quer interromper usa EnsureNotDeleted(), que lança.

🧩 Entidades (Detalhes)

BaseEntity

• Propriedades
  • Id (Guid) — coluna id (uuid)
• Construtores (para classes derivadas)
  • BaseEntity() — gera Id automaticamente
  • BaseEntity(Guid id) — define Id determinístico (seed/testes/factories)
• Observações
  • O Id tem setter privado. Classes derivadas definem o identificador pelo SetId protegido, que recusa Guid.Empty e recusa trocar a identidade de uma entidade já criada — nos dois casos por notificação, sem lançar.
  • A igualdade compara tipo e identificador: entidades de tipos diferentes com o mesmo Id não são iguais. A comparação aceita herança nos dois sentidos, para não quebrar com os proxies de carregamento tardio do Entity Framework.
  • Exemplos de Uso.

InitialEntity

• Propriedades
  • CreatedById (Guid) — coluna created_by (uuid)
  • CreatedAt (DateTime/UTC) — coluna created_at (timestamp with time zone)
• Métodos
  • SetCreatedBy(CreatedBy createdById)
• Observações
  • Herda de BaseEntity.
  • SetCreatedBy recebe o Value Object CreatedBy, que aceita conversão implícita a partir de Guid.
  • Em caso de dados inválidos, lança BadRequestException.
  • Exemplos de Uso.

DetailedEntity

• Propriedades
  • UpdatedById (Guid) — coluna updated_by (uuid)
  • UpdatedAt (DateTime/UTC) — coluna updated_at (timestamp with time zone)
• Métodos
  • SetCreatedBy(CreatedBy createdById) — define também UpdatedById e UpdatedAt, iguais aos da criação
  • SetUpdatedBy(UpdatedBy updatedById)
• Observações
  • Herda de InitialEntity.
  • SetUpdatedBy recebe o Value Object UpdatedBy, que aceita conversão implícita a partir de Guid.
  • Em caso de dados inválidos, lança BadRequestException.
  • Exemplos de Uso.

VersionedEntity

• Propriedades
  • Version (long) — coluna version (bigint), valor padrão 1
• Métodos
  • SetUpdatedBy(UpdatedBy updatedById) — atualiza e incrementa a versão
• Observações
  • Herda de DetailedEntity.
  • Em caso de dados inválidos, lança BadRequestException.
  • Exemplos de Uso.

SoftDeletableEntity

• Propriedades
  • Deleted (bool) — coluna deleted (bool), valor padrão false
• Métodos
  • ValidateNotDeleted() — valida se não está deletada e adiciona notificação
  • EnsureNotDeleted() — lança exception se estiver deletada
  • SetDeleted(UpdatedBy changedById) — marca como deletada e atualiza; ignorada se já estiver deletada
  • SetRestored(UpdatedBy changedById) — restaura e atualiza; ignorada se não estiver deletada
• Observações
  • Herda de DetailedEntity.
  • Em caso de dados inválidos, lança BadRequestException.
  • Exemplos de Uso.

AuditableEntity

• Propriedades
  • Version (long)
  • Deleted (bool)
  • DeletedById (Guid?) — coluna deleted_by (uuid)
  • DeletedAt (DateTime?) — coluna deleted_at (timestamp with time zone)
  • RestoredById (Guid?) — coluna restored_by (uuid)
  • RestoredAt (DateTime?) — coluna restored_at (timestamp with time zone)
• Métodos
  • ValidateNotDeleted() — valida se não está deletada e adiciona notificação
  • EnsureNotDeleted() — lança exception se estiver deletada
  • SetUpdatedBy(UpdatedBy updatedById) — atualiza e incrementa a versão
  • SetDeleted(DeletedBy deletedById) — marca como deletada, registra o usuário e a data da exclusão, atualiza UpdatedById/UpdatedAt e incrementa a versão
  • SetRestored(RestoredBy restoredById) — restaura, registra o usuário e a data da restauração, atualiza UpdatedById/UpdatedAt e incrementa a versão
• Observações
  • Herda de DetailedEntity.
  • Em caso de dados inválidos, lança BadRequestException.
  • Exemplos de Uso.

FileEntity

• Propriedades
  • FileName (string) — coluna file_name (text)
  • Title (string) — coluna title (varchar(255))
  • Link (string) — coluna link (text)
  • FileFormat (string?) — coluna file_format (varchar(10))
  • Type (EFileType) — coluna type (int)
  • Size (long) — coluna size (bigint)
• Construtores (para classes derivadas)
  • FileEntity(FileStorage file, Title title, CreatedBy createdById)
  • FileEntity(FileStorage file, Title title, string fileFormat, EFileType type, long size, CreatedBy createdById)
• Observações
  • Herda de InitialEntity.
  • FileStorage e Title são Value Objects. Em caso de dados inválidos, lança BadRequestException.
  • Exemplos de Uso.

📝 Exemplos de Uso

Entidade Base

using Tooark.Entities;

public class Produto : BaseEntity
{
  public Produto() { }
  public Produto(Guid id) : base(id) { }

  public string Nome { get; set; } = string.Empty;
  public decimal Valor { get; set; }
}

public class Program
{
  public static void Main()
  {
    var produto = new Produto
    {
      Nome = "Produto A",
      Valor = 100.0m
    };

    var idGerado = produto.Id;
    var produtoDeterministico = new Produto(Guid.Parse("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"));
  }
}

Entidade Inicial

using Tooark.Entities;

public class Produto : InitialEntity
{
  public string Nome { get; set; } = string.Empty;
  public decimal Valor { get; set; }
}

public class Program
{
  public static void Main()
  {
    var produto = new Produto
    {
      Nome = "Produto A",
      Valor = 100.0m
    };

    // SetCreatedBy recebe CreatedBy (Value Object), mas Guid converte implicitamente.
    produto.SetCreatedBy(Guid.NewGuid());
  }
}

Entidade Detalhada

using Tooark.Entities;

public class Produto : DetailedEntity
{
  public string Nome { get; set; } = string.Empty;
  public decimal Valor { get; set; }
}

public class Program
{
  public static void Main()
  {
    var produto = new Produto
    {
      Nome = "Produto A",
      Valor = 100.0m
    };

    produto.SetCreatedBy(Guid.NewGuid());
    produto.SetUpdatedBy(Guid.NewGuid());
  }
}

Entidade Versionada

using Tooark.Entities;

public class Produto : VersionedEntity
{
  public string Nome { get; set; } = string.Empty;
  public decimal Valor { get; set; }
}

public class Program
{
  public static void Main()
  {
    var produto = new Produto
    {
      Nome = "Produto A",
      Valor = 100.0m
    };

    produto.SetCreatedBy(Guid.NewGuid());
    produto.SetUpdatedBy(Guid.NewGuid());

    var version = produto.Version;
  }
}

Entidade Deletável

using Tooark.Entities;

public class Produto : SoftDeletableEntity
{
  public string Nome { get; set; } = string.Empty;
  public decimal Valor { get; set; }
}

public class Program
{
  public static void Main()
  {
    var produto = new Produto
    {
      Nome = "Produto A",
      Valor = 100.0m
    };

    produto.SetCreatedBy(Guid.NewGuid());
    produto.SetDeleted(Guid.NewGuid());
    produto.SetRestored(Guid.NewGuid());
  }
}

Entidade Auditável

using Tooark.Entities;

public class Produto : AuditableEntity
{
  public string Nome { get; set; } = string.Empty;
  public decimal Valor { get; set; }
}

public class Program
{
  public static void Main()
  {
    var produto = new Produto
    {
      Nome = "Produto A",
      Valor = 100.0m
    };

    produto.SetCreatedBy(Guid.NewGuid());
    produto.SetUpdatedBy(Guid.NewGuid());
    produto.SetDeleted(Guid.NewGuid());
    produto.SetRestored(Guid.NewGuid());
  }
}

Entidade de Arquivo

using Tooark.Entities;
using Tooark.Enums;
using Tooark.ValueObjects;

public class Arquivo : FileEntity
{
  public Arquivo(string link, string name, string title, Guid createdById)
    : base(new FileStorage(link, name), new Title(title), new CreatedBy(createdById))
  { }

  public Arquivo(string link, string name, string title, string fileFormat, EFileType type, long size, Guid createdById)
    : base(new FileStorage(link, name), new Title(title), fileFormat, type, size, createdById)
  { }
}

public class Program
{
  public static void Main()
  {
    var arquivo = new Arquivo(
      link: "https://bucket.com/arquivo.pdf",
      name: "Arquivo.pdf",
      title: "Arquivo de teste",
      createdById: Guid.NewGuid()
    );

    var arquivoDetalhado = new Arquivo(
      link: "https://bucket.com/arquivo.pdf",
      name: "Arquivo.pdf",
      title: "Arquivo de teste",
      fileFormat: "pdf",
      type: EFileType.Document,
      size: 1024,
      createdById: Guid.NewGuid()
    );
  }
}

📋 Dependências

⚠️ Códigos de Erro, Notificações e Soluções

Os códigos de erro para notificações seguem o padrão T.ENT.<SIGLA><N> (ex.: T.ENT.BAS1).

Códigos emitidos pelas entidades:

O código acompanha a notificação, esteja ela registrada na entidade ou transportada pela exceção. As mensagens que vêm dos objetos de valor — Field.Invalid;CreatedBy e as demais — são emitidas pelo Tooark.ValueObjects e carregam o código dele, não um T.ENT.*. Repare que o link reprovado do FileEntity reporta ProtocolHttp, que é o objeto de valor interno do FileStorage, e não FileStorage.

Tabela de erros/notificações:

Vale para todas as entidades: argumento nulo produz Field.Required;<campo> — CreatedBy, UpdatedBy, DeletedBy ou RestoredBy, conforme a operação — como Exception.

🪪 Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues e pull requests no repositório Tooark.Entities.

📄 Licença

Este projeto está licenciado sob a licença BSD 3-Clause. Veja o arquivo LICENSE para mais detalhes.