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

# 变更日志

## 元数据
- 需求编号：001-04
- 变更时间：2026-01-30
- 变更人：AI Assistant
- 版本号：v1.0.0
- 状态：已完成

## 变更概述
实现 Salesforce Partner API 的查询功能，包括 SOQL 查询（Query）、查询所有记录（QueryAll）、分页查询（QueryMore）和 SOSL 搜索（Search）四个核心功能。提供完整的 REST API 接口，支持查询结果分页、参数验证、异常处理和权限控制。

## 变更内容

### 新增功能

#### 1. SOQL 查询（Query）
- 执行标准 SOQL 查询语句
- 支持自定义批次大小（1-2000，默认 500）
- 支持关系查询（如 Account.Name）
- 返回查询结果、分页信息和记录数量
- 最多返回 50000 条记录

#### 2. 查询所有记录（QueryAll）
- 执行 SOQL 查询，包括已删除的记录（Recycle Bin 中的记录）
- 支持自定义批次大小
- 适用于数据恢复和审计场景

#### 3. 分页查询（QueryMore）
- 使用 QueryLocator 获取查询结果的下一页
- 支持 Query 和 QueryAll 结果的分页
- 自动处理分页边界条件

#### 4. SOSL 搜索（Search）
- 执行 SOSL 搜索语句
- 支持跨对象搜索
- 返回按对象类型分组的搜索结果
- 支持全文搜索和字段搜索

### 新增 DTO 类

1. **QueryDto.java** - SOQL 查询请求参数
   - 路径：`datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/QueryDto.java`
   - 字段：soql（查询语句）、batchSize（批次大小）
   - 验证：@NotBlank、@Min(1)、@Max(2000)

2. **QueryAllDto.java** - QueryAll 请求参数
   - 路径：`datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/QueryAllDto.java`
   - 字段：soql（查询语句）、batchSize（批次大小）
   - 验证：@NotBlank、@Min(1)、@Max(2000)

3. **QueryMoreDto.java** - QueryMore 请求参数
   - 路径：`datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/QueryMoreDto.java`
   - 字段：queryLocator（查询定位器）
   - 验证：@NotBlank

4. **SearchDto.java** - SOSL 搜索请求参数
   - 路径：`datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/SearchDto.java`
   - 字段：sosl（搜索语句）
   - 验证：@NotBlank

### 新增 VO 类

1. **QueryResultVo.java** - 查询结果
   - 路径：`datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/QueryResultVo.java`
   - 字段：records（记录列表）、queryLocator（查询定位器）、done（是否完成）、size（记录数量）、success（是否成功）、errors（错误信息）

2. **SearchResultVo.java** - 搜索结果
   - 路径：`datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/SearchResultVo.java`
   - 字段：searchRecords（搜索结果列表）、success（是否成功）、errors（错误信息）

3. **SearchRecordVo.java** - 搜索记录
   - 路径：`datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/SearchRecordVo.java`
   - 字段：type（记录类型）、record（记录数据）

### 新增 Service 接口和实现

1. **IPartnerQueryService.java** - 查询服务接口
   - 路径：`datai-salesforce-partner/src/main/java/com/datai/partner/service/IPartnerQueryService.java`
   - 方法：query(QueryDto)、queryAll(QueryAllDto)、queryMore(QueryMoreDto)、search(SearchDto)

2. **PartnerQueryServiceImpl.java** - 查询服务实现
   - 路径：`datai-salesforce-partner/src/main/java/com/datai/partner/service/impl/PartnerQueryServiceImpl.java`
   - 功能：
     - 通过 PartnerConnectionFactory 获取连接
     - 设置查询选项（批次大小）
     - 执行查询并处理结果
     - 异常处理和日志记录
     - SObject 到 Map 的转换

### 新增 Controller

**PartnerQueryController.java** - 查询控制器
- 路径：`datai-salesforce-partner/src/main/java/com/datai/partner/controller/PartnerQueryController.java`
- 接口：
  - POST `/partner/query` - 执行 SOQL 查询
  - POST `/partner/queryAll` - 查询所有记录（包括已删除的）
  - POST `/partner/queryMore` - 获取查询结果的下一页
  - POST `/partner/search` - 执行 SOSL 搜索
- 权限控制：@PreAuthorize("@ss.hasLogin()")
- Swagger 文档：@Operation、@Tag

### 新增单元测试

**PartnerQueryServiceImplTest.java** - 查询服务单元测试
- 路径：`datai-salesforce-partner/src/test/java/com/datai/partner/service/impl/PartnerQueryServiceImplTest.java`
- 测试用例：
  - testQuerySuccess - 查询成功场景
  - testQueryEmptyResult - 查询空结果场景
  - testQueryConnectionException - 连接异常场景
  - testQueryAllSuccess - QueryAll 成功场景
  - testQueryMoreSuccess - QueryMore 成功场景
  - testSearchSuccess - 搜索成功场景
  - testSearchEmptyResult - 搜索空结果场景
  - testSearchConnectionException - 搜索连接异常场景

### 新增文档

1. **设计文档**：[2026-01-30-004-查询功能-设计.md](./design/2026-01-30-004-查询功能-设计.md)
2. **决策记录**：[2026-01-30-004-ADR-查询功能技术选型.md](./decisions/2026-01-30-004-ADR-查询功能技术选型.md)
3. **提示词**：[2026-01-30-004-prompt-查询功能.md](./prompts/2026-01-30-004-prompt-查询功能.md)

## 影响范围

### 模块级别
- **模块**：`datai-salesforce-partner`
- **新增文件**：11 个
  - 4 个 DTO 类
  - 3 个 VO 类
  - 1 个 Service 接口
  - 1 个 Service 实现
  - 1 个 Controller
  - 1 个单元测试类

### 功能级别
- **功能**：Salesforce Partner API 查询功能
- **子功能**：
  - SOQL 查询（Query）
  - 查询所有记录（QueryAll）
  - 分页查询（QueryMore）
  - SOSL 搜索（Search）

### 接口级别
- **新增接口**：4 个 REST API 接口
  - POST `/partner/query`
  - POST `/partner/queryAll`
  - POST `/partner/queryMore`
  - POST `/partner/search`

### 依赖关系
- **依赖模块**：`datai-salesforce-auth`
  - PartnerConnectionFactory
  - SessionManager
- **依赖模块**：`datai-salesforce-common`
  - SalesforceAuthException
  - SalesforceOperationException
  - ErrorVo

## 技术特性

### 查询选项
- 支持通过 `setQueryOptions(int)` 设置查询批处理大小
- 默认批次大小：500
- 最大批次大小：2000

### 结果处理
- SObject 数组转换为 List<Map<String, Object>>
- 支持关系字段访问（如 Account.Name）
- 自动处理空结果和异常场景

### 分页机制
- 使用 QueryLocator 进行分页
- QueryMore 获取下一页结果
- 自动检测是否完成（done 标志）

### 搜索功能
- 支持 SOSL 全文搜索
- 按对象类型分组返回结果
- 支持多对象搜索

## 相关文档

- [需求文档](../requirements/sub/2026-01-28-001-04-查询功能.md)
- [设计文档](../design/2026-01-30-004-查询功能-设计.md)
- [决策记录](../decisions/2026-01-30-004-ADR-查询功能技术选型.md)
- [提示词文档](../prompts/2026-01-30-004-prompt-查询功能.md)
- [会话记录](../sessions/2026-01-28-001-session.md)
- [API 文档](../api-docs/2026-01-30-004-api.md)
- [复盘文档](../retros/2026-01-30-004-retro.md)