kris/datai

Fork 0

Kris 6357f1c579 feat：提交所有模块基础搭建完成

2026-02-06 09:58:58 +08:00

16 KiB

Raw Blame History

会话记录 - SOQL 查询功能 (004-08)

元数据

需求编号: 004-08
需求名称: SOQL 查询功能
会话时间: 2026-02-06
当前阶段: 阶段 9：闭环复盘和接口文档
会话状态: 已完成

需求描述

实现 Tooling API SOQL 查询功能，包括执行 SOQL 查询、获取更多查询结果（queryMore）、查询所有结果（自动处理分页）等功能。支持所有 Tooling API 对象的查询，支持复杂的查询条件、排序、分页。提供完整的 REST API 接口，所有操作记录到数据库。

执行阶段

阶段 1：需求定义与入库

状态: 已完成
生成文档: 需求文档
关键决策: 确定需求优先级为高，包含 5 个核心 REST API 接口

阶段 2：方案设计

状态: 已完成
生成文档: 设计文档
关键决策:
1. 采用分层架构模式，复用 004-01 的连接管理功能
2. 通过 Service 层封装 Tooling API 调用
3. 提供标准化的 REST API 接口

阶段 3：方案决策

状态: 已完成
生成文档: 决策记录
关键决策:
1. 选择直接使用 ToolingConnection.query() 方法执行 SOQL 查询
2. 复用现有 SoqlBuilder 工具类构建查询
3. 使用异步方式记录操作日志

阶段 4：数据库结构生成

状态: 已完成
生成文档: SQL 脚本
关键决策: 创建 datai_tooling_soql_query_log 表，包含查询字符串、执行时间、结果数量等字段

阶段 5：提示词生成

状态: 已完成
生成文档: 提示词文档
关键决策: 定义了详细的代码生成要求和规范

阶段 6：执行代码生成

状态: 已完成
关键决策:
1. 代码生成器已生成基础代码（Entity、Mapper、Service、Controller）
2. 手动实现业务逻辑代码（SOQL 查询 Service、Controller、DTO、ErrorCode）
3. 支持 5 个 REST API 接口

阶段 7：记录当前会话

状态: 已完成
关键决策: 完整记录了当前会话的所有信息和对话记录

阶段 8：变更记录与归档

状态: 已完成
生成文档: 变更日志
关键决策:
1. 创建了详细的变更日志文档
2. 更新了根目录 CHANGELOG.md
3. 更新了索引文档
4. 更新了需求文档的执行状态
5. 记录了所有新增功能、代码文件和错误码

阶段 9：闭环复盘和接口文档

状态: 已完成
生成文档:
- 复盘文档
- API 文档
关键决策:
1. 创建了详细的复盘文档，总结了成功经验、改进点、问题分析和行动计划
2. 提取了有效的 Prompt 技巧和避免的坑
3. 创建了完整的 API 文档，包含 5 个接口的详细说明
4. 更新了索引和需求文档
复盘主要结论:
- 成功经验：SSOT 流程严格执行、代码复用策略有效、完整的错误码体系设计
- 改进点：阶段间过渡可以更流畅、单元测试覆盖率可以提升
- 问题分析：查询结果限制处理、queryLocator 有效期管理、SOQL 查询字符串验证

阶段 6：执行代码生成

现状与目标

现状: 已完成需求定义、方案设计、方案决策、数据库结构生成和提示词生成目标: 根据提示词生成符合项目规范的代码文件

代码生成器扫描结果

已生成的代码生成器文件（基础代码）:

