datai/docs/archive/changelog/2026-01-27-014-3-changelog.md

变更日志

元数据

• 需求编号：014-3
• 创建时间：2026-01-27
• 创建人：SSOT 架构师
• 版本号：v1.0.0

变更概述

实现 Apex 业务逻辑执行与日志管理功能，利用 Tooling API 的 ExecuteAnonymous、TraceFlag、DebugLevel 和 ApexLog 对象，支持动态执行 Apex 代码、配置持久化调试级别、获取和分析日志，为生产环境问题排查提供强大的调试能力。

变更内容

新增功能

• 实现匿名 Apex 执行功能，通过 Tooling API 的 executeAnonymous 方法执行 Apex 代码
• 实现持久化调试配置管理，支持 TraceFlag 和 DebugLevel 对象的 CRUD 操作
• 实现日志获取功能，通过 Tooling API 的 retrieve 方法获取 ApexLog 对象
• 实现日志解析功能，解析 ApexLog 的 Body 字段，提取 USER_DEBUG 行
• 实现 TraceFlag 并发控制，确保同一用户同一时间只能有一个生效的 TraceFlag
• 实现 RESTful API 接口，提供匿名执行、调试配置管理和日志获取功能
• 实现权限控制和参数验证，确保 API 安全性
• 实现完整的单元测试，测试覆盖率不低于 80%

新增文档

• 需求文档 - Apex 业务逻辑执行与日志管理需求
• 设计文档 - Apex 业务逻辑执行与日志管理设计
• 决策记录 - Apex 执行与日志管理技术选型
• 提示词文档 - Apex 业务逻辑执行与日志管理提示词
• 会话记录 - Apex 业务逻辑执行与日志管理实现会话记录

新增代码文件

Controller 层（3个）

• datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/ApexExecutorController.java - 匿名 Apex 执行控制器
• datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/DebugConfigController.java - 调试配置控制器
• datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/LogRetrieverController.java - 日志获取控制器

Service 层（6个）

• datai-salesforce-tooling/src/main/java/com/datai/tooling/service/IAnonymousExecutorService.java - 匿名执行器服务接口
• datai-salesforce-tooling/src/main/java/com/datai/tooling/service/impl/AnonymousExecutorServiceImpl.java - 匿名执行器服务实现
• datai-salesforce-tooling/src/main/java/com/datai/tooling/service/IDebugConfigService.java - 调试配置服务接口
• datai-salesforce-tooling/src/main/java/com/datai/tooling/service/impl/DebugConfigServiceImpl.java - 调试配置服务实现
• datai-salesforce-tooling/src/main/java/com/datai/tooling/service/ILogRetrieverService.java - 日志获取服务接口
• datai-salesforce-tooling/src/main/java/com/datai/tooling/service/impl/LogRetrieverServiceImpl.java - 日志获取服务实现

Manager 层（3个）

• datai-salesforce-tooling/src/main/java/com/datai/tooling/manager/AnonymousExecutorManager.java - 匿名执行器管理器
• datai-salesforce-tooling/src/main/java/com/datai/tooling/manager/DebugConfigManager.java - 调试配置管理器
• datai-salesforce-tooling/src/main/java/com/datai/tooling/manager/LogRetrieverManager.java - 日志获取管理器

Model 层（14个）

• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/domain/TraceFlag.java - TraceFlag 实体类
• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/domain/DebugLevel.java - DebugLevel 实体类
• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/domain/ApexLog.java - ApexLog 实体类
• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/dto/ExecuteApexRequest.java - 执行 Apex 请求
• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/dto/ExecuteApexResponse.java - 执行 Apex 响应
• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/dto/CreateTraceFlagRequest.java - 创建 TraceFlag 请求
• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/dto/UpdateTraceFlagRequest.java - 更新 TraceFlag 请求
• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/dto/CreateDebugLevelRequest.java - 创建 DebugLevel 请求
• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/dto/UpdateDebugLevelRequest.java - 更新 DebugLevel 请求
• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/dto/GetLogRequest.java - 获取日志请求
• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/vo/ExecuteApexVo.java - 执行 Apex 视图对象
• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/vo/TraceFlagVo.java - TraceFlag 视图对象
• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/vo/DebugLevelVo.java - DebugLevel 视图对象
• datai-salesforce-tooling/src/main/java/com/datai/tooling/model/vo/ApexLogVo.java - ApexLog 视图对象

