89 lines
4.3 KiB
Markdown
89 lines
4.3 KiB
Markdown
# 会话记录 - 检索操作
|
||
|
||
## 元数据
|
||
- 需求编号：003-06
|
||
- 需求名称：检索操作
|
||
- 开始时间：2026-02-03
|
||
- 结束时间：2026-02-03
|
||
- 当前阶段：阶段 4：数据库结构生成
|
||
|
||
## 阶段记录
|
||
|
||
### 阶段 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
|
||
|
||
## 待完成阶段
|
||
- [x] 阶段 1：需求定义
|
||
- [x] 阶段 2：方案设计
|
||
- [x] 阶段 3：方案决策
|
||
- [x] 阶段 4：数据库结构生成
|
||
- [ ] 阶段 5：提示词生成
|
||
- [ ] 阶段 6：代码生成
|
||
- [ ] 阶段 7：会话记录
|
||
- [ ] 阶段 8：变更日志
|
||
- [ ] 阶段 9：复盘和 API 文档
|
||
- [ ] 阶段 10：代码提交
|
||
|
||
## 相关文档
|
||
- [需求文档](../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)
|