Kris
2e6f087732
- 完成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方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
216 lines
7.8 KiB
Markdown
216 lines
7.8 KiB
Markdown
# 架构决策记录 - 版本回溯功能
|
||
|
||
## 背景
|
||
|
||
在 Salesforce 元数据拉取和部署过程中，需要支持版本回溯功能，以便在出现问题时能够查看和恢复历史版本的元数据文件。当前系统已经实现了文件存储和解压处理（REQ-010-7）和文件哈希对比和增量检测（REQ-010-12），需要在此基础上实现版本回溯功能。
|
||
|
||
版本回溯功能对于元数据管理至关重要，可以帮助用户：
|
||
1. 查看历史版本的元数据文件
|
||
2. 对比不同版本的差异
|
||
3. 恢复到指定的历史版本
|
||
4. 回滚到上一个版本
|
||
|
||
## 决策
|
||
|
||
### 1. 版本历史记录方案
|
||
|
||
**决策**: 使用 MyBatis Plus 的 BaseMapper 实现版本历史记录，使用时间戳记录版本。
|
||
|
||
**理由**:
|
||
- MyBatis Plus 的 BaseMapper 提供了丰富的 CRUD 方法，简化数据库操作
|
||
- 时间戳可以准确记录版本的时间信息
|
||
- 版本历史记录可以支持按时间查询、按任务查询、分页查询等
|
||
|
||
**实现方案**:
|
||
- 创建 MetadataVersion 实体类，存储版本历史信息
|
||
- 创建 MetadataVersionMapper 接口，使用 MyBatis Plus 的 BaseMapper
|
||
- 创建 IMetadataVersionService 服务接口
|
||
- 创建 MetadataVersionServiceImpl 服务实现
|
||
- 在每次拉取和部署时，自动记录版本信息
|
||
- 使用时间戳记录版本时间
|
||
- 支持按时间查询版本、按任务查询版本、分页查询
|
||
|
||
### 2. 版本对比方案
|
||
|
||
**决策**: 使用 Diff 算法对比文件内容，使用哈希值对比文件差异。
|
||
|
||
**理由**:
|
||
- Diff 算法可以准确对比文件内容的差异
|
||
- 哈希值对比可以快速判断文件是否发生变化
|
||
- 结合两种方式可以全面对比版本差异
|
||
|
||
**实现方案**:
|
||
- 创建 IVersionComparisonService 服务接口
|
||
- 创建 VersionComparisonServiceImpl 服务实现
|
||
- 使用 Google Diff Match Patch 库实现 Diff 算法
|
||
- 使用哈希值对比文件差异
|
||
- 支持文件内容对比、文件哈希对比
|
||
- 支持差异高亮显示
|
||
- 返回对比结果，包括新增、删除、修改的内容
|
||
|
||
### 3. 版本恢复方案
|
||
|
||
**决策**: 使用历史版本的文件进行恢复，使用事务确保恢复原子性。
|
||
|
||
**理由**:
|
||
- 历史版本的文件是完整的，可以直接用于恢复
|
||
- 事务可以确保恢复操作的原子性，避免数据不一致
|
||
- 恢复操作需要记录日志，便于追踪
|
||
|
||
**实现方案**:
|
||
- 创建 IVersionRecoveryService 服务接口
|
||
- 创建 VersionRecoveryServiceImpl 服务实现
|
||
- 使用历史版本的文件进行恢复
|
||
- 使用 @Transactional 注解确保恢复原子性
|
||
- 支持选择历史版本进行恢复
|
||
- 记录恢复日志，包括恢复时间、恢复人、恢复内容等
|
||
- 恢复前备份当前版本，以便回滚
|
||
|
||
### 4. 版本回滚方案
|
||
|
||
**决策**: 使用上一个版本的文件进行回滚，使用事务确保回滚原子性。
|
||
|
||
**理由**:
|
||
- 上一个版本的文件是最近的历史版本，可以快速回滚
|
||
- 事务可以确保回滚操作的原子性，避免数据不一致
|
||
- 回滚操作需要记录日志，便于追踪
|
||
|
||
**实现方案**:
|
||
- 创建 IVersionRollbackService 服务接口
|
||
- 创建 VersionRollbackServiceImpl 服务实现
|
||
- 使用上一个版本的文件进行回滚
|
||
- 使用 @Transactional 注解确保回滚原子性
|
||
- 支持一键回滚到上一个版本
|
||
- 记录回滚日志，包括回滚时间、回滚人、回滚内容等
|
||
- 回滚前备份当前版本，以便再次回滚
|
||
|
||
## 备选方案
|
||
|
||
### 备选方案 1: 使用 Git 进行版本管理
|
||
|
||
**优点**:
|
||
- Git 是成熟的版本管理系统，功能强大
|
||
- 支持分支管理、合并等高级功能
|
||
- 可以查看完整的版本历史
|
||
|
||
**缺点**:
|
||
- 增加依赖，增加项目复杂度
|
||
- 需要学习 Git 的使用方法
|
||
- 可能存在安全风险
|
||
|
||
**结论**: 不采用，因为增加依赖和复杂度，不符合项目需求。
|
||
|
||
### 备选方案 2: 使用文件系统快照
|
||
|
||
**优点**:
|
||
- 实现简单，无需额外依赖
|
||
- 可以快速创建快照
|
||
|
||
**缺点**:
|
||
- 占用大量存储空间
|
||
- 不支持细粒度的版本管理
|
||
- 不支持版本对比
|
||
|
||
**结论**: 不采用，因为占用大量存储空间，不支持细粒度的版本管理。
|
||
|
||
### 备选方案 3: 使用数据库存储文件内容
|
||
|
||
**优点**:
|
||
- 可以方便地查询和对比版本
|
||
- 支持细粒度的版本管理
|
||
|
||
**缺点**:
|
||
- 占用大量数据库空间
|
||
- 可能影响数据库性能
|
||
- 不适合存储大文件
|
||
|
||
**结论**: 不采用，因为占用大量数据库空间，可能影响数据库性能。
|
||
|
||
## 影响
|
||
|
||
### 对系统架构的影响
|
||
|
||
- 新增 version-rollback 包，包含版本回溯相关的服务、控制器、DTO、实体、Mapper、工具类
|
||
- 复用现有的 IFileStorageService 接口，用于读取和存储文件
|
||
- 复用现有的 IMetadataRetrieveService 服务接口，用于恢复版本
|
||
- 复用现有的 IMetadataDeployService 服务接口，用于回滚版本
|
||
|
||
### 对开发流程的影响
|
||
|
||
- 开发人员需要了解版本回溯的实现原理
|
||
- 需要编写单元测试和集成测试，确保功能正常
|
||
- 需要编写文档，说明如何使用版本回溯功能
|
||
|
||
### 对运维管理的影响
|
||
|
||
- 需要监控版本历史记录的存储空间
|
||
- 需要定期清理过期的版本历史记录
|
||
- 需要监控版本恢复和回滚的性能
|
||
|
||
## 风险
|
||
|
||
### 技术风险
|
||
|
||
- **版本记录风险**: 版本记录不完整可能导致无法恢复
|
||
- **缓解措施**: 在每次拉取和部署时自动记录版本信息，确保版本记录完整
|
||
- **对比风险**: 版本对比不准确可能导致误判
|
||
- **缓解措施**: 使用 Diff 算法和哈希值对比两种方式，确保对比准确
|
||
- **恢复风险**: 恢复操作失败可能导致数据不一致
|
||
- **缓解措施**: 使用事务确保恢复原子性，恢复前备份当前版本
|
||
- **回滚风险**: 回滚操作失败可能导致无法恢复
|
||
- **缓解措施**: 使用事务确保回滚原子性，回滚前备份当前版本
|
||
|
||
### 业务风险
|
||
|
||
- **存储空间风险**: 版本历史记录过多可能占用大量存储空间
|
||
- **缓解措施**: 定期清理过期的版本历史记录，限制版本历史记录的数量
|
||
|
||
### 实施风险
|
||
|
||
- **性能风险**: 版本对比和恢复性能可能不满足要求
|
||
- **缓解措施**: 使用异步执行，避免阻塞主线程
|
||
- **兼容性风险**: 新增功能可能与现有功能不兼容
|
||
- **缓解措施**: 充分测试，确保兼容性
|
||
|
||
## 回滚策略
|
||
|
||
如果决策实施后出现问题，可以采取以下回滚策略：
|
||
|
||
1. **禁用版本回溯**: 在配置中禁用版本回溯功能，回退到手动管理版本
|
||
2. **删除版本历史记录**: 如果版本历史记录出现问题，可以删除版本历史记录
|
||
3. **回退到手动恢复**: 如果版本恢复和回滚失败，可以回退到手动恢复
|
||
|
||
## 验收标准
|
||
|
||
定义验证该决策有效性的具体标准和测试方法：
|
||
|
||
1. **功能完整性**: 所有版本回溯功能能够正常工作
|
||
2. **性能指标**: 版本对比和恢复性能满足要求
|
||
3. **安全性**: 恢复和回滚操作安全可靠，有完整的日志记录
|
||
4. **代码规范性**: 代码符合项目编码规范，有清晰的注释
|
||
5. **可维护性**: 代码结构清晰，易于扩展和维护
|
||
6. **可测试性**: 代码易于单元测试和集成测试
|
||
|
||
## 视觉锚点
|
||
|
||
### Visual Reference
|
||
|
||
引用 Canvas 的具体节点或快照：
|
||
- [Authentication.canvas](../../Authentication.canvas) - 相关架构图
|
||
- **具体节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
|
||
### Status
|
||
|
||
- [x] Draft
|
||
- [ ] Accepted
|
||
- [ ] Superceded
|
||
|
||
## 参考资料
|
||
|
||
列出与该决策相关的参考资料，包括文档、文章或其他资源：
|
||
|
||
- [REQ-010-13.md](../requirements/REQ-010-13.md) - 版本回溯功能需求文档
|
||
- [REQ-010-7.md](../requirements/REQ-010-7.md) - 文件存储和解压处理需求文档
|
||
- [REQ-010-12.md](../requirements/REQ-010-12.md) - 文件哈希对比和增量检测需求文档
|
||
- [file/index.md](../api-docs/file/index.md) - 文件模块 API 文档索引（唯一真源）
|