datai/docs/archive/prompts/002-sync-progress-tracking.md

syncObjectData 同步进度跟踪实现提示词

输入引用

引用相关的 docs 文档链接：

• REQ-002.md - syncObjectData 同步进度跟踪需求文档
• 0002-sync-progress-tracking.md - syncObjectData 同步进度跟踪架构决策
• DataiIntegrationObjectController - 对象同步控制接口
• DataiIntegrationObjectServiceImpl - 对象同步服务实现

Context Maps

强制列出本次 Prompt 依赖的 Canvas 文件：

• Authentication.canvas - 项目架构视觉化展示
• 相关节点: DataiIntegrationObjectController - 对象同步控制接口
• 相关节点: DataiIntegrationObjectServiceImpl - 对象同步服务实现

目标

实现 syncObjectData 同步进度跟踪功能，包括：

1. 创建进度信息数据结构（SyncProgress 实体类）
2. 创建进度跟踪服务接口和实现类
3. 在 Controller 中添加进度查询接口
4. 在 Service 中集成进度跟踪功能
5. 同步任务完成后立即清除该同步进度信息，不保留历史记录

输出格式

输出以下 Java 代码文件：

1. SyncProgress.java - 进度信息实体类

   • 路径：datai-salesforce-integration/src/main/java/com/datai/integration/model/domain/SyncProgress.java
   • 包含字段：objectId、syncType、totalBatches、processedBatches、currentBatch、progressPercentage、startTime、endTime、status、errorMessage
   • 使用 Lombok 注解（@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor）

2. ISyncProgressService.java - 进度跟踪服务接口

   • 路径：datai-salesforce-integration/src/main/java/com/datai/integration/service/ISyncProgressService.java
   • 包含方法：
     • startProgressTracking(Integer objectId, Integer totalBatches, String syncType)
     • updateProgress(Integer objectId, Integer processedBatches, Integer currentBatch)
     • completeProgress(Integer objectId) - 完成进度跟踪并立即清除该同步进度信息
     • failProgress(Integer objectId, String errorMessage) - 标记进度失败并立即清除该同步进度信息
     • getProgress(Integer objectId)
     • getAllProgress()

3. SyncProgressServiceImpl.java - 进度跟踪服务实现类

   • 路径：datai-salesforce-integration/src/main/java/com/datai/integration/service/impl/SyncProgressServiceImpl.java
   • 使用 ConcurrentHashMap 存储进度信息
   • 实现所有接口方法
   • completeProgress 和 failProgress 方法在完成后立即清除该同步进度信息
   • 使用 @Service 注解
   • 添加日志记录

4. DataiIntegrationObjectController.java - 添加进度查询接口

   • 在现有 Controller 中添加以下接口：
     • GET /integration/object/progress/{objectId} - 查询指定对象的同步进度
     • GET /integration/object/progress - 查询所有正在同步的对象进度
   • 使用 @RestController 和 @RequestMapping 注解
   • 返回统一响应格式（AjaxResult）

5. DataiIntegrationObjectServiceImpl.java - 集成进度跟踪

   • 注入 ISyncProgressService
   • 在 syncObjectData 方法开始时调用 startProgressTracking
   • 在同步过程中调用 updateProgress 更新进度
   • 在同步完成时调用 completeProgress（该方法会立即清除进度信息）
   • 在同步失败时调用 failProgress（该方法会立即清除进度信息）

约束

列出使用此提示词时的约束条件，例如：

1. 技术栈限制：

   • 使用 Spring Boot 框架
   • 使用 Lombok 简化代码
   • 使用 SLF4J 进行日志记录
   • 使用 ConcurrentHashMap 作为进度存储容器

2. 性能要求：

   • 进度查询接口响应时间 < 100ms
   • 进度更新操作对同步性能影响 < 5%
   • 支持 10 个对象同时同步并跟踪进度

3. 安全性要求：

   • 进度查询接口需要登录认证
   • 避免内存泄漏，确保过期数据被正确清理

4. 兼容性要求：

   • 不影响现有的同步逻辑
   • 与现有的 ADR-0001（Salesforce CDC 同步方案）不冲突
   • 保持代码风格一致性

Rule Set

"请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。"

具体规则：

• 必须使用 Canvas 中定义的类名和方法名
• 必须遵循 Canvas 中定义的调用关系
• 必须参考 Canvas 中的流程图逻辑
• 必须遵循项目现有的代码风格和命名规范
• 必须使用项目现有的工具类和依赖（如 AjaxResult、SecurityUtils 等）

验收标准

定义验证输出质量的具体标准，例如：

1. 功能完整性：

   • 所有接口方法正确实现
   • 进度信息能够正确初始化、更新、完成和失败
   • 进度查询接口能够返回准确的进度信息

2. 代码正确性：

   • 代码编译通过，无语法错误
   • 遵循 Java 编码规范
   • 使用正确的注解和依赖注入

3. 性能指标：

   • 进度查询接口响应时间 < 100ms
   • 进度更新操作轻量级，对同步性能影响 < 5%

4. 文档准确性：

   • 代码注释清晰，说明关键逻辑
   • 方法命名准确，符合业务含义

风险

识别使用此提示词可能带来的风险，例如：

1. 输出质量风险：

   • 生成的代码可能存在 bug
   • 代码风格可能与现有代码不一致

2. 技术实现风险：

   • 修改现有的 syncObjectData 方法可能引入 bug
   • 进度跟踪逻辑与同步逻辑耦合，可能影响代码可维护性

3. 时间成本风险：

   • 实现和测试工作量可能超出预期

使用记录

日期	使用场景	输入参数	输出结果	反馈	改进措施
2026-01-16	实现 syncObjectData 同步进度跟踪功能	REQ-002、ADR-0002	生成 6 个 Java 文件	待验证	待定