268 lines
16 KiB
Markdown
268 lines
16 KiB
Markdown
# 会话记录
|
||
|
||
## 元数据
|
||
- 需求编号：004
|
||
- 子需求编号：004-01
|
||
- 子需求名称：连接管理
|
||
- 开始时间：2026-01-28
|
||
- 结束时间：2026-02-05
|
||
- 当前阶段：阶段 9：闭环复盘和接口文档
|
||
- 状态：已完成
|
||
|
||
## 需求澄清记录
|
||
|
||
### 原始需求
|
||
严格遵守项目规则，现在我有个需求，想将 `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\docs\reference-code\sforce\docs\tooling-module.md` 中的功能结合当前模块的实际情况，在 `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling` 模块下进行实现，默认实现源org类型
|
||
|
||
### 第一轮澄清
|
||
**AI 提问**：
|
||
1. 这个功能的核心目标是什么？
|
||
2. 这个功能涉及哪些业务场景？
|
||
3. 这个功能需要支持哪些用户角色？
|
||
4. 功能边界：根据 `tooling-module.md` 文档，Tooling API 包含大量功能（元数据操作、开发工具功能、AI 和智能功能、动作和自动化、访问和安全、高级功能等）。您希望实现所有功能？还是优先实现核心功能？哪些功能是必须实现的？
|
||
5. 使用场景：这个模块的主要使用场景是什么？
|
||
6. 用户角色：谁会使用这个模块？
|
||
7. 依赖包：我看到 `datai-salesforce-tooling/src/main/resources/lib/tooling.jar` 已经存在，这个是 Salesforce 官方的 Tooling API 客户端吗？我们需要基于这个包进行封装吗？
|
||
8. 认证集成：与 Partner API、Apex API、Metadata API 模块类似，是否也需要使用 `datai-salesforce-auth` 的 SessionManager 管理会话？
|
||
9. 模块设计：是否需要独立的 Controller 层？还是只提供 Service 层？是否需要数据库表？
|
||
10. 异常处理：是否需要自定义异常类？还是使用 `datai-salesforce-common` 模块中的现有异常？
|
||
11. 日志记录：是否需要记录 API 调用日志？还是暂不考虑？
|
||
12. 连接管理：是否需要连接池？还是每次调用都创建新连接？
|
||
13. 并发控制：是否需要限流？还是暂不考虑？
|
||
14. 缓存策略：是否需要缓存元数据描述结果？
|
||
15. SOQL 查询：Tooling API 支持 SOQL 查询，是否需要实现查询功能？
|
||
|
||
**用户回答**：
|
||
1、在 datai-salesforce-tooling 模块中实现 ToolingAPI 的全部功能，对于源 org（Source Org）
|
||
2、全部实现
|
||
3、主要使用场景 `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\docs\reference-code\sforce\docs\tooling-module.md` 文档中所有的场景
|
||
4、也需要使用 datai-salesforce-auth 的 SessionManager 管理会话
|
||
5、需要独立的 Controller 层
|
||
6、需要数据库表（存储编译结果、测试结果等），实际当前模块中需要储存下来的数据，创建个表进行存储
|
||
7、使用 datai-salesforce-common 模块中的现有异常，没有则自定义
|
||
8、日志、性能相关暂不考虑
|
||
9、需要实现查询功能
|
||
|
||
### 澄清总结
|
||
- **功能范围**：实现 Tooling API 的所有功能模块（元数据操作、开发工具功能、AI 和智能功能、动作和自动化、访问和安全、高级功能）
|
||
- **业务流程**：用户调用 REST API → Service 层处理 → 使用 tooling.jar 调用 Salesforce API → 存储结果到数据库 → 返回结果
|
||
- **数据交互**：需要创建数据库表存储代码覆盖率、测试结果等数据
|
||
- **性能要求**：暂不考虑连接池、并发控制、缓存等性能优化，异步操作需要轮询检查状态
|
||
- **安全要求**：集成 `datai-salesforce-auth` 模块的会话管理，使用 SessionManager 获取 Session ID 和 Server URL
|
||
- **兼容性要求**：支持 Salesforce Tooling API v65.0，兼容 Java 22 和 Spring Boot
|
||
- **数据存储要求**：需要创建表存储代码覆盖率、测试结果等数据，支持历史记录查询和统计分析
|
||
- **SOQL 查询**：必须实现查询功能，这是 Tooling API 的核心特性
|
||
|
||
## 需求描述
|
||
在 `datai-salesforce-tooling` 模块中实现 Salesforce Tooling API 的完整功能，提供对 Salesforce 源 org（Source Org）的开发工具和元数据操作能力，包括元数据操作、开发工具功能、AI 和智能功能、动作和自动化、访问和安全、高级功能等。
|
||
|
||
## 执行阶段
|
||
|
||
### 阶段 1：需求定义与入库
|
||
- 状态：已完成
|
||
- 生成文档：[需求文档](../requirements/2026-01-28-004-ToolingAPI源org实现.md)
|
||
- 关键决策：
|
||
- 实现所有 Tooling API 功能模块
|
||
- 使用 SessionManager 管理会话
|
||
- 提供 Service 层和 Controller 层
|
||
- 创建数据库表存储代码覆盖率、测试结果等数据
|
||
- 直接使用 tooling.jar 中的现有类
|
||
- 必须实现 SOQL 查询功能
|
||
- 优先使用 datai-salesforce-common 模块中的现有异常
|
||
- 暂不考虑性能优化（连接池、并发控制、缓存）
|
||
|
||
### 阶段 2：方案设计（子需求 004-01）
|
||
- 状态：已完成
|
||
- 生成文档：[设计文档](../design/2026-02-03-004-01-连接管理-设计.md)
|
||
- 关键决策：
|
||
- 使用 AbstractConnectionFactory 提供连接缓存与刷新能力
|
||
- 固定 source orgType 作为连接管理目标
|
||
- 通过 SessionManager 获取 Session ID 与 Instance URL
|
||
- 使用 ConcurrentHashMap 实现线程安全的连接缓存
|
||
- 执行简单 SOQL 查询验证 Session 有效性
|
||
- 提供完整的 RESTful API 接口
|
||
|
||
### 阶段 3：方案决策（子需求 004-01）
|
||
- 状态：已完成
|
||
- 生成文档：[决策记录](../decisions/2026-02-03-004-01-ADR-连接管理技术选型.md)
|
||
- 关键决策：
|
||
- 选择方案 1：使用 AbstractConnectionFactory + SessionManager
|
||
- 选择方案 1：使用 ConcurrentHashMap 缓存连接
|
||
- 选择方案 1：执行简单 SOQL 查询验证 Session 有效性
|
||
- 选择方案 1：同步记录日志
|
||
- 与认证和会话管理、Apex 连接管理、Metadata 连接管理保持一致
|
||
- 连接缓存与 Session 有效性检查由基础设施统一提供
|
||
|
||
### 阶段 4：数据库结构（子需求 004-01）
|
||
- 状态：跳过
|
||
- 原因：当前子需求不需要新建数据库表，使用现有日志表记录连接操作
|
||
|
||
### 阶段 5：提示词生成（子需求 004-01）
|
||
- 状态：已完成
|
||
- 生成文档：[提示词文档](../prompts/2026-02-03-004-01-prompt-Tooling连接管理.md)
|
||
- 关键决策：
|
||
- 引用真源：需求文档、设计文档、决策记录
|
||
- 明确输出结构：Factory、Service、Controller、Domain、DTO、Enum
|
||
- 约束不生成 SQL 脚本
|
||
- 要求生成单元测试（覆盖率不低于 80%）
|
||
|
||
### 阶段 6：代码生成（子需求 004-01）
|
||
- 状态：已完成
|
||
- 生成文件：
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/factory/ToolingConnectionFactory.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/service/IToolingConnectionService.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/service/impl/ToolingConnectionServiceImpl.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/ToolingConnectionController.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/enums/ToolingConnectionErrorCode.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/model/vo/ToolingConnectionResult.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/model/vo/ToolingConnectionRequest.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/model/dto/ToolingConnectionResultDTO.java`
|
||
- 代码生成器：未使用（不涉及表新增）
|
||
- 备注：按照 Prompt 要求生成了所有代码文件，包含 REST API、Service、Factory 和数据模型。单元测试文件待补充。
|
||
|
||
### 阶段 7：会话记录
|
||
- 状态：已完成
|
||
- 生成文档：无
|
||
- 关键决策：完整记录了当前会话的所有信息
|
||
|
||
### 阶段 8：变更日志
|
||
- 状态：已完成
|
||
- 生成文档：[变更日志](../changelog/2026-02-05-004-01-changelog.md)
|
||
- 关键决策：
|
||
- 创建详细的变更日志，记录所有新增功能和代码文件
|
||
- 更新根目录 CHANGELOG.md
|
||
- 更新索引文件
|
||
- 变更内容：
|
||
- 新增 8 个代码文件
|
||
- 新增 5 个 REST API 接口
|
||
- 定义 8 个标准错误码
|
||
- 实现连接管理核心功能
|
||
|
||
### 阶段 9：复盘与接口
|
||
- 状态：已完成
|
||
- 生成文档：
|
||
- [复盘文档](../retros/2026-02-05-004-01-retro.md)
|
||
- [API 文档](../api-docs/2026-02-05-004-01-api.md)
|
||
- 关键决策：
|
||
- 创建了详细的复盘文档，总结了成功经验、改进点、问题分析和行动计划
|
||
- 创建了完整的 API 文档，包含 5 个接口的详细说明
|
||
- 更新了索引文件和需求文档
|
||
- 复盘主要结论：
|
||
- 成功经验：SSOT 流程严格执行、复用现有基础设施、详细的提示词设计、清晰的架构设计、完整的错误码体系
|
||
- 改进点：单元测试需要补充、API 文档可以更加详细、阶段转换时的沟通可以更充分
|
||
- 问题分析：单元测试未生成、部分错误码定义与实际代码不完全匹配
|
||
- 行动计划：补充单元测试、更新提示词模板、建立错误码使用规范
|
||
|
||
### 阶段 10：代码提交
|
||
- 状态：未开始
|
||
|
||
## 对话记录
|
||
|
||
**用户**：严格遵守项目规则，现在我有个需求，想将 `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\docs\reference-code\sforce\docs\tooling-module.md` 中的功能结合当前模块的实际情况，在 `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\datai-salesforce-tooling` 模块下进行实现，默认实现源org类型
|
||
|
||
**AI**：我理解您的需求。在创建需求文档前，我需要先澄清一些问题：
|
||
|
||
**第一轮澄清**：
|
||
1. 这个功能的核心目标是什么？
|
||
2. 这个功能涉及哪些业务场景？
|
||
3. 这个功能需要支持哪些用户角色？
|
||
4. 功能边界：根据 `tooling-module.md` 文档，Tooling API 包含大量功能（元数据操作、开发工具功能、AI 和智能功能、动作和自动化、访问和安全、高级功能等）。您希望实现所有功能？还是优先实现核心功能？哪些功能是必须实现的？
|
||
5. 使用场景：这个模块的主要使用场景是什么？
|
||
6. 用户角色：谁会使用这个模块？
|
||
7. 依赖包：我看到 `datai-salesforce-tooling/src/main/resources/lib/tooling.jar` 已经存在，这个是 Salesforce 官方的 Tooling API 客户端吗？我们需要基于这个包进行封装吗？
|
||
8. 认证集成：与 Partner API、Apex API、Metadata API 模块类似，是否也需要使用 `datai-salesforce-auth` 的 SessionManager 管理会话？
|
||
9. 模块设计：是否需要独立的 Controller 层？还是只提供 Service 层？是否需要数据库表？
|
||
10. 异常处理：是否需要自定义异常类？还是使用 `datai-salesforce-common` 模块中的现有异常？
|
||
11. 日志记录：是否需要记录 API 调用日志？还是暂不考虑？
|
||
12. 连接管理：是否需要连接池？还是每次调用都创建新连接？
|
||
13. 并发控制：是否需要限流？还是暂不考虑？
|
||
14. 缓存策略：是否需要缓存元数据描述结果？
|
||
15. SOQL 查询：Tooling API 支持 SOQL 查询，是否需要实现查询功能？
|
||
|
||
**用户**：
|
||
1、在 datai-salesforce-tooling 模块中实现 ToolingAPI 的全部功能，对于源 org（Source Org）
|
||
2、全部实现
|
||
3、主要使用场景 `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\docs\reference-code\sforce\docs\tooling-module.md` 文档中所有的场景
|
||
4、也需要使用 datai-salesforce-auth 的 SessionManager 管理会话
|
||
5、需要独立的 Controller 层
|
||
6、需要数据库表（存储编译结果、测试结果等），实际当前模块中需要储存下来的数据，创建个表进行存储
|
||
7、使用 datai-salesforce-common 模块中的现有异常，没有则自定义
|
||
8、日志、性能相关暂不考虑
|
||
9、需要实现查询功能
|
||
|
||
**AI**：好的，感谢您的详细回答。让我总结一下需求：
|
||
|
||
**澄清总结**：
|
||
- **功能范围**：实现 Tooling API 的所有功能模块（元数据操作、开发工具功能、AI 和智能功能、动作和自动化、访问和安全、高级功能）
|
||
- **使用场景**：开发工具集成（IDE 插件开发、代码生成工具、元数据浏览器、部署工具）、测试和质量保证（代码覆盖率分析、测试执行管理、测试结果查询、质量报告生成）、CI/CD 集成（自动化测试、持续集成、部署自动化、质量门禁）、AI 和智能功能（AI 应用管理、AI 评估配置、AI 创作工具、智能推荐）、元数据管理（批量元数据操作、依赖关系分析、影响分析、元数据同步）
|
||
- **认证集成**：使用 `datai-salesforce-auth` 的 `SessionManager` 管理会话，通过 SessionManager 获取 Session ID 和 Server URL
|
||
- **模块设计**：提供 Service 层和 Controller 层（REST API），默认实现 source org 类型（源 org），需要数据库表（存储代码覆盖率、测试结果等数据）
|
||
- **技术实现**：直接使用 `tooling.jar` 中的现有类（ToolingConnection、ApexClass、ApexTrigger、ApexCodeCoverage 等），不进行二次封装
|
||
- **异常处理**：优先使用 `datai-salesforce-common` 模块中的现有异常，没有的话就自定义
|
||
- **暂不考虑的功能**：日志记录、连接池、并发控制、缓存策略、限流
|
||
- **SOQL 查询**：必须实现查询功能，这是 Tooling API 的核心特性
|
||
|
||
还有其他需要补充的吗？
|
||
|
||
**用户**：没有
|
||
|
||
**AI**：好的，我现在开始创建需求文档。
|
||
|
||
---
|
||
|
||
**2026-02-05 用户**：`d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\docs\design\2026-02-03-004-01-连接管理-设计.md` `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\docs\prompts\2026-02-03-004-01-prompt-Tooling连接管理.md` 当前子需求进入阶段6
|
||
|
||
**AI**：根据技能书指引，现在开始执行阶段 6：代码生成。
|
||
|
||
**现状**：已完成需求定义、方案设计、方案决策、数据库结构生成和提示词生成
|
||
**目标**：根据提示词生成符合项目规范的代码文件
|
||
|
||
[执行代码生成检查...]
|
||
|
||
**AI**：根据我的调查，**阶段 6：代码生成** 的代码文件已经存在：
|
||
|
||
## 代码生成状态确认
|
||
|
||
### 已生成的代码文件
|
||
|
||
| 文件类型 | 文件路径 | 状态 |
|
||
|---------|---------|------|
|
||
| **Factory** | `ToolingConnectionFactory.java` | ✅ 已实现 |
|
||
| **Service 接口** | `IToolingConnectionService.java` | ✅ 已实现 |
|
||
| **Service 实现** | `ToolingConnectionServiceImpl.java` | ✅ 已实现 |
|
||
| **Controller** | `ToolingConnectionController.java` | ✅ 已实现 |
|
||
| **ErrorCode 枚举** | `ToolingConnectionErrorCode.java` | ✅ 已实现 |
|
||
| **Domain - Result** | `ToolingConnectionResult.java` | ✅ 已实现 |
|
||
| **Domain - Request** | `ToolingConnectionRequest.java` | ✅ 已实现 |
|
||
| **DTO** | `ToolingConnectionResultDTO.java` | ✅ 已实现 |
|
||
|
||
**AI**：请问您需要：
|
||
1. **补全单元测试代码** - 生成缺失的单元测试文件
|
||
2. **进入下一阶段（阶段 7：会话记录）** - 如果代码已确认完成
|
||
3. **审查现有代码** - 检查代码是否需要修改
|
||
|
||
**用户**：进入下一阶段（阶段 7：会话记录）
|
||
|
||
**AI**：根据技能书指引，现在开始执行阶段 7：会话记录。
|
||
|
||
[更新会话记录...]
|
||
|
||
## 生成的文档
|
||
- [需求文档](../requirements/2026-01-28-004-ToolingAPI源org实现.md)
|
||
- [设计文档](../design/2026-02-03-004-01-连接管理-设计.md)
|
||
- [决策记录](../decisions/2026-02-03-004-01-ADR-连接管理技术选型.md)
|
||
- [提示词文档](../prompts/2026-02-03-004-01-prompt-Tooling连接管理.md)
|
||
|
||
## 生成的代码文件
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/factory/ToolingConnectionFactory.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/service/IToolingConnectionService.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/service/impl/ToolingConnectionServiceImpl.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/ToolingConnectionController.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/enums/ToolingConnectionErrorCode.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/model/vo/ToolingConnectionResult.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/model/vo/ToolingConnectionRequest.java`
|
||
- `datai-salesforce-tooling/src/main/java/com/datai/tooling/model/dto/ToolingConnectionResultDTO.java`
|
||
|
||
## 回退记录
|
||
无
|