kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/prompts/2026-02-03-004-08-prompt-SOQL查询功能.md

11 KiB
Raw Permalink Blame History

提示词：SOQL 查询功能

引用真源

需求描述

根据需求文档，实现 Tooling API SOQL 查询功能，包括：

  1. 执行 SOQL 查询（executeQuery）
  2. 获取更多查询结果（queryMore）
  3. 查询所有结果（queryAll，自动处理分页）
  4. 使用 SoqlBuilder 执行查询（executeQuery with SoqlBuilder）
  5. 使用 SoqlBuilder 查询所有结果（queryAll with SoqlBuilder）
  6. 获取查询日志（getLogs）
  7. 支持所有 Tooling API 对象的查询
  8. 支持复杂的查询条件、排序、分页
  9. 所有操作都记录到数据库（datai_tooling_soql_query_log 表）

设计方案

根据设计文档和决策记录，采用以下技术方案：

  1. 复用子需求 004-01 实现的 ToolingConnectionFactory，使用 getConnection("source") 获取连接
  2. 使用 CompletableFuture 异步记录操作日志，不影响主流程性能
  3. 使用 datai-salesforce-common 模块的异常体系，统一处理各种异常情况
  4. 使用 SoqlBuilder 构建 SOQL 查询语句，简化查询逻辑
  5. 遵循 RESTful API 设计规范，接口清晰易懂
  6. 使用 MyBatis Plus 进行数据库操作
  7. 使用若依框架的 @PreAuthorize 注解进行权限控制
  8. 使用若依框架的 @DataScope 注解进行数据权限控制
  9. 使用若依框架的 @Log 注解记录操作日志
  10. 使用若依框架的 GlobalExceptionHandler 处理异常

输出格式要求

必须包含以下文件

Controller 层

  • ToolingSoqlQueryController.java
    • 路径：datai-salesforce-tooling/src/main/java/com/datai/salesforce/tooling/controller/ToolingSoqlQueryController.java
    • 功能：提供 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 - 获取查询日志

Service 层

  • IToolingSoqlQueryService.java

    • 路径：datai-salesforce-tooling/src/main/java/com/datai/salesforce/tooling/service/IToolingSoqlQueryService.java
    • 功能：Service 接口定义

  • ToolingSoqlQueryServiceImpl.java

    • 路径：datai-salesforce-tooling/src/main/java/com/datai/salesforce/tooling/service/impl/ToolingSoqlQueryServiceImpl.java
    • 功能：Service 实现

  • IAsyncLogService.java

    • 路径：datai-salesforce-tooling/src/main/java/com/datai/salesforce/tooling/service/IAsyncLogService.java
    • 功能：异步日志记录 Service 接口定义

  • AsyncLogServiceImpl.java

    • 路径：datai-salesforce-tooling/src/main/java/com/datai/salesforce/tooling/service/impl/AsyncLogServiceImpl.java
    • 功能：异步日志记录 Service 实现

Mapper 层

  • ToolingSoqlQueryLogMapper.java
    • 路径：datai-salesforce-tooling/src/main/java/com/datai/salesforce/tooling/mapper/ToolingSoqlQueryLogMapper.java
    • 功能：MyBatis Plus Mapper 接口

Domain 层

  • ToolingSoqlQueryLog.java

    • 路径：datai-salesforce-tooling/src/main/java/com/datai/salesforce/tooling/domain/ToolingSoqlQueryLog.java
    • 功能：操作日志实体类

  • ToolingSoqlQueryRequest.java

    • 路径：datai-salesforce-tooling/src/main/java/com/datai/salesforce/tooling/domain/dto/ToolingSoqlQueryRequest.java
    • 功能：SOQL 查询请求 DTO

  • ToolingSoqlQueryResult.java

    • 路径：datai-salesforce-tooling/src/main/java/com/datai/salesforce/tooling/domain/dto/ToolingSoqlQueryResult.java
    • 功能：SOQL 查询结果 DTO

  • ToolingSoqlQueryLogVO.java

    • 路径：datai-salesforce-tooling/src/main/java/com/datai/salesforce/tooling/domain/vo/ToolingSoqlQueryLogVO.java
    • 功能：操作日志 VO

