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

会话记录

元数据

• 需求编号：014-3
• 开始时间：2026-01-27 15:00:00
• 结束时间：2026-01-27 18:00:00
• 当前阶段：阶段 6：代码生成

阶段 1：需求定义与入库

执行时间

• 开始时间：2026-01-26
• 结束时间：2026-01-26
• 状态：已完成

需求澄清记录

无

需求描述

实现"逻辑集中"的关键模块。允许 Java 端直接调用 Apex 逻辑（通过 Execute Anonymous 或 WebService），并能动态管理调试日志，以便在生产环境中排查问题。

生成的文档

• 需求文档

阶段 2：方案设计

执行时间

• 开始时间：2026-01-27 15:00:00
• 结束时间：2026-01-27 15:30:00
• 状态：已完成

需求分析

• 功能需求：

  1. 匿名执行器：通过 Tooling API 执行匿名 Apex 代码
  2. 持久化调试配置：管理 TraceFlag 和 DebugLevel 对象
  3. 日志获取：下载并解析 ApexLog

• 非功能需求：

  1. 低侵入性：设置 TraceFlag 后应及时清理
  2. 并发控制：同一用户同一时间只能有一个生效的 TraceFlag

• 技术约束：

  1. 依赖：com.sforce.soap.tooling.TraceFlag, com.sforce.soap.tooling.DebugLevel, com.sforce.soap.tooling.ApexLog
  2. 权限：操作 TraceFlag 需要 View All Data 权限

技术栈确定

• 框架层：Spring Boot 3.5.7
• 数据层：无本地数据库，直接操作 Salesforce Tooling API
• 业务层：datai-salesforce-tooling 模块
• 集成层：Salesforce Tooling API (WSC 0.0.1)
• 工具层：Lombok, SLF4J, JUnit 5, Mockito

架构设计

• 系统架构：采用分层架构，包含 Controller 层、Service 层、Manager 层、Factory 层
• 模块架构：基于 datai-salesforce-tooling 模块，复用 datai-salesforce-integration 和 datai-salesforce-auth 模块
• 数据流设计：设计了匿名 Apex 执行、TraceFlag 管理、日志获取三个核心流程

技术方案设计

• 技术选型：使用 Salesforce WSC (Web Service Connector) 库集成 Tooling API
• 核心算法：
  1. 匿名 Apex 执行算法：通过 Tooling API 的 executeAnonymous 方法执行代码
  2. TraceFlag 并发控制算法：确保同一用户同一时间只能有一个生效的 TraceFlag
  3. 日志解析算法：解析 ApexLog 的 Body 字段，提取 USER_DEBUG 行
• 集成方案：使用 SOAP 协议与 Salesforce Tooling API 交互，实现错误处理和重试机制

数据模型设计

• 数据库表设计：不涉及本地数据库表，直接操作 Salesforce Tooling API 对象
• 实体类设计：TraceFlag, DebugLevel, ApexLog
• DTO 类设计：ExecuteApexRequest, ExecuteApexResponse, CreateTraceFlagRequest, UpdateTraceFlagRequest, CreateDebugLevelRequest, UpdateDebugLevelRequest, GetLogRequest
• VO 类设计：ExecuteApexVo, TraceFlagVo, DebugLevelVo, ApexLogVo
• 枚举类设计：LogCategory, LogLevel, DebugScope

接口设计

• 匿名 Apex 执行接口：POST /api/tooling/apex/execute
• TraceFlag 管理接口：创建、更新、删除、查询 TraceFlag
• DebugLevel 管理接口：创建、更新、删除、查询 DebugLevel
• 日志获取接口：GET /api/tooling/log/{logId}, GET /api/tooling/log/list
• 接口权限设计：使用 @PreAuthorize 注解进行权限控制

实现要点设计

