# Server模块Service缓存调整为Vo对象 - CONSENSUS文档

## 1. 需求描述

### 1.1 核心需求

将Contract-Manager项目Server模块中所有使用@CacheConfig注解的Service类的缓存值从实体对象（Model）调整为视图对象（VO），以提高系统性能和安全性。

### 1.2 任务分解

任务1：分析现有Service类结构和依赖关系
任务2：设计实体类和VO类之间的转换机制
任务3：设计缓存策略
任务4：修改Service类以实现缓存调整
任务5：编写测试用例
任务6：集成测试和验证

## 2. 验收标准

### 2.1 任务1验收标准

- 完成Service类结构分析报告，包含所有注解了@CacheConfig的Service类的列表
- 绘制Service类的依赖关系图
- 分析并记录IEntityService、QueryService、VoableService接口的泛型参数
- 分析并记录WebSocketServerCallbackManager与IEntityService接口的交互逻辑
- 分析并记录特殊方法和缓存配置

### 2.2 总体验收标准

- 所有Service类的缓存值从实体对象成功调整为Vo对象
- 系统功能保持不变，没有引入新的bug
- 系统性能（特别是查询性能）有所提升
- 代码质量符合项目规范
- 文档完整且与代码保持一致

## 3. 技术实现方案

### 3.1 缓存调整策略

1. **缓存键设计**：
   - 统一缓存键的命名规则：`{cacheName}:{entityType}:{id}`
   - 保留原有的缓存名称（通过@CacheConfig指定）

2. **缓存值转换**：
   - 在Service类的方法中，将实体对象转换为Vo对象后再存入缓存
   - 修改getById、findAll等方法的缓存配置，使用Vo对象作为缓存值

3. **关联实体处理**：
   - 对于有关联实体的情况，在updateByVo方法中添加实体匹配检查
   - 使用getById方法获取关联实体，避免直接使用findById

### 3.2 WebSocket交互优化

1. **消息处理优化**：
   - 优化WebSocketServerCallbackManager中的方法调用逻辑
   - 减少不必要的反射操作

2. **缓存一致性维护**：
   - 确保WebSocket操作对实体的修改能够正确地清理相关缓存
   - 维护实体缓存和Vo缓存的一致性

### 3.3 接口实现规范

1. **泛型参数规范**：
   - Service类实现IEntityService<T>接口时，T为实体类类型
   - Service类实现QueryService<Vo>接口时，Vo为对应的VO类类型
   - Service类实现VoableService<M, Vo>接口时，M为实体类类型，Vo为对应的VO类类型

2. **方法实现规范**：
   - getById方法：不使用@Cacheable注解，直接调用Repository的findById方法
   - findById方法（QueryService）：调用getById方法获取实体，然后转换为Vo对象，使用@Cacheable注解
   - findAll方法：根据参数类型分别实现
   - save/delete方法：使用@CacheEvict或@Caching注解清理相关缓存

## 4. 技术约束和集成方案

### 4.1 技术约束

- 严格遵循项目现有的技术栈和架构
- 确保修改不影响系统的稳定性和可用性
- 遵循项目的代码规范和命名约定
- 确保缓存调整后与客户端的通信不受影响

### 4.2 集成方案

1. **与现有系统集成**：
   - 逐步替换的方式，先在非核心模块进行试点
   - 全面测试确保与现有功能的兼容性

2. **与WebSocket服务集成**：
   - WebSocketServerCallbackManager需要正确处理返回Vo对象的Service方法
   - 确保WebSocket消息的序列化和反序列化正确处理Vo对象

3. **与缓存系统集成**：
   - 确保Redis缓存配置正确，能够存储和检索Vo对象
   - 设计合理的缓存过期策略

## 5. 任务边界限制

### 5.1 范围限制

- 仅限于Server模块中注解了@CacheConfig的Service类
- 不涉及client模块和common模块的修改
- 不改变现有的实体类和VO类的结构

### 5.2 时间限制

- 按照6A工作流的阶段划分逐步执行
- 每个阶段都需要进行质量门控，确保阶段成果的质量

## 6. 不确定性解决方案

### 6.1 缓存调整的具体目标

解决方案：完全替换实体对象缓存为Vo对象缓存，提高系统性能和安全性。

### 6.2 缓存键的设计

解决方案：统一缓存键的命名规则，使用`{cacheName}:{entityType}:{id}`格式，提高系统的可维护性。

### 6.3 多接口实现的泛型参数

解决方案：制定统一的规范，确保Service类实现多个接口时泛型参数的使用一致。

### 6.4 WebSocket通信的兼容性

解决方案：修改WebSocketServerCallbackManager中处理缓存的逻辑，确保兼容性。

### 6.5 测试策略

解决方案：编写单元测试和集成测试，测试缓存的读写、清理等操作，确保缓存调整的正确性和性能。

## 7. 最终共识

所有不确定性已解决，明确了需求描述、验收标准、技术实现方案、技术约束和任务边界。项目将按照6A工作流的阶段划分逐步执行，确保每个阶段的成果质量。