datai/docs/archive/decisions/adr/0002-sync-progress-tracking.md

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

背景

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

当前 syncObjectData 方法在执行同步操作时，用户无法获知同步的实际进度，只能等待同步完成。这导致用户体验不佳，特别是在处理大量数据时，用户无法判断同步是否正常进行、还需要多长时间完成。根据 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 - 项目架构视觉化展示
• 具体节点: DataiIntegrationObjectController - 对象同步控制接口
• 具体节点: DataiIntegrationObjectServiceImpl - 对象同步服务实现

Status

• Draft
• Accepted
• Superceded

参考资料

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

• REQ-002.md - syncObjectData 同步进度跟踪需求文档
• 0001-salesforce-cdc-sync.md - Salesforce CDC 同步方案
• ConcurrentHashMap Java Documentation
• Spring @Scheduled Annotation