11 KiB
复盘文档：AI 和智能功能
元数据
- 需求编号: 004-04
- 复盘时间: 2026-02-05
- 创建人: AI Assistant
- 状态: 已完成
- 关联需求: AI 和智能功能
复盘概述
本次复盘对 Tooling API AI 和智能功能的开发过程进行全面回顾。该需求涉及 AI 应用管理（创建、查询、更新、删除）、AI 评估配置查询（评估主题类型、处理状态、指标类型）、AI 创作工具查询（创作包类型、版本状态、助手模板状态）以及操作日志记录功能。通过复盘总结经验教训，为后续类似需求的开发提供参考。
目标与实际产出对比
目标
- 实现 AI 应用管理功能，支持创建、查询、更新、删除 AI 应用
- 实现 AI 评估配置查询功能，支持查询评估主题类型、处理状态、指标类型
- 实现 AI 创作工具查询功能，支持查询创作包类型、版本状态、助手模板状态
- 实现异步操作日志记录功能
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
- 生成符合项目规范的代码
实际产出
- ✅ 成功实现 AI 应用管理功能，包含 4 个 REST API 接口
- ✅ 成功实现 AI 评估配置查询功能，包含 3 个 REST API 接口
- ✅ 成功实现 AI 创作工具查询功能，包含 3 个 REST API 接口
- ✅ 成功实现异步操作日志记录功能，使用 Spring @Async
- ✅ 严格按照 SSOT 流程执行，完成阶段 1-8 的所有文档
- ✅ 生成 15 个代码文件（11 个手动实现 + 4 个代码生成器生成），约 990 行代码
- ✅ 定义 11 个标准错误码（TOOLING_AI_001 ~ TOOLING_AI_011）
- ✅ 创建 1 个数据库表（datai_tooling_ai_operation_log）
成功经验
1. 分层架构设计的有效应用
经验描述: 采用 Controller → Service → Factory → Tooling API 的分层架构，职责清晰，便于维护和扩展。
具体案例:
- Controller 层负责接收请求和返回响应
- Service 层负责业务逻辑处理
- Factory 层负责连接管理
- Tooling API 层负责与 Salesforce 交互
效果: 代码结构清晰，各层职责明确，便于后续维护和扩展。
2. 异步日志记录的性能优化
经验描述: 使用 Spring @Async 实现异步操作日志记录，避免影响主流程性能。
具体案例:
@Async("taskExecutor")
public void logOperationAsync(AIOperationLogDTO logDTO) {
// 异步记录日志
}
效果: 日志记录不影响主流程响应时间，系统性能得到保障。
3. 错误码体系的规范化设计
经验描述: 定义 11 个标准错误码，覆盖所有可能的错误场景，便于错误定位和问题排查。
具体案例:
- TOOLING_AI_001: Session 无效或已过期
- TOOLING_AI_002: 创建 AI 应用失败
- TOOLING_AI_003: 更新 AI 应用失败
- ...
效果: 错误信息标准化，便于前端统一处理和用户理解。
4. SoqlBuilder 工具类的复用
经验描述: 复用现有的 SoqlBuilder 工具类构建 SOQL 查询语句，提高代码可读性和可维护性。
具体案例:
String soql = new SoqlBuilder()
.select("Id", "DeveloperName", "MasterLabel")
.from("AIApplication")
.where("Status = '" + status + "'")
.build();
效果: 代码简洁，避免硬编码 SQL，提高可维护性。
5. 代码生成器与手动实现的结合
经验描述: 代码生成器生成基础 CRUD 代码（Entity、Mapper、Service），手动实现核心业务逻辑（Controller、DTO、Service 实现）。
具体案例:
- 代码生成器生成：DataiToolingAiOperationLog.java、Mapper、Service
- 手动实现：ToolingAIController.java、IToolingAIService.java、ToolingAIServiceImpl.java、DTOs
效果: 提高开发效率，同时保证核心业务逻辑的质量。
改进点
1. API 接口的批量操作支持
改进描述: 当前 AI 应用管理接口只支持单条操作，可以考虑增加批量操作接口，提高操作效率。
建议方案:
- 增加批量创建 AI 应用接口
- 增加批量删除 AI 应用接口
- 增加批量更新 AI 应用接口
优先级: 中 计划时间: 下一个迭代
2. 缓存机制的引入
改进描述: AI 类型查询（评估主题类型、处理状态等）数据变化频率低，可以引入缓存机制，减少数据库查询次数。
建议方案:
- 使用 Redis 缓存 AI 类型数据
- 设置合理的缓存过期时间
- 提供缓存刷新接口
优先级: 中 计划时间: 下一个迭代
3. 接口权限控制的细化
改进描述: 当前接口使用通用的权限控制，可以考虑根据操作类型细化权限控制。
建议方案:
- 查询操作：tooling:ai:query
- 创建操作：tooling:ai:create
- 更新操作：tooling:ai:update
- 删除操作：tooling:ai:delete
优先级: 低 计划时间: 后续迭代
4. 单元测试覆盖率的提升
改进描述: 当前代码缺少单元测试，建议补充完整的单元测试。
建议方案:
- 为 Service 层编写单元测试
- 使用 Mockito 模拟依赖
- 覆盖正常和异常场景
优先级: 高 计划时间: 立即执行
问题分析
问题 1：AI 应用字段映射的复杂性
问题描述: AI 应用（AIApplication）对象字段较多，且 Salesforce API 返回的字段名与 DTO 字段名需要映射，容易出错。
根因分析:
- Salesforce 字段命名规范与 Java 命名规范不一致
- 字段映射逻辑分散在多个地方
- 缺乏统一的字段映射机制
解决方案:
- 使用 MapStruct 或类似工具自动生成字段映射代码
- 在 DTO 中明确标注字段映射关系
- 增加字段映射的单元测试
状态: 已记录，待后续优化
问题 2：异步日志记录的异常处理
问题描述: 异步日志记录方法如果抛出异常，可能会影响主流程（虽然使用了 @Async，但异常处理仍需完善）。
根因分析:
- 异步方法内部异常未捕获
- 缺乏异步操作的监控机制
- 日志记录失败没有告警
解决方案:
- 在异步方法内部增加 try-catch 块
- 记录日志记录失败的错误信息
- 增加异步操作的监控和告警
状态: 已记录，待后续优化
问题 3：SOQL 查询的 SQL 注入风险
问题描述: 当前使用字符串拼接构建 SOQL 查询，存在 SQL 注入风险。
根因分析:
- 用户输入直接拼接到 SOQL 语句中
- 缺乏输入验证和转义机制
- SoqlBuilder 工具类不支持参数化查询
解决方案:
- 对用户输入进行验证和转义
- 增强 SoqlBuilder 支持参数化查询
- 使用 PreparedStatement 类似的机制
状态: 已记录，待后续优化
行动计划
| 序号 | 行动项 | 责任人 | 优先级 | 计划时间 | 状态 |
|---|---|---|---|---|---|
| 1 | 补充 Service 层单元测试 | AI Assistant | 高 | 立即执行 | 待开始 |
| 2 | 优化异步日志异常处理 | AI Assistant | 中 | 下一个迭代 | 待开始 |
| 3 | 引入 Redis 缓存机制 | 项目团队 | 中 | 下一个迭代 | 待开始 |
| 4 | 增加批量操作接口 | 项目团队 | 中 | 后续迭代 | 待开始 |
| 5 | 优化 SOQL 查询安全性 | AI Assistant | 高 | 下一个迭代 | 待开始 |
| 6 | 细化接口权限控制 | 项目团队 | 低 | 后续迭代 | 待开始 |
提取模式
有效的 Prompt 技巧
1. 明确的输出格式要求
技巧描述: 在提示词中明确指定需要生成的文件、路径、格式等。
应用案例:
## 输出格式要求
### 1. 必须包含以下文件
#### Controller
- **文件**: `ToolingAIController.java`
- **路径**: `datai-scenes/datai-scene-salesforce/src/main/java/com/datai/tooling/controller/`
- **功能**: 提供 AI 功能的 RESTful API 接口
效果: 生成的代码结构清晰，符合项目规范。
2. 引用真源
技巧描述: 在提示词开头引用需求文档和设计文档的链接。
应用案例:
## 引用真源
- **需求文档**: [004-04-AI和智能功能需求文档](../requirements/sub/2026-01-28-004-04-AI和智能功能.md)
- **设计文档**: [004-04-AI和智能功能设计文档](../design/2026-02-03-004-04-AI和智能功能-设计.md)
效果: 确保生成的代码符合需求和设计要求。
3. 详细的代码规范要求
技巧描述: 在提示词中明确指定代码规范、命名规范、注释规范等。
应用案例:
## 代码规范
### 1. 命名规范
- Controller 类名: `ToolingAIController`
- Service 接口名: `IToolingAIService`
- Service 实现类名: `ToolingAIServiceImpl`
- DTO 类名: `AIApplicationDTO`
效果: 生成的代码质量高，可读性好。
避免的坑
1. 不要忽略异常处理
坑描述: 在生成代码时忽略异常处理，导致代码健壮性差。
避免方法: 在提示词中明确要求异常处理，包括异常捕获、错误码转换、日志记录等。
2. 不要忽略日志记录
坑描述: 在生成代码时忽略日志记录，导致问题难以排查。
避免方法: 在提示词中明确要求日志记录，包括操作日志、错误日志等。
3. 不要硬编码配置
坑描述: 在代码中硬编码配置信息，导致代码难以维护。
避免方法: 使用配置文件或常量类管理配置信息，在提示词中明确要求。
模板迭代
当前模板的优点
- 结构清晰，包含所有必要章节
- 提供了详细的代码规范要求
- 明确了输出格式要求
当前模板的不足
- 缺少对单元测试的具体要求
- 缺少对性能优化的具体要求
- 缺少对安全性的具体要求
改进计划
在下一个迭代中更新提示词模板，增加以下内容：
- 单元测试要求: 明确要求为 Service 层编写单元测试，使用 Mockito 模拟依赖
- 性能优化要求: 明确要求异步处理、缓存机制等性能优化措施
- 安全性要求: 明确要求输入验证、SQL 注入防护等安全措施
- 监控要求: 明确要求操作监控、异常告警等监控措施
相关文档
总结
本次需求开发顺利完成，实现了预期的功能目标。通过复盘总结了 5 条成功经验、4 个改进点和 3 个问题。后续将重点关注单元测试补充、异步日志优化和 SOQL 查询安全性提升。整体开发过程遵循 SSOT 流程，文档完整，代码质量良好。