Exception 层（3个）

• datai-salesforce-tooling/src/main/java/com/datai/tooling/exception/ApexExecutionException.java - Apex 执行异常
• datai-salesforce-tooling/src/main/java/com/datai/tooling/exception/DebugConfigException.java - 调试配置异常
• datai-salesforce-tooling/src/main/java/com/datai/tooling/exception/LogRetrievalException.java - 日志获取异常

Enums 层（3个）

• datai-salesforce-tooling/src/main/java/com/datai/tooling/enums/LogCategory.java - 日志类别枚举
• datai-salesforce-tooling/src/main/java/com/datai/tooling/enums/LogLevel.java - 日志级别枚举
• datai-salesforce-tooling/src/main/java/com/datai/tooling/enums/DebugScope.java - 调试范围枚举

修改功能

• 无

删除功能

• 无

修复 Bug

• 无

性能优化

• 优化 Tooling API 连接管理，复用连接工厂
• 优化日志解析性能，提供可选的日志解析功能
• 优化 TraceFlag 并发控制，减少不必要的 API 调用

安全增强

• 添加权限控制，使用 @PreAuthorize 注解进行权限验证
• 添加参数验证，防止注入攻击
• 添加日志脱敏，保护敏感信息

影响范围

模块影响

• datai-salesforce-tooling：新增 Apex 执行、调试配置和日志获取功能
• datai-salesforce-integration：复用 AbstractConnectionFactory 和 ConnectionProxy
• datai-salesforce-auth：复用 SessionManager

API 影响

• 新增 11 个 RESTful API 接口：
  • POST /api/tooling/apex/execute - 执行匿名 Apex 代码
  • POST /api/tooling/traceflag/create - 创建 TraceFlag
  • PUT /api/tooling/traceflag/update - 更新 TraceFlag
  • DELETE /api/tooling/traceflag/delete/{id} - 删除 TraceFlag
  • GET /api/tooling/traceflag/list - 查询 TraceFlag 列表
  • POST /api/tooling/debuglevel/create - 创建 DebugLevel
  • PUT /api/tooling/debuglevel/update - 更新 DebugLevel
  • DELETE /api/tooling/debuglevel/delete/{id} - 删除 DebugLevel
  • GET /api/tooling/debuglevel/list - 查询 DebugLevel 列表
  • GET /api/tooling/log/{logId} - 获取日志详情
  • GET /api/tooling/log/list - 查询日志列表

数据库影响

• 无（直接操作 Salesforce Tooling API 对象）

配置影响

• 无

依赖变更

新增依赖

• 无

修改依赖

• 无

删除依赖

• 无

兼容性

向后兼容性

• 完全兼容，不影响现有功能

向前兼容性

• 完全兼容，不影响未来功能

API 兼容性

• 新增 API 接口，不影响现有 API

测试

单元测试

• 新增 6 个单元测试类：
  • AnonymousExecutorServiceImplTest.java - 匿名执行器服务测试
  • DebugConfigServiceImplTest.java - 调试配置服务测试
  • LogRetrieverServiceImplTest.java - 日志获取服务测试
  • AnonymousExecutorManagerTest.java - 匿名执行器管理器测试
  • DebugConfigManagerTest.java - 调试配置管理器测试
  • LogRetrieverManagerTest.java - 日志获取管理器测试

集成测试

• 待补充

性能测试

• 待补充

部署说明

部署步骤

1. 编译项目：mvn clean package
2. 部署到应用服务器
3. 配置 Salesforce 连接信息
4. 重启应用

回滚步骤

1. 停止应用
2. 回滚到上一个版本
3. 重启应用

注意事项

• 确保 Salesforce 连接信息正确配置
• 确保操作 TraceFlag 的用户具有 View All Data 权限

相关文档

• 需求文档
• 设计文档
• 决策记录
• 提示词文档
• 会话记录