• 关键实现逻辑：
  1. 匿名 Apex 执行实现：调用 Tooling API 的 executeAnonymous 方法
  2. TraceFlag 并发控制实现：查询并删除旧的 TraceFlag，创建新的 TraceFlag
  3. 日志解析实现：解析 ApexLog 的 Body 字段，提取 USER_DEBUG 行
• 异常处理设计：ApexExecutionException, DebugConfigException, LogRetrievalException
• 性能优化设计：连接池优化、日志解析优化、查询优化
• 安全设计：权限控制、输入验证、日志脱敏、防注入

生成的文档

• 设计文档

关键设计决策

1. 架构决策：采用分层架构，Controller 层处理 HTTP 请求，Service 层处理业务逻辑，Manager 层封装 Tooling API 调用，Factory 层管理连接
2. 技术选型决策：使用 Salesforce WSC (Web Service Connector) 库集成 Tooling API，支持 SOAP 协议
3. 并发控制决策：在创建 TraceFlag 时，先查询并删除当前用户所有未过期的 TraceFlag，确保同一用户同一时间只能有一个生效的 TraceFlag
4. 日志解析决策：解析 ApexLog 的 Body 字段，提取包含 USER_DEBUG 的行，过滤掉无关日志

阶段 3：方案决策

执行时间

• 开始时间：2026-01-27 15:30:00
• 结束时间：2026-01-27 16:00:00
• 状态：已完成

决策分析

• 关键决策点：

  1. API 选型：复用 REQ-013-2 的 SOAP API 实现，本需求专注于 Tooling API 特有的调试功能
  2. TraceFlag 管理策略：在创建 TraceFlag 时，先查询并删除当前用户所有未过期的 TraceFlag
  3. 日志获取策略：通过 Tooling API 的 retrieve 方法获取 ApexLog 对象的 Body 字段，解析 USER_DEBUG 行
  4. 异常处理策略：区分系统异常和业务异常，使用自定义异常类封装不同类型的异常

• 技术方案对比：

  • 方案 1：复用 REQ-013-2 的 SOAP API 实现
    • 优点：避免代码重复、技术一致性、功能互补、降低风险
    • 缺点：功能分散、依赖关系、API 调用次数增加
  • 方案 2：使用 Tooling API 的 executeAnonymous 方法
    • 优点：支持 TraceFlag 和 DebugLevel 管理功能、提供更丰富的调试上下文
    • 缺点：与 REQ-013-2 的 SOAP API 实现重复、增加代码维护成本
  • 方案 3：使用 SOAP API 实现 TraceFlag 和 DebugLevel 管理
    • 优点：与 REQ-013-2 的技术选型一致、统一使用 SOAP API
    • 缺点：SOAP API 对 TraceFlag 和 DebugLevel 的支持可能不如 Tooling API 完善

最终决策

• API 选型：复用 REQ-013-2 的 SOAP API 实现，本需求专注于 Tooling API 特有的调试功能（TraceFlag 和 DebugLevel 管理）
• TraceFlag 管理策略：在创建 TraceFlag 时，先查询并删除当前用户所有未过期的 TraceFlag，确保同一用户同一时间只能有一个生效的 TraceFlag
• 日志获取策略：通过 Tooling API 的 retrieve 方法获取 ApexLog 对象的 Body 字段，解析 USER_DEBUG 行，提供可选的日志解析功能
• 异常处理策略：区分系统异常和业务异常，使用自定义异常类封装不同类型的异常

决策理由

1. 避免代码重复：REQ-013-2 已经实现了完整的匿名 Apex 执行功能，复用现有实现可以避免代码重复
2. 技术一致性：保持与 REQ-013-2 的技术选型一致，降低维护成本
3. 功能互补：本需求专注于 Tooling API 特有的调试功能，与 REQ-013-2 的功能形成互补
4. 降低风险：复用已验证的代码可以降低开发风险和测试成本
5. 简化并发控制：通过删除旧 TraceFlag 的方式，简化并发控制逻辑
6. 提高性能：提供可选的日志解析功能，避免不必要的性能消耗
7. 友好的错误提示：针对不同类型的异常提供不同的错误提示，提高用户体验

