kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dd4efbd4e1
datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0018-quick-deploy.md
Kris 2e6f087732 docs: 完成REQ-010-17和REQ-010-2的文档创建 
- 完成REQ-010-17（性能优化和限流处理）的所有6个阶段
  - 创建ADR文档：0026-performance-optimization.md
  - 创建Prompt文档：027-performance-optimization.md
  - 创建会话记录：20260119-performance-optimization.md
  - 创建变更记录：20260119-performance-optimization.md
  - 创建复盘报告：20260119-performance-optimization-retro.md
  - 更新index.md和CHANGELOG.md

- 完成REQ-010-2（基础实体类和Mapper创建）的前3个阶段
  - 更新ADR文档：0011-entity-mapper-create.md
  - 创建Prompt文档：002-entity-mapper-create.md
  - 更新index.md

所有文档均按照SSOT方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
2026-01-19 10:06:09 +08:00

219 lines
9.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 架构决策记录 - 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 官方文档
Reference in New Issue View Git Blame Copy Permalink