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

## 背景

在 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 文档索引（唯一真源）