219 lines
9.0 KiB
Markdown
219 lines
9.0 KiB
Markdown
# 架构决策记录 - Quick Deploy功能实现
|
||
|
||
## 背景
|
||
|
||
REQ-010-9 要求实现 Quick Deploy 功能，支持基于最近一次成功的部署记录快速重新部署，无需重新运行测试。Quick Deploy 是 Salesforce Metadata API 提供的一个特殊功能，允许用户在最近一次成功部署的基础上快速重新部署相同的元数据，跳过测试步骤，从而显著提高部署速度。
|
||
|
||
当前系统已经实现了元数据部署核心功能（REQ-010-8），包括手动触发部署、异步部署执行、状态监控、部署历史记录、部署进度查询、部署取消功能和部署结果解析。Quick Deploy 功能需要基于现有的部署历史记录，提供快速重新部署的能力。
|
||
|
||
## 决策
|
||
|
||
### 1. Quick Deploy 触发方案
|
||
|
||
**决策**: 使用 RESTful API 接口实现 Quick Deploy 触发，基于最近一次成功的部署记录，使用 MetadataApiClient 的 quickDeploy() 方法。
|
||
|
||
**理由**:
|
||
- RESTful API 是标准的接口设计模式，易于使用和理解
|
||
- 可以与前端组件无缝集成
|
||
- 支持多种客户端（Web、移动端、第三方应用）
|
||
- 符合项目现有的 API 设计规范
|
||
- 基于最近一次成功的部署记录，确保 Quick Deploy 的可用性
|
||
|
||
**实现方案**:
|
||
- 创建 QuickDeployController 控制器
|
||
- 提供 POST /metadata/quick-deploy/trigger 接口
|
||
- 接收组织配置ID作为参数
|
||
- 查询最近一次成功的部署记录
|
||
- 验证 Quick Deploy 可用性（检查部署记录是否在 30 天内）
|
||
- 调用 MetadataApiService 的 quickDeployAsync() 方法
|
||
- 返回 Job ID 和初始状态
|
||
|
||
### 2. Quick Deploy 历史记录方案
|
||
|
||
**决策**: 使用 MyBatis Plus 的 BaseMapper 实现 Quick Deploy 历史记录查询，支持分页查询和条件查询。
|
||
|
||
**理由**:
|
||
- MyBatis Plus 是项目现有的持久层框架，符合技术栈要求
|
||
- BaseMapper 提供了丰富的查询方法，易于使用
|
||
- 支持分页查询，避免一次性加载大量数据
|
||
- 支持条件查询，灵活满足不同的查询需求
|
||
- 与现有的部署历史记录保持一致的设计模式
|
||
|
||
**实现方案**:
|
||
- 使用 DataiMetaJobExecution 表存储 Quick Deploy 历史记录
|
||
- 使用 jobType 字段区分 Quick Deploy 和普通部署
|
||
- 使用 MyBatis Plus 的 BaseMapper 实现查询
|
||
- 使用 Page 对象实现分页查询
|
||
- 使用 QueryWrapper 实现条件查询
|
||
|
||
### 3. Quick Deploy 状态监控方案
|
||
|
||
**决策**: 使用状态机模式管理 Quick Deploy 状态，使用轮询机制检查 Quick Deploy 状态，复用现有的 DeployStatus 枚举和状态管理逻辑。
|
||
|
||
**理由**:
|
||
- 状态机模式可以清晰地管理状态转换，避免状态混乱
|
||
- 轮询机制可以实时获取 Quick Deploy 状态，提供准确的进度信息
|
||
- 复用现有的 DeployStatus 枚举和状态管理逻辑，保持代码一致性
|
||
- 与现有的部署状态监控保持一致的设计模式
|
||
- 易于扩展和维护
|
||
|
||
**实现方案**:
|
||
- 复用 DeployStatus 枚举（Pending/Processing/Success/Failed/Partial_Success/Cancelled）
|
||
- 使用状态机模式管理 Quick Deploy 状态转换
|
||
- 使用轮询机制检查 Quick Deploy 状态
|
||
- 使用定时任务定期检查 Quick Deploy 状态
|
||
- 使用 ConcurrentHashMap 缓存 Quick Deploy 进度信息
|
||
|
||
### 4. Quick Deploy 结果解析方案
|
||
|
||
**决策**: 使用 JSON 解析库处理 API 响应，使用正则表达式提取错误信息，复用现有的部署结果解析逻辑。
|
||
|
||
**理由**:
|
||
- JSON 解析库可以方便地处理 Salesforce Metadata API 的响应
|
||
- 正则表达式可以灵活地提取错误信息，适应不同的错误格式
|
||
- 复用现有的部署结果解析逻辑，保持代码一致性
|
||
- 与现有的部署结果解析保持一致的设计模式
|
||
- 易于扩展和维护
|
||
|
||
**实现方案**:
|
||
- 使用 Jackson 或 Gson 解析 JSON 响应
|
||
- 使用正则表达式提取错误信息和代码覆盖率
|
||
- 将解析结果存储到数据库
|
||
- 提供详细的错误信息给用户
|
||
- 支持多种部署状态（Success/Failed/Partial_Success）
|
||
|
||
## 备选方案
|
||
|
||
### 方案 1: 使用消息队列实现异步 Quick Deploy
|
||
|
||
**优点**:
|
||
- 解耦部署触发和部署执行
|
||
- 支持高并发部署
|
||
- 提供更好的可扩展性
|
||
|
||
**缺点**:
|
||
- 增加系统复杂度
|
||
- 需要额外的消息队列基础设施
|
||
- 增加运维成本
|
||
- 与现有的异步执行机制不一致
|
||
|
||
**未选择原因**: 现有的 @Async 机制已经能够满足需求，使用消息队列会增加不必要的复杂度。
|
||
|
||
### 方案 2: 使用 WebSocket 实现实时状态推送
|
||
|
||
**优点**:
|
||
- 实时推送状态更新
|
||
- 减少客户端轮询频率
|
||
- 提供更好的用户体验
|
||
|
||
**缺点**:
|
||
- 增加系统复杂度
|
||
- 需要维护 WebSocket 连接
|
||
- 增加服务器负载
|
||
- 与现有的轮询机制不一致
|
||
|
||
**未选择原因**: 现有的轮询机制已经能够满足需求，使用 WebSocket 会增加不必要的复杂度。
|
||
|
||
## 影响
|
||
|
||
### 系统架构影响
|
||
|
||
- **新增模块**: QuickDeployController、IQuickDeployService、QuickDeployServiceImpl
|
||
- **现有模块**: MetadataApiClient 需要添加 quickDeploy() 方法
|
||
- **数据库**: 使用现有的 DataiMetaJobExecution 表，无需新增表
|
||
- **API**: 新增 4 个 RESTful API 接口
|
||
|
||
### 开发流程影响
|
||
|
||
- **开发工作量**: 中等，复用现有的部署核心功能代码
|
||
- **测试工作量**: 中等，需要测试 Quick Deploy 的特殊场景
|
||
- **文档工作量**: 低，复用现有的文档模板
|
||
|
||
### 运维管理影响
|
||
|
||
- **部署复杂度**: 低，与现有部署流程一致
|
||
- **监控复杂度**: 低，复用现有的监控机制
|
||
- **日志复杂度**: 低，复用现有的日志机制
|
||
|
||
## 风险
|
||
|
||
### 技术风险
|
||
|
||
- **Quick Deploy 验证风险**: Quick Deploy 验证逻辑复杂可能导致验证不准确
|
||
- **缓解措施**: 仔细验证 Quick Deploy 的可用性条件，包括部署记录是否在 30 天内、部署状态是否为 Success 等
|
||
- **状态监控风险**: 状态监控不准确可能导致 Quick Deploy 状态不一致
|
||
- **缓解措施**: 使用状态机模式管理状态转换，确保状态转换的正确性
|
||
- **结果解析风险**: 结果解析不完善可能导致错误信息不准确
|
||
- **缓解措施**: 使用正则表达式提取错误信息，确保错误信息的准确性
|
||
|
||
### 业务风险
|
||
|
||
- **Quick Deploy 可用性风险**: Quick Deploy 可能在某些情况下不可用
|
||
- **缓解措施**: 提供清晰的错误信息，告知用户 Quick Deploy 不可用的原因
|
||
- **部署历史记录风险**: Quick Deploy 历史记录过多可能影响查询性能
|
||
- **缓解措施**: 使用分页查询，定期清理过期历史记录
|
||
|
||
### 实施风险
|
||
|
||
- **依赖风险**: 依赖于 REQ-010-1, REQ-010-2, REQ-010-8
|
||
- **缓解措施**: 确保依赖的需求已经完成，避免依赖问题
|
||
|
||
## 回滚策略
|
||
|
||
如果 Quick Deploy 功能实施后出现问题，可以采取以下回滚策略：
|
||
|
||
1. **禁用 Quick Deploy 功能**: 通过配置开关禁用 Quick Deploy 功能，回退到普通部署
|
||
2. **删除 Quick Deploy 相关代码**: 删除 QuickDeployController、IQuickDeployService、QuickDeployServiceImpl 等代码
|
||
3. **清理 Quick Deploy 历史记录**: 清理 DataiMetaJobExecution 表中的 Quick Deploy 记录
|
||
4. **恢复 API**: 删除 Quick Deploy 相关的 API 接口
|
||
|
||
## 验收标准
|
||
|
||
### 功能验收标准
|
||
|
||
- Quick Deploy 触发成功，支持选择最近一次成功的部署记录
|
||
- Quick Deploy 验证成功，检查部署记录是否在 30 天内
|
||
- Quick Deploy 历史记录成功，支持分页查询和条件查询
|
||
- Quick Deploy 状态监控正常工作，使用状态机管理 Quick Deploy 状态
|
||
- Quick Deploy 结果解析成功，错误信息提取正确
|
||
|
||
### 性能验收标准
|
||
|
||
- Quick Deploy 触发响应时间 < 1s
|
||
- Quick Deploy 状态轮询任务执行时间 < 1s
|
||
- Quick Deploy 进度查询响应时间 < 500ms
|
||
- Quick Deploy 历史记录查询响应时间 < 1s
|
||
|
||
### 代码质量验收标准
|
||
|
||
- 代码符合项目编码规范，有清晰的注释
|
||
- 单元测试覆盖率 > 80%
|
||
- 集成测试通过率 100%
|
||
- 无严重的代码质量问题
|
||
|
||
## 视觉锚点
|
||
|
||
### Visual Reference
|
||
|
||
引用 Canvas 的具体节点或快照：
|
||
- [Authentication.canvas](../../Authentication.canvas) - 相关架构图
|
||
- **具体节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
- **具体节点**: [IMetadataApiService](node_metadata_api_service) - 元数据API服务接口
|
||
- **具体节点**: [MetadataApiClient](node_metadata_api_client) - Metadata API客户端
|
||
|
||
### Status
|
||
|
||
- [x] Draft
|
||
- [ ] Accepted
|
||
- [ ] Superceded
|
||
|
||
## 参考资料
|
||
|
||
列出与该决策相关的参考资料，包括文档、文章或其他资源：
|
||
|
||
- [REQ-010-9.md](../requirements/REQ-010-9.md) - Quick Deploy功能实现需求文档
|
||
- [REQ-010-8.md](../requirements/REQ-010-8.md) - 元数据部署核心功能需求文档
|
||
- [metadata-module.md](../reference-code/com/docs/metadata-module.md) - Salesforce Metadata API 模块说明
|
||
- [004-元数据部署网页资料链接地址](../reference-code/metadata/004-元数据部署网页资料链接地址) - 官方文档和开源项目参考
|
||
- [Salesforce Metadata API Quick Deploy](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_quickdeploy.htm) - Salesforce 官方文档
|