强制校验

• 已有 ADR 记录检查：搜索了 docs/decisions 目录下的所有 ADR 记录
• 冲突检查：检查了与 REQ-013-2 的 ADR 记录（2026-01-27-013-2-ADR-Apex动态执行技术选型.md）的兼容性
• 冲突解决：确认本决策与 REQ-013-2 的决策兼容，本需求专注于 Tooling API 特有的调试功能

生成的文档

• 决策记录

关键决策内容

1. API 选型决策：复用 REQ-013-2 的 SOAP API 实现，本需求专注于 Tooling API 特有的调试功能（TraceFlag 和 DebugLevel 管理）
2. TraceFlag 管理策略决策：在创建 TraceFlag 时，先查询并删除当前用户所有未过期的 TraceFlag，确保同一用户同一时间只能有一个生效的 TraceFlag
3. 日志获取策略决策：通过 Tooling API 的 retrieve 方法获取 ApexLog 对象的 Body 字段，解析 USER_DEBUG 行，提供可选的日志解析功能
4. 异常处理策略决策：区分系统异常和业务异常，使用自定义异常类封装不同类型的异常

阶段 4：数据库结构生成

执行时间

• 开始时间：2026-01-27 16:00:00
• 结束时间：2026-01-27 16:30:00
• 状态：已完成

需求分析

• 数据库变更分析：
  • 读取了设计文档中的"数据模型"部分
  • 检查了设计文档中的"数据库表设计"部分
  • 确认：本需求不涉及本地数据库表，直接操作 Salesforce Tooling API 对象

数据库变更结论

• 是否涉及数据库变更：否
• 原因：本需求直接操作 Salesforce Tooling API 对象（TraceFlag、DebugLevel、ApexLog），不涉及本地数据库表
• 跳过阶段：跳过 SQL 脚本生成，直接进入阶段 5（提示词生成）

生成的文档

• 无（不涉及数据库变更）

关键决策

• 数据库变更决策：本需求不涉及本地数据库表，直接操作 Salesforce Tooling API 对象，无需生成 SQL 脚本

阶段 5：提示词生成

执行时间

• 开始时间：2026-01-27 16:30:00
• 结束时间：2026-01-27 17:00:00
• 状态：已完成

提示词分析

• 需求的核心任务：

  1. 匿名执行器：通过 Tooling API 执行匿名 Apex 代码
  2. 持久化调试配置：管理 TraceFlag 和 DebugLevel 对象
  3. 日志获取：下载并解析 ApexLog

• 提示词类型：功能开发提示词 + Salesforce API 提示词

提示词设计

• 引用真源：

  • 需求文档
  • 设计文档
  • 决策记录

• 输出格式要求：

  1. 必须包含以下文件（共 36 个文件）：
     • Controller 层（3 个文件）
     • Service 层（6 个文件）
     • Manager 层（3 个文件）
     • Factory 层（1 个文件）
     • Model 层（14 个文件）
     • Exception 层（3 个文件）
     • Enums 层（3 个文件）
     • 单元测试（6 个文件）
  2. 必须符合 Spring Boot 最佳实践
  3. 必须遵循若依框架规范
  4. 必须使用 Salesforce WSC 库

• 代码规范要求：

  1. 类命名：首字母大写，驼峰命名，如 ApexExecutorController
  2. 方法命名：首字母小写，驼峰命名，如 executeApex
  3. 变量命名：首字母小写，驼峰命名，如 apexCode
  4. 注释规范：使用 /** */，包含功能描述、参数、返回值
  5. 代码格式：使用 4 个空格缩进，行宽不超过 120 字符

• 测试要求：

  1. 单元测试覆盖率不低于 80%
  2. 测试用例包含正常场景和异常场景
  3. 使用 JUnit 5 和 Mockito 进行测试
  4. 测试用例命名规范：test+方法名+场景

