122 lines
4.7 KiB
Markdown
122 lines
4.7 KiB
Markdown
|
# syncObjectData 同步进度跟踪需求
|
|||
|
|
|
|||
|
|
## 需求信息
|
|||
|
|
|
|||
|
|
- **需求名称**: syncObjectData 同步进度跟踪
|
|||
|
|
- **需求类型**: 功能需求
|
|||
|
|
- **需求编号**: REQ-002
|
|||
|
|
- **创建日期**: 2026-01-16
|
|||
|
|
- **需求版本**: v1.0.0
|
|||
|
|
- **需求提出人**: 用户
|
|||
|
|
- **需求状态**: ✅ 已批准
|
|||
|
|
|
|||
|
|
## 输入引用
|
|||
|
|
|
|||
|
|
引用相关的 docs 文档链接：
|
|||
|
|
|
|||
|
|
- [0001-salesforce-realtime-sync.md](0001-salesforce-realtime-sync.md) - Salesforce数据及时同步至本地数据库
|
|||
|
|
- [0002-sync-progress-tracking.md](../decisions/adr/0002-sync-progress-tracking.md) - syncObjectData 同步进度跟踪架构决策
|
|||
|
|
- [002-sync-progress-tracking.md](../prompts/002-sync-progress-tracking.md) - syncObjectData 同步进度跟踪实现提示词
|
|||
|
|
- [DataiIntegrationObjectController](../../datai-salesforce-integration/src/main/java/com/datai/integration/controller/DataiIntegrationObjectController.java) - 对象同步控制接口
|
|||
|
|
- [DataiIntegrationObjectServiceImpl](../../datai-salesforce-integration/src/main/java/com/datai/integration/service/impl/DataiIntegrationObjectServiceImpl.java) - 对象同步服务实现
|
|||
|
|
|
|||
|
|
## Context Maps
|
|||
|
|
|
|||
|
|
强制列出本次需求依赖的 Canvas 文件：
|
|||
|
|
|
|||
|
|
- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
|
|||
|
|
- **相关节点**: DataiIntegrationObjectController - 对象同步控制接口
|
|||
|
|
|
|||
|
|
## 需求目标
|
|||
|
|
|
|||
|
|
在 syncObjectData 方法执行过程中，提供实时的同步进度跟踪功能，让用户能够了解当前同步任务的实际进度、已处理的数据量、剩余数据量等信息，提升用户体验和系统透明度。
|
|||
|
|
|
|||
|
|
## 需求描述
|
|||
|
|
|
|||
|
|
### 概述
|
|||
|
|
|
|||
|
|
当前 syncObjectData 方法在执行同步操作时，用户无法获知同步的实际进度，只能等待同步完成。本需求旨在实现同步进度的实时跟踪和查询功能。
|
|||
|
|
|
|||
|
|
### 详细需求
|
|||
|
|
|
|||
|
|
#### 1. 进度跟踪机制
|
|||
|
|
|
|||
|
|
- **需求描述**: 在 syncObjectData 方法执行过程中，实时记录和更新同步进度信息
|
|||
|
|
- **优先级**: 高
|
|||
|
|
- **验收标准**:
|
|||
|
|
- 同步开始时，初始化进度跟踪记录
|
|||
|
|
- 同步过程中，实时更新已处理的数据量
|
|||
|
|
- 同步完成时，标记进度为完成状态并立即清除该同步进度信息
|
|||
|
|
- 同步失败时，标记进度为失败状态并立即清除该同步进度信息
|
|||
|
|
- **依赖关系**: 无
|
|||
|
|
- **实现建议**: 使用内存缓存（如 ConcurrentHashMap）存储进度信息，key 为对象 ID，value 为进度对象
|
|||
|
|
|
|||
|
|
#### 2. 进度查询接口
|
|||
|
|
|
|||
|
|
- **需求描述**: 提供查询接口，让用户能够获取当前同步任务的进度信息
|
|||
|
|
- **优先级**: 高
|
|||
|
|
- **验收标准**:
|
|||
|
|
- 提供 REST API 接口查询同步进度
|
|||
|
|
- 返回进度百分比、已处理数量、总数量、当前状态等信息
|
|||
|
|
- 支持按对象 ID 查询进度
|
|||
|
|
- **依赖关系**: 依赖需求 1（进度跟踪机制）
|
|||
|
|
- **实现建议**: 在 DataiIntegrationObjectController 中添加进度查询接口
|
|||
|
|
|
|||
|
|
#### 3. 进度信息存储
|
|||
|
|
|
|||
|
|
## 约束
|
|||
|
|
|
|||
|
|
列出需求实现时的约束条件，例如：
|
|||
|
|
- 进度信息存储在内存中，系统重启后进度信息丢失
|
|||
|
|
- 同步任务完成后立即清除该同步进度信息，不保留历史记录
|
|||
|
|
- 进度查询接口需要考虑并发访问的性能
|
|||
|
|
- 进度跟踪不应影响同步操作的性能
|
|||
|
|
- 进度信息的更新频率需要合理控制
|
|||
|
|
|
|||
|
|
## Rule Set
|
|||
|
|
|
|||
|
|
"请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。"
|
|||
|
|
|
|||
|
|
**具体规则**：
|
|||
|
|
- 必须使用 Canvas 中定义的类名和方法名
|
|||
|
|
- 必须遵循 Canvas 中定义的调用关系
|
|||
|
|
- 必须参考 Canvas 中的流程图逻辑
|
|||
|
|
|
|||
|
|
## 验收标准
|
|||
|
|
|
|||
|
|
定义验证需求是否满足的具体标准，例如：
|
|||
|
|
- 功能完整性：能够正确跟踪和查询同步进度
|
|||
|
|
- 性能指标：进度查询接口响应时间 < 100ms
|
|||
|
|
- 并发支持：支持至少 10 个对象同时同步并跟踪进度
|
|||
|
|
- 用户体验：进度信息准确、实时、易理解
|
|||
|
|
|
|||
|
|
## 风险
|
|||
|
|
|
|||
|
|
识别需求可能带来的风险，例如：
|
|||
|
|
- 技术实现风险：内存存储可能导致系统重启后进度丢失
|
|||
|
|
- 时间风险：实现进度跟踪可能需要修改现有的同步逻辑
|
|||
|
|
- 性能风险：频繁的进度更新可能影响同步性能
|
|||
|
|
- 质量风险：并发同步时可能出现进度信息不一致
|
|||
|
|
|
|||
|
|
## 需求变更记录
|
|||
|
|
|
|||
|
|
| 日期 | 变更内容 | 变更原因 | 变更人 | 审核人 | 状态 |
|
|||
|
|
|------|---------|---------|--------|--------|------|
|
|||
|
|
| 2026-01-16 | 创建需求文档 | 新增需求 | 用户 | 待审核 | 待审核 |
|
|||
|
|
|
|||
|
|
## 相关人员
|
|||
|
|
|
|||
|
|
- **需求提出人**: 用户
|
|||
|
|
- **需求负责人**: 待定
|
|||
|
|
- **技术负责人**: 待定
|
|||
|
|
- **测试负责人**: 待定
|
|||
|
|
- **其他相关人员**: 待定
|
|||
|
|
|
|||
|
|
## 评审信息
|
|||
|
|
|
|||
|
|
- **评审日期**: 待定
|
|||
|
|
- **评审人员**: 待定
|
|||
|
|
- **评审结果**: 待定
|
|||
|
|
- **评审意见**: 待定
|
|||
|
|
- **修改建议**: 待定
|