DataiToolingSoqlQueryLogController.java - 基础 CRUD Controller（日志管理）
DataiToolingSoqlQueryResultController.java - 基础 CRUD Controller（结果管理）
DataiToolingSoqlQueryLog.java - 日志实体类
DataiToolingSoqlQueryResult.java - 结果实体类
DataiToolingSoqlQueryLogVo.java - 日志 VO 类
DataiToolingSoqlQueryResultVo.java - 结果 VO 类
DataiToolingSoqlQueryLogDto.java - 日志 DTO 类
DataiToolingSoqlQueryResultDto.java - 结果 DTO 类
DataiToolingSoqlQueryLogMapper.java - 日志 Mapper 接口
DataiToolingSoqlQueryResultMapper.java - 结果 Mapper 接口
IDataiToolingSoqlQueryLogService.java - 日志 Service 接口
IDataiToolingSoqlQueryResultService.java - 结果 Service 接口
DataiToolingSoqlQueryLogServiceImpl.java - 日志 Service 实现
DataiToolingSoqlQueryResultServiceImpl.java - 结果 Service 实现

手动实现的代码文件

1. Controller 层

文件: ToolingSoqlQueryController.java
路径: datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/
功能: 提供 5 个 REST API 接口
- POST /salesforce/tooling/soql/query - 执行 SOQL 查询
- POST /salesforce/tooling/soql/queryMore - 获取更多查询结果
- POST /salesforce/tooling/soql/queryAll - 查询所有结果（自动处理分页）
- POST /salesforce/tooling/soql/queryWithBuilder - 使用 SoqlBuilder 执行查询
- GET /salesforce/tooling/soql/logs - 获取查询日志列表

2. Service 层

接口文件: IToolingSoqlQueryService.java
实现文件: ToolingSoqlQueryServiceImpl.java
路径: datai-salesforce-tooling/src/main/java/com/datai/tooling/service/ 和 service/impl/
功能: 封装 Tooling API 调用，提供 4 个核心方法

3. DTO 类

路径: datai-salesforce-tooling/src/main/java/com/datai/tooling/dto/
文件列表:
- ToolingSoqlQueryRequestDTO.java - SOQL 查询请求 DTO
- ToolingSoqlQueryResultDTO.java - SOQL 查询结果 DTO

4. ErrorCode 枚举

文件: ToolingSoqlErrorCode.java
路径: datai-salesforce-tooling/src/main/java/com/datai/tooling/enums/
错误码列表:
- TOOLING_SOQL_001 - Session 无效或已过期
- TOOLING_SOQL_002 - 查询失败
- TOOLING_SOQL_003 - 权限不足
- TOOLING_SOQL_004 - 用户未登录
- TOOLING_SOQL_005 - 查询定位器无效
- TOOLING_SOQL_006 - 查询结果超出限制

技术实现要点

1. SOQL 查询执行

ToolingConnection connection = toolingConnectionFactory.getConnection("source");
QueryResult queryResult = connection.query(queryString);

2. 自动分页处理

while (!queryResult.isDone() && queryResult.getQueryLocator() != null) {
    queryResult = connection.queryMore(queryResult.getQueryLocator());
    // 合并结果
}

3. SoqlBuilder 支持

SoqlBuilder builder = SoqlBuilder.select(requestDTO.getSelect())
        .from(requestDTO.getFrom())
        .where(requestDTO.getWhere())
        .orderBy(requestDTO.getOrderBy())
        .limit(requestDTO.getLimit());

4. 异步日志记录

采用 Spring @Async 异步记录操作日志，包含执行时间、查询字符串、结果数量等信息。

5. 异常处理

捕获 ConnectionException，根据错误类型返回对应的错误码
处理 Session 无效、查询失败、权限不足、查询定位器无效等异常
检查查询结果是否超过 50000 条记录限制

AI 的质疑与决策

质疑 1：是否需要支持所有 Tooling API 对象？

分析: SOQL 查询功能应该支持所有 Tooling API 对象，包括 ApexClass、ApexTrigger、Flow 等决策: 支持所有 Tooling API 对象，通过通用的 SOQL 查询字符串实现

质疑 2：如何处理查询结果超过 50000 条的情况？