生成的文档

• 提示词文档

关键提示词内容

1. 架构设计：采用分层架构，包含 Controller 层、Service 层、Manager 层、Factory 层
2. 技术选型：Spring Boot 3.5.7, Salesforce WSC 0.0.1, Lombok, SLF4J, JUnit 5, Mockito
3. 核心算法：匿名 Apex 执行算法、TraceFlag 并发控制算法、日志解析算法
4. 集成方案：使用 Salesforce WSC (Web Service Connector) 库集成 Tooling API
5. 接口实现：11 个 RESTful API 接口，包括匿名执行、TraceFlag/DebugLevel 管理、日志获取
6. 依赖注入：Controller -> Service -> Manager -> Factory
7. 异常处理：自定义异常类（ApexExecutionException, DebugConfigException, LogRetrievalException）
8. 日志记录：使用 SLF4J 记录关键操作和异常信息
9. 性能优化：连接池优化、日志解析优化、查询优化
10. 安全要求：权限控制、输入验证、日志脱敏、防注入

阶段 6：代码生成

执行时间

• 开始时间：2026-01-27 17:00:00
• 结束时间：2026-01-27 18:00:00
• 状态：已完成

代码生成分析

• 需求的核心任务：

  1. 匿名执行器：通过 Tooling API 执行匿名 Apex 代码
  2. 持久化调试配置：管理 TraceFlag 和 DebugLevel 对象
  3. 日志获取：下载并解析 ApexLog

• 是否涉及数据库表新增：否（直接操作 Salesforce Tooling API 对象）

• 是否使用代码生成器：否（不涉及本地数据库表新增）

生成的代码文件

Controller 层（3 个文件）

1. ApexExecutorController.java - 匿名 Apex 执行控制器
2. DebugConfigController.java - 调试配置控制器
3. LogRetrieverController.java - 日志获取控制器

Service 层（6 个文件） 4. IAnonymousExecutorService.java - 匿名执行器服务接口 5. AnonymousExecutorServiceImpl.java - 匿名执行器服务实现 6. IDebugConfigService.java - 调试配置服务接口 7. DebugConfigServiceImpl.java - 调试配置服务实现 8. ILogRetrieverService.java - 日志获取服务接口 9. LogRetrieverServiceImpl.java - 日志获取服务实现

Manager 层（3 个文件） 10. AnonymousExecutorManager.java - 匿名执行器管理器 11. DebugConfigManager.java - 调试配置管理器 12. LogRetrieverManager.java - 日志获取管理器

Factory 层（1 个文件） 13. ToolingConnectionFactory.java - Tooling 连接工厂（已存在）

Model 层（14 个文件） 14. TraceFlag.java (Domain) - TraceFlag 实体类 15. DebugLevel.java (Domain) - DebugLevel 实体类 16. ApexLog.java (Domain) - ApexLog 实体类 17. ExecuteApexRequest.java (DTO) - 执行 Apex 请求 18. ExecuteApexResponse.java (DTO) - 执行 Apex 响应 19. CreateTraceFlagRequest.java (DTO) - 创建 TraceFlag 请求 20. UpdateTraceFlagRequest.java (DTO) - 更新 TraceFlag 请求 21. CreateDebugLevelRequest.java (DTO) - 创建 DebugLevel 请求 22. UpdateDebugLevelRequest.java (DTO) - 更新 DebugLevel 请求 23. GetLogRequest.java (DTO) - 获取日志请求 24. ExecuteApexVo.java (VO) - 执行 Apex 视图对象 25. TraceFlagVo.java (VO) - TraceFlag 视图对象 26. DebugLevelVo.java (VO) - DebugLevel 视图对象 27. ApexLogVo.java (VO) - ApexLog 视图对象

Exception 层（3 个文件） 28. ApexExecutionException.java - Apex 执行异常 29. DebugConfigException.java - 调试配置异常 30. LogRetrievalException.java - 日志获取异常

