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方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
7.8 KiB
7.8 KiB
架构决策记录 - 版本回溯功能
背景
在 Salesforce 元数据拉取和部署过程中，需要支持版本回溯功能，以便在出现问题时能够查看和恢复历史版本的元数据文件。当前系统已经实现了文件存储和解压处理（REQ-010-7）和文件哈希对比和增量检测（REQ-010-12），需要在此基础上实现版本回溯功能。
版本回溯功能对于元数据管理至关重要，可以帮助用户：
- 查看历史版本的元数据文件
- 对比不同版本的差异
- 恢复到指定的历史版本
- 回滚到上一个版本
决策
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 算法和哈希值对比两种方式，确保对比准确
- 恢复风险: 恢复操作失败可能导致数据不一致
- 缓解措施: 使用事务确保恢复原子性，恢复前备份当前版本
- 回滚风险: 回滚操作失败可能导致无法恢复
- 缓解措施: 使用事务确保回滚原子性，回滚前备份当前版本
业务风险
- 存储空间风险: 版本历史记录过多可能占用大量存储空间
- 缓解措施: 定期清理过期的版本历史记录，限制版本历史记录的数量
实施风险
- 性能风险: 版本对比和恢复性能可能不满足要求
- 缓解措施: 使用异步执行，避免阻塞主线程
- 兼容性风险: 新增功能可能与现有功能不兼容
- 缓解措施: 充分测试，确保兼容性
回滚策略
如果决策实施后出现问题，可以采取以下回滚策略：
- 禁用版本回溯: 在配置中禁用版本回溯功能，回退到手动管理版本
- 删除版本历史记录: 如果版本历史记录出现问题，可以删除版本历史记录
- 回退到手动恢复: 如果版本恢复和回滚失败，可以回退到手动恢复
验收标准
定义验证该决策有效性的具体标准和测试方法：
- 功能完整性: 所有版本回溯功能能够正常工作
- 性能指标: 版本对比和恢复性能满足要求
- 安全性: 恢复和回滚操作安全可靠，有完整的日志记录
- 代码规范性: 代码符合项目编码规范，有清晰的注释
- 可维护性: 代码结构清晰，易于扩展和维护
- 可测试性: 代码易于单元测试和集成测试
视觉锚点
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 文档索引（唯一真源）