datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0002-sync-progress-tracking.md

# 架构决策记录：syncObjectData 同步进度跟踪

## 背景

描述决策的背景和上下文，包括面临的问题、约束条件和相关的业务需求。

当前 syncObjectData 方法在执行同步操作时，用户无法获知同步的实际进度，只能等待同步完成。这导致用户体验不佳，特别是在处理大量数据时，用户无法判断同步是否正常进行、还需要多长时间完成。根据 [REQ-002.md](../../requirements/REQ-002.md) 需求文档，需要实现同步进度的实时跟踪和查询功能，提升用户体验和系统透明度。

## 决策

明确陈述所做出的架构决策，包括具体的技术选择、设计方案或实现策略。

1. **采用内存存储方案（ConcurrentHashMap）**：
   - 使用 `ConcurrentHashMap` 作为进度信息的存储容器
   - Key 为对象 ID（Integer），Value 为进度对象（SyncProgress）
   - 利用 ConcurrentHashMap 的线程安全特性，支持并发访问
   - 进度信息存储在内存中，访问速度快，响应时间 < 10ms
   - **不将同步进度数据同步到数据库**，避免数据库写入开销，提升性能

2. **进度信息数据结构设计**：
   - 创建 `SyncProgress` 实体类，包含以下字段：
     - `objectId`: 对象 ID
     - `syncType`: 同步类型（全量/增量）
     - `totalBatches`: 总批次数量
     - `processedBatches`: 已处理批次数量
     - `currentBatch`: 当前批次
     - `progressPercentage`: 进度百分比（0-100）
     - `startTime`: 开始时间
     - `endTime`: 结束时间
     - `status`: 状态（RUNNING、COMPLETED、FAILED）
     - `errorMessage`: 错误信息（如果有）

3. **进度跟踪服务设计**：
   - 创建 `ISyncProgressService` 接口，定义进度跟踪的核心方法：
     - `startProgressTracking(objectId, totalBatches, syncType)`: 开始进度跟踪
     - `updateProgress(objectId, processedBatches, currentBatch)`: 更新进度
     - `completeProgress(objectId)`: 完成进度跟踪并立即清除该同步进度信息
     - `failProgress(objectId, errorMessage)`: 标记进度失败并立即清除该同步进度信息
     - `getProgress(objectId)`: 获取进度信息
     - `getAllProgress()`: 获取所有进度信息
   - 创建 `SyncProgressServiceImpl` 实现类，使用 ConcurrentHashMap 存储进度信息
   - 在同步任务完成或失败时立即清除该同步进度信息，不保留历史记录

4. **进度查询接口设计**：
   - 在 `DataiIntegrationObjectController` 中添加进度查询接口：
     - `GET /integration/object/progress/{objectId}`: 查询指定对象的同步进度
     - `GET /integration/object/progress`: 查询所有正在同步的对象进度
   - 返回 JSON 格式的进度信息

5. **与现有 syncObjectData 方法的集成**：
   - 在 `DataiIntegrationObjectServiceImpl` 中注入 `ISyncProgressService`
   - 在 syncObjectData 方法开始时调用 `startProgressTracking`
   - 在同步过程中调用 `updateProgress` 更新进度
   - 在同步完成时调用 `completeProgress`（该方法会立即清除进度信息）
   - 在同步失败时调用 `failProgress`（该方法会立即清除进度信息）

## 备选方案

列出考虑过的其他备选方案，包括每种方案的优缺点。

1. **Redis 缓存方案**：
   - **优点**：
     - 支持分布式部署，多个服务实例可以共享进度信息
     - 数据持久化，系统重启后进度信息不丢失
     - Redis 性能优秀，响应时间 < 1ms
     - 支持自动过期机制，无需手动清理
   - **缺点**：
     - 需要额外部署 Redis 服务，增加运维成本
     - 增加系统依赖，Redis 故障会影响进度查询
     - 网络开销，相比内存存储稍慢
     - 需要额外的序列化/反序列化操作

2. **数据库存储方案**：
   - **优点**：
     - 数据持久化，系统重启后进度信息不丢失
     - 支持分布式部署，多个服务实例可以共享进度信息
     - 可以利用现有的数据库基础设施
     - 支持复杂查询和历史记录
   - **缺点**：
     - 数据库写入开销大，影响同步性能
     - 需要创建新的进度表，增加数据库维护成本
     - 响应时间较慢（10-100ms），用户体验不佳
     - 频繁的数据库操作可能导致锁竞争

