datai/datai-scenes/datai-scene-salesforce/docs/changelog/2026-01-30-002-changelog.md

# 变更日志

## 元数据
- 需求编号：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）

### 新增文档
- [需求文档](../requirements/sub/2026-01-28-001-02-CRUD操作.md)
- [设计文档](../design/2026-01-30-002-CRUD操作-设计.md)
- [决策记录](../decisions/2026-01-30-002-ADR-CRUD操作技术选型.md)
- [提示词](../prompts/2026-01-30-002-prompt-CRUD操作.md)

### 新增代码文件

#### 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 客户端）

## 相关文档
- [需求文档](../requirements/sub/2026-01-28-001-02-CRUD操作.md)
- [设计文档](../design/2026-01-30-002-CRUD操作-设计.md)
- [决策记录](../decisions/2026-01-30-002-ADR-CRUD操作技术选型.md)
- [提示词](../prompts/2026-01-30-002-prompt-CRUD操作.md)
- [会话记录](../sessions/2026-01-28-001-session.md)

## 技术栈
- 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）
- 实现高级功能（搜索、获取更新、获取删除、回收站等）