datai/docs/archive/decisions/adr/0003-insert-progress-tracking.md

架构决策记录：insertObjectDataToTarget 插入数据进度跟踪

背景

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

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

决策

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

1. 采用内存存储方案（ConcurrentHashMap）：

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

2. 进度信息数据结构设计：

   • 复用现有的 SyncProgress 实体类，包含以下字段：
     • objectId: 对象 ID
     • syncType: 插入类型（INSERT）
     • 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/insertProgress/{objectId}: 查询指定对象的插入进度
     • GET /integration/object/insertProgress: 查询所有正在插入的对象进度
   • 返回 JSON 格式的进度信息

5. 与现有 insertObjectDataToTarget 方法的集成：

   • 在 DataiIntegrationObjectServiceImpl 中注入 ISyncProgressService
   • 在 insertObjectDataToTarget 方法开始时调用 startProgressTracking
   • 在插入过程中调用 updateProgress 更新进度
   • 在插入完成时调用 completeProgress（该方法会立即清除进度信息）
   • 在插入失败时调用 failProgress（该方法会立即清除进度信息）

备选方案

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

1. Redis 缓存方案：

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

2. 数据库存储方案：

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

3. 内存存储方案（ConcurrentHashMap）：

   • 优点：
     • 实现简单，无需额外依赖
     • 访问速度快，响应时间 < 10ms
     • 线程安全，支持并发访问
     • 无网络开销，性能最优
     • 插入任务完成后立即清除进度信息，无需额外的清理机制
     • 与 syncObjectData 同步进度跟踪功能保持一致，复用现有代码
   • 缺点：
     • 数据存储在内存中，系统重启后进度信息丢失
     • 不支持分布式部署，多个服务实例无法共享进度信息
     • 不保留历史记录，无法查询已完成的插入进度

影响

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

1. 系统架构影响：

   • 复用现有的进度跟踪服务层，不增加新的系统模块
   • 不影响现有的插入逻辑，通过依赖注入方式集成
   • 内存存储方案简单，不增加系统复杂性
   • 与现有的 ADR-0001（Salesforce CDC 同步方案）不冲突
   • 与现有的 ADR-0002（syncObjectData 同步进度跟踪）保持一致

2. 开发流程影响：

   • 复用现有的服务接口和实现类，无需创建新的服务
   • 需要修改现有的 insertObjectDataToTarget 方法，集成进度跟踪
   • 需要创建新的插入进度查询接口
   • 开发工作量较小，预计 1 天完成

3. 运维管理影响：

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

4. 性能影响：

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

风险

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

1. 技术风险：

   • 系统重启后进度信息丢失，用户需要重新查询
   • 并发插入多个对象时，可能出现进度信息不一致
   • 进度更新频率过高可能影响插入性能

2. 业务风险：

   • 用户可能依赖进度信息做决策，系统重启可能导致信息丢失
   • 进度信息不准确可能影响用户体验
   • 大量并发插入时，内存占用可能过高

3. 实施风险：

   • 修改现有的 insertObjectDataToTarget 方法可能引入 bug
   • 进度跟踪逻辑与插入逻辑耦合，可能影响代码可维护性
   • 测试覆盖不充分可能导致线上问题

回滚策略

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

1. 回滚步骤：

   • 移除 insertObjectDataToTarget 方法中的进度跟踪调用
   • 注释掉插入进度查询接口
   • 保留进度跟踪服务代码，但不使用

2. 调整策略：

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

3. 应急方案：

   • 提供插入日志查询功能，作为进度信息的补充
   • 增加插入状态监控，及时发现插入异常
   • 提供手动触发插入的功能，作为自动插入的补充

验收标准

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

1. 功能验收：

   • insertObjectDataToTarget 方法执行时，进度信息能够正确初始化和更新
   • 插入进度查询接口能够返回准确的进度信息
   • 进度信息包含所有必需的字段（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-003.md - insertObjectDataToTarget 插入数据进度跟踪需求文档
• 0002-sync-progress-tracking.md - syncObjectData 同步进度跟踪架构决策（参考实现）
• 0001-salesforce-cdc-sync.md - Salesforce CDC 同步方案
• ConcurrentHashMap Java Documentation