datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0003-insert-progress-tracking.md

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

## 背景

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

当前 insertObjectDataToTarget 方法在执行插入操作时，用户无法获知插入的实际进度，只能等待插入完成。这导致用户体验不佳，特别是在处理大量数据时，用户无法判断插入是否正常进行、还需要多长时间完成。根据 [REQ-003.md](../../requirements/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](../../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-003.md](../../requirements/REQ-003.md) - insertObjectDataToTarget 插入数据进度跟踪需求文档
- [0002-sync-progress-tracking.md](0002-sync-progress-tracking.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)