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-002-changelog.md

7.7 KiB
Raw Blame History

变更日志

元数据

  • 需求编号：001
  • 子需求编号：001-02
  • 创建时间：2026-01-30
  • 创建人：AI Assistant
  • 版本号：v1.0.0

变更概述

实现 Salesforce Partner API 的 CRUD 操作功能，包括 Create、Retrieve、Update、Delete、Upsert、Merge 六个核心操作，支持单条记录和批量记录操作，提供完整的 RESTful API 接口，实现参数验证、异常处理、权限控制、Swagger 文档等功能。

变更内容

新增功能

CRUD 操作功能

  • 实现创建记录（Create）功能，包括：
    • 单条记录创建
    • 批量记录创建（最多 200 条）
    • 字段值映射和验证
    • 创建结果返回（记录 ID、成功状态、错误信息）
  • 实现查询记录（Retrieve）功能，包括：
    • 单条记录查询
    • 批量记录查询（最多 200 条）
    • 指定字段查询
    • 查询结果返回（记录数据、查询状态、错误信息）
  • 实现更新记录（Update）功能，包括：
    • 单条记录更新
    • 批量记录更新（最多 200 条）
    • 字段值映射和验证
    • 更新结果返回（记录 ID、成功状态、错误信息）
  • 实现删除记录（Delete）功能，包括：
    • 单条记录删除
    • 批量记录删除（最多 200 条）
    • 删除结果返回（记录 ID、成功状态、错误信息）
  • 实现更新或插入记录（Upsert）功能，包括：
    • 单条记录 Upsert
    • 批量记录 Upsert（最多 200 条）
    • 支持外部 ID 字段标识
    • Upsert 结果返回（记录 ID、成功状态、是否创建、错误信息）
  • 实现合并记录（Merge）功能，包括：
    • 合并三条记录
    • 指定主记录和待合并记录
    • 合并结果返回（记录 ID、成功状态、错误信息）

RESTful API 接口

  • 提供 6 个 REST API 接口：
    • POST /partner/crud/create - 创建记录
    • GET /partner/crud/retrieve - 查询记录
    • PUT /partner/crud/update - 更新记录
    • DELETE /partner/crud/delete - 删除记录
    • POST /partner/crud/upsert - 更新或插入记录
    • POST /partner/crud/merge - 合并记录

异常处理

  • 使用 datai-salesforce-common 模块的异常体系
  • 统一处理各种异常情况：
    • ConnectionException - Salesforce 连接异常
    • SalesforceSessionException - Salesforce 会话异常
    • SalesforceOperationException - Salesforce 操作异常
    • SalesforceValidationException - Salesforce 验证异常
  • 完善的错误信息返回机制

权限控制

  • 使用 Spring Security 的 @PreAuthorize 注解
  • 所有接口要求用户登录（@PreAuthorize("@ss.hasLogin()")）
  • 确保只有登录用户才能访问 CRUD 操作接口

参数验证

  • 使用 Spring Boot 的 @Validated 注解
  • 对所有请求参数进行验证
  • 支持自定义验证规则
  • 完善的验证错误提示

Swagger 文档

  • 使用 Swagger/OpenAPI 注解
  • 提供完整的 API 文档
  • 包含接口描述、参数说明、返回值说明
  • 支持在线测试

日志记录

  • 使用 Slf4j 日志框架
  • 记录所有 CRUD 操作的执行过程
  • 记录成功和失败的操作
  • 记录异常信息

SObject 转换

  • 实现 SObjectConverter 工具类
  • 支持 Map<String, Object> 到 SObject 的转换
  • 支持批量转换（最多 200 条）
  • 支持字段值类型转换（String、Integer、Boolean、Date、DateTime）
  • 支持字段清空（设置为 null）

新增文档

新增代码文件

Controller 层

  • datai-salesforce-partner/src/main/java/com/datai/partner/controller/PartnerCrudController.java - REST API 控制器，提供 6 个 CRUD 操作接口

Service 层

  • datai-salesforce-partner/src/main/java/com/datai/partner/service/IPartnerCrudService.java - CRUD 操作服务接口
  • datai-salesforce-partner/src/main/java/com/datai/partner/service/impl/PartnerCrudServiceImpl.java - CRUD 操作服务实现

DTO 层

  • datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/CreateRecordDto.java - 创建记录请求参数
  • datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/UpdateRecordDto.java - 更新记录请求参数
  • datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/DeleteRecordDto.java - 删除记录请求参数
  • datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/UpsertRecordDto.java - 更新或插入记录请求参数
  • datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/MergeRecordDto.java - 合并记录请求参数

VO 层

  • datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/RecordResultVo.java - 记录操作结果
  • datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/RetrieveResultVo.java - 查询结果
  • datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/ErrorVo.java - 错误信息

工具类

  • datai-salesforce-partner/src/main/java/com/datai/partner/util/SObjectConverter.java - SObject 转换工具类

测试文件

  • datai-salesforce-partner/src/test/java/com/datai/partner/service/impl/PartnerCrudServiceImplTest.java - CRUD 操作服务单元测试

影响范围

模块级别

  • 模块：datai-salesforce-partner
  • 功能：Salesforce Partner API CRUD 操作
  • 文件：13 个新文件（1 个 Controller + 2 个 Service + 5 个 DTO + 3 个 VO + 1 个工具类 + 1 个测试）

功能级别

  • 新增功能：CRUD 操作（Create、Retrieve、Update、Delete、Upsert、Merge）
  • 新增接口：6 个 REST API 接口
  • 新增文档：4 个文档（需求、设计、决策、提示词）

依赖关系

  • 依赖模块：datai-salesforce-auth（通过 SessionManager 获取会话信息）
  • 依赖模块：datai-salesforce-common（使用异常类）
  • 依赖包：partner.jar（Salesforce Partner API 客户端）

相关文档

技术栈

  • Spring Boot 3.x
  • Spring Security 6.x
  • 若依框架
  • Salesforce Partner API（partner.jar）
  • Lombok
  • Swagger/OpenAPI
  • JUnit 5
  • Mockito
  • Slf4j

代码规范

  • 类命名：使用 PascalCase（如 PartnerCrudController）
  • 方法命名：使用 camelCase（如 createRecord）
  • 变量命名：使用 camelCase（如 objectType）
  • 注释规范：使用 JavaDoc 格式
  • 代码格式：遵循 Google Java Style Guide
  • 导入规范：按字母顺序排序，移除未使用的导入
  • Lombok 注解：使用 @Data、@Slf4j、@Service、@RestController 等

测试要求

  • 单元测试覆盖率不低于 80%
  • 包含正常场景测试
  • 包含批量操作场景测试
  • 包含异常场景测试
  • 使用 JUnit 5 和 Mockito 框架

注意事项

  • 使用 partner.jar 现有类（Connector、PartnerConnection、SObject、QueryResult、SaveResult 等）
  • 使用 PartnerConnectionFactory 获取连接（getConnection("source")）
  • 使用 datai-salesforce-common 模块的异常类
  • 所有接口要求用户登录（@PreAuthorize("@ss.hasLogin()")）
  • 批量操作限制最多 200 条记录
  • 字段清空需要设置为 null
  • 子对象关系需要特殊处理
  • 使用 Lombok 注解减少样板代码
  • 使用 Swagger 注解生成 API 文档
  • 记录所有操作的日志

后续计划

  • 实现批量操作功能
  • 实现查询功能（SOQL）
  • 实现描述功能（Describe）
  • 实现高级功能（搜索、获取更新、获取删除、回收站等）