contract-manager/docs/task/server模块service缓存调整为Vo对象/CONSENSUS_server模块service缓存调整为Vo对象.md

6A工作流 - CONSENSUS阶段文档

任务名称：Server模块Service缓存调整为Vo对象

1. 需求描述

1.1 基础需求

• 修改范围: server模块中所有注解了@CacheConfig的Service类
• 泛型调整: 调整Service类的接口泛型参数，保持IEntityService泛型为实体类，QueryService泛型为Vo类
• 接口实现: Service类同时实现IEntityService和QueryService接口
• 方法适配: 根据接口要求实现对应的方法，特别处理同名方法的实现
• 缓存优化: 使用VO对象替代实体类进行缓存，彻底避免Hibernate代理对象序列化问题和懒加载异常

1.2 扩展需求

• 数据转换机制: 确保从实体类到VO的转换和从VO到实体类的转换逻辑完善且性能良好
• 依赖组件处理: 确保修改后不影响调用Service的其他组件正常运行
• 兼容性保障: 确保WebSocket服务和任务管理等组件能够适配新的接口定义

1.3 需求目标

• 优化缓存机制: 使用VO对象替代实体类进行缓存，提高系统稳定性和性能
• 代码结构优化: 使Service类的接口实现更加清晰，职责更加明确
• 问题解决: 彻底解决因Hibernate代理对象序列化导致的懒加载异常
• 扩展性提升: 为后续系统扩展和维护奠定良好基础

2. 验收标准

1. 代码修改完整性: 所有注解了@CacheConfig的Service类都按要求进行了泛型参数调整和方法实现修改

   • 验证方式: 代码审查，确保所有符合条件的Service类都被修改

2. 缓存对象类型: 所有标注@Cacheable的方法返回VO对象而非实体类对象

   • 验证方式: 代码审查，检查@Cacheable注解的方法返回类型

3. 实体转换机制: 实体类正确实现Voable接口，提供toVo方法

   • 验证方式: 代码审查，确保实体类实现了必要的接口和方法

4. 功能兼容性: 修改后系统功能正常运行，没有出现新的错误或异常

   • 验证方式: 功能测试，确保核心业务流程正常

5. 缓存键表达式有效性: 缓存注解中的键表达式在修改后仍然有效

   • 验证方式: 功能测试，确保缓存能够正常工作

6. WebSocket服务兼容性: WebSocket服务能够正常工作，不受Service类修改的影响

   • 验证方式: 功能测试，确保WebSocket相关功能正常

3. 技术实现方案

3.1 泛型修改方案

• 对于每个注解了@CacheConfig的Service类，修改其实现的接口为：

  @CacheConfig(cacheNames = "entityCache")
  public class XXXService implements IEntityService<XXXModel>, QueryService<XXXVo>, VoableService<XXXModel, XXXVo> {
      // 方法实现
  }
  

3.2 数据转换策略

• 实体类实现Voable接口，提供toVo方法：

  public class XXXModel implements Voable<XXXVo> {
      @Override
      public XXXVo toVo() {
          XXXVo vo = new XXXVo();
          // 进行属性复制
          return vo;
      }
  }
  

• Service类中的查询方法（如findById、findAll）先查询实体，再转换为Vo对象：

  @Cacheable(key = "#id")
  @Override
  public XXXVo findById(Integer id) {
      Optional<XXXModel> optional = repository.findById(id);
      return optional.map(XXXModel::toVo).orElse(null);
  }
  

3.3 缓存注解处理

• 保持现有的缓存注解配置不变，确保键表达式仍然有效
• 确保所有标注@Cacheable的方法都返回VO对象

3.4 Specification处理

• IEntityService接口的getSpecification方法保持返回基于实体类的Specification
• QueryService接口的findAll方法中，先使用基于实体类的Specification查询数据，然后转换为Vo对象

  @Override
  public Page<XXXVo> findAll(JsonNode paramsNode, Pageable pageable) {
      Specification<XXXModel> spec = getSpecification(paramsNode);
      Page<XXXModel> page = findAll(spec, pageable);
      return page.map(XXXModel::toVo);
  }
  

4. 技术约束

1. 保持接口定义不变: 不修改IEntityService、QueryService和VoableService接口的定义，只修改实现类

2. 确保事务一致性: 修改后不影响现有事务处理逻辑，确保数据一致性

3. 兼容性保障: 确保修改后与现有系统和组件的兼容性，特别是WebSocket服务

4. 性能优化: 数据转换逻辑应高效，避免性能瓶颈

5. 错误处理: 完善异常处理机制，确保系统稳定性

6. 缓存策略: 严格遵循缓存策略，避免缓存穿透、缓存雪崩等问题

7. 代码规范: 遵循项目现有的代码规范和命名约定

5. 集成方案

1. 逐步实施: 按模块或按业务功能逐步实施修改，降低风险

2. 测试验证: 对每个修改的Service类进行单元测试和集成测试

3. 依赖分析: 分析修改对其他组件的影响，确保所有依赖都能正确适配

4. 缓存清理: 在部署前清理Redis缓存，避免新旧数据混合导致的问题

5. 监控机制: 部署后加强监控，及时发现和解决可能出现的问题

6. 任务边界限制

1. 修改范围限制: 仅修改server模块中注解了@CacheConfig的Service类

2. 接口定义限制: 不修改IEntityService、QueryService和VoableService接口的定义

3. 业务逻辑限制: 不修改现有业务逻辑，仅调整接口实现和数据转换方式

7. 关键假设确认

1. Vo类结构: 假设所有Vo类与对应的实体类具有相似的属性结构，特别是ID属性

2. 接口稳定性: 假设IEntityService、QueryService和VoableService接口在短时间内不会发生重大变化

3. 依赖关系: 假设Service类的主要依赖关系和调用方式不会发生变化

8. 项目特性规范对齐

1. 代码风格: 遵循项目现有的代码风格和命名约定

2. 注释规范: 为新增代码和修改的代码添加适当的JavaDoc注释

3. 文档同步: 及时更新相关文档，确保文档与代码的一致性

4. 测试规范: 按照项目测试规范编写测试用例，确保代码质量

所有关键假设已得到确认，任务边界清晰，技术方案与现有架构对齐，验收标准具体可测试。