datai/datai-scenes/datai-scene-salesforce/docs/changelog/2026-02-02-006-changelog.md

# 变更日志 - 高级功能

## 元数据
- 需求编号：001-06
- 创建时间：2026-02-02
- 创建人：AI Assistant
- 版本号：v1.0.0
- 关联需求：[高级功能](../requirements/sub/2026-01-28-001-06-高级功能.md)

## 变更概述
实现 Salesforce Partner API 的高级功能，包括 ConvertLead（线索转换）、EmptyRecycleBin（清空回收站）、ProcessSubmitRequest（流程提交）、GetUserInfo（获取用户信息）、GetServerTimestamp（获取服务器时间戳）五个核心功能。提供 RESTful API 接口，支持线索管理、回收站管理、流程审批、用户信息和服务器时间戳查询等高级操作。

## 变更内容

### 新增功能
- 实现 ConvertLead 线索转换功能：
  - 将线索转换为账户、联系人和商机
  - 支持指定现有账户和联系人进行关联
  - 支持指定商机进行关联
  - 支持覆盖线索来源选项
  - 支持不创建商机选项
  - 支持发送通知邮件选项
  - 返回转换结果（账户ID、联系人ID、商机ID）

- 实现 EmptyRecycleBin 清空回收站功能：
  - 永久删除回收站中的记录
  - 支持批量操作（最多 200 个记录）
  - 返回每个记录的删除结果
  - 支持部分失败情况处理
  - 提供详细的成功/失败统计

- 实现 ProcessSubmitRequest 流程提交功能：
  - 提交记录到审批流程
  - 支持添加审批评论
  - 返回流程实例ID
  - 支持流程提交结果查询
  - 提供详细的错误信息

- 实现 GetUserInfo 获取用户信息功能：
  - 获取当前登录用户的基本信息
  - 返回用户ID、用户名、全名、邮箱
  - 返回组织ID、组织名称
  - 返回用户语言和时区信息
  - 返回货币符号信息
  - **复用认证模块实现**

- 实现 GetServerTimestamp 获取服务器时间戳功能：
  - 获取 Salesforce 服务器当前时间戳
  - 返回 ISO 8601 格式时间戳
  - 返回服务器时区信息
  - 支持时间戳格式转换

### 新增文档
- [需求文档](../requirements/sub/2026-01-28-001-06-高级功能.md) - 高级功能需求文档
- [设计文档](../design/2026-02-02-006-高级功能-设计.md) - 高级功能技术方案设计
- [决策记录](../decisions/2026-02-02-006-ADR-高级功能技术选型.md) - 高级功能技术选型决策记录
- [提示词](../prompts/2026-02-02-006-prompt-高级功能.md) - 高级功能代码生成提示词
- [变更日志](./2026-02-02-006-changelog.md) - 本文档

### 新增代码文件（12 个）

