89 lines
4.6 KiB
Markdown
89 lines
4.6 KiB
Markdown
# 会话记录 - 异步操作
|
||
|
||
## 元数据
|
||
- 需求编号：003-04
|
||
- 需求名称：异步操作
|
||
- 开始时间：2026-02-03
|
||
- 结束时间：2026-02-03
|
||
- 当前阶段：阶段 4：数据库结构生成
|
||
|
||
## 阶段记录
|
||
|
||
### 阶段 1：需求定义
|
||
- 状态：已完成
|
||
- 需求文档：[2026-01-28-003-04-异步操作.md](../requirements/sub/2026-01-28-003-04-异步操作.md)
|
||
|
||
### 阶段 2：方案设计
|
||
- 状态：已完成
|
||
- 设计文档：[2026-02-03-003-04-异步操作-设计.md](../design/2026-02-03-003-04-异步操作-设计.md)
|
||
- 关键设计决策：
|
||
1. **架构设计**：采用分层架构（Controller → Service → Factory → Metadata API），复用 003-01 的连接管理
|
||
2. **通用异步操作管理**：Service 层不依赖具体的元数据类型，支持部署、检索等各种异步操作的统一管理
|
||
3. **技术选型**：
|
||
- Spring Boot 2.7.x + Spring @Async 异步记录操作历史
|
||
- MyBatis Plus 3.5.x 简化数据库操作
|
||
- Salesforce Metadata API 原生 AsyncResult 和 AsyncRequestState
|
||
4. **数据模型**：创建 `datai_metadata_async` 表，包含 13 个字段和 5 个索引
|
||
5. **核心算法**：
|
||
- 获取异步操作结果：查询状态 → 记录历史 → 返回结果
|
||
- 轮询异步操作状态：循环查询 → 完成/超时检查 → 等待间隔 → 返回结果
|
||
- 取消异步操作：执行取消 → 记录状态 → 返回结果
|
||
6. **接口设计**：4 个 REST API 接口（获取异步结果、轮询状态、取消操作、获取历史）
|
||
7. **VO 设计**：定义 AsyncResultVO、MetadataAsyncVO 用于前后端数据交换
|
||
8. **错误处理**：4 个专用错误码（ASYNC_001 ~ ASYNC_004）
|
||
9. **性能优化**：异步日志、连接复用、轮询优化、索引优化
|
||
10. **安全设计**：权限控制、参数校验、错误信息隐藏、超时控制
|
||
|
||
### 阶段 3：方案决策
|
||
- 状态：已完成
|
||
- 决策文档：
|
||
- [2026-02-03-003-04-ADR-异步操作技术选型.md](../decisions/2026-02-03-003-04-ADR-异步操作技术选型.md)
|
||
- [2026-02-03-003-04-ADR-异步操作轮询策略.md](../decisions/2026-02-03-003-04-ADR-异步操作轮询策略.md)
|
||
- 关键决策：
|
||
1. **异步操作结果处理方式**：Service 层直接返回 Salesforce 原生 `AsyncResult` 对象，Controller 层转换为 VO
|
||
2. **轮询策略**：服务端同步轮询（Server-side Synchronous Polling）
|
||
3. **操作历史记录方式**：使用 Spring `@Async` 异步记录操作历史
|
||
4. **错误处理策略**：使用专用错误码体系 + 统一异常处理
|
||
- 替代方案分析：
|
||
- 客户端轮询：服务端无状态，但服务端依赖结果时需重复实现
|
||
- 响应式/异步非阻塞：资源利用率高，但增加复杂度
|
||
- 消息队列记录日志：解耦彻底，但引入额外中间件
|
||
- 自定义 AsyncResult 封装：完全控制结构，但增加维护成本
|
||
|
||
### 阶段 4：数据库结构生成
|
||
- 状态：已完成
|
||
- 涉及数据库变更：**是**
|
||
- SQL 脚本：[2026-02-03-003-04-异步操作日志.sql](../sql/2026-02-03-003-04-异步操作日志.sql)
|
||
- 数据库变更内容：
|
||
1. **新建表**：`datai_metadata_async`
|
||
- 13 个字段：id, async_id, status, done, message, error_message, operation_time, user_id, create_by, create_time, update_by, update_time, del_flag
|
||
- 5 个索引：idx_async_id, idx_status, idx_operation_time, idx_user_id, idx_create_time
|
||
2. **表用途**：记录 Metadata API 异步操作的状态查询、轮询、取消等操作历史
|
||
3. **字段说明**：
|
||
- async_id: 异步操作ID（Salesforce返回）
|
||
- status: 操作状态（Queued/InProgress/Completed/Failed/Canceled/Timeout）
|
||
- done: 是否完成（0否 1是）
|
||
- message: 操作消息
|
||
- error_message: 错误消息
|
||
- operation_time: 操作时间
|
||
|
||
## 待完成阶段
|
||
- [x] 阶段 1：需求定义
|
||
- [x] 阶段 2：方案设计
|
||
- [x] 阶段 3：方案决策
|
||
- [x] 阶段 4：数据库结构生成
|
||
- [ ] 阶段 5：提示词生成
|
||
- [ ] 阶段 6：代码生成
|
||
- [ ] 阶段 7：会话记录
|
||
- [ ] 阶段 8：变更日志
|
||
- [ ] 阶段 9：复盘和 API 文档
|
||
- [ ] 阶段 10：代码提交
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/sub/2026-01-28-003-04-异步操作.md)
|
||
- [设计文档](../design/2026-02-03-003-04-异步操作-设计.md)
|
||
- [决策记录 - 异步操作技术选型](../decisions/2026-02-03-003-04-ADR-异步操作技术选型.md)
|
||
- [决策记录 - 异步操作轮询策略](../decisions/2026-02-03-003-04-ADR-异步操作轮询策略.md)
|
||
- [SQL 脚本](../sql/2026-02-03-003-04-异步操作日志.sql)
|
||
- [连接管理设计文档](../design/2026-02-02-003-01-连接管理-设计.md)
|