290 lines
11 KiB
Markdown
290 lines
11 KiB
Markdown
# 复盘文档：AI 和智能功能
|
||
|
||
## 元数据
|
||
- **需求编号**: 004-04
|
||
- **复盘时间**: 2026-02-05
|
||
- **创建人**: AI Assistant
|
||
- **状态**: 已完成
|
||
- **关联需求**: [AI 和智能功能](../requirements/sub/2026-01-28-004-04-AI和智能功能.md)
|
||
|
||
## 复盘概述
|
||
本次复盘对 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 实现异步操作日志记录，避免影响主流程性能。
|
||
|
||
**具体案例**:
|
||
```java
|
||
@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 查询语句，提高代码可读性和可维护性。
|
||
|
||
**具体案例**:
|
||
```java
|
||
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. 不要硬编码配置
|
||
**坑描述**: 在代码中硬编码配置信息，导致代码难以维护。
|
||
|
||
**避免方法**: 使用配置文件或常量类管理配置信息，在提示词中明确要求。
|
||
|
||
## 模板迭代
|
||
|
||
### 当前模板的优点
|
||
1. 结构清晰，包含所有必要章节
|
||
2. 提供了详细的代码规范要求
|
||
3. 明确了输出格式要求
|
||
|
||
### 当前模板的不足
|
||
1. 缺少对单元测试的具体要求
|
||
2. 缺少对性能优化的具体要求
|
||
3. 缺少对安全性的具体要求
|
||
|
||
### 改进计划
|
||
在下一个迭代中更新提示词模板，增加以下内容：
|
||
1. **单元测试要求**: 明确要求为 Service 层编写单元测试，使用 Mockito 模拟依赖
|
||
2. **性能优化要求**: 明确要求异步处理、缓存机制等性能优化措施
|
||
3. **安全性要求**: 明确要求输入验证、SQL 注入防护等安全措施
|
||
4. **监控要求**: 明确要求操作监控、异常告警等监控措施
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/sub/2026-01-28-004-04-AI和智能功能.md)
|
||
- [设计文档](../design/2026-02-03-004-04-AI和智能功能-设计.md)
|
||
- [决策记录](../decisions/2026-02-03-004-04-ADR-AI和智能功能技术选型.md)
|
||
- [变更日志](../changelog/2026-02-05-004-04-changelog.md)
|
||
- [会话记录](../sessions/2026-02-03-004-04-session.md)
|
||
- [API 文档](../api-docs/2026-02-05-004-04-api.md)
|
||
|
||
## 总结
|
||
本次需求开发顺利完成，实现了预期的功能目标。通过复盘总结了 5 条成功经验、4 个改进点和 3 个问题。后续将重点关注单元测试补充、异步日志优化和 SOQL 查询安全性提升。整体开发过程遵循 SSOT 流程，文档完整，代码质量良好。
|