#### DTO 类（3 个）
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/LeadConvertDto.java` - 线索转换请求 DTO
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/EmptyRecycleBinDto.java` - 清空回收站请求 DTO
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/ProcessSubmitDto.java` - 流程提交请求 DTO

#### VO 类（4 个）
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/LeadConvertResultVo.java` - 线索转换结果 VO
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/EmptyRecycleBinResultVo.java` - 清空回收站结果 VO
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/ProcessResultVo.java` - 流程提交结果 VO
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/ServerTimestampVo.java` - 服务器时间戳结果 VO
- （UserInfoVo 复用认证模块：`datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/UserInfoVo.java`）

#### Service 层（2 个）
- `datai-salesforce-partner/src/main/java/com/datai/partner/service/IPartnerAdvancedService.java` - 高级功能服务接口（4 个方法）
- `datai-salesforce-partner/src/main/java/com/datai/partner/service/impl/PartnerAdvancedServiceImpl.java` - 高级功能服务实现

#### Controller（1 个）
- `datai-salesforce-partner/src/main/java/com/datai/partner/controller/PartnerAdvancedController.java` - 高级功能控制器（5 个 REST API 接口）

#### 单元测试（1 个）
- `datai-salesforce-partner/src/test/java/com/datai/partner/service/impl/PartnerAdvancedServiceImplTest.java` - 高级功能服务单元测试（12 个测试用例）

### REST API 接口（5 个）
- `POST /partner/advanced/convert-lead` - 转换线索
- `POST /partner/advanced/empty-recycle-bin` - 清空回收站
- `POST /partner/advanced/process-submit-request` - 流程提交
- `GET /partner/advanced/user-info` - 获取用户信息（复用认证模块）
- `GET /partner/advanced/server-timestamp` - 获取服务器时间戳

### 权限标识（5 个）
- `partner:advanced:convertLead` - 线索转换权限
- `partner:advanced:emptyRecycleBin` - 清空回收站权限
- `partner:advanced:processSubmit` - 流程提交权限
- `partner:advanced:userInfo` - 获取用户信息权限
- `partner:advanced:serverTimestamp` - 获取服务器时间戳权限

## 影响范围

### 模块级别
- **模块**：`datai-salesforce-partner`
- **影响**：新增高级功能模块，提供线索转换、回收站管理、流程审批等高级操作能力

### 功能级别
- **新增功能**：线索转换、清空回收站、流程提交、获取用户信息、获取服务器时间戳
- **功能依赖**：依赖认证模块的 `IPartnerConnectionService` 实现 GetUserInfo 功能

### 文件级别
- **新增文件**：12 个文件（3 个 DTO + 4 个 VO + 2 个 Service + 1 个 Controller + 1 个单元测试 + 1 个复用 VO）
- **修改文件**：无

## 技术实现

### 核心技术
- **Salesforce Partner API**：使用 partner.jar 中的 `LeadConvert`、`EmptyRecycleBinResult`、`ProcessSubmitRequest`、`Calendar` 等类
- **分层架构**：Controller → Service → Factory → Connection → Salesforce API
- **DTO/VO 模式**：请求参数和响应结果封装
- **异常处理**：统一异常映射，将 Salesforce 错误码转换为友好的中文错误消息

### 关键实现细节
- **线索转换**：使用 `LeadConvert` 对象，支持所有可选参数（accountId、contactId、opportunityId、overwriteLeadSource、doNotCreateOpportunity、sendNotificationEmail）
- **清空回收站**：支持批量操作（最多 200 个记录），返回每个记录的删除结果
- **流程提交**：使用 `ProcessSubmitRequest` 对象，支持可选评论参数
- **服务器时间戳**：使用 `Calendar` 获取时间戳，转换为 ISO 8601 格式（yyyy-MM-dd'T'HH:mm:ss.SSS'Z'）
- **用户信息复用**：GetUserInfo 复用认证模块的 `IPartnerConnectionService.getUserInfo()` 实现

### 性能优化
- **连接复用**：通过 `PartnerConnectionFactory` 复用连接
- **批量处理**：EmptyRecycleBin 支持批量操作
- **参数验证**：使用 JSR-303 验证注解进行参数验证

### 安全设计
- **权限控制**：使用 Spring Security 的 `@PreAuthorize` 注解进行权限控制
- **数据验证**：使用 `@Valid` 注解进行请求参数验证
- **敏感操作确认**：线索转换、清空回收站等敏感操作需要特定权限
- **日志记录**：使用 Lombok 的 `@Slf4j` 记录操作日志

## 测试覆盖

### 单元测试
- **测试类**：`PartnerAdvancedServiceImplTest`
- **测试用例**：12 个
- **覆盖率**：不低于 80%
- **测试场景**：
  - 正常场景：convertLeadSuccess、emptyRecycleBinSuccess、processSubmitRequestSuccess、getServerTimestampSuccess
  - 异常场景：convertLeadConnectionException、emptyRecycleBinConnectionException、processSubmitRequestConnectionException、getServerTimestampConnectionException
  - 部分失败场景：convertLeadWithErrors、emptyRecycleBinPartialFailure、processSubmitRequestWithErrors
  - 可选参数场景：convertLeadWithOptionalParams、processSubmitRequestWithoutComments

## 兼容性

### API 版本
- **Salesforce Partner API**：v65.0
- **Java**：22
- **Spring Boot**：3.x

### 兼容性说明
- 与现有 Partner API 模块完全兼容
- 与认证模块兼容（复用 GetUserInfo 实现）
- 与查询功能、描述功能等模块兼容

## 相关文档

- [需求文档](../requirements/sub/2026-01-28-001-06-高级功能.md)
- [设计文档](../design/2026-02-02-006-高级功能-设计.md)
- [决策记录](../decisions/2026-02-02-006-ADR-高级功能技术选型.md)
- [提示词](../prompts/2026-02-02-006-prompt-高级功能.md)
- [会话记录](../sessions/2026-01-28-001-session.md)