refactor(service): 调整接口泛型参数并优化缓存策略

docs(task): 更新接口泛型修改相关文档 - 重构QueryService接口，移除未使用的Specification相关方法 - InventoryCatalogService实现IEntityService和QueryService接口 - 新增delete方法实现并调整缓存配置 - 删除过时的任务文档并重新组织文档结构 - 更新ALIGNMENT、CONSENSUS等文档，添加WebSocket服务兼容性说明
2025-09-28 19:11:53 +08:00
parent b03b5385a5
commit 1f354853b0
9 changed files with 322 additions and 83 deletions
--- a/docs/task/server模块service缓存调整为Vo对象/DESIGN_server模块service缓存调整为Vo对象.md
+++ b/docs/task/server模块service缓存调整为Vo对象/DESIGN_server模块service缓存调整为Vo对象.md
@@ -0,0 +1,353 @@
+# IEntityService接口泛型修改任务设计文档
+
+## 1. 整体架构图
+
+```mermaid
+flowchart TD
+    subgraph 控制器层
+        Controller[Controller控制器]
+    end
+
+    subgraph 服务层
+        direction LR
+        Service1[Service类
+        实现IEntityService<Vo>]
+        Service2[Service类
+        实现IEntityService<Vo>]
+        Service3[Service类
+        实现IEntityService<Vo>]
+    end
+
+    subgraph WebSocket服务层
+        WebSocketHandler[WebSocketServerHandler
+        处理WebSocket连接]
+        WebSocketTaskManager[WebSocketServerTaskManager
+        管理WebSocket任务]
+        WebSocketCallbackManager[WebSocketServerCallbackManager
+        处理服务调用回调]
+    end
+
+    subgraph 数据转换层
+        Mapper[实体-VO转换器
+        负责双向转换]
+    end
+
+    subgraph 数据访问层
+        Repository[Repository接口
+        操作实体类]
+    end
+
+    subgraph 数据层
+        Database[(数据库)]
+    end
+
+    subgraph 缓存层
+        RedisCache[Redis缓存
+        存储VO对象]
+    end
+
+    Controller -->|调用服务方法| Service1
+    Controller -->|调用服务方法| Service2
+    Controller -->|调用服务方法| Service3
+    WebSocketHandler -->|注入服务| Service1
+    WebSocketHandler -->|注入服务| Service2
+    WebSocketHandler -->|注入服务| Service3
+    WebSocketTaskManager -->|注入服务| Service1
+    WebSocketTaskManager -->|注入服务| Service2
+    WebSocketTaskManager -->|注入服务| Service3
+    WebSocketCallbackManager -->|反射调用| Service1
+    WebSocketCallbackManager -->|反射调用| Service2
+    WebSocketCallbackManager -->|反射调用| Service3
+    Service1 -->|转换VO到实体| Mapper
+    Service2 -->|转换VO到实体| Mapper
+    Service3 -->|转换VO到实体| Mapper
+    Mapper -->|转换实体到VO| Service1
+    Mapper -->|转换实体到VO| Service2
+    Mapper -->|转换实体到VO| Service3
+    Service1 -->|CRUD操作| Repository
+    Service2 -->|CRUD操作| Repository
+    Service3 -->|CRUD操作| Repository
+    Repository -->|存取数据| Database
+    Service1 <-->|缓存VO对象| RedisCache
+    Service2 <-->|缓存VO对象| RedisCache
+    Service3 <-->|缓存VO对象| RedisCache
+
+    %% 关键修改点
+    style RedisCache fill:#bbf,stroke:#333,stroke-width:2px
+    style WebSocketCallbackManager fill:#fbb,stroke:#333,stroke-width:2px
+```
+
+## 2. 分层设计和核心组件
+
+### 2.1 控制器层
+- **职责**: 处理HTTP请求，调用Service层方法，返回处理结果
+- **影响**: 可能需要调整调用Service层方法的参数和返回值类型
+
+### 2.2 服务层
+- **职责**: 实现业务逻辑，处理数据转换，调用Repository层进行数据操作，管理缓存
+- **核心组件**: 所有注解了@CacheConfig的Service类
+- **修改内容**: 
+  - 将IEntityService<T>的泛型T从实体类改为VO类
+  - 修改实现的接口方法，添加数据转换逻辑
+  - 确保缓存中存储的是VO对象而非实体类对象
+
+### 2.3 WebSocket服务层
+- **职责**: 处理WebSocket连接、消息传递、任务管理和回调处理
+- **核心组件**: 
+  - WebSocketServerHandler：处理WebSocket连接、消息传递和断开连接
+  - WebSocketServerTaskManager：管理WebSocket任务的注册和执行
+  - WebSocketServerCallbackManager：通过反射调用服务方法，处理回调
+- **影响**: 
+  - WebSocketServerCallbackManager直接调用IEntityService接口，泛型修改将对其产生直接影响
+  - 需要特别关注createNewEntity、findEntityTypeInInterfaces等方法的实现
+  - invokerFindByIdMethod、invokerFindAllMethod等方法需要适应VO类型的返回值
+
+### 2.4 数据转换层
+- **职责**: 负责实体类和VO类之间的数据转换
+- **核心组件**: 
+  - 现有的VoableService接口
+  - 新增的实体-VO转换工具方法
+  - WebSocketServerCallbackManager中的toVo方法
+- **设计考虑**: 可以使用工具类或在每个Service类中实现转换逻辑
+
+### 2.5 数据访问层
+- **职责**: 提供对数据库的访问操作
+- **核心组件**: Spring Data JPA Repository接口
+- **影响**: 基本不受修改影响，仍然操作实体类
+
+### 2.6 缓存层
+- **职责**: 存储VO对象，提高数据访问性能
+- **核心组件**: Redis缓存
+- **关键修改**: 确保只缓存VO对象，避免代理对象序列化问题
+
+## 3. 模块依赖关系图
+
+```mermaid
+flowchart TD
+    subgraph 接口定义
+        IEntityService[IEntityService<Model>
+        定义CRUD操作接口] --> VoableService[VoableService<M, Vo>
+        定义VO更新方法]
+        QueryService[QueryService<Vo>
+        定义查询操作接口]
+    end
+
+    subgraph 服务实现
+        ServiceImpl[Service实现类
+        实现IEntityService<Model>、QueryService<Vo>和VoableService]
+    end
+
+    subgraph WebSocket服务
+        WebSocketHandler[WebSocketServerHandler
+        处理WebSocket连接] --> WebSocketTaskManager[WebSocketServerTaskManager
+        管理WebSocket任务]
+        WebSocketTaskManager --> WebSocketCallbackManager[WebSocketServerCallbackManager
+        处理服务调用回调]
+    end
+
+    subgraph 数据访问
+        Repository[Repository接口
+        操作实体类]
+    end
+
+    subgraph 数据模型
+        Entity[实体类
+        持久化对象]
+        VO[VO类
+        视图对象]
+    end
+
+    subgraph 缓存
+        RedisCache[Redis缓存
+        存储VO对象]
+    end
+
+    IEntityService --> ServiceImpl
+    QueryService --> ServiceImpl
+    VoableService --> ServiceImpl
+    ServiceImpl --> Repository
+    Repository --> Entity
+    ServiceImpl --> Entity
+    ServiceImpl --> VO
+    ServiceImpl <-->|缓存VO对象| RedisCache
+    WebSocketHandler -->|注入| ServiceImpl
+    WebSocketTaskManager -->|注入| ServiceImpl
+    WebSocketCallbackManager -->|反射调用| IEntityService
+    WebSocketCallbackManager -->|类型转换| VO
+    
+    style RedisCache fill:#bbf,stroke:#333,stroke-width:2px
+    style WebSocketCallbackManager fill:#fbb,stroke:#333,stroke-width:2px
+```
+
+## 4. 接口契约定义
+
+### 4.1 IEntityService<Model>接口
+
+```java
+public interface IEntityService<Model> {
+    // 根据ID查询Model对象
+    Model findById(Integer id);
+    
+    // 根据查询规范和分页参数查询Model对象列表
+    Page<Model> findAll(Specification<Model> spec, Pageable pageable);
+    
+    // 根据搜索文本构建查询规范
+    Specification<Model> getSpecification(String searchText);
+    
+    // 搜索Model对象列表（默认方法）
+    default List<Model> search(String searchText) {
+        throw new UnsupportedOperationException();
+    }
+    
+    // 删除Model对象
+    void delete(Model entity);
+    
+    // 保存Model对象
+    Model save(Model entity);
+}
+
+### 4.2 QueryService<Vo>接口
+
+```java
+public interface QueryService<Vo> {
+    // 根据查询参数和分页条件获取Vo对象列表
+    Page<Vo> findAll(JsonNode paramsNode, Pageable pageable);
+    
+    // 计数方法
+    default long count(JsonNode paramsNode) {
+        return 0;
+    }
+}
+```
+
+### 4.2 Service实现类接口契约
+
+对于每个Service实现类，需要实现以下方法的契约转换：
+
+| 原方法签名 | 新方法签名 | 实现逻辑 |
+|---------|---------|---------|
+| `Entity findById(Integer id)` | `Vo findById(Integer id)` | 1. 调用repository.findById(id)
+2. 将查询到的实体对象转换为VO对象
+3. 返回VO对象 |
+| `Page<Entity> findAll(Specification<Entity> spec, Pageable pageable)` | `Page<Vo> findAll(Specification<Vo> spec, Pageable pageable)` | 1. 将VO的Specification转换为Entity的Specification
+2. 调用repository.findAll(spec, pageable)
+3. 将查询结果中的每个实体对象转换为VO对象
+4. 返回包含VO对象的Page |
+| `Specification<Entity> getSpecification(String searchText)` | `Specification<Vo> getSpecification(String searchText)` | 1. 构建基于Entity的Specification
+2. 封装或转换为基于Vo的Specification（可能需要特殊处理） |
+| `void delete(Entity entity)` | `void delete(Vo entity)` | 1. 将VO对象转换为实体对象
+2. 调用repository.delete(entity) |
+| `Entity save(Entity entity)` | `Vo save(Vo entity)` | 1. 将VO对象转换为实体对象
+2. 调用repository.save(entity)
+3. 将保存结果转换为VO对象
+4. 返回VO对象 |
+
+## 5. 数据流向图
+
+```mermaid
+flowchart TD
+    subgraph 服务请求处理流程
+        B[Controller接收请求
+        调用Service方法] --> C[Service方法处理
+        接收VO参数] --> D{检查Redis缓存
+        中是否存在VO对象}
+        D -->|存在| D1[直接返回缓存中的VO对象]
+        D -->|不存在| D2[VO转换为Entity
+        准备数据操作]
+        D2 --> E[调用Repository
+        执行数据操作] --> F[Repository操作数据库
+        返回Entity结果]
+        F --> G[Entity转换为VO
+        准备响应数据]
+        G --> H[将VO对象存入Redis缓存] --> I[Service返回VO
+        Controller组装响应]
+        D1 --> I
+    end
+
+    subgraph WebSocket请求处理流程
+        W1[WebSocket客户端请求
+        消息传递] --> W2[WebSocketServerHandler
+        接收消息] --> W3[WebSocketServerTaskManager
+        处理任务] --> W4[WebSocketServerCallbackManager
+        反射调用Service方法] --> W5{检查Redis缓存
+        中是否存在VO对象}
+        W5 -->|存在| W6[直接返回缓存中的VO对象]
+        W5 -->|不存在| W7[Service处理请求
+        进行数据转换] --> W8[Entity转换为VO
+        准备响应数据] --> W9[WebSocketServerCallbackManager
+        处理VO响应] --> W10[WebSocketServerHandler
+        发送响应消息] --> W11[WebSocket客户端接收
+        VO响应数据]
+        W6 --> W9
+    end
+
+    subgraph 数据转换流程
+        K[VO对象] -->|属性映射| L[Entity对象
+        用于数据持久化]
+        L -->|属性映射| K
+    end
+
+    C --> K
+    D2 --> K
+    F --> L
+    G --> K
+    W4 --> C
+    W7 --> G
+    W9 --> K
+    
+    style H fill:#bbf,stroke:#333,stroke-width:2px
+    style D fill:#bbf,stroke:#333,stroke-width:2px
+    style W5 fill:#fbb,stroke:#333,stroke-width:2px
+    style W9 fill:#fbb,stroke:#333,stroke-width:2px
+```
+
+## 6. 异常处理策略
+
+1. **转换异常处理**: 
+   - 在实体类和VO类之间进行转换时，捕获并处理可能的转换异常
+   - 提供清晰的错误信息，指明转换失败的原因
+
+2. **数据验证**: 
+   - 在接收VO对象时，进行数据验证，确保数据的有效性
+   - 对于无效数据，抛出适当的异常并提供错误信息
+
+3. **事务处理**: 
+   - 保持原有的事务边界，确保数据操作的原子性
+   - 在事务中包含完整的数据操作和转换过程
+
+4. **缓存异常**: 
+   - 处理可能的缓存操作异常，确保即使缓存失败也不会影响业务逻辑
+   - 考虑添加缓存回退机制
+   - 特别处理Redis连接问题和序列化问题，确保系统可用性
+
+5. **序列化异常**: 
+   - 处理VO对象序列化失败的情况
+   - 确保VO类实现Serializable接口，避免在VO类中包含不可序列化的引用
+
+6. **WebSocket服务异常处理**: 
+   - 处理WebSocketServerCallbackManager中反射调用IEntityService接口时可能出现的类型转换异常
+   - 特别关注createNewEntity、findEntityTypeInInterfaces等依赖泛型参数的方法
+   - 确保WebSocket服务在接口泛型修改后能够正常处理异常情况
+   - 在invokerFindByIdMethod、invokerFindAllMethod等方法中添加类型安全检查
+
+## 7. 设计原则
+
+1. **最小化修改原则**: 仅修改必要的代码，避免不必要的重构
+
+2. **向后兼容原则**: 尽量保持与原有系统的兼容性，特别是对依赖这些Service的组件，包括WebSocket服务
+
+3. **数据一致性原则**: 确保实体类和VO类之间的数据转换不会导致数据丢失或不一致
+
+4. **可测试性原则**: 设计支持单元测试和集成测试的代码结构，包括WebSocket服务的测试
+
+5. **性能优化原则**: 考虑数据转换可能带来的性能影响，必要时进行优化
+
+6. **代码复用原则**: 尽量复用现有的代码和模式，特别是数据转换相关的代码
+
+7. **序列化安全原则**: 确保所有缓存的VO对象都是可序列化的，避免在VO对象中包含循环引用和不可序列化的组件
+
+8. **类型安全原则**: 在WebSocketServerCallbackManager中添加类型安全检查，确保能够正确处理从实体类到VO类的泛型变化
+
+9. **服务兼容性原则**: 确保修改后的IEntityService接口能够与WebSocket服务和其他现有服务组件兼容
+
+通过以上设计，我们可以系统地完成IEntityService接口泛型的修改任务，确保修改后的系统能够正确、高效地运行。