295 lines
14 KiB
Markdown
295 lines
14 KiB
Markdown
# 会话记录 - 检索操作
|
||
|
||
## 元数据
|
||
- 需求编号：003-06
|
||
- 需求名称：检索操作
|
||
- 开始时间：2026-02-03
|
||
- 结束时间：2026-02-06
|
||
- 当前阶段：阶段 7：记录当前会话
|
||
- 状态：已完成
|
||
|
||
## 阶段记录
|
||
|
||
### 阶段 1：需求定义
|
||
- 状态：已完成
|
||
- 需求文档：[2026-01-28-003-06-检索操作.md](../requirements/sub/2026-01-28-003-06-检索操作.md)
|
||
|
||
### 阶段 2：方案设计
|
||
- 状态：已完成
|
||
- 设计文档：[2026-02-03-003-06-检索操作-设计.md](../design/2026-02-03-003-06-检索操作-设计.md)
|
||
- 关键设计决策：
|
||
1. **架构设计**：采用分层架构（Controller → Service → Repository → Metadata API），复用 003-01 的连接管理
|
||
2. **异步处理机制**：由于检索操作通常较为耗时，采用"提交请求-轮询状态-获取结果"的异步流程
|
||
3. **技术选型**：
|
||
- Spring Boot 2.7+ (配合若依框架)
|
||
- MyBatis Plus 进行数据库交互
|
||
- Salesforce Metadata API (WSC/Partner JAR)
|
||
- MySQL 5.7+ 数据库
|
||
4. **数据模型**：创建 `datai_metadata_retrieve` 表，包含 9 个字段和 2 个索引
|
||
- 字段：id, async_id, status, done, message, error_message, retrieve_time, update_time, user_id
|
||
- 索引：idx_async_id, idx_retrieve_time
|
||
5. **核心算法**：
|
||
- **提交检索**：调用 `connection.retrieve(request)` → 获取 `AsyncResult` → 立即存入数据库 → 返回 `AsyncResult`
|
||
- **轮询状态**：循环调用 `checkRetrieveStatus(asyncId)` → 检查状态 → 更新数据库 → 返回结果或继续等待
|
||
- **超时机制**：设置 5 分钟超时，防止无限等待
|
||
6. **接口设计**：3 个 REST API 接口
|
||
- `POST /salesforce/metadata/retrieve` - 提交检索请求
|
||
- `GET /salesforce/metadata/retrieve/{asyncId}` - 获取检索状态/结果
|
||
- `GET /salesforce/metadata/retrieve/history` - 获取检索历史
|
||
7. **实体类设计**：`MetadataRetrieveEntity` 使用 MyBatis Plus 注解映射数据库表
|
||
8. **异常处理**：
|
||
- 捕获 `ConnectionException`，转换为 `SalesforceAuthException` 或 `SalesforceOperationException`
|
||
- 即使 API 调用失败，也要尽可能记录失败状态到数据库
|
||
9. **性能优化**：
|
||
- 长轮询策略：Controller 层实现长轮询或立即返回，由前端控制轮询间隔
|
||
- ZIP 文件不存储到数据库，仅在 API 响应中返回
|
||
10. **安全设计**：
|
||
- 验证 `RetrieveRequest` 中的包名和文件路径，防止非法访问
|
||
- 记录操作用户 ID (`userId`)，确保审计可追溯
|
||
|
||
### 阶段 3：方案决策
|
||
- 状态：已完成
|
||
- 决策文档：[2026-02-03-003-06-ADR-检索操作技术选型.md](../decisions/2026-02-03-003-06-ADR-检索操作技术选型.md)
|
||
- 关键决策：
|
||
1. **ZIP 文件处理**：不持久化到数据库，直接在 API 响应中返回
|
||
- 理由：避免数据库性能问题，简化系统复杂度
|
||
2. **状态管理**：创建专用历史表 `datai_metadata_retrieve`
|
||
- 理由：审计追踪，状态同步
|
||
3. **架构模式**：复用通用异步策略
|
||
- 理由：保持一致性，简化客户端
|
||
|
||
### 阶段 4：数据库结构生成
|
||
- 状态：已完成
|
||
- 涉及数据库变更：是
|
||
- SQL 脚本：[2026-02-03-003-06-检索操作日志.sql](../sql/2026-02-03-003-06-检索操作日志.sql)
|
||
- 数据库变更内容：
|
||
1. **创建表**：`datai_metadata_retrieve`
|
||
- 13 个字段：id, async_id, status, done, message, error_message, retrieve_time, update_time, user_id, create_by, create_time, update_by, del_flag
|
||
- 4 个索引：idx_async_id, idx_retrieve_time, idx_user_id, idx_create_time
|
||
- 字符集：utf8mb4
|
||
- 存储引擎：InnoDB
|
||
|
||
### 阶段 5：提示词生成
|
||
- 状态：已完成
|
||
- 提示词文档：[2026-02-03-003-06-prompt-检索操作.md](../prompts/2026-02-03-003-06-prompt-检索操作.md)
|
||
- 提示词内容概要：
|
||
1. **引用真源**：需求文档、设计文档、ADR 文档、SQL 脚本
|
||
2. **需求描述**：实现 Salesforce 元数据检索功能，支持提交检索请求、轮询状态、查询历史
|
||
3. **设计方案**：Controller-Service-Repository 分层架构，异步处理机制
|
||
4. **输出格式**：Entity、Mapper、Service、Controller、单元测试
|
||
5. **代码规范**：Spring Boot 最佳实践、若依框架规范、MyBatis Plus 使用规范
|
||
6. **测试要求**：JUnit 5 和 Mockito，覆盖率不低于 80%
|
||
|
||
### 阶段 6：执行代码生成
|
||
- 状态：已完成
|
||
- 代码生成器使用：**是**
|
||
- 代码生成器扫描结果：
|
||
- ✅ Entity: `DataiMetadataRetrieve.java`, `DataiMetadataRetrieveResult.java`, `DataiMetadataRetrieveMessage.java` - 已生成
|
||
- ✅ Mapper: `DataiMetadataRetrieveMapper.java` 等 - 已生成
|
||
- ✅ Service 接口: `IDataiMetadataRetrieveService.java` 等 - 已生成
|
||
- ✅ Service 实现: `DataiMetadataRetrieveServiceImpl.java` 等 - 已生成
|
||
- ✅ Controller: `DataiMetadataRetrieveController.java` 等 - 已生成
|
||
- ✅ DTO/VO: `DataiMetadataRetrieveDto.java`, `DataiMetadataRetrieveVo.java` 等 - 已生成
|
||
- 手动实现的代码文件：
|
||
1. **DTO**: `RetrieveRequest.java` - 检索请求 DTO（包含 Unpackaged 和 PackageTypeMember 内部类）
|
||
2. **VO**: `RetrieveResultVo.java` - 检索结果 VO（包含 fromSalesforceResult 转换方法）
|
||
3. **VO**: `RetrieveMessageVo.java` - 检索消息 VO
|
||
4. **Service 接口**: `IMetadataRetrieveService.java` - 业务 Service 接口（检索、轮询、查询历史）
|
||
5. **Service 实现**: `MetadataRetrieveServiceImpl.java` - 业务 Service 实现（调用 Metadata API、异步记录）
|
||
6. **Controller**: `MetadataRetrieveController.java` - 业务 Controller（5 个 REST API 接口）
|
||
7. **Mapper 扩展**: `DataiMetadataRetrieveMapper.java` - 添加 selectByAsyncId 和 selectRetrieveHistory 方法
|
||
8. **Mapper XML 扩展**: `DataiMetadataRetrieveMapper.xml` - 添加对应的 SQL 语句
|
||
9. **单元测试**: `MetadataRetrieveServiceTest.java` - 包含 11 个测试用例，覆盖率 > 80%
|
||
|
||
**生成的代码文件清单：**
|
||
```
|
||
datai-salesforce-metadata/src/main/java/com/datai/metadata/
|
||
├── model/dto/
|
||
│ └── RetrieveRequest.java # 检索请求 DTO
|
||
├── model/vo/
|
||
│ ├── RetrieveResultVo.java # 检索结果 VO
|
||
│ └── RetrieveMessageVo.java # 检索消息 VO
|
||
├── service/
|
||
│ └── IMetadataRetrieveService.java # 业务 Service 接口
|
||
└── service/impl/
|
||
├── MetadataRetrieveServiceImpl.java # 业务 Service 实现
|
||
└── MetadataRetrieveServiceTest.java # 单元测试
|
||
└── controller/
|
||
└── MetadataRetrieveController.java # REST API Controller
|
||
```
|
||
|
||
**REST API 接口：**
|
||
1. `POST /salesforce/metadata/retrieve` - 提交检索请求
|
||
2. `GET /salesforce/metadata/retrieve/status/{asyncId}` - 轮询检索状态
|
||
3. `GET /salesforce/metadata/retrieve/check/{asyncId}` - 单次检查状态
|
||
4. `GET /salesforce/metadata/retrieve/history` - 获取检索历史
|
||
5. `GET /salesforce/metadata/retrieve/record/{asyncId}` - 查询检索记录
|
||
9. **单元测试**: `MetadataRetrieveServiceTest.java` - 完整的单元测试（10 个测试用例）
|
||
- 生成的代码列表：
|
||
| 文件类型 | 文件路径 | 生成方式 |
|
||
|---------|---------|---------|
|
||
| DTO | `com.datai.metadata.model.dto.RetrieveRequest` | 手动 |
|
||
| VO | `com.datai.metadata.model.vo.RetrieveResultVo` | 手动 |
|
||
| VO | `com.datai.metadata.model.vo.RetrieveMessageVo` | 手动 |
|
||
| Service 接口 | `com.datai.metadata.service.IMetadataRetrieveService` | 手动 |
|
||
| Service 实现 | `com.datai.metadata.service.impl.MetadataRetrieveServiceImpl` | 手动 |
|
||
| Controller | `com.datai.metadata.controller.MetadataRetrieveController` | 手动 |
|
||
| Mapper 扩展 | `com.datai.metadata.mapper.DataiMetadataRetrieveMapper` | 修改 |
|
||
| Mapper XML | `DataiMetadataRetrieveMapper.xml` | 修改 |
|
||
| 单元测试 | `com.datai.metadata.service.impl.MetadataRetrieveServiceTest` | 手动 |
|
||
- 关键实现逻辑：
|
||
1. **异步检索**：调用 `MetadataConnection.retrieve()` 提交请求，返回 `AsyncResult`
|
||
2. **状态轮询**：循环调用 `checkRetrieveStatus()` 直到完成或超时
|
||
3. **异步记录**：使用 `@Async("threadPoolTaskExecutor")` 异步记录检索历史
|
||
4. **错误处理**：10 个专用错误码（RETRIEVE_001 ~ RETRIEVE_010）
|
||
5. **ZIP 文件处理**：转换为 Base64 返回，不存储到数据库
|
||
- REST API 接口：
|
||
1. `POST /salesforce/metadata/retrieve` - 提交检索请求
|
||
2. `GET /salesforce/metadata/retrieve/status/{asyncId}` - 轮询检索状态
|
||
3. `GET /salesforce/metadata/retrieve/check/{asyncId}` - 单次检查状态
|
||
4. `GET /salesforce/metadata/retrieve/history` - 获取检索历史
|
||
5. `GET /salesforce/metadata/retrieve/record/{asyncId}` - 查询检索记录
|
||
|
||
### 阶段 7：记录当前会话
|
||
- 状态：已完成
|
||
- 会话记录：[2026-02-03-003-06-session.md](./2026-02-03-003-06-session.md)
|
||
- 关键记录：
|
||
1. 完整记录了从需求定义到代码生成的全过程
|
||
2. 记录了代码生成器扫描结果和手动实现代码清单
|
||
3. 记录了 REST API 接口设计
|
||
4. 记录了单元测试覆盖情况（11 个测试用例）
|
||
|
||
## 对话记录
|
||
|
||
### 2026-02-06 会话记录
|
||
|
||
**用户**：进入下一阶段（阶段 9：闭环复盘和接口文档）
|
||
|
||
**AI**：收到，进入阶段 9。首先让我读取检索操作的需求文档...
|
||
|
||
（阶段 9 执行过程记录详见复盘文档）
|
||
|
||
---
|
||
|
||
**用户**：`d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\docs\requirements\sub\2026-01-28-003-06-检索操作.md` 更新相关文档索引
|
||
|
||
**AI**：收到，正在更新检索操作需求文档的相关文档索引...
|
||
|
||
（索引更新完成）
|
||
|
||
---
|
||
|
||
**用户**：暂停，进入 `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\docs\requirements\sub\2026-01-28-003-06-检索操作.md` 的代码生成阶段
|
||
|
||
**AI**：收到，进入代码生成阶段。首先扫描代码生成器生成的基础代码...
|
||
|
||
---
|
||
|
||
**用户**：是，扫描所有基础代码，基于此生成代码
|
||
|
||
**AI**：已扫描到代码生成器生成的所有基础代码：
|
||
- ✅ Entity: DataiMetadataRetrieve.java 等 - 已生成
|
||
- ✅ Mapper: DataiMetadataRetrieveMapper.java 等 - 已生成
|
||
- ✅ Service: DataiMetadataRetrieveServiceImpl.java 等 - 已生成
|
||
- ✅ Controller: DataiMetadataRetrieveController.java 等 - 已生成
|
||
|
||
**用户**：继续
|
||
|
||
**AI**：现在开始生成业务逻辑代码...
|
||
|
||
（代码生成过程记录）
|
||
|
||
---
|
||
|
||
**AI**：检索操作（003-06）的代码生成阶段已完成！以下是生成的代码文件汇总...
|
||
|
||
**用户**：进入下一阶段
|
||
|
||
**AI**：收到，进入阶段 7：记录当前会话...
|
||
|
||
## 待完成阶段
|
||
- [x] 阶段 1：需求定义
|
||
- [x] 阶段 2：方案设计
|
||
- [x] 阶段 3：方案决策
|
||
- [x] 阶段 4：数据库结构生成
|
||
- [x] 阶段 5：提示词生成
|
||
- [x] 阶段 6：代码生成
|
||
- [x] 阶段 7：会话记录（已完成）
|
||
- [x] 阶段 8：变更日志（已完成 - 2026-02-06）
|
||
- [x] 阶段 9：复盘和 API 文档（已完成 - 2026-02-06）
|
||
- [ ] 阶段 10：代码提交
|
||
|
||
## 阶段 9：闭环复盘和接口文档（已完成）
|
||
|
||
### 复盘文档
|
||
- [2026-02-06-003-06-retro.md](../retros/2026-02-06-003-06-retro.md)
|
||
|
||
### 复盘主要结论
|
||
1. **成功经验**：
|
||
- 异步处理模式的成功应用（提交-轮询-结果）
|
||
- 代码生成器与手动实现的良好结合
|
||
- 复杂 DTO 结构的设计（RetrieveRequest 嵌套结构）
|
||
- 完整的错误码体系（10 个标准错误码）
|
||
- 异步日志记录的性能优化
|
||
|
||
2. **改进点**：
|
||
- ZIP 文件处理可以更加灵活（支持流式下载）
|
||
- 检索历史查询可以支持更多筛选条件（时间范围、状态等）
|
||
- 单元测试可以覆盖更多边界场景
|
||
|
||
3. **问题分析**：
|
||
- DTO 与 Salesforce API 对象的转换逻辑较复杂 → 使用 MapStruct 优化
|
||
- 轮询间隔和超时时间的配置不够灵活 → 配置化参数
|
||
|
||
4. **行动计划**：5 个具体行动项，已记录责任人和时间节点
|
||
|
||
5. **提取模式**：3 条有效的 Prompt 技巧 + 3 个避免的坑
|
||
|
||
### API 文档
|
||
- [2026-02-06-003-06-api.md](../api-docs/2026-02-06-003-06-api.md)
|
||
|
||
### API 文档内容
|
||
- **5 个 REST API 接口**：
|
||
1. `POST /salesforce/metadata/retrieve` - 提交检索请求
|
||
2. `GET /salesforce/metadata/retrieve/status/{asyncId}` - 轮询检索状态
|
||
3. `GET /salesforce/metadata/retrieve/check/{asyncId}` - 单次检查状态
|
||
4. `GET /salesforce/metadata/retrieve/history` - 获取检索历史
|
||
5. `GET /salesforce/metadata/retrieve/record/{asyncId}` - 查询检索记录
|
||
- **10 个错误码**：RETRIEVE_001 ~ RETRIEVE_010
|
||
- **详细示例**：包含请求示例、响应示例、错误示例
|
||
- **使用流程**：3 个典型使用场景
|
||
|
||
### 更新的文件
|
||
- docs/index.md（新增复盘文档和 API 文档链接）
|
||
- 需求文档（添加复盘和 API 文档引用）
|
||
- 会话记录（添加阶段 9 记录）
|
||
|
||
## 阶段 8：变更日志（已完成）
|
||
|
||
### 变更日志文档
|
||
- [2026-02-06-003-06-changelog.md](../changelog/2026-02-06-003-06-changelog.md)
|
||
|
||
### 变更内容摘要
|
||
- **新增功能**：实现 Salesforce 元数据检索（Retrieve）功能
|
||
- **新增数据库表**：datai_metadata_retrieve（检索操作日志表）
|
||
- **新增代码文件**：15+ 个代码文件（代码生成器生成 + 手动实现）
|
||
- **新增 REST API**：5 个接口（提交检索、轮询状态、检查状态、历史查询、记录查询）
|
||
- **错误码体系**：9 个标准错误码（RETRIEVE_001 ~ RETRIEVE_010）
|
||
- **技术实现**：异步状态轮询、ZIP 文件 Base64 编码、完整错误处理
|
||
|
||
### 更新的文件
|
||
- 根目录 CHANGELOG.md（新增 Metadata API 模块变更记录）
|
||
- docs/index.md（新增变更日志链接）
|
||
- 需求文档（添加变更日志引用）
|
||
- 会话记录（添加阶段 8 记录）
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/sub/2026-01-28-003-06-检索操作.md)
|
||
- [设计文档](../design/2026-02-03-003-06-检索操作-设计.md)
|
||
- [决策文档](../decisions/2026-02-03-003-06-ADR-检索操作技术选型.md)
|
||
- [SQL 脚本](../sql/2026-02-03-003-06-检索操作日志.sql)
|
||
- [连接管理设计文档](../design/2026-02-02-003-01-连接管理-设计.md)
|
||
- [变更日志](../changelog/2026-02-06-003-06-changelog.md)
|
||
- [复盘文档](../retros/2026-02-06-003-06-retro.md)
|
||
- [API 文档](../api-docs/2026-02-06-003-06-api.md)
|