kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
34dcb2811c
datai/datai-scenes/datai-scene-salesforce/docs/changelog/2026-01-30-003-changelog.md

7.2 KiB
Raw Blame History

变更日志

元数据

  • 需求编号：001-03
  • 创建时间：2026-01-30
  • 创建人：AI Assistant
  • 版本号：v1.0.0
  • 变更类型：新增功能

变更概述

实现 Salesforce Partner API 的批量操作功能，提供批量创建、批量更新、批量删除、批量 Upsert 四个核心操作。支持最多 1000 条记录，自动分批处理（每批最多 200 条），支持部分失败情况，提供详细的成功/失败统计。

变更内容

新增功能

  • 批量创建记录

    • 支持最多 1000 条记录
    • 自动分批处理（每批最多 200 条）
    • 支持 AllOrNoneHeader 控制（可选全部成功或全部失败）
    • 使用 DisableFeedTrackingHeader 提高性能
    • 批次间休眠时间可配置（默认 100ms）
    • 返回详细的成功/失败统计

  • 批量更新记录

    • 支持最多 1000 条记录
    • 自动分批处理（每批最多 200 条）
    • 支持 AllOrNoneHeader 控制
    • 使用 DisableFeedTrackingHeader 提高性能
    • 批次间休眠时间可配置
    • 返回详细的成功/失败统计

  • 批量删除记录

    • 支持最多 1000 条记录
    • 自动分批处理（每批最多 200 条）
    • 支持 AllOrNoneHeader 控制
    • 批次间休眠时间可配置
    • 返回详细的成功/失败统计

  • 批量 Upsert 记录

    • 支持最多 1000 条记录
    • 自动分批处理（每批最多 200 条）
    • 支持外部 ID 字段指定
    • 支持 AllOrNoneHeader 控制
    • 使用 DisableFeedTrackingHeader 提高性能
    • 批次间休眠时间可配置
    • 返回详细的成功/失败统计，包括创建数量和更新数量

新增 REST API 接口

  • POST /partner/batch/create - 批量创建记录
  • POST /partner/batch/update - 批量更新记录
  • POST /partner/batch/delete - 批量删除记录
  • POST /partner/batch/upsert - 批量 Upsert 记录

新增代码文件

  1. Controller：

    • PartnerBatchController.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/controller/PartnerBatchController.java）
    • 提供 4 个 REST API 接口
    • 集成 Spring Security 权限控制
    • 使用 Swagger/OpenAPI 注解生成 API 文档

  2. Service 接口：

    • IPartnerBatchService.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/service/IPartnerBatchService.java）
    • 定义批量操作接口方法

  3. Service 实现：

    • PartnerBatchServiceImpl.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/service/impl/PartnerBatchServiceImpl.java）
    • 实现批量操作业务逻辑
    • 自动分批处理算法
    • 批量操作统计算法
    • 集成 PartnerConnectionFactory 获取连接
    • 使用 DisableFeedTrackingHeader 提高性能
    • 支持 AllOrNoneHeader 控制
    • 批次间休眠机制

  4. DTO（4 个）：

    • BatchCreateDto.java - 批量创建记录请求参数
    • BatchUpdateDto.java - 批量更新记录请求参数
    • BatchDeleteDto.java - 批量删除记录请求参数
    • BatchUpsertDto.java - 批量 Upsert 记录请求参数

  5. VO（2 个）：

    • BatchResultVo.java - 批量操作结果
    • BatchItemResultVo.java - 批量操作单项结果

  6. 单元测试：

    • PartnerBatchServiceImplTest.java（路径：datai-salesforce-partner/src/test/java/com/datai/partner/service/impl/PartnerBatchServiceImplTest.java）
    • 包含 11 个测试方法
    • 覆盖正常场景、部分失败场景、全部失败场景、超过限制场景、自动分批处理场景、AllOrNoneHeader 控制场景、DisableFeedTrackingHeader 使用场景、批次间休眠场景

新增文档

影响范围

模块级别

  • 模块：datai-salesforce-partner
  • 功能：批量操作（Batch Operations）
  • 新增文件：10 个

功能级别

  • 批量创建：支持大规模数据导入
  • 批量更新：支持大规模数据修改
  • 批量删除：支持大规模数据清理
  • 批量 Upsert：支持大规模数据同步（根据外部 ID 自动判断创建或更新）

依赖关系

  • 依赖模块：datai-salesforce-auth（使用 SessionManager 获取会话信息）
  • 依赖库：partner.jar（Salesforce Partner API）
  • 依赖服务：PartnerConnectionFactory（获取 Salesforce 连接）

技术实现

核心算法

  1. 自动分批处理算法

    • 输入：记录列表（最多 1000 条）
    • 处理：将记录列表分割为多个批次（每批最多 200 条）
    • 输出：批次列表

  2. 批量操作统计算法

    • 输入：SaveResult[] / DeleteResult[] / UpsertResult[]
    • 处理：遍历结果数组，统计成功数量、失败数量、创建数量、更新数量
    • 输出：BatchResultVo（包含详细统计信息和单项结果列表）

性能优化

  • 连接缓存：使用 PartnerConnectionFactory 提供的连接缓存
  • 自动分批处理：避免单次请求超过 Salesforce API 限制
  • DisableFeedTrackingHeader：禁用 Feed 跟踪，提高性能
  • 批次间休眠：可配置的休眠时间，避免 API 限流

异常处理

  • 使用 datai-salesforce-common 模块的异常体系
  • 统一处理 ConnectionException、InvalidSObjectException 等异常
  • 返回友好的错误消息（中文）
  • 记录详细的错误日志

测试覆盖

单元测试

  • 测试类：PartnerBatchServiceImplTest
  • 测试方法：11 个
  • 覆盖率：不低于 80%
  • 测试场景：
    • 正常场景（批量创建、更新、删除、Upsert 成功）
    • 部分失败场景（部分记录失败）
    • 全部失败场景（所有记录失败）
    • 超过限制场景（记录数超过 1000）
    • 自动分批处理场景（超过 200 条记录）
    • AllOrNoneHeader 控制场景
    • DisableFeedTrackingHeader 使用场景
    • 批次间休眠场景
    • 连接异常场景

相关文档

需求文档

设计文档

决策记录

提示词

会话记录

参考文档

注意事项

使用限制

  • 单次请求最多支持 1000 条记录
  • 每批最多 200 条记录
  • 需要有效的 Salesforce 会话
  • 需要相应的对象权限

性能建议

  • 对于大规模数据操作，建议使用适当的批次间休眠时间
  • 使用 DisableFeedTrackingHeader 可以提高性能
  • 避免在高峰期进行大规模批量操作

安全建议

  • 所有接口需要登录权限（@PreAuthorize("@ss.hasLogin()")）
  • 使用 HTTPS 加密传输
  • 参数验证防止注入攻击