实体基类

命名空间：ZhonTai.Admin.Core.Entities

中台 Admin 提供了一套完整的实体基类体系，通过接口组合和继承链实现主键、审计、软删除、多租户、数据权限、乐观锁等通用功能。

应用场景

新建数据库表对应的实体类时，选择合适的基类继承
避免在每个实体中重复定义公共字段
自动享受全局过滤器（软删除、租户隔离、数据权限）

实体继承关系

主键实体链（含审计+软删除）

Entity<TKey>                        主键 Id（雪花Id）
  └── EntityAdd<TKey>               + 创建审计字段
        └── EntityUpdate<TKey>      + 修改审计字段
              └── EntityDelete<TKey> + 软删除字段
                    └── EntityBase    完整基类（推荐）

无主键实体链（仅审计）

IEntityAdd                          创建审计接口
  └── EntityAddNoId                 + 创建审计字段
        └── EntityUpdateNoId        + 修改审计字段

EntityBase<TKey> 派生类

EntityBase<TKey>
  ├── EntityTenant<TKey>            + 租户隔离
  │     └── EntityTenantWithData<TKey> + 数据权限
  ├── EntityData<TKey>              + 数据权限（无租户）
  ├── EntityVersion<TKey>           + 乐观锁
  └── EntityMember<TKey>            + 会员（含软删除+时间审计）
        └── EntityMemberWithTenant<TKey> + 租户隔离

可组合接口

接口	字段	说明
`IEntity<TKey>`	`Id`	主键接口
`IEntityAdd`	`CreatedUserId/Name/RealName/Time`	创建审计
`IEntityUpdate`	`ModifiedUserId/Name/RealName/Time`	修改审计
`IDelete`	`IsDeleted`	软删除
`ITenant`	`TenantId`	多租户
`IMember`	`MemberId`	会员
`IData`	`OwnerId/OwnerOrgId/OwnerOrgName`	数据权限
`IVersion`	`Version`	乐观锁
`IChilds<T>`	`List<T> Childs`	树形子级

各基类详细字段

Entity<TKey>

基础实体，提供雪花Id主键。

csharp

public class Entity<TKey> : IEntity<TKey>
{
    [Snowflake] // 雪花Id自动生成
    public virtual TKey Id { get; set; }
}

非泛型快捷类：Entity（即 Entity<long>）

TIP

通常使用非泛型快捷类 Entity（即 Entity<long>，主键为 long 类型），无需指定泛型参数。

EntityAdd<TKey>

在 Entity 基础上增加创建审计字段：

字段	类型	说明
`CreatedUserId`	`long?`	创建者用户Id
`CreatedUserName`	`string`	创建者用户名
`CreatedUserRealName`	`string`	创建者姓名
`CreatedTime`	`DateTime?`	创建时间（`[ServerTime]` 自动赋值）

非泛型快捷类：EntityAdd（即 EntityAdd<long>）

EntityUpdate<TKey>

在 EntityAdd 基础上增加修改审计字段：

字段	类型	说明
`ModifiedUserId`	`long?`	修改者用户Id
`ModifiedUserName`	`string`	修改者用户名
`ModifiedUserRealName`	`string`	修改者姓名
`ModifiedTime`	`DateTime?`	修改时间（`CanInsert=false, CanUpdate=true`）

非泛型快捷类：EntityUpdate（即 EntityUpdate<long>）

EntityDelete<TKey>

在 EntityUpdate 基础上增加软删除字段：

字段	类型	默认值	说明
`IsDeleted`	`bool`	`false`	软删除标记

非泛型快捷类：EntityDelete（即 EntityDelete<long>）

TIP

继承了 IDelete 的实体，删除操作会自动转为更新 IsDeleted=true，配合 FreeSql 全局过滤器自动过滤已删除数据。

EntityBase<TKey>

完整基类，继承 EntityDelete（即包含主键+审计+软删除全部字段），最常用的基类。

非泛型快捷类：EntityBase（即 EntityBase<long>）

EntityAddNoId

无主键的创建审计实体，实现 IEntityAdd，适用于不需要独立主键的场景（如关联表、日志表）。

字段	类型	说明
`CreatedUserId`	`long?`	创建者用户Id
`CreatedUserName`	`string`	创建者用户名
`CreatedUserRealName`	`string`	创建者姓名
`CreatedTime`	`DateTime?`	创建时间（`[ServerTime]` 自动赋值）

EntityUpdateNoId

无主键的修改审计实体，继承 EntityAddNoId，实现 IEntityUpdate。