分析: Salesforce 限制最多返回 50000 条记录决策: 在 queryAll 方法中检查记录数量，超过限制时抛出异常，返回错误码 TOOLING_SOQL_006

质疑 3：是否需要提供原生 QueryResult 返回？

分析: 前端可能需要 queryLocator 进行分页查询决策: executeQuery 和 queryMore 方法返回包含 queryLocator 的结果，queryAll 方法返回合并后的完整列表

复现步骤

扫描代码生成器生成的文件，确认基础代码已生成
创建 ErrorCode 枚举类
创建 2 个 DTO 类（请求和结果）
创建 Service 接口和实现类
创建 Controller 类，实现 5 个 REST API 接口
更新索引和设计文档
创建会话记录

生成的代码文件清单

代码生成器生成文件

文件类型	文件路径
Entity	`datai-salesforce-tooling/src/main/java/com/datai/tooling/model/domain/DataiToolingSoqlQueryLog.java`
Entity	`datai-salesforce-tooling/src/main/java/com/datai/tooling/model/domain/DataiToolingSoqlQueryResult.java`
Mapper	`datai-salesforce-tooling/src/main/java/com/datai/tooling/mapper/DataiToolingSoqlQueryLogMapper.java`
Mapper	`datai-salesforce-tooling/src/main/java/com/datai/tooling/mapper/DataiToolingSoqlQueryResultMapper.java`
Service Interface	`datai-salesforce-tooling/src/main/java/com/datai/tooling/service/IDataiToolingSoqlQueryLogService.java`
Service Interface	`datai-salesforce-tooling/src/main/java/com/datai/tooling/service/IDataiToolingSoqlQueryResultService.java`
Service Impl	`datai-salesforce-tooling/src/main/java/com/datai/tooling/service/impl/DataiToolingSoqlQueryLogServiceImpl.java`
Service Impl	`datai-salesforce-tooling/src/main/java/com/datai/tooling/service/impl/DataiToolingSoqlQueryResultServiceImpl.java`
Controller	`datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/DataiToolingSoqlQueryLogController.java`
Controller	`datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/DataiToolingSoqlQueryResultController.java`
DTO	`datai-salesforce-tooling/src/main/java/com/datai/tooling/model/dto/DataiToolingSoqlQueryLogDto.java`
DTO	`datai-salesforce-tooling/src/main/java/com/datai/tooling/model/dto/DataiToolingSoqlQueryResultDto.java`
VO	`datai-salesforce-tooling/src/main/java/com/datai/tooling/model/vo/DataiToolingSoqlQueryLogVo.java`
VO	`datai-salesforce-tooling/src/main/java/com/datai/tooling/model/vo/DataiToolingSoqlQueryResultVo.java`

手动实现文件

文件类型	文件路径
Controller	`datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/ToolingSoqlQueryController.java`
Service Interface	`datai-salesforce-tooling/src/main/java/com/datai/tooling/service/IToolingSoqlQueryService.java`
Service Impl	`datai-salesforce-tooling/src/main/java/com/datai/tooling/service/impl/ToolingSoqlQueryServiceImpl.java`
ErrorCode	`datai-salesforce-tooling/src/main/java/com/datai/tooling/enums/ToolingSoqlErrorCode.java`
DTO	`datai-salesforce-tooling/src/main/java/com/datai/tooling/dto/ToolingSoqlQueryRequestDTO.java`
DTO	`datai-salesforce-tooling/src/main/java/com/datai/tooling/dto/ToolingSoqlQueryResultDTO.java`

对话记录

2026-02-06 会话开始

用户: 暂停，更新 d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\docs\requirements\sub\2026-01-28-004-08-SOQL查询功能.md 相关文档索引
AI: 读取需求文档，准备更新相关文档索引

更新相关文档索引

AI: 已更新需求文档，添加了相关文档链接（设计文档、决策记录、SQL 脚本、提示词文档、变更日志、会话记录、复盘文档、API 文档）
用户: 内容是否达标？是否继续执行下一阶段？