Enums 层

  • ToolingSoqlErrorCode.java
    • 路径：datai-salesforce-tooling/src/main/java/com/datai/salesforce/tooling/enums/ToolingSoqlErrorCode.java
    • 功能：SOQL 查询错误码枚举

必须包含单元测试

  • ToolingSoqlQueryServiceImplTest.java

    • 路径：datai-salesforce-tooling/src/test/java/com/datai/salesforce/tooling/service/impl/ToolingSoqlQueryServiceImplTest.java
    • 功能：Service 层单元测试

  • ToolingSoqlQueryControllerTest.java

    • 路径：datai-salesforce-tooling/src/test/java/com/datai/salesforce/tooling/controller/ToolingSoqlQueryControllerTest.java
    • 功能：Controller 层单元测试

必须符合以下规范

  1. 必须符合 Spring Boot 最佳实践
  2. 必须遵循若依框架规范
  3. 必须使用 MyBatis Plus 进行数据库操作
  4. 必须使用 Lombok 简化代码
  5. 必须使用 Jakarta Validation 进行请求参数校验
  6. 必须使用 CompletableFuture 异步记录日志
  7. 必须使用自定义线程池进行异步操作

代码规范要求

类命名规范

  1. Controller 类：XxxController，如 ToolingSoqlQueryController
  2. Service 接口：IXxxService，如 IToolingSoqlQueryService
  3. Service 实现：XxxServiceImpl，如 ToolingSoqlQueryServiceImpl
  4. Mapper 接口：XxxMapper，如 ToolingSoqlQueryLogMapper
  5. Entity 类：Xxx，如 ToolingSoqlQueryLog
  6. DTO 类：XxxRequest、XxxResult，如 ToolingSoqlQueryRequest、ToolingSoqlQueryResult
  7. VO 类：XxxVO，如 ToolingSoqlQueryLogVO
  8. Enum 类：XxxErrorCode，如 ToolingSoqlErrorCode

方法命名规范

  1. Controller 方法：使用动词，如 executeQuery、queryMore、queryAll、getLogs
  2. Service 方法：使用动词，如 executeQuery、queryMore、queryAll、saveLog
  3. Mapper 方法：遵循 MyBatis Plus 规范，如 selectList、selectById、insert

变量命名规范

  1. 类成员变量：使用驼峰命名，如 queryString、queryLocator
  2. 局部变量：使用驼峰命名，如 startTime、endTime
  3. 常量：使用全大写下划线分隔，如 MAX_QUERY_SIZE

注释规范

  1. 类注释：使用 /** */，包含类功能描述、作者、创建时间
  2. 方法注释：使用 /** */，包含方法功能、参数、返回值、异常描述
  3. 字段注释：使用 /** */，包含字段功能描述
  4. 枚举注释：使用 /** */，包含枚举值说明

代码格式规范

  1. 使用 4 个空格缩进
  2. 行宽不超过 120 字符
  3. 左大括号不换行
  4. 右大括号独占一行
  5. if、for、while 等关键字后加空格

导入规范

  1. 使用 import 静态导入，避免通配符导入
  2. 导入顺序：Java 标准库、第三方库、项目内部类
  3. 每组导入之间空一行

异常处理规范

  1. 使用 datai-salesforce-common 模块的异常体系
  2. 捕获 Salesforce ConnectionException，转换为自定义异常
  3. 使用 try-catch-finally 确保资源释放
  4. 在 finally 块中记录日志

日志规范

  1. 使用 SLF4J + Logback
  2. 日志级别：ERROR（错误）、WARN（警告）、INFO（信息）、DEBUG（调试）
  3. 使用占位符：log.error("查询失败: {}", e.getMessage())
  4. 异常日志必须包含堆栈信息

测试要求

