kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
21c82a4b36
datai/datai-scenes/datai-scene-salesforce/docs/api-docs/integration/DataiIntegrationObjectController/0014-query-update-progress.md
Kris 85f71e1dc3 feat: 实现数据同步进度跟踪功能 
- 新增 SyncProgress 实体类、ISyncProgressService 接口和 SyncProgressServiceImpl 实现类
- 在 DataiIntegrationObjectController 中添加 6 个进度查询接口：
  - 查询指定对象的同步进度
  - 查询所有正在同步的对象进度
  - 查询指定对象的插入进度
  - 查询所有正在插入的对象进度
  - 查询指定对象的更新进度
  - 查询所有正在更新的对象进度
- 在 DataiIntegrationObjectServiceImpl 中集成进度跟踪功能：
  - syncFullData 方法集成同步进度跟踪
  - syncIncrementalData 方法集成同步进度跟踪
  - insertObjectDataToTarget 方法集成插入进度跟踪
  - updateObjectDataToTarget 方法集成更新进度跟踪
- 进度信息存储在内存中（ConcurrentHashMap），任务完成后立即清除
- 新增 3 个需求文档（REQ-002、REQ-003、REQ-004）
- 新增 3 个架构决策记录（0002、0003、0004）
- 新增 3 个提示词文件（002、003、004）
- 新增 3 个会话记录
- 新增 3 个变更记录（0012、0013、0014）
- 新增 3 个复盘报告
- 新增 6 个 API 文档
- 更新 CHANGELOG.md 和 docs/index.md
2026-01-16 13:02:09 +08:00

3.8 KiB
Raw Blame History

查询指定对象的更新进度

接口信息

  • 接口名称: 查询指定对象的更新进度
  • 接口路径: /integration/object/updateProgress/{id}
  • 请求方法: GET
  • 接口描述: 该方法用于查询指定对象的更新进度信息。进度信息包括：对象ID、更新类型、总批次数量、已处理批次数量、当前批次、进度百分比、开始时间、结束时间、状态、错误信息。如果更新任务已完成或失败，进度信息会被清除，此时无法查询到进度信息。

请求参数

路径参数

参数名 类型 必填 说明
id Integer 是 对象ID，用于标识需要查询更新进度的对象

请求示例

GET /integration/object/updateProgress/123

响应参数

响应格式

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "objectId": 123,
    "syncType": "UPDATE",
    "totalBatches": 10,
    "processedBatches": 5,
    "currentBatch": 5,
    "progressPercentage": 50,
    "startTime": "2026-01-16 10:00:00",
    "endTime": null,
    "status": "RUNNING",
    "errorMessage": null
  }
}

响应字段说明

字段名 类型 说明
code Integer 响应状态码，200表示成功，其他表示失败
msg String 响应消息，成功时返回"操作成功"，失败时返回错误信息
data Object 响应数据，包含更新进度信息
data.objectId Integer 对象ID
data.syncType String 更新类型（UPDATE）
data.totalBatches Integer 总批次数量
data.processedBatches Integer 已处理批次数量
data.currentBatch Integer 当前批次
data.progressPercentage Integer 进度百分比（0-100）
data.startTime String 开始时间，格式：yyyy-MM-dd HH:mm:ss
data.endTime String 结束时间，格式：yyyy-MM-dd HH:mm:ss，更新进行中时为null
data.status String 状态（RUNNING/COMPLETED/FAILED）
data.errorMessage String 错误信息，更新成功时为null

响应示例（失败）

{
  "code": 500,
  "msg": "未找到更新进度信息",
  "data": null
}

权限要求

  • 权限标识: integration:object:progress
  • 说明: 需要登录认证，且用户需要具有查询对象更新进度的权限

业务规则

  1. 如果对象ID为空，返回错误信息"对象ID不能为空"
  2. 如果未找到更新进度信息（更新任务已完成或失败），返回错误信息"未找到更新进度信息"
  3. 进度信息存储在内存中，系统重启后进度信息丢失
  4. 更新任务完成后立即清除进度信息，不保留历史记录

异常处理

异常场景 响应码 响应消息
对象ID为空 500 对象ID不能为空
未找到更新进度信息 500 未找到更新进度信息
查询进度时发生异常 500 查询对象更新进度时发生异常: [异常信息]

使用场景

  1. 用户触发对象更新后，通过该接口查询更新进度
  2. 前端页面定时轮询该接口，实时显示更新进度
  3. 管理员监控多个对象的更新进度

注意事项

  1. 进度信息仅在更新进行中存在，更新完成后会被清除
  2. 如果查询到进度信息，说明更新正在进行中
  3. 如果未查询到进度信息，说明更新已完成或失败，或者从未触发过更新
  4. 进度百分比计算公式：progressPercentage = (processedBatches / totalBatches) * 100

相关接口