94 lines
5.0 KiB
Markdown
94 lines
5.0 KiB
Markdown
# 会话记录 - 检查部署和检索状态
|
||
|
||
## 元数据
|
||
- 需求编号：003-07
|
||
- 需求名称：检查部署和检索状态
|
||
- 开始时间：2026-02-03
|
||
- 结束时间：2026-02-03
|
||
- 当前阶段：阶段 4：数据库结构生成
|
||
|
||
## 阶段记录
|
||
|
||
### 阶段 1：需求定义
|
||
- 状态：已完成
|
||
- 需求文档：[2026-01-28-003-07-检查部署和检索状态.md](../requirements/sub/2026-01-28-003-07-检查部署和检索状态.md)
|
||
|
||
### 阶段 2：方案设计
|
||
- 状态：已完成
|
||
- 设计文档：[2026-02-03-003-07-检查部署和检索状态-设计.md](../design/2026-02-03-003-07-检查部署和检索状态-设计.md)
|
||
- 关键设计决策：
|
||
1. **架构设计**：采用分层架构（Controller → Service → Repository → Metadata API），复用 003-01 的连接管理
|
||
2. **核心功能**：
|
||
- 检查部署状态：`checkDeployStatus(asyncId, includeDetails)` → `DeployResult`
|
||
- 检查检索状态：`checkRetrieveStatus(asyncId, includeDetails)` → `RetrieveResult`
|
||
3. **技术选型**：
|
||
- Spring Boot 2.7.x (配合若依框架)
|
||
- MyBatis Plus 3.5.x 进行数据库交互
|
||
- Salesforce Metadata API (WSC/Partner JAR)
|
||
- MySQL 8.0 数据库
|
||
4. **数据模型**：创建 `datai_metadata_status_check` 表，包含 8 个字段
|
||
- 字段：check_id, async_id, operation_type, status, check_time, error_message, created_by, create_time
|
||
- 关联表更新：同步更新 `datai_metadata_deploy` 和 `datai_metadata_retrieve` 表的状态
|
||
5. **核心算法**：
|
||
- **状态检查**：调用 `connection.checkDeployStatus(asyncId)` 或 `connection.checkRetrieveStatus(asyncId)` → 获取结果 → 更新关联表 → 记录检查历史
|
||
- **数据同步**：根据 asyncId 查询本地记录 → 更新状态、完成时间、错误信息等字段
|
||
- **审计日志**：每次检查结果写入 `datai_metadata_status_check` 表
|
||
6. **接口设计**：2 个 REST API 接口
|
||
- `GET /metadata/deploy/{asyncId}/status?includeDetails={boolean}` - 检查部署状态
|
||
- `GET /metadata/retrieve/{asyncId}/status?includeDetails={boolean}` - 检查检索状态
|
||
7. **实体类设计**：
|
||
- `MetadataStatusCheckEntity`：状态检查记录实体
|
||
- 复用 `MetadataDeployEntity` 和 `MetadataRetrieveEntity` 进行关联表更新
|
||
8. **异常处理**：
|
||
- 捕获 `ConnectionException`，转换为 `SalesforceOperationException`
|
||
- 即使 API 调用失败，也要记录检查失败的日志到 `datai_metadata_status_check`
|
||
9. **性能优化**：
|
||
- 支持轻量级调用（`includeDetails=false`），仅在需要详细错误信息时开启详情
|
||
- 数据库更新操作使用事务，确保一致性
|
||
10. **安全设计**：
|
||
- 验证 `asyncId` 的格式合法性
|
||
- 基于 Spring Security 确保只有授权用户可以查询状态
|
||
|
||
### 阶段 3：方案决策
|
||
- 状态：已完成
|
||
- 决策文档：[2026-02-03-003-07-ADR-检查部署和检索状态技术选型.md](../decisions/2026-02-03-003-07-ADR-检查部署和检索状态技术选型.md)
|
||
- 关键决策：
|
||
1. **状态检查机制**：主动查询 (Active Polling)
|
||
- 理由：Metadata API 不支持 Webhook，主动查询是官方推荐的标准做法
|
||
2. **轮询策略**：复用服务端同步轮询 (Server-side Synchronous Polling)
|
||
- 理由：保持一致性，简化客户端，复用 ADR-003-04 的轮询策略
|
||
3. **数据存储与审计**：独立审计表 + 主表状态同步
|
||
- 理由：可追溯性（排查操作卡住或失败的原因），数据完整性（主表展示最新状态，审计表展示过程）
|
||
|
||
### 阶段 4：数据库结构生成
|
||
- 状态：已完成
|
||
- 涉及数据库变更：是
|
||
- SQL 脚本：[2026-02-03-003-07-状态检查日志.sql](../sql/2026-02-03-003-07-状态检查日志.sql)
|
||
- 数据库变更内容：
|
||
1. **创建表**：`datai_metadata_status_check`
|
||
- 12 个字段：id, check_id, async_id, operation_type, status, check_time, error_message, create_by, create_time, update_by, update_time, del_flag
|
||
- 6 个索引：idx_check_id, idx_async_id, idx_operation_type, idx_status, idx_check_time, 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-07-检查部署和检索状态.md)
|
||
- [设计文档](../design/2026-02-03-003-07-检查部署和检索状态-设计.md)
|
||
- [决策文档](../decisions/2026-02-03-003-07-ADR-检查部署和检索状态技术选型.md)
|
||
- [SQL 脚本](../sql/2026-02-03-003-07-状态检查日志.sql)
|
||
- [连接管理设计文档](../design/2026-02-02-003-01-连接管理-设计.md)
|
||
- [部署操作设计文档](../design/2026-02-03-003-02-元数据部署-设计.md)
|
||
- [检索操作设计文档](../design/2026-02-03-003-06-检索操作-设计.md)
|