223 lines
10 KiB
Markdown
223 lines
10 KiB
Markdown
# 会话记录 - 元数据拉取核心功能
|
||
|
||
## 现状
|
||
|
||
REQ-010-6 需要实现 Salesforce 元数据拉取的核心功能，包括手动触发拉取、异步拉取执行、状态监控、拉取历史记录、拉取进度查询、拉取取消功能等。
|
||
|
||
目前已经完成了需求定义、架构决策和提示词资产化阶段，现在需要开始执行会话和代码生成阶段。
|
||
|
||
## 目标
|
||
|
||
实现 Salesforce 元数据拉取的核心功能，包括：
|
||
1. 手动触发拉取功能 - 使用 MetadataApiClient 调用 retrieve() 方法，使用异步线程池执行拉取任务，使用 RESTful API 设计接口
|
||
2. 异步拉取执行 - 使用 Spring 的 @Async 注解实现异步执行，使用 ThreadPoolTaskExecutor 配置线程池，使用 CompletableFuture 支持异步结果
|
||
3. 状态监控 - 使用状态机管理拉取状态，使用轮询机制检查拉取状态，使用枚举类定义拉取状态
|
||
4. 拉取历史记录 - 使用 MyBatis Plus 的 BaseMapper 实现历史记录查询，使用分页插件实现分页查询，使用条件查询支持多条件查询
|
||
5. 拉取进度查询 - 使用轮询机制获取进度，使用缓存提高查询性能，使用百分比显示进度
|
||
6. 拉取取消功能 - 使用 Future.cancel() 取消异步任务，使用状态机管理取消状态，使用异常处理机制处理取消异常
|
||
|
||
## 输入链接
|
||
|
||
- [REQ-010-6.md](../requirements/REQ-010-6.md) - 元数据拉取核心功能需求文档
|
||
- [REQ-010-1.md](../requirements/REQ-010-1.md) - 数据库表结构设计和创建
|
||
- [REQ-010-2.md](../requirements/REQ-010-2.md) - 基础实体类和Mapper创建
|
||
- [REQ-010-3.md](../requirements/REQ-010-3.md) - Salesforce组织配置管理
|
||
- [REQ-010-4.md](../requirements/REQ-010-4.md) - 元数据任务定义管理
|
||
- [REQ-010-5.md](../requirements/REQ-010-5.md) - Metadata API客户端封装
|
||
- [0015-metadata-retrieve-core.md](../decisions/adr/0015-metadata-retrieve-core.md) - 元数据拉取核心功能架构决策
|
||
|
||
## Prompt 文件
|
||
|
||
- [006-metadata-retrieve-core.md](../prompts/006-metadata-retrieve-core.md) - 元数据拉取核心功能实现提示词
|
||
|
||
## Context Snapshot
|
||
|
||
记录本次会话参考了哪些 Canvas 节点：
|
||
|
||
- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
|
||
- **参考节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
- **参考节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
|
||
- **快照时间**: 2026-01-19 00:00:00
|
||
|
||
## 执行过程
|
||
|
||
详细记录本次会话的执行过程，包括：
|
||
|
||
1. **创建 JobExecutionStatus 枚举类**
|
||
- 创建 JobExecutionStatus 枚举类，定义拉取状态（Pending/Processing/Success/Failed/Partial_Success/Cancelled）
|
||
- 使用 @EnumValue 注解映射数据库值
|
||
- 使用 @JsonValue 注解序列化为 JSON
|
||
- 提供 fromCode() 方法从代码转换为枚举
|
||
|
||
2. **创建 MetadataRetrieveController 控制器**
|
||
- 创建 MetadataRetrieveController 控制器，提供 4 个 RESTful API 接口
|
||
- 提供 POST /api/metadata/retrieve 接口，手动触发拉取
|
||
- 提供 GET /api/metadata/retrieve/history 接口，查询拉取历史记录
|
||
- 提供 GET /api/metadata/retrieve/progress/{jobId} 接口，查询拉取进度
|
||
- 提供 POST /api/metadata/retrieve/cancel/{jobId} 接口，取消拉取
|
||
- 使用 @Validated 注解进行参数验证
|
||
- 使用 Slf4j 记录日志
|
||
|
||
3. **创建 RetrieveRequest DTO**
|
||
- 创建 RetrieveRequest DTO，定义拉取请求参数
|
||
- 包含 taskId 和 orgConfigId 字段
|
||
- 使用 @NotNull 注解进行参数验证
|
||
|
||
4. **创建 RetrieveResponse DTO**
|
||
- 创建 RetrieveResponse DTO，定义拉取响应参数
|
||
- 包含 jobId 和 message 字段
|
||
|
||
5. **创建 RetrieveProgressResponse DTO**
|
||
- 创建 RetrieveProgressResponse DTO，定义拉取进度响应参数
|
||
- 包含 jobId、status、progress、message 字段
|
||
|
||
6. **创建 IMetadataRetrieveService 服务接口**
|
||
- 创建 IMetadataRetrieveService 服务接口，定义元数据拉取服务接口
|
||
- 定义 triggerRetrieve() 方法，手动触发拉取
|
||
- 定义 getRetrieveHistory() 方法，查询拉取历史记录
|
||
- 定义 getRetrieveProgress() 方法，查询拉取进度
|
||
- 定义 cancelRetrieve() 方法，取消拉取
|
||
|
||
7. **创建 MetadataRetrieveServiceImpl 服务实现**
|
||
- 创建 MetadataRetrieveServiceImpl 服务实现，实现元数据拉取服务
|
||
- 实现 triggerRetrieve() 方法，创建作业执行记录，调用异步方法执行拉取
|
||
- 实现 executeRetrieveAsync() 方法，使用 @Async 注解实现异步执行，使用 MetadataApiClient 调用 retrieve() 方法
|
||
- 实现 getRetrieveHistory() 方法，使用 MyBatis Plus 的 QueryWrapper 实现条件查询，使用分页插件实现分页查询
|
||
- 实现 getRetrieveProgress() 方法，查询作业执行记录，计算进度百分比
|
||
- 实现 cancelRetrieve() 方法，使用 Future.cancel() 取消异步任务
|
||
- 使用 ConcurrentHashMap 存储正在运行的作业
|
||
- 使用 updateJobStatus() 方法更新作业状态
|
||
- 使用 calculateProgress() 方法计算进度百分比
|
||
|
||
8. **创建 RetrieveException 异常类**
|
||
- 创建 RetrieveException 异常类，封装拉取异常
|
||
- 提供两个构造方法，支持消息和原因
|
||
|
||
9. **创建单元测试**
|
||
- 创建 MetadataRetrieveServiceImplTest 单元测试
|
||
- 测试 triggerRetrieve() 方法
|
||
- 测试 getRetrieveHistory() 方法
|
||
- 测试 getRetrieveProgress() 方法
|
||
- 测试 cancelRetrieve() 方法
|
||
- 使用 Mockito 模拟依赖
|
||
|
||
## 关键产出
|
||
|
||
记录本次会话的关键产出，例如：
|
||
|
||
- 生成的代码文件：
|
||
- JobExecutionStatus 枚举类
|
||
- MetadataRetrieveController 控制器
|
||
- RetrieveRequest DTO
|
||
- RetrieveResponse DTO
|
||
- RetrieveProgressResponse DTO
|
||
- IMetadataRetrieveService 服务接口
|
||
- MetadataRetrieveServiceImpl 服务实现
|
||
- RetrieveException 异常类
|
||
- MetadataRetrieveServiceImplTest 单元测试
|
||
|
||
- 更新的文档：
|
||
- 无
|
||
|
||
- 解决的问题：
|
||
- 实现了手动触发拉取功能
|
||
- 实现了异步拉取执行
|
||
- 实现了状态监控
|
||
- 实现了拉取历史记录
|
||
- 实现了拉取进度查询
|
||
- 实现了拉取取消功能
|
||
|
||
- 达成的共识：
|
||
- 使用 MetadataApiClient 调用 retrieve() 方法
|
||
- 使用 Spring 的 @Async 注解实现异步执行
|
||
- 使用 ThreadPoolTaskExecutor 配置线程池
|
||
- 使用状态机管理拉取状态
|
||
- 使用 MyBatis Plus 的 BaseMapper 实现历史记录查询
|
||
- 使用轮询机制获取进度
|
||
- 使用 Future.cancel() 取消异步任务
|
||
|
||
## 质疑与替代方案
|
||
|
||
记录在执行过程中提出的质疑和考虑的替代方案：
|
||
|
||
- 质疑：是否需要使用消息队列实现手动触发拉取？
|
||
- 替代方案：使用消息队列实现手动触发拉取
|
||
- 评估：消息队列可以解耦任务提交和任务执行，支持任务持久化和重试，但消息队列增加了系统复杂度，需要引入额外的依赖。异步线程池可以满足业务需求，不需要引入额外的依赖。
|
||
|
||
- 质疑：是否需要使用消息队列实现异步拉取执行？
|
||
- 替代方案：使用消息队列实现异步拉取执行
|
||
- 评估：消息队列可以解耦任务提交和任务执行，支持任务持久化和重试，但消息队列增加了系统复杂度，需要引入额外的依赖。Spring 的 @Async 注解可以简化异步编程，提高开发效率，满足业务需求。
|
||
|
||
- 质疑：是否需要使用回调机制实现状态监控？
|
||
- 替代方案：使用回调机制实现状态监控
|
||
- 评估：Salesforce Metadata API 不支持回调机制，需要使用 Webhook，增加系统复杂度。轮询机制可以定期检查任务状态，及时获取任务进度，满足业务需求。
|
||
|
||
- 质疑：是否需要使用缓存实现拉取历史记录？
|
||
- 替代方案：使用缓存实现拉取历史记录
|
||
- 评估：缓存可以提高查询性能，减少数据库查询，但缓存可能导致数据不一致，缓存容量有限。MyBatis Plus 的 BaseMapper 可以提供基础的 CRUD 方法，简化开发，满足业务需求。
|
||
|
||
- 质疑：是否需要使用数据库查询实现拉取进度查询？
|
||
- 替代方案：使用数据库查询实现拉取进度查询
|
||
- 评估：数据库查询可以实时获取进度，实现简单，但数据库查询性能差，可能影响系统性能。轮询机制可以及时获取进度，支持实时进度查询，满足业务需求。
|
||
|
||
- 质疑：是否需要使用标志位实现拉取取消？
|
||
- 替代方案：使用标志位实现拉取取消
|
||
- 评估：标志位实现简单，不需要额外的依赖，但标志位不能真正取消任务，资源可能无法释放。Future.cancel() 可以取消异步任务，释放资源，满足业务需求。
|
||
|
||
## 结论
|
||
|
||
总结本次会话的结果，包括：
|
||
|
||
- 完成的工作：
|
||
- 创建了 JobExecutionStatus 枚举类
|
||
- 创建了 MetadataRetrieveController 控制器
|
||
- 创建了 RetrieveRequest DTO
|
||
- 创建了 RetrieveResponse DTO
|
||
- 创建了 RetrieveProgressResponse DTO
|
||
- 创建了 IMetadataRetrieveService 服务接口
|
||
- 创建了 MetadataRetrieveServiceImpl 服务实现
|
||
- 创建了 RetrieveException 异常类
|
||
- 创建了 MetadataRetrieveServiceImplTest 单元测试
|
||
|
||
- 达成的目标：
|
||
- 实现了手动触发拉取功能
|
||
- 实现了异步拉取执行
|
||
- 实现了状态监控
|
||
- 实现了拉取历史记录
|
||
- 实现了拉取进度查询
|
||
- 实现了拉取取消功能
|
||
|
||
- 后续的行动计划：
|
||
- 进行集成测试，确保功能正常
|
||
- 进行性能测试，确保性能满足要求
|
||
- 进行安全测试，确保安全性满足要求
|
||
- 编写用户文档，说明如何使用元数据拉取功能
|
||
|
||
- 需要跟进的事项：
|
||
- 监控异步线程池的使用情况
|
||
- 监控状态轮询的频率
|
||
- 监控拉取任务的执行情况
|
||
- 监控 Redis 缓存的使用情况
|
||
|
||
## Design Update
|
||
|
||
- [x] 是否需要更新 Canvas?
|
||
- [ ] Authentication.canvas
|
||
- [ ] 其他 Canvas 文件: ____________________
|
||
|
||
## 复现步骤
|
||
|
||
提供复现本次会话结果的具体步骤：
|
||
|
||
1. 创建 JobExecutionStatus 枚举类
|
||
2. 创建 MetadataRetrieveController 控制器
|
||
3. 创建 RetrieveRequest DTO
|
||
4. 创建 RetrieveResponse DTO
|
||
5. 创建 RetrieveProgressResponse DTO
|
||
6. 创建 IMetadataRetrieveService 服务接口
|
||
7. 创建 MetadataRetrieveServiceImpl 服务实现
|
||
8. 创建 RetrieveException 异常类
|
||
9. 创建 MetadataRetrieveServiceImplTest 单元测试
|
||
10. 运行单元测试，确保所有测试通过
|
||
11. 进行集成测试，确保功能正常
|