进入代码生成阶段

用户: d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\docs\requirements\sub\2026-01-28-004-08-SOQL查询功能.md 进入代码生成阶段，我已经使用代码生成器生成基础代码详细扫描一下
AI: 扫描代码生成器输出，发现已生成 14 个基础代码文件
AI: 确认需要手动实现 6 个代码文件（Controller、Service、DTO、ErrorCode）

代码生成完成

AI: 已生成所有手动实现代码文件
- ToolingSoqlQueryController.java（5 个 REST API 接口）
- IToolingSoqlQueryService.java / ToolingSoqlQueryServiceImpl.java
- ToolingSoqlQueryRequestDTO.java / ToolingSoqlQueryResultDTO.java
- ToolingSoqlErrorCode.java（6 个错误码）
AI: 已更新索引和设计文档
AI: 已创建会话记录
用户: 进入下一阶段（阶段 7：记录当前会话）

生成的文档

生成的代码文件

代码生成器生成文件（14 个）

datai-salesforce-tooling/src/main/java/com/datai/tooling/model/domain/DataiToolingSoqlQueryLog.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/model/domain/DataiToolingSoqlQueryResult.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/mapper/DataiToolingSoqlQueryLogMapper.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/mapper/DataiToolingSoqlQueryResultMapper.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/service/IDataiToolingSoqlQueryLogService.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/service/IDataiToolingSoqlQueryResultService.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/service/impl/DataiToolingSoqlQueryLogServiceImpl.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/service/impl/DataiToolingSoqlQueryResultServiceImpl.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/DataiToolingSoqlQueryLogController.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/DataiToolingSoqlQueryResultController.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/model/dto/DataiToolingSoqlQueryLogDto.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/model/dto/DataiToolingSoqlQueryResultDto.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/model/vo/DataiToolingSoqlQueryLogVo.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/model/vo/DataiToolingSoqlQueryResultVo.java

手动实现文件（6 个）

datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/ToolingSoqlQueryController.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/service/IToolingSoqlQueryService.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/service/impl/ToolingSoqlQueryServiceImpl.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/enums/ToolingSoqlErrorCode.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/dto/ToolingSoqlQueryRequestDTO.java
datai-salesforce-tooling/src/main/java/com/datai/tooling/dto/ToolingSoqlQueryResultDTO.java

回退记录

无

下一步行动

阶段 9 已完成，建议进入阶段 10：代码提交。

16 KiB Raw Blame History Unescape Escape

会话记录 - SOQL 查询功能 (004-08)

元数据

需求描述

执行阶段

阶段 1：需求定义与入库

阶段 2：方案设计

阶段 3：方案决策

阶段 4：数据库结构生成

阶段 5：提示词生成

阶段 6：执行代码生成

阶段 7：记录当前会话

阶段 8：变更记录与归档

阶段 9：闭环复盘和接口文档

阶段 6：执行代码生成

现状与目标

代码生成器扫描结果

手动实现的代码文件

1. Controller 层

2. Service 层

3. DTO 类

4. ErrorCode 枚举

技术实现要点

1. SOQL 查询执行

2. 自动分页处理

3. SoqlBuilder 支持

4. 异步日志记录

5. 异常处理

AI 的质疑与决策

质疑 1：是否需要支持所有 Tooling API 对象？

质疑 2：如何处理查询结果超过 50000 条的情况？

质疑 3：是否需要提供原生 QueryResult 返回？

复现步骤

生成的代码文件清单

代码生成器生成文件

手动实现文件

对话记录

2026-02-06 会话开始

更新相关文档索引

进入代码生成阶段

代码生成完成

生成的文档

生成的代码文件

代码生成器生成文件（14 个）

手动实现文件（6 个）

回退记录

下一步行动

相关文档链接

16 KiB

Raw Blame History