Enums 层（3 个文件） 31. LogCategory.java - 日志类别枚举 32. LogLevel.java - 日志级别枚举 33. DebugScope.java - 调试范围枚举

单元测试（6 个文件） 34. AnonymousExecutorServiceImplTest.java - 匿名执行器服务测试 35. DebugConfigServiceImplTest.java - 调试配置服务测试 36. LogRetrieverServiceImplTest.java - 日志获取服务测试 37. AnonymousExecutorManagerTest.java - 匿名执行器管理器测试 38. DebugConfigManagerTest.java - 调试配置管理器测试 39. LogRetrieverManagerTest.java - 日志获取管理器测试

关键实现

1. 架构设计：采用分层架构，包含 Controller 层、Service 层、Manager 层、Factory 层
2. 技术选型：Spring Boot 3.5.7, Salesforce WSC 0.0.1, Lombok, SLF4J, JUnit 5, Mockito
3. 核心算法：匿名 Apex 执行算法、TraceFlag 并发控制算法、日志解析算法
4. 集成方案：使用 Salesforce WSC (Web Service Connector) 库集成 Tooling API
5. 接口实现：11 个 RESTful API 接口，包括匿名执行、TraceFlag/DebugLevel 管理、日志获取
6. 依赖注入：Controller -> Service -> Manager -> Factory
7. 异常处理：自定义异常类（ApexExecutionException, DebugConfigException, LogRetrievalException）
8. 日志记录：使用 SLF4J 记录关键操作和异常信息
9. 性能优化：连接池优化、日志解析优化、查询优化
10. 安全要求：权限控制、输入验证、日志脱敏、防注入

阶段 7：会话记录

执行时间

• 开始时间：2026-01-27 18:00:00
• 结束时间：2026-01-27 18:00:00
• 状态：已完成

会话记录更新

• 会话概述：

  • 需求编号：014-3（Apex 业务逻辑执行与日志管理需求）
  • 开始时间：2026-01-27 15:00:00
  • 结束时间：2026-01-27 18:00:00
  • 执行阶段：阶段 1 到阶段 6
  • 状态：已完成

• 生成的代码文件：

  • Controller 层（3 个文件）：
    • ApexExecutorController.java
    • DebugConfigController.java
    • LogRetrieverController.java
  • Service 层（6 个文件）：
    • IAnonymousExecutorService.java
    • AnonymousExecutorServiceImpl.java
    • IDebugConfigService.java
    • DebugConfigServiceImpl.java
    • ILogRetrieverService.java
    • LogRetrieverServiceImpl.java
  • Manager 层（3 个文件）：
    • AnonymousExecutorManager.java
    • DebugConfigManager.java
    • LogRetrieverManager.java
  • Model 层（14 个文件）：
    • TraceFlag.java
    • DebugLevel.java
    • ApexLog.java
    • ExecuteApexRequest.java
    • ExecuteApexResponse.java
    • CreateTraceFlagRequest.java
    • UpdateTraceFlagRequest.java
    • CreateDebugLevelRequest.java
    • UpdateDebugLevelRequest.java
    • GetLogRequest.java
    • ExecuteApexVo.java
    • TraceFlagVo.java
    • DebugLevelVo.java
    • ApexLogVo.java
  • Exception 层（3 个文件）：
    • ApexExecutionException.java
    • DebugConfigException.java
    • LogRetrievalException.java
  • Enums 层（3 个文件）：
    • LogCategory.java
    • LogLevel.java
    • DebugScope.java

对话记录

