# 6A工作流 - CONSENSUS阶段文档

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

## 1. 需求描述

### 1.1 基础需求
- **修改范围**: server模块中所有注解了@CacheConfig的Service类
- **泛型调整**: 调整Service类的接口泛型参数，保持IEntityService泛型为实体类，QueryService泛型为Vo类
- **接口实现**: Service类同时实现IEntityService<Model>和QueryService<Vo>接口
- **方法适配**: 根据接口要求实现对应的方法，特别处理同名方法的实现
- **缓存优化**: 使用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类，修改其实现的接口为：
  ```java
  @CacheConfig(cacheNames = "entityCache")
  public class XXXService implements IEntityService<XXXModel>, QueryService<XXXVo>, VoableService<XXXModel, XXXVo> {
      // 方法实现
  }
  ```

### 3.2 数据转换策略
- 实体类实现Voable接口，提供toVo方法：
  ```java
  public class XXXModel implements Voable<XXXVo> {
      @Override
      public XXXVo toVo() {
          XXXVo vo = new XXXVo();
          // 进行属性复制
          return vo;
      }
  }
  ```

- Service类中的查询方法（如findById、findAll）先查询实体，再转换为Vo对象：
  ```java
  @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对象
  ```java
  @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. **测试规范**: 按照项目测试规范编写测试用例，确保代码质量

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