194 lines
7.2 KiB
Markdown
194 lines
7.2 KiB
Markdown
# 变更日志
|
||
|
||
## 元数据
|
||
- 需求编号：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 使用场景、批次间休眠场景
|
||
|
||
### 新增文档
|
||
- [需求文档](../requirements/sub/2026-01-28-001-03-批量操作.md)
|
||
- [设计文档](../design/2026-01-30-003-批量操作-设计.md)
|
||
- [决策记录](../decisions/2026-01-30-003-ADR-批量操作技术选型.md)
|
||
- [提示词](../prompts/2026-01-30-003-prompt-批量操作.md)
|
||
|
||
## 影响范围
|
||
|
||
### 模块级别
|
||
- **模块**：`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 使用场景
|
||
- 批次间休眠场景
|
||
- 连接异常场景
|
||
|
||
## 相关文档
|
||
|
||
### 需求文档
|
||
- [批量操作需求文档](../requirements/sub/2026-01-28-001-03-批量操作.md)
|
||
|
||
### 设计文档
|
||
- [批量操作设计文档](../design/2026-01-30-003-批量操作-设计.md)
|
||
|
||
### 决策记录
|
||
- [批量操作技术选型](../decisions/2026-01-30-003-ADR-批量操作技术选型.md)
|
||
|
||
### 提示词
|
||
- [批量操作提示词](../prompts/2026-01-30-003-prompt-批量操作.md)
|
||
|
||
### 会话记录
|
||
- [会话记录](../sessions/2026-01-28-001-session.md)
|
||
|
||
### 参考文档
|
||
- [Partner API 模块说明](../reference-code/sforce/docs/partner-module.md)
|
||
- [datai-salesforce-common 模块详细文档](../reference-code/datai-salesforce-common模块详细文档.md)
|
||
|
||
## 注意事项
|
||
|
||
### 使用限制
|
||
- 单次请求最多支持 1000 条记录
|
||
- 每批最多 200 条记录
|
||
- 需要有效的 Salesforce 会话
|
||
- 需要相应的对象权限
|
||
|
||
### 性能建议
|
||
- 对于大规模数据操作，建议使用适当的批次间休眠时间
|
||
- 使用 DisableFeedTrackingHeader 可以提高性能
|
||
- 避免在高峰期进行大规模批量操作
|
||
|
||
### 安全建议
|
||
- 所有接口需要登录权限（`@PreAuthorize("@ss.hasLogin()")`）
|
||
- 使用 HTTPS 加密传输
|
||
- 参数验证防止注入攻击
|