kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3d290a8dd1
datai/docs/archive/REQ-003.md

5.9 KiB
Raw Blame History

Requirements - insertObjectDataToTarget 插入数据进度跟踪

需求信息

  • 需求名称: insertObjectDataToTarget 插入数据进度跟踪
  • 需求类型: 功能需求
  • 需求编号: REQ-003
  • 创建日期: 2026-01-16
  • 需求版本: v1.0.0
  • 需求提出人: 用户
  • 需求状态: 已批准

输入引用

引用相关的 docs 文档链接：

Context Maps

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

  • Authentication.canvas - 项目架构视觉化展示
  • 相关节点: DataiIntegrationObjectController、DataiIntegrationObjectServiceImpl、DataiIntegrationBatchController、DataiIntegrationBatchServiceImpl

需求目标

在 insertObjectDataToTarget 过程中，提供实时的插入数据进度跟踪能力，让用户能够了解当前插入任务的执行进度，包括已处理的批次数量、当前批次、进度百分比等信息。

需求描述

概述

insertObjectDataToTarget 方法用于将本地数据库中的指定对象数据插入到目标 Salesforce 系统。该方法会查询本地表中该对象的所有批次数据，然后通过 SOAP API 插入到目标系统。由于可能涉及多个批次，插入操作可能需要较长时间，因此需要提供进度跟踪能力。

详细需求

1. 插入进度跟踪

  • 需求描述: 在 insertObjectDataToTarget 执行过程中，实时跟踪插入进度，包括总批次数量、已处理批次数量、当前批次、进度百分比、开始时间、结束时间、状态、错误信息
  • 优先级: 高
  • 验收标准:
    • 能够在 insertObjectDataToTarget 开始时初始化进度信息
    • 能够在每个批次插入完成后更新进度信息
    • 能够在所有批次插入完成后标记进度为已完成
    • 能够在插入失败时标记进度为失败，并记录错误信息
  • 依赖关系: 无
  • 实现建议: 参考 REQ-002.md 的实现方式，使用内存存储方案（ConcurrentHashMap）存储进度信息

2. 进度查询接口

  • 需求描述: 提供 REST API 接口，用于查询指定对象的插入进度信息
  • 优先级: 高
  • 验收标准:
    • 提供 GET /integration/object/insertProgress/{id} 接口，查询指定对象的插入进度
    • 提供 GET /integration/object/insertProgress 接口，查询所有正在插入的对象进度
    • 返回的进度信息包括：对象ID、目标ORG类型、总批次数量、已处理批次数量、当前批次、进度百分比、开始时间、结束时间、状态、错误信息
  • 依赖关系: 依赖需求 1（插入进度跟踪）
  • 实现建议: 参考 REQ-002.md 的实现方式，在 DataiIntegrationObjectController 中添加进度查询接口

3. 进度信息存储

  • 需求描述: 将插入进度信息存储在内存中，插入任务完成后立即清除进度信息，不保留历史记录
  • 优先级: 高
  • 验收标准:
    • 使用 ConcurrentHashMap 存储进度信息，支持并发访问
    • 插入任务完成后立即清除进度信息
    • 插入任务失败时立即清除进度信息
    • 系统重启后进度信息丢失
  • 依赖关系: 依赖需求 1（插入进度跟踪）
  • 实现建议: 参考 REQ-002.md 的实现方式，使用 SyncProgress 实体类和 SyncProgressService 服务类

约束

列出需求实现时的约束条件，例如：

  • 技术栈限制: 使用 Spring Boot、MyBatis、Lombok
  • 性能要求: 进度更新操作对插入性能影响 < 5%
  • 安全性要求: 进度查询接口需要登录认证和权限控制
  • 兼容性要求: 与现有的 syncObjectData 同步进度跟踪功能保持一致
  • 时间限制: 无
  • 预算限制: 无
  • 其他约束: 不将插入进度数据同步到数据库，只存储在内存中

Rule Set

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

具体规则：

  • 必须使用 Canvas 中定义的类名和方法名
  • 必须遵循 Canvas 中定义的调用关系
  • 必须参考 Canvas 中的流程图逻辑
  • 必须参考 REQ-002.md 的实现方式，保持与 syncObjectData 同步进度跟踪功能的一致性

验收标准

定义验证需求是否满足的具体标准，例如：

  • 功能完整性: 能够正确跟踪插入进度，提供进度查询接口
  • 性能指标: 进度更新操作对插入性能影响 < 5%
  • 安全性要求: 进度查询接口需要登录认证和权限控制
  • 用户体验: 进度信息准确、实时，查询接口响应时间 < 100ms
  • 其他验收标准: 与 syncObjectData 同步进度跟踪功能保持一致的实现方式

风险

识别需求可能带来的风险，例如：

  • 技术实现风险: 进度更新频率可能影响插入性能，需要优化进度更新策略
  • 时间风险: 无
  • 成本风险: 无
  • 质量风险: 进度信息可能不准确，需要确保进度更新的准确性
  • 其他潜在风险: 内存泄漏风险，需要确保进度信息能够及时清除

需求变更记录

日期 变更内容 变更原因 变更人 审核人 状态
2026-01-16 初始版本创建 用户提出 insertObjectDataToTarget 插入数据进度跟踪需求 用户 AI 已批准

相关人员

  • 需求提出人: 用户 - 联系方式: 无
  • 需求负责人: AI - 联系方式: 无
  • 技术负责人: AI - 联系方式: 无
  • 测试负责人: 用户 - 联系方式: 无
  • 其他相关人员: 无

评审信息

  • 评审日期: 2026-01-16
  • 评审人员: AI
  • 评审结果: 通过
  • 评审意见: 需求清晰明确，参考 REQ-002.md 的实现方式，可以开始实施
  • 修改建议: 无