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

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

---

适用场景

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

---

继承关系总览

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

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

EntityBase 派生类

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 - 基础实体

提供雪花 Id 主键。

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

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

---

EntityAdd - 创建审计

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

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

[!TIP]
非泛型快捷类：EntityAdd（即 EntityAdd<long>）

---

EntityUpdate - 修改审计

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

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

[!TIP]
非泛型快捷类：EntityUpdate（即 EntityUpdate<long>）

---

EntityDelete - 软删除

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

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

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

---

EntityBase - 完整基类

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

[!TIP]
非泛型快捷类：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 - 多租户

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

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

[!TIP]
非泛型快捷类：EntityTenant（即 EntityTenant<long>）

---

EntityTenantWithData - 多租户 + 数据权限

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

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

[!TIP]
非泛型快捷类：EntityTenantWithData（即 EntityTenantWithData<long>）

---

EntityData - 数据权限

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

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

[!TIP]
非泛型快捷类：EntityData（即 EntityData<long>）

---

EntityVersion - 乐观锁

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

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

[!TIP]
非泛型快捷类：EntityVersion（即 EntityVersion<long>）

---

EntityMember - 会员

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

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

[!TIP]
非泛型快捷类：EntityMember（即 EntityMember<long>）

---

EntityMemberWithTenant - 会员 + 租户

继承 EntityMember，实现 ITenant。

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

[!TIP]
非泛型快捷类：EntityMemberWithTenant（即 EntityMemberWithTenant<long>）

---

使用示例

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

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; }
}

---

多租户实体

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

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

---

多租户 + 数据权限实体

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

展开后等价于：

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; }
}

---

数据权限实体（无租户）

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

---

乐观锁实体

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

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

---

会员实体

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; }
}

---

会员 + 租户实体

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

---

无主键实体（关联表）

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

---

树形实体

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; }
}

---

树形 + 多租户实体

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

---

仅主键实体

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)]	乐观锁版本字段

#中台 #中台/分布式微服务 #中台/.NET模板 #Code/C#