# Changelog - 版本回溯功能

## 变更信息

- **版本号**: v0.0.23
- **发布日期**: 2026-01-19
- **变更类型**: 特性更新

## 变更摘要

本次变更实现了版本回溯功能，支持查看和恢复历史版本的元数据文件。包括版本历史记录、版本对比、版本恢复、版本回滚。复用现有的 IFileStorageService、IMetadataRetrieveService、IMetadataDeployService 服务接口，保持代码一致性。

## 详细变更

### 特性更新

- **版本历史记录** - 实现了版本历史记录功能，记录每次拉取和部署的版本，使用 MyBatis Plus 的 BaseMapper 实现版本历史记录，使用时间戳记录版本
- **版本对比** - 实现了版本对比功能，对比不同版本的元数据文件，使用 Google Diff Match Patch 库实现 Diff 算法，使用哈希值对比文件差异，支持差异高亮显示
- **版本恢复** - 实现了版本恢复功能，恢复到指定的历史版本，使用历史版本的文件进行恢复，使用 @Transactional 注解确保恢复原子性
- **版本回滚** - 实现了版本回滚功能，回滚到上一个版本，使用上一个版本的文件进行回滚，使用 @Transactional 注解确保回滚原子性

### Bug 修复

无

### 性能优化

- **索引优化** - 为 task_id、org_config_id、file_path、version_time 字段创建索引，提高查询性能
- **分页查询优化** - 使用 MyBatis Plus 的分页插件实现分页查询，避免一次性加载大量数据
- **异步执行优化** - 使用 Spring 的 @Async 注解实现异步执行，避免阻塞主线程
- **缓存优化** - 使用缓存存储版本信息，提高查询性能

### 安全修复

- **认证安全** - 版本回溯操作需要认证，使用 SessionManager 进行会话管理
- **数据安全** - 版本恢复和回滚操作需要权限控制，敏感信息不记录到日志
- **权限控制** - 版本回溯操作权限控制
- **事务安全** - 使用 @Transactional 注解确保恢复和回滚的原子性

### 其他变更

- **配置文件更新** - 新增线程池配置 versionExecutor，用于版本恢复和回滚
- **依赖更新** - 新增 Google Diff Match Patch 依赖，用于版本对比
- **数据库表新增** - 新增 datai_metadata_version 表，存储版本历史信息

## 影响范围

### 受影响的模块

- **datai-salesforce-metadata** - 新增 version-rollback 包，包含版本回溯相关的服务、控制器、DTO、实体、Mapper、工具类，影响程度：新增功能，不影响现有功能
- **application.yml** - 新增线程池配置 versionExecutor，用于版本恢复和回滚
- **pom.xml** - 新增 Google Diff Match Patch 依赖，用于版本对比
- **数据库** - 新增 datai_metadata_version 表，存储版本历史信息

### 兼容性说明

- **向后兼容** - 本次变更不影响现有功能，向后兼容
- **配置兼容** - 新增线程池配置 versionExecutor，不影响现有配置
- **依赖兼容** - 新增 Google Diff Match Patch 依赖，不影响现有依赖

## 升级指南

### 升级步骤

1. **更新代码** - 拉取最新代码，包含新增的版本回溯功能
2. **更新依赖** - 添加 Google Diff Match Patch 依赖
3. **更新数据库** - 执行数据库迁移脚本，创建 datai_metadata_version 表，为 task_id、org_config_id、file_path、version_time 字段创建索引
4. **更新配置** - 新增线程池配置 versionExecutor，用于版本恢复和回滚
5. **重启应用** - 重启应用，使代码生效
6. **验证功能** - 验证版本回溯功能是否正常工作

### 注意事项

- **版本记录** - 系统会自动记录版本信息，无需手动操作
- **版本对比** - 版本对比使用 Diff 算法和哈希值对比两种方式，确保对比准确
- **版本恢复** - 版本恢复需要选择历史版本，恢复前会备份当前版本
- **版本回滚** - 版本回滚会回滚到上一个版本，回滚前会备份当前版本
- **存储空间** - 版本历史记录会占用存储空间，建议定期清理过期的版本历史记录

## 测试信息

### 测试环境

- **开发环境** - Windows 10，Java 17，Spring Boot 3
- **测试环境** - Linux，Java 17，Spring Boot 3

### 测试结果

- **单元测试** - 所有单元测试通过，测试覆盖率 > 80%
- **集成测试** - 所有集成测试通过，功能正常
- **性能测试** - 版本历史记录查询响应时间 < 1s，版本对比响应时间 < 500ms，版本恢复响应时间 < 5s，版本回滚响应时间 < 5s
- **并发测试** - 并发查询 100 次无性能下降，并发恢复 10 次无性能下降
- **安全测试** - 版本回溯操作需要认证，会话管理正常，版本恢复和回滚操作需要权限控制，敏感信息不记录到日志

## 相关链接

- [REQ-010-13.md](../requirements/REQ-010-13.md) - 版本回溯功能需求文档
- [0022-version-rollback.md](../decisions/adr/0022-version-rollback.md) - 版本回溯功能架构决策
- [023-version-rollback.md](../prompts/023-version-rollback.md) - 版本回溯功能实现提示词
- [20260119-version-rollback.md](../sessions/20260119-version-rollback.md) - 版本回溯功能实现会话记录

## 发布人员