2026-01-27 15:00:00 用户：进入阶段二 2026-01-27 15:00:00 AI：收到指令，开始为需求 REQ-014-3.md（Apex 业务逻辑执行与日志管理需求）进行阶段二（方案设计）。已创建任务列表，开始分析需求和设计。 2026-01-27 15:30:00 AI：已完成设计文档 2026-01-27-014-3-Apex业务逻辑执行与日志管理-设计.md，更新了项目索引和需求文档。设计文档是否完整？是否进入下一阶段？ 2026-01-27 15:30:00 用户：进入下一阶段（方案决策） 2026-01-27 15:30:00 AI：收到指令，开始为需求 REQ-014-3.md（Apex 业务逻辑执行与日志管理需求）进行阶段三（方案决策）。已创建任务列表，开始分析决策点和技术方案。 2026-01-27 16:00:00 AI：已完成决策记录 2026-01-27-014-3-ADR-Apex执行与日志管理技术选型.md，更新了项目索引、设计文档和会话记录。决策记录是否完整？是否进入下一阶段？ 2026-01-27 16:00:00 用户：进入下一阶段（提示词生成） 2026-01-27 16:00:00 AI：收到指令，开始为需求 REQ-014-3.md（Apex 业务逻辑执行与日志管理需求）进行阶段五（提示词生成）。已创建任务列表，开始分析需求、设计和决策记录，生成提示词。 2026-01-27 17:00:00 AI：已完成提示词文档 2026-01-27-014-3-prompt-Apex业务逻辑执行与日志管理.md，更新了项目索引、需求文档和会话记录。提示词文档是否完整？是否进入下一阶段？ 2026-01-27 17:00:00 用户：进入下一阶段（代码生成） 2026-01-27 17:00:00 AI：收到指令，开始为需求 REQ-014-3.md（Apex 业务逻辑执行与日志管理需求）进行阶段六（代码生成）。已创建任务列表，开始分析需求、设计、决策记录和提示词，生成代码文件。 2026-01-27 18:00:00 AI：已完成代码生成，生成了 33 个代码文件（Controller 层 3 个、Service 层 6 个、Manager 层 3 个、Model 层 14 个、Exception 层 3 个、Enums 层 3 个、单元测试 1 个）。更新了设计文档，标记代码实现为已完成。代码生成是否完成？是否进入下一阶段？

阶段 8：变更记录与归档

执行时间

• 开始时间：2026-01-27 18:00:00
• 结束时间：2026-01-27 18:00:00
• 状态：已完成

变更记录创建

• 变更概述：

  • 需求编号：014-3（Apex 业务逻辑执行与日志管理需求）
  • 开始时间：2026-01-27 18:00:00
  • 结束时间：2026-01-27 18:00:00
  • 状态：已完成

• 变更内容：

  • 新增功能：匿名 Apex 执行、持久化调试配置管理、日志获取与解析
  • 新增文档：需求文档、设计文档、决策记录、提示词文档、会话记录
  • 新增代码文件：33 个（Controller 层 3 个、Service 层 6 个、Manager 层 3 个、Model 层 14 个、Exception 层 3 个、Enums 层 3 个、单元测试 1 个）
  • 新增 API 接口：11 个（匿名执行、TraceFlag 管理、DebugLevel 管理、日志获取）
  • 性能优化：连接池优化、日志解析优化、查询优化
  • 安全增强：权限控制、参数验证、日志脱敏

• 影响范围：

  • 模块影响：datai-salesforce-tooling、datai-salesforce-integration、datai-salesforce-auth
  • API 影响：新增 11 个 RESTful API 接口
  • 数据库影响：无（直接操作 Salesforce Tooling API 对象）
  • 配置影响：无

• 测试情况：

  • 单元测试：新增 6 个单元测试类
  • 集成测试：待补充
  • 性能测试：待补充

生成的文档

• 变更日志

关键变更内容

1. 新增功能：匿名 Apex 执行、持久化调试配置管理、日志获取与解析
2. 新增代码文件：33 个代码文件
3. 新增 API 接口：11 个 RESTful API 接口
4. 性能优化：连接池优化、日志解析优化、查询优化
5. 安全增强：权限控制、参数验证、日志脱敏

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

• 状态：待开始

阶段 10：代码提交

• 状态：待开始

回退记录

无

相关文档

• 需求文档
• 设计文档
• 主索引