# 基础实体模型 **本文档引用的文件** - [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 等包组织，形成“领域模型 + 基础设施”的清晰分层。 ```mermaid 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](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) - [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.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) - [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) 章节来源 - [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) - [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.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) - [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) ## 核心组件 - BaseEntity：所有业务实体的根基类，定义统一的标识、审计与通用能力（如分页、排序、逻辑删除标记等）。 - OwnedEntity：在 BaseEntity 基础上增加数据所有权相关字段与校验，用于实现租户/部门/用户级别的数据隔离。 - StatusEnum / HasValueEnum：统一的状态与值对象枚举规范，确保跨模块一致性与可扩展性。 - MetaObjectFillHandler：自动填充审计字段（创建时间、更新时间、创建人、更新人），减少样板代码。 - MybatisPlusConfig / CrmSqlInjector：集成 MyBatis-Plus 的能力，注入通用 SQL 片段与分页插件。 - DataOwnership / DataScopeHelper / DataVisibilityContext：数据可见性与权限上下文管理，支撑细粒度数据范围控制。 - IBaseService / BaseServiceImpl：通用服务接口与实现，封装 CRUD、分页、批量操作与审计填充。 - CrmBaseMapper：通用 Mapper 基类，为各业务 Mapper 提供统一扩展点。 章节来源 - [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) - [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) ## 架构总览 下图展示了基础实体模型与 ORM、安全上下文、服务层的协作关系。 ```mermaid 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](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) - [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) ## 详细组件分析 ### 基础实体：BaseEntity - 职责：定义所有实体的通用字段与行为，包括主键、审计字段、逻辑删除标记、通用查询辅助方法。 - 关键设计要点： - 审计字段：创建时间、更新时间、创建人、更新人，通过元对象处理器自动填充。 - 软删除：通过逻辑删除字段配合 MyBatis-Plus 插件实现，避免物理删除带来的数据丢失风险。 - 通用查询：提供分页、排序、条件构造等便捷方法，提升开发效率。 - 扩展建议： - 新增通用字段时，需同步在元对象处理器中配置默认值或填充策略。 - 若需要额外的查询能力，优先在 CrmSqlInjector 中注入通用 SQL 片段，保持 Mapper 简洁。 章节来源 - [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.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) ### 数据所有权实体：OwnedEntity - 职责：在 BaseEntity 基础上引入数据所有权相关字段（如 owner、tenant、dept），并配套数据范围校验与过滤。 - 关键设计要点： - 字段设计：包含所有者标识、租户标识、部门标识等，便于多租户与部门级数据隔离。 - 数据范围：结合 DataOwnership 注解与 DataScopeHelper，动态生成 WHERE 条件，限制查询范围。 - 上下文管理：通过 DataVisibilityContext 维护当前请求的数据可见性，从 LoginUser 提取用户信息。 - 扩展建议： - 新增数据维度（如项目、客户群）时，扩展 OwnedEntity 字段并在 DataScopeHelper 中补充规则。 - 对敏感操作进行二次校验，确保写入路径也遵循所有权约束。 章节来源 - [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.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) ### 枚举规范：StatusEnum 与 HasValueEnum - 职责：统一状态与值对象的表达，保证跨模块一致性。 - 关键设计要点： - StatusEnum：定义状态码、描述、有效性校验；推荐提供 toLabel、isValid 等方法。 - HasValueEnum：定义 value/label 对，并提供 toOptions 等前端友好输出方法。 - 扩展建议： - 新增枚举时，遵循相同的命名与结构约定，避免散乱定义。 - 在 DTO/VO 层尽量使用枚举类型，减少字符串硬编码。 章节来源 - [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 - 职责：在插入与更新时自动填充审计字段（创建时间、更新时间、创建人、更新人）。 - 关键设计要点： - 插入填充：设置 createTime、createBy 等默认值。 - 更新填充：设置 updateTime、updateBy，避免覆盖未变更字段。 - 安全上下文：从 SecurityUtils 或 DataVisibilityContext 获取当前登录用户信息。 - 扩展建议： - 如需额外审计字段（如 IP、设备），可在填充器中追加逻辑。 - 注意并发场景下的线程安全，避免共享可变状态。 章节来源 - [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) - [SecurityUtils.java](file://crm-base/src/main/java/com/crm/base/security/SecurityUtils.java) - [DataVisibilityContext.java](file://crm-base/src/main/java/com/crm/base/security/DataVisibilityContext.java) ### ORM 配置与通用能力：MybatisPlusConfig、CrmSqlInjector、CrmBaseMapper - 职责：集成 MyBatis-Plus 的分页、元对象处理器、SQL 注入器，提供通用 Mapper 能力。 - 关键设计要点： - 分页插件：启用分页拦截器，统一分页行为。 - 元对象处理器：注册 MetaObjectFillHandler，实现审计字段自动填充。 - SQL 注入：通过 CrmSqlInjector 注入通用 SQL 片段（如软删除过滤、数据范围条件）。 - 通用 Mapper：CrmBaseMapper 作为业务 Mapper 的父类，提供统一扩展点。 - 扩展建议： - 新增通用查询条件时，优先在 CrmSqlInjector 中定义，避免在各 Mapper 中重复实现。 - 合理配置分页参数，避免全表扫描与大结果集传输。 章节来源 - [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) - [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java) ### 通用服务：IBaseService 与 BaseServiceImpl - 职责：封装 CRUD、分页、批量操作与审计填充，为业务 Service 提供统一基类。 - 关键设计要点： - 标准接口：定义 save、update、deleteById、getById、page、list 等通用方法。 - 实现细节：在 BaseServiceImpl 中统一处理事务、异常、审计字段填充与数据范围过滤。 - 扩展点：允许子类覆写特定方法以注入业务逻辑。 - 扩展建议： - 复杂查询建议在 Service 层组合多个 Mapper 方法，保持单一职责。 - 批量操作注意性能与事务边界，必要时拆分批次。 章节来源 - [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) ### 数据可见性与权限：DataOwnership、DataScopeHelper、DataVisibilityContext、LoginUser - 职责：基于注解与上下文实现细粒度的数据范围控制，确保用户只能访问其有权访问的数据。 - 关键设计要点： - 注解驱动：DataOwnership 标注在 Controller/Service 方法上，声明数据范围策略。 - 范围计算：DataScopeHelper 根据上下文与策略生成 WHERE 条件。 - 上下文管理：DataVisibilityContext 保存当前请求的用户与租户信息。 - 用户信息：LoginUser 承载 userId、deptId、tenantId 等关键标识。 - 扩展建议： - 新增数据维度时，扩展 DataScopeHelper 的规则集合。 - 对越权访问进行日志记录与告警，提升安全性。 章节来源 - [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) ### 通用常量：CommonConstants - 职责：集中定义系统级常量（如分页默认值、状态码、错误码等），避免魔法数字。 - 使用建议： - 所有模块引用 CommonConstants 中的常量，保持一致性。 - 新增常量时按分类组织，便于检索与维护。 章节来源 - [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java) ## 依赖关系分析 下图展示基础实体模型与 ORM、安全、服务层之间的依赖关系。 ```mermaid graph LR BaseEntity --> MetaObjectFillHandler OwnedEntity --> BaseEntity OwnedEntity --> DataScopeHelper DataScopeHelper --> DataVisibilityContext DataVisibilityContext --> LoginUser MybatisPlusConfig --> MetaObjectFillHandler CrmSqlInjector --> CrmBaseMapper IBaseService --> BaseServiceImpl BaseServiceImpl --> CrmBaseMapper ``` 图表来源 - [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) - [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.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) - [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) - [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.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) 章节来源 - [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) - [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.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) - [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) - [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.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) ## 性能考虑 - 分页与排序： - 始终使用分页查询，避免一次性加载大结果集。 - 在常用查询字段上建立索引，提升排序与过滤性能。 - 审计字段填充： - 仅在必要字段触发填充，避免不必要的数据库写入。 - 批量操作时合并填充逻辑，减少往返次数。 - 数据范围过滤： - 将数据范围条件下推到 SQL 层，减少内存过滤开销。 - 对高频维度（如 tenantId、deptId）建立复合索引。 - 缓存与幂等： - 对只读枚举与字典数据使用缓存，降低数据库压力。 - 对写操作实现幂等性，避免重复提交导致的数据不一致。 - 连接池与事务： - 合理配置连接池大小与超时时间，避免连接耗尽。 - 控制事务边界，避免长事务阻塞资源。 [本节为通用指导，不直接分析具体文件] ## 故障排查指南 - 审计字段未填充： - 检查 MetaObjectFillHandler 是否已注册到 MybatisPlusConfig。 - 确认实体字段名与填充策略一致，且未被手动覆盖。 - 数据范围无效： - 检查 DataOwnership 注解是否正确标注，以及 DataVisibilityContext 是否设置了正确的上下文。 - 验证 DataScopeHelper 的规则是否覆盖了新维度。 - 分页异常： - 确认分页插件已启用，且查询未绕过分页拦截器。 - 检查 SQL 中是否存在不支持分页的函数或子查询。 - 软删除问题： - 确认 CrmSqlInjector 已注入软删除过滤条件。 - 检查业务逻辑是否误用物理删除方法。 章节来源 - [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) - [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) - [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java) ## 结论 通过 BaseEntity 与 OwnedEntity 的统一抽象，配合枚举规范、审计填充、数据范围控制与通用服务层，本项目为业务实体提供了标准化、可扩展、高性能的基础模型参考。遵循本文档的设计原则与实践建议，可显著提升开发效率与系统可维护性。 [本节为总结性内容，不直接分析具体文件] ## 附录 - 最佳实践清单： - 所有实体继承 BaseEntity 或 OwnedEntity。 - 使用 StatusEnum/HasValueEnum 表达状态与值对象。 - 通过 MetaObjectFillHandler 自动填充审计字段。 - 使用 DataOwnership 与 DataScopeHelper 控制数据范围。 - 在 CrmSqlInjector 中注入通用 SQL 片段。 - 通过 IBaseService/BaseServiceImpl 封装通用 CRUD。 - 常见问题速查： - 审计字段为空：检查填充器注册与字段名匹配。 - 数据范围不生效：检查注解与上下文设置。 - 分页失效：检查分页插件与 SQL 兼容性。 - 软删除异常：检查注入的通用 SQL 与调用方法。 [本节为补充说明，不直接分析具体文件]