# Requirements - updateObjectDataToTarget 更新数据进度跟踪

## 需求信息

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

## 输入引用

引用相关的 docs 文档链接：

- [REQ-002.md](REQ-002.md) - syncObjectData 同步进度跟踪（参考实现）
- [REQ-003.md](REQ-003.md) - insertObjectDataToTarget 插入数据进度跟踪（参考实现）
- [0002-sync-progress-tracking.md](../decisions/adr/0002-sync-progress-tracking.md) - syncObjectData 同步进度跟踪架构决策（参考实现）
- [0003-insert-progress-tracking.md](../decisions/adr/0003-insert-progress-tracking.md) - insertObjectDataToTarget 插入数据进度跟踪架构决策（参考实现）

## Context Maps

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

- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
- **相关节点**: DataiIntegrationObjectController、DataiIntegrationObjectServiceImpl、DataiIntegrationBatchController、DataiIntegrationBatchServiceImpl

## 需求目标

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

## 需求描述

### 概述

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

### 详细需求

#### 1. 更新进度跟踪

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

#### 2. 进度查询接口

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

#### 3. 进度信息存储

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

## 约束

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

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

## Rule Set

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

**具体规则**：
- 必须使用 Canvas 中定义的类名和方法名
- 必须遵循 Canvas 中定义的调用关系
- 必须参考 Canvas 中的流程图逻辑
- 必须参考 REQ-002.md 和 REQ-003.md 的实现方式，保持与 syncObjectData 同步进度跟踪功能和 insertObjectDataToTarget 插入数据进度跟踪功能的一致性

## 验收标准

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

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

## 风险

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

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

## 需求变更记录

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

## 相关人员

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

## 评审信息

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