字段	类型	说明
`ModifiedUserId`	`long?`	修改者用户Id
`ModifiedUserName`	`string`	修改者用户名
`ModifiedUserRealName`	`string`	修改者姓名
`ModifiedTime`	`DateTime?`	修改时间（`CanInsert=false, CanUpdate=true`）

EntityTenant<TKey>

多租户实体，继承 EntityBase，实现 ITenant。启用多租户后，查询自动按租户隔离数据，每个租户只能访问自己的数据。

字段	类型	说明
`TenantId`	`long?`	租户Id（创建后不可修改）

非泛型快捷类：EntityTenant（即 EntityTenant<long>）

EntityTenantWithData<TKey>

多租户+数据权限实体，继承 EntityTenant，实现 IData。支持租户隔离+数据权限双重过滤。

字段	类型	说明
`TenantId`	`long?`	租户Id（继承自 EntityTenant）
`OwnerId`	`long?`	拥有者Id
`OwnerOrgId`	`long?`	拥有者部门Id
`OwnerOrgName`	`string`	拥有者部门名称

非泛型快捷类：EntityTenantWithData（即 EntityTenantWithData<long>）

EntityData<TKey>

数据权限实体，继承 EntityBase，实现 IData，支持数据权限过滤（无租户隔离）。适用于不需要多租户但需要数据权限的场景。

字段	类型	说明
`OwnerId`	`long?`	拥有者Id
`OwnerOrgId`	`long?`	拥有者部门Id
`OwnerOrgName`	`string`	拥有者部门名称

非泛型快捷类：EntityData（即 EntityData<long>）

EntityVersion<TKey>

乐观锁实体，继承 EntityBase，实现 IVersion。更新时自动检查版本号，版本不匹配则抛出并发异常，适用于高并发更新场景。

字段	类型	说明
`Version`	`long`	数据版本（`[Column(IsVersion = true)]`）

非泛型快捷类：EntityVersion（即 EntityVersion<long>）

EntityMember<TKey>

会员实体，继承 Entity，实现 IMember 和 IDelete。与 EntityBase 的区别：不继承完整的审计字段，仅包含 MemberId、时间审计和软删除。

字段	类型	说明
`Id`	`TKey`	主键（雪花Id）
`MemberId`	`long?`	会员Id
`CreatedTime`	`DateTime?`	创建时间（`[ServerTime]`）
`ModifiedTime`	`DateTime?`	修改时间（`CanInsert=false, CanUpdate=true`）
`IsDeleted`	`bool`	软删除标记（默认 `false`）

非泛型快捷类：EntityMember（即 EntityMember<long>）

EntityMemberWithTenant<TKey>

会员+租户实体，继承 EntityMember，实现 ITenant。

字段	类型	说明
`MemberId`	`long?`	会员Id（继承自 EntityMember）
`TenantId`	`long?`	租户Id（创建后不可修改）

非泛型快捷类：EntityMemberWithTenant（即 EntityMemberWithTenant<long>）

使用示例

基础实体（含审计+软删除）

最常用的实体，继承 EntityBase，包含主键、创建/修改审计和软删除。

csharp

using FreeSql.DataAnnotations;
using ZhonTai.Admin.Core.Entities;

public class ArticleEntity : EntityBase
{
    [Description("标题")]
    [MaxLength(200)]
    public string Title { get; set; }

    [Description("内容")]
    [Column(StringLength = -1)]
    public string Content { get; set; }

    public bool Enabled { get; set; }
}

多租户实体

需要租户数据隔离时使用，继承 EntityTenant。

csharp

public class ConfigEntity : EntityTenant
{
    [Description("配置键")]
    [MaxLength(100)]
    public string Key { get; set; }

    [Description("配置值")]
    [Column(StringLength = -1)]
    public string Value { get; set; }
}

多租户+数据权限实体

需要租户隔离+数据权限过滤时使用，继承 EntityTenantWithData。

csharp

public class OrderEntity : EntityTenantWithData
{
    public string OrderNo { get; set; }
    public decimal Amount { get; set; }
}

等价于：

csharp

public class OrderEntity : Entity
{
    public long Id { get; set; }                    // 雪花Id
    public long? CreatedUserId { get; set; }
    public string CreatedUserName { get; set; }
    public string CreatedUserRealName { get; set; }
    public DateTime? CreatedTime { get; set; }
    public long? ModifiedUserId { get; set; }
    public string ModifiedUserName { get; set; }
    public string ModifiedUserRealName { get; set; }
    public DateTime? ModifiedTime { get; set; }
    public bool IsDeleted { get; set; }
    public long? TenantId { get; set; }              // 租户隔离
    public long? OwnerId { get; set; }               // 数据权限
    public long? OwnerOrgId { get; set; }
    public string OwnerOrgName { get; set; }
}

