crm-backend-matt/.qoder/repowiki/zh/content/数据模型/基础实体模型.md

基础实体模型

**本文档引用的文件** - [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java) - [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java) - [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java) - [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java) - [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java) - [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java) - [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java) - [DataOwnership.java](file://crm-base/src/main/java/com/crm/base/security/DataOwnership.java) - [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java) - [DataVisibilityContext.java](file://crm-base/src/main/java/com/crm/base/security/DataVisibilityContext.java) - [LoginUser.java](file://crm-base/src/main/java/com/crm/base/security/LoginUser.java) - [SecurityUtils.java](file://crm-base/src/main/java/com/crm/base/security/SecurityUtils.java) - [IBaseService.java](file://crm-base/src/main/java/com/crm/base/service/IBaseService.java) - [BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java) - [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java) - [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能考虑
8. 故障排查指南
9. 结论
10. 附录

简介

本文件面向所有业务实体的标准化建模，聚焦于基础实体模型的设计与使用。内容涵盖：

• BaseEntity、OwnedEntity 等基础实体的通用字段设计、继承关系与公共属性
• 状态枚举与值对象枚举的统一规范（如 StatusEnum、HasValueEnum）
• 审计字段（创建时间、更新时间、操作人）、数据所有权控制、软删除机制
• 扩展模式与自定义字段添加方法、通用查询条件支持
• 实体基类设计原则、ORM 映射配置与性能优化建议 目标是为企业级 CRM 后端提供统一、可复用、易扩展的基础模型参考。

项目结构

基础实体模型位于 crm-base 模块中，围绕 domain/entity、domain/enums、config、security、service、mapper 等包组织，形成“领域模型 + 基础设施”的清晰分层。

graph TB
subgraph "基础层 crm-base"
A["entity/BaseEntity"] --> B["entity/OwnedEntity"]
C["enums/StatusEnum"] --> D["enums/HasValueEnum"]
E["config/MetaObjectFillHandler"] --> F["config/MybatisPlusConfig"]
G["config/CrmSqlInjector"] --> H["mapper/CrmBaseMapper"]
I["security/DataOwnership"] --> J["security/DataScopeHelper"]
K["security/DataVisibilityContext"] --> L["security/LoginUser"]
M["service/IBaseService"] --> N["service/impl/BaseServiceImpl"]
end
B --> C
B --> D
N --> H
J --> K

图表来源

• BaseEntity.java
• OwnedEntity.java
• StatusEnum.java
• HasValueEnum.java
• MetaObjectFillHandler.java
• MybatisPlusConfig.java
• CrmSqlInjector.java
• CrmBaseMapper.java
• DataOwnership.java
• DataScopeHelper.java
• DataVisibilityContext.java
• LoginUser.java
• IBaseService.java
• BaseServiceImpl.java

章节来源

• BaseEntity.java
• OwnedEntity.java
• StatusEnum.java
• HasValueEnum.java
• MetaObjectFillHandler.java
• MybatisPlusConfig.java
• CrmSqlInjector.java
• CrmBaseMapper.java
• DataOwnership.java
• DataScopeHelper.java
• DataVisibilityContext.java
• LoginUser.java
• IBaseService.java
• BaseServiceImpl.java

核心组件

• BaseEntity：所有业务实体的根基类，定义统一的标识、审计与通用能力（如分页、排序、逻辑删除标记等）。
• OwnedEntity：在 BaseEntity 基础上增加数据所有权相关字段与校验，用于实现租户/部门/用户级别的数据隔离。
• StatusEnum / HasValueEnum：统一的状态与值对象枚举规范，确保跨模块一致性与可扩展性。
• MetaObjectFillHandler：自动填充审计字段（创建时间、更新时间、创建人、更新人），减少样板代码。
• MybatisPlusConfig / CrmSqlInjector：集成 MyBatis-Plus 的能力，注入通用 SQL 片段与分页插件。
• DataOwnership / DataScopeHelper / DataVisibilityContext：数据可见性与权限上下文管理，支撑细粒度数据范围控制。
• IBaseService / BaseServiceImpl：通用服务接口与实现，封装 CRUD、分页、批量操作与审计填充。
• CrmBaseMapper：通用 Mapper 基类，为各业务 Mapper 提供统一扩展点。

章节来源

• BaseEntity.java
• OwnedEntity.java
• StatusEnum.java
• HasValueEnum.java
• MetaObjectFillHandler.java
• MybatisPlusConfig.java
• CrmSqlInjector.java
• DataOwnership.java
• DataScopeHelper.java
• DataVisibilityContext.java
• IBaseService.java
• BaseServiceImpl.java
• CrmBaseMapper.java

架构总览

下图展示了基础实体模型与 ORM、安全上下文、服务层的协作关系。

classDiagram
class BaseEntity {
+id
+createTime
+updateTime
+createBy
+updateBy
+deleted
+通用查询方法()
}
class OwnedEntity {
+ownerId
+tenantId
+deptId
+数据范围校验()
}
class StatusEnum {
+code
+desc
+isValid()
}
class HasValueEnum {
+value
+label
+toOptions()
}
class MetaObjectFillHandler {
+fillInsert()
+fillUpdate()
}
class MybatisPlusConfig {
+分页插件()
+元对象处理器()
}
class CrmSqlInjector {
+注入通用SQL()
}
class DataOwnership {
+注解 : 数据所有权
}
class DataScopeHelper {
+构建数据范围()
}
class DataVisibilityContext {
+设置上下文()
+获取上下文()
}
class LoginUser {
+userId
+deptId
+tenantId
}
class IBaseService {
+CRUD()
+分页()
+批量()
}
class BaseServiceImpl {
+实现通用服务()
}
class CrmBaseMapper {
+通用Mapper()
}
OwnedEntity --|> BaseEntity : "继承"
MetaObjectFillHandler --> BaseEntity : "填充审计字段"
MybatisPlusConfig --> MetaObjectFillHandler : "注册"
CrmSqlInjector --> CrmBaseMapper : "注入SQL"
DataOwnership --> DataScopeHelper : "驱动范围计算"
DataScopeHelper --> DataVisibilityContext : "读写上下文"
DataVisibilityContext --> LoginUser : "读取当前用户"
IBaseService <|-- BaseServiceImpl : "实现"
BaseServiceImpl --> CrmBaseMapper : "调用"

图表来源

• BaseEntity.java
• OwnedEntity.java
• StatusEnum.java
• HasValueEnum.java
• MetaObjectFillHandler.java
• MybatisPlusConfig.java
• CrmSqlInjector.java
• DataOwnership.java
• DataScopeHelper.java
• DataVisibilityContext.java
• LoginUser.java
• IBaseService.java
• BaseServiceImpl.java
• CrmBaseMapper.java

详细组件分析

基础实体：BaseEntity

• 职责：定义所有实体的通用字段与行为，包括主键、审计字段、逻辑删除标记、通用查询辅助方法。
• 关键设计要点：
  • 审计字段：创建时间、更新时间、创建人、更新人，通过元对象处理器自动填充。
  • 软删除：通过逻辑删除字段配合 MyBatis-Plus 插件实现，避免物理删除带来的数据丢失风险。
  • 通用查询：提供分页、排序、条件构造等便捷方法，提升开发效率。
• 扩展建议：
  • 新增通用字段时，需同步在元对象处理器中配置默认值或填充策略。
  • 若需要额外的查询能力，优先在 CrmSqlInjector 中注入通用 SQL 片段，保持 Mapper 简洁。

章节来源

• BaseEntity.java
• MetaObjectFillHandler.java
• MybatisPlusConfig.java
• CrmSqlInjector.java

数据所有权实体：OwnedEntity

• 职责：在 BaseEntity 基础上引入数据所有权相关字段（如 owner、tenant、dept），并配套数据范围校验与过滤。
• 关键设计要点：
  • 字段设计：包含所有者标识、租户标识、部门标识等，便于多租户与部门级数据隔离。
  • 数据范围：结合 DataOwnership 注解与 DataScopeHelper，动态生成 WHERE 条件，限制查询范围。
  • 上下文管理：通过 DataVisibilityContext 维护当前请求的数据可见性，从 LoginUser 提取用户信息。
• 扩展建议：
  • 新增数据维度（如项目、客户群）时，扩展 OwnedEntity 字段并在 DataScopeHelper 中补充规则。
  • 对敏感操作进行二次校验，确保写入路径也遵循所有权约束。

章节来源

• OwnedEntity.java
• DataOwnership.java
• DataScopeHelper.java
• DataVisibilityContext.java
• LoginUser.java

枚举规范：StatusEnum 与 HasValueEnum

• 职责：统一状态与值对象的表达，保证跨模块一致性。
• 关键设计要点：
  • StatusEnum：定义状态码、描述、有效性校验；推荐提供 toLabel、isValid 等方法。
  • HasValueEnum：定义 value/label 对，并提供 toOptions 等前端友好输出方法。
• 扩展建议：
  • 新增枚举时，遵循相同的命名与结构约定，避免散乱定义。
  • 在 DTO/VO 层尽量使用枚举类型，减少字符串硬编码。

章节来源

• StatusEnum.java
• HasValueEnum.java

审计字段自动填充：MetaObjectFillHandler

• 职责：在插入与更新时自动填充审计字段（创建时间、更新时间、创建人、更新人）。
• 关键设计要点：
  • 插入填充：设置 createTime、createBy 等默认值。
  • 更新填充：设置 updateTime、updateBy，避免覆盖未变更字段。
  • 安全上下文：从 SecurityUtils 或 DataVisibilityContext 获取当前登录用户信息。
• 扩展建议：
  • 如需额外审计字段（如 IP、设备），可在填充器中追加逻辑。
  • 注意并发场景下的线程安全，避免共享可变状态。

章节来源

• MetaObjectFillHandler.java
• MybatisPlusConfig.java
• SecurityUtils.java
• DataVisibilityContext.java

ORM 配置与通用能力：MybatisPlusConfig、CrmSqlInjector、CrmBaseMapper

• 职责：集成 MyBatis-Plus 的分页、元对象处理器、SQL 注入器，提供通用 Mapper 能力。
• 关键设计要点：
  • 分页插件：启用分页拦截器，统一分页行为。
  • 元对象处理器：注册 MetaObjectFillHandler，实现审计字段自动填充。
  • SQL 注入：通过 CrmSqlInjector 注入通用 SQL 片段（如软删除过滤、数据范围条件）。
  • 通用 Mapper：CrmBaseMapper 作为业务 Mapper 的父类，提供统一扩展点。
• 扩展建议：
  • 新增通用查询条件时，优先在 CrmSqlInjector 中定义，避免在各 Mapper 中重复实现。
  • 合理配置分页参数，避免全表扫描与大结果集传输。

章节来源

• MybatisPlusConfig.java
• CrmSqlInjector.java
• CrmBaseMapper.java

通用服务：IBaseService 与 BaseServiceImpl

• 职责：封装 CRUD、分页、批量操作与审计填充，为业务 Service 提供统一基类。
• 关键设计要点：
  • 标准接口：定义 save、update、deleteById、getById、page、list 等通用方法。
  • 实现细节：在 BaseServiceImpl 中统一处理事务、异常、审计字段填充与数据范围过滤。
  • 扩展点：允许子类覆写特定方法以注入业务逻辑。
• 扩展建议：
  • 复杂查询建议在 Service 层组合多个 Mapper 方法，保持单一职责。
  • 批量操作注意性能与事务边界，必要时拆分批次。

章节来源

• IBaseService.java
• BaseServiceImpl.java

数据可见性与权限：DataOwnership、DataScopeHelper、DataVisibilityContext、LoginUser

• 职责：基于注解与上下文实现细粒度的数据范围控制，确保用户只能访问其有权访问的数据。
• 关键设计要点：
  • 注解驱动：DataOwnership 标注在 Controller/Service 方法上，声明数据范围策略。
  • 范围计算：DataScopeHelper 根据上下文与策略生成 WHERE 条件。
  • 上下文管理：DataVisibilityContext 保存当前请求的用户与租户信息。
  • 用户信息：LoginUser 承载 userId、deptId、tenantId 等关键标识。
• 扩展建议：
  • 新增数据维度时，扩展 DataScopeHelper 的规则集合。
  • 对越权访问进行日志记录与告警，提升安全性。

章节来源

• DataOwnership.java
• DataScopeHelper.java
• DataVisibilityContext.java
• LoginUser.java

通用常量：CommonConstants

• 职责：集中定义系统级常量（如分页默认值、状态码、错误码等），避免魔法数字。
• 使用建议：
  • 所有模块引用 CommonConstants 中的常量，保持一致性。
  • 新增常量时按分类组织，便于检索与维护。

章节来源

• CommonConstants.java

依赖关系分析

下图展示基础实体模型与 ORM、安全、服务层之间的依赖关系。

graph LR
BaseEntity --> MetaObjectFillHandler
OwnedEntity --> BaseEntity
OwnedEntity --> DataScopeHelper
DataScopeHelper --> DataVisibilityContext
DataVisibilityContext --> LoginUser
MybatisPlusConfig --> MetaObjectFillHandler
CrmSqlInjector --> CrmBaseMapper
IBaseService --> BaseServiceImpl
BaseServiceImpl --> CrmBaseMapper

图表来源

• BaseEntity.java
• OwnedEntity.java
• MetaObjectFillHandler.java
• DataScopeHelper.java
• DataVisibilityContext.java
• LoginUser.java
• MybatisPlusConfig.java
• CrmSqlInjector.java
• CrmBaseMapper.java
• IBaseService.java
• BaseServiceImpl.java

章节来源

• BaseEntity.java
• OwnedEntity.java
• MetaObjectFillHandler.java
• DataScopeHelper.java
• DataVisibilityContext.java
• LoginUser.java
• MybatisPlusConfig.java
• CrmSqlInjector.java
• CrmBaseMapper.java
• IBaseService.java
• BaseServiceImpl.java

性能考虑

• 分页与排序：
  • 始终使用分页查询，避免一次性加载大结果集。
  • 在常用查询字段上建立索引，提升排序与过滤性能。
• 审计字段填充：
  • 仅在必要字段触发填充，避免不必要的数据库写入。
  • 批量操作时合并填充逻辑，减少往返次数。
• 数据范围过滤：
  • 将数据范围条件下推到 SQL 层，减少内存过滤开销。
  • 对高频维度（如 tenantId、deptId）建立复合索引。
• 缓存与幂等：
  • 对只读枚举与字典数据使用缓存，降低数据库压力。
  • 对写操作实现幂等性，避免重复提交导致的数据不一致。
• 连接池与事务：
  • 合理配置连接池大小与超时时间，避免连接耗尽。
  • 控制事务边界，避免长事务阻塞资源。

[本节为通用指导，不直接分析具体文件]

故障排查指南

• 审计字段未填充：
  • 检查 MetaObjectFillHandler 是否已注册到 MybatisPlusConfig。
  • 确认实体字段名与填充策略一致，且未被手动覆盖。
• 数据范围无效：
  • 检查 DataOwnership 注解是否正确标注，以及 DataVisibilityContext 是否设置了正确的上下文。
  • 验证 DataScopeHelper 的规则是否覆盖了新维度。
• 分页异常：
  • 确认分页插件已启用，且查询未绕过分页拦截器。
  • 检查 SQL 中是否存在不支持分页的函数或子查询。
• 软删除问题：
  • 确认 CrmSqlInjector 已注入软删除过滤条件。
  • 检查业务逻辑是否误用物理删除方法。

章节来源

• MetaObjectFillHandler.java
• MybatisPlusConfig.java
• DataOwnership.java
• DataScopeHelper.java
• DataVisibilityContext.java
• CrmSqlInjector.java

结论

通过 BaseEntity 与 OwnedEntity 的统一抽象，配合枚举规范、审计填充、数据范围控制与通用服务层，本项目为业务实体提供了标准化、可扩展、高性能的基础模型参考。遵循本文档的设计原则与实践建议，可显著提升开发效率与系统可维护性。

[本节为总结性内容，不直接分析具体文件]

附录

• 最佳实践清单：
  • 所有实体继承 BaseEntity 或 OwnedEntity。
  • 使用 StatusEnum/HasValueEnum 表达状态与值对象。
  • 通过 MetaObjectFillHandler 自动填充审计字段。
  • 使用 DataOwnership 与 DataScopeHelper 控制数据范围。
  • 在 CrmSqlInjector 中注入通用 SQL 片段。
  • 通过 IBaseService/BaseServiceImpl 封装通用 CRUD。
• 常见问题速查：
  • 审计字段为空：检查填充器注册与字段名匹配。
  • 数据范围不生效：检查注解与上下文设置。
  • 分页失效：检查分页插件与 SQL 兼容性。
  • 软删除异常：检查注入的通用 SQL 与调用方法。

[本节为补充说明，不直接分析具体文件]