单元测试要求

  1. 单元测试覆盖率不低于 80%
  2. 测试用例包含以下场景：
    • 正常查询成功
    • 查询失败（语法错误）
    • Session 无效
    • 用户未登录
    • 权限不足
    • 查询定位器无效
    • 查询结果超出限制
    • 异步日志记录成功
    • 异步日志记录失败
  3. 使用 JUnit 5 和 Mockito 进行测试
  4. 测试用例命名规范：test+方法名+场景，如 testExecuteQuerySuccess
  5. 测试数据使用 Mockito 模拟

集成测试要求

  1. 测试完整的请求流程
  2. 测试数据库操作
  3. 测试异常处理
  4. 测试异步日志记录

测试数据准备

  1. 使用 @BeforeEach 初始化测试数据
  2. 使用 @AfterEach 清理测试数据
  3. 使用 @TestConfiguration 配置测试环境

注意事项

Salesforce API 约束

  1. 不支持 SELECT *，必须明确指定字段或使用 FIELDS()
  2. 不支持 BETWEEN 运算符，使用 >= 和 <= 组合代替
  3. 不支持 JOIN，使用关系查询（Relationship Queries）
  4. 不支持 UNION，无法合并两个不相关的结果集
  5. 支持的运算符：=, !=, >, >=, <, <=, LIKE, IN, NOT IN, = NULL, != NULL
  6. 支持的子句：WHERE, GROUP BY, HAVING, ORDER BY, LIMIT, OFFSET
  7. 查询最多返回 50000 条记录
  8. OFFSET 上限为 2000，且必须与 LIMIT 一起使用
  9. 查询定位器（queryLocator）有有效期限制，过期后需要重新查询

若依框架集成

  1. 必须使用若依的 @PreAuthorize 注解进行权限控制
  2. 必须使用若依的 @DataScope 注解进行数据权限控制
  3. 必须使用若依的 @Log 注解记录操作日志
  4. 必须使用若依的 GlobalExceptionHandler 处理异常
  5. 必须使用若依的 AjaxResult 作为统一响应格式
  6. 必须使用若依的 TableDataInfo 作为分页响应格式

异常处理

  1. Session 无效异常：INVALID_SESSION_ID -> SalesforceAuthException（TOOLING_SOQL_001）
  2. 查询失败异常：MALFORMED_QUERY、INVALID_QUERY、QUERY_TIMEOUT -> SalesforceAuthException（TOOLING_SOQL_002）
  3. 权限不足异常：INSUFFICIENT_ACCESS -> SalesforceAuthException（TOOLING_SOQL_003）
  4. 未登录异常：SessionManager 返回 null 或 Session 已过期 -> SalesforceLoginException（TOOLING_SOQL_004）
  5. 查询定位器无效异常：queryLocator 无效或已过期 -> SalesforceAuthException（TOOLING_SOQL_005）
  6. 查询结果超出限制异常：查询结果超过 50000 条记录 -> SalesforceAuthException（TOOLING_SOQL_006）

异步日志记录

  1. 使用 CompletableFuture.runAsync() 异步执行日志记录
  2. 使用自定义线程池，避免影响主线程池
  3. 日志记录失败不影响主操作结果
  4. 记录日志记录失败到系统日志
  5. 使用 @Async 注解标记异步方法

性能优化

  1. 记录查询执行时间，用于性能监控
  2. 使用连接缓存，避免重复创建连接
  3. 使用异步日志记录，避免影响主操作性能
  4. 合理设置线程池大小

安全性

  1. 验证 SOQL 查询字符串，防止 SQL 注入
  2. 限制查询结果数量，防止资源耗尽
  3. 记录所有查询操作，便于审计
  4. 使用权限注解控制接口访问

元数据

  • 需求编号：004
  • 子需求编号：004-08
  • 子需求名称：SOQL 查询功能
  • 阶段：阶段 5：提示词生成
  • 创建时间：2026-02-03
  • 创建人：AI Assistant
  • 状态：已完成