数据权限实体（无租户）

不需要多租户但需要数据权限过滤时使用，继承 EntityData。

csharp

public class ProjectEntity : EntityData
{
    public string Name { get; set; }
    public long? OwnerId { get; set; }               // 负责人
    public long? OwnerOrgId { get; set; }            // 所属部门
}

乐观锁实体

高并发更新场景下防止并发冲突，继承 EntityVersion。

csharp

public class SettingEntity : EntityVersion
{
    [Description("配置键")]
    [MaxLength(100)]
    public string Key { get; set; }

    [Description("配置值")]
    [Column(StringLength = -1)]
    public string Value { get; set; }
}

会员实体

前台会员数据使用，继承 EntityMember，包含 MemberId、时间审计和软删除。

csharp

public class AddressEntity : EntityMember
{
    [Description("收货人")]
    [MaxLength(50)]
    public string Receiver { get; set; }

    [Description("手机号")]
    [MaxLength(20)]
    public string Phone { get; set; }

    [Description("详细地址")]
    [MaxLength(200)]
    public string Address { get; set; }
}

会员+租户实体

需要按租户隔离会员数据时使用，继承 EntityMemberWithTenant。

csharp

public class CartEntity : EntityMemberWithTenant
{
    public long ProductId { get; set; }
    public int Quantity { get; set; }
}

无主键实体（关联表）

不需要独立主键的关联表或日志表，继承 EntityUpdateNoId。

csharp

public class ArticleTagEntity : EntityUpdateNoId
{
    public long ArticleId { get; set; }
    public long TagId { get; set; }
}

树形实体

需要树形结构时，继承 EntityBase 并实现 IChilds<T>。

csharp

public class CategoryEntity : EntityBase, IChilds<CategoryEntity>
{
    [Description("父级Id")]
    public long ParentId { get; set; }

    [Description("分类名称")]
    [MaxLength(50)]
    public string Name { get; set; }

    public List<CategoryEntity> Childs { get; set; }
}

树形+多租户实体

csharp

public class CategoryEntity : EntityTenant, IChilds<CategoryEntity>
{
    public long ParentId { get; set; }
    public string Name { get; set; }
    public List<CategoryEntity> Childs { get; set; }
}

仅主键实体

只需要雪花Id主键，不需要审计和软删除时使用，继承 Entity。

csharp

public class DictEntity : Entity
{
    public string Name { get; set; }
    public string Value { get; set; }
}

自动赋值特性

特性	说明
`[Snowflake]`	主键自动生成雪花Id
`[ServerTime]`	插入时自动赋值服务器时间
`[ServerTime(CanInsert=false, CanUpdate=true)]`	仅更新时赋值服务器时间
`[Column(IsVersion = true)]`	乐观锁版本字段

实体基类 ​

应用场景 ​

实体继承关系 ​

主键实体链（含审计+软删除） ​

无主键实体链（仅审计） ​

EntityBase<TKey> 派生类 ​

可组合接口 ​

各基类详细字段 ​

Entity<TKey> ​

EntityAdd<TKey> ​

EntityUpdate<TKey> ​

EntityDelete<TKey> ​

EntityBase<TKey> ​

EntityAddNoId ​

EntityUpdateNoId ​

EntityTenant<TKey> ​

EntityTenantWithData<TKey> ​

EntityData<TKey> ​

EntityVersion<TKey> ​

EntityMember<TKey> ​

EntityMemberWithTenant<TKey> ​

使用示例 ​

基础实体（含审计+软删除） ​

多租户实体 ​

多租户+数据权限实体 ​

数据权限实体（无租户） ​

乐观锁实体 ​

会员实体 ​

会员+租户实体 ​

无主键实体（关联表） ​

树形实体 ​

树形+多租户实体 ​

仅主键实体 ​

自动赋值特性 ​

实体基类

应用场景

实体继承关系

主键实体链（含审计+软删除）

无主键实体链（仅审计）

EntityBase<TKey> 派生类

可组合接口

各基类详细字段

Entity<TKey>

EntityAdd<TKey>

EntityUpdate<TKey>

EntityDelete<TKey>

EntityBase<TKey>

EntityAddNoId

EntityUpdateNoId

EntityTenant<TKey>

EntityTenantWithData<TKey>

EntityData<TKey>

EntityVersion<TKey>

EntityMember<TKey>

EntityMemberWithTenant<TKey>

使用示例

基础实体（含审计+软删除）

多租户实体

多租户+数据权限实体

数据权限实体（无租户）

乐观锁实体

会员实体

会员+租户实体

无主键实体（关联表）

树形实体

树形+多租户实体

仅主键实体

自动赋值特性