3. **内存存储方案（ConcurrentHashMap）**：
   - **优点**：
     - 实现简单，无需额外依赖
     - 访问速度快，响应时间 < 10ms
     - 线程安全，支持并发访问
     - 无网络开销，性能最优
     - 同步任务完成后立即清除进度信息，无需额外的清理机制
   - **缺点**：
     - 数据存储在内存中，系统重启后进度信息丢失
     - 不支持分布式部署，多个服务实例无法共享进度信息
     - 不保留历史记录，无法查询已完成的同步进度

## 影响

分析该决策对系统架构、开发流程、运维管理等方面的影响。

1. **系统架构影响**：
   - 引入进度跟踪服务层，增加系统模块化程度
   - 不影响现有的同步逻辑，通过依赖注入方式集成
   - 内存存储方案简单，不增加系统复杂性
   - 与现有的 ADR-0001（Salesforce CDC 同步方案）不冲突

2. **开发流程影响**：
   - 需要创建新的服务接口和实现类
   - 需要修改现有的 syncObjectData 方法，集成进度跟踪
   - 需要创建新的进度查询接口
   - 开发工作量适中，预计 2-3 天完成

3. **运维管理影响**：
   - 无需额外部署服务，不增加运维成本
   - 无需监控内存泄漏风险，进度信息在同步完成后立即清除
   - 无需定时清理任务，简化运维管理
   - 系统重启后进度信息丢失，需要告知用户

4. **性能影响**：
   - 进度更新操作轻量级，对同步性能影响 < 5%
   - 进度查询响应时间 < 10ms，用户体验良好
   - 内存占用可控（每个进度对象约 200 字节，100 个并发同步约 20KB）

## 风险

识别该决策可能带来的风险，包括技术风险、业务风险和实施风险。

1. **技术风险**：
   - 系统重启后进度信息丢失，用户需要重新查询
   - 并发同步多个对象时，可能出现进度信息不一致
   - 进度更新频率过高可能影响同步性能

2. **业务风险**：
   - 用户可能依赖进度信息做决策，系统重启可能导致信息丢失
   - 进度信息不准确可能影响用户体验
   - 大量并发同步时，内存占用可能过高

3. **实施风险**：
   - 修改现有的 syncObjectData 方法可能引入 bug
   - 进度跟踪逻辑与同步逻辑耦合，可能影响代码可维护性
   - 测试覆盖不充分可能导致线上问题

## 回滚策略

描述如果决策实施后出现问题，如何进行回滚或调整。

1. **回滚步骤**：
   - 移除 syncObjectData 方法中的进度跟踪调用
   - 注释掉进度查询接口
   - 保留进度跟踪服务代码，但不使用

2. **调整策略**：
   - 降低进度更新频率，减少性能影响
   - 优化进度查询接口，增加缓存机制
   - 考虑切换到 Redis 缓存方案，如果分布式部署需求增加

3. **应急方案**：
   - 提供同步日志查询功能，作为进度信息的补充
   - 增加同步状态监控，及时发现同步异常
   - 提供手动触发同步的功能，作为自动同步的补充

## 验收标准

定义验证该决策有效性的具体标准和测试方法。

1. **功能验收**：
   - syncObjectData 方法执行时，进度信息能够正确初始化和更新
   - 进度查询接口能够返回准确的进度信息
   - 进度信息包含所有必需的字段（objectId、syncType、totalBatches、processedBatches、currentBatch、progressPercentage、startTime、endTime、status、errorMessage）
   - 同步完成后，进度状态正确标记为 COMPLETED
   - 同步失败时，进度状态正确标记为 FAILED，并记录错误信息

2. **性能验收**：
   - 进度查询接口响应时间 < 100ms
   - 进度更新操作对同步性能影响 < 5%
   - 支持 10 个对象同时同步并跟踪进度
   - 内存占用 < 100MB（100 个并发同步）

3. **可靠性验收**：
   - 并发访问时，进度信息保持一致性
   - 同步任务完成后，进度信息能够正确清除
   - 同步任务失败时，进度信息能够正确清除

4. **用户体验验收**：
   - 进度信息准确、实时、易理解
   - 进度百分比计算准确（0-100%）
   - 错误信息清晰、有用

## 视觉锚点

### Visual Reference

引用 Canvas 的具体节点或快照：
- [Authentication.canvas](../../Authentication.canvas) - 项目架构视觉化展示
- **具体节点**: [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) - 对象同步服务实现

### Status

- [ ] Draft
- [x] Accepted
- [ ] Superceded

## 参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源。

- [REQ-002.md](../../requirements/REQ-002.md) - syncObjectData 同步进度跟踪需求文档
- [0001-salesforce-cdc-sync.md](0001-salesforce-cdc-sync.md) - Salesforce CDC 同步方案
- [ConcurrentHashMap Java Documentation](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ConcurrentHashMap.html)
- [Spring @Scheduled Annotation](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/annotation/Scheduled.html)