datai/docs/archive/decisions/adr/0022-version-rollback.md

架构决策记录 - 版本回溯功能

背景

在 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 - 相关架构图
• 具体节点: 集成核心 - 提供与Salesforce的各种连接方式

Status

• Draft
• Accepted
• Superceded

参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源：

• REQ-010-13.md - 版本回溯功能需求文档
• REQ-010-7.md - 文件存储和解压处理需求文档
• REQ-010-12.md - 文件哈希对比和增量检测需求文档
• file/index.md - 文件模块 API 文档索引（唯一真源）