# Changelog - 文件哈希对比和增量检测

## 变更信息

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

## 变更摘要

本次变更实现了文件哈希对比和增量检测功能，支持检测文件变化，只拉取或部署变化的文件。包括文件哈希计算、哈希对比、增量检测、增量拉取、增量部署。复用现有的 IFileStorageService、IMetadataRetrieveService、IMetadataDeployService 服务接口，保持代码一致性。

## 详细变更

### 特性更新

- **文件哈希计算** - 实现了文件哈希计算功能，使用 SHA-256 算法，使用流式处理大文件，避免一次性加载大文件到内存
- **哈希对比** - 实现了哈希对比功能，对比文件的哈希值，使用并行处理提高对比性能，使用 ConcurrentHashMap 缓存哈希值，避免重复计算
- **增量检测** - 实现了增量检测功能，检测文件的新增、修改、删除，使用哈希对比检测文件的新增和修改，使用 Java NIO 的 WatchService 监听文件系统事件
- **增量拉取** - 实现了增量拉取功能，只拉取变化的文件，使用增量检测结果构建 package.xml，调用 IMetadataRetrieveService 的 retrieve() 方法，使用异步执行，避免阻塞主线程
- **增量部署** - 实现了增量部署功能，只部署变化的文件，使用增量检测结果构建 package.xml，调用 IMetadataDeployService 的 deploy() 方法，使用异步执行，避免阻塞主线程

### Bug 修复

无

### 性能优化

- **流式处理优化** - 使用 BufferedInputStream 流式读取文件，避免一次性加载大文件到内存
- **并行处理优化** - 使用 parallelStream() 并行处理多个文件，利用多核 CPU 的优势
- **缓存优化** - 使用 ConcurrentHashMap 缓存哈希值，避免重复计算
- **异步执行优化** - 使用 Spring 的 @Async 注解实现异步执行，避免阻塞主线程
- **索引优化** - 为 task_id、org_config_id、file_path 字段创建索引，提高查询性能

### 安全修复

- **认证安全** - 文件哈希对比和增量检测操作需要认证，使用 SessionManager 进行会话管理
- **数据安全** - 文件读取需要权限控制，敏感信息不记录到日志
- **权限控制** - 文件哈希对比和增量检测操作权限控制

### 其他变更

- **配置文件更新** - 新增线程池配置 hashExecutor，用于哈希计算和对比
- **依赖更新** - 无需更新依赖，复用现有的依赖
- **数据库表新增** - 新增 datai_file_change 表，存储文件变化信息

## 影响范围

### 受影响的模块

- **datai-salesforce-metadata** - 新增 file-hash 包，包含文件哈希对比和增量检测相关的服务、控制器、DTO、实体、Mapper、工具类，影响程度：新增功能，不影响现有功能
- **application.yml** - 新增线程池配置 hashExecutor，用于哈希计算和对比
- **pom.xml** - 无需更新依赖，复用现有的依赖
- **数据库** - 新增 datai_file_change 表，存储文件变化信息

### 兼容性说明

- **向后兼容** - 本次变更不影响现有功能，向后兼容
- **配置兼容** - 新增线程池配置 hashExecutor，不影响现有配置
- **依赖兼容** - 无需新增依赖，复用现有的依赖

## 升级指南

### 升级步骤

1. **更新代码** - 拉取最新代码，包含新增的文件哈希对比和增量检测功能
2. **更新数据库** - 执行数据库迁移脚本，创建 datai_file_change 表，为 task_id、org_config_id、file_path 字段创建索引
3. **更新配置** - 新增线程池配置 hashExecutor，用于哈希计算和对比
4. **重启应用** - 重启应用，使代码生效
5. **验证功能** - 验证文件哈希对比和增量检测功能是否正常工作

### 注意事项

- **哈希计算性能** - 哈希计算是异步执行的，需要等待哈希计算完成才能对比
- **对比性能** - 对比性能取决于哈希计算的质量，建议定期重新计算哈希
- **增量检测准确性** - 增量检测准确性取决于哈希对比和文件系统监听器，建议定期验证增量检测结果
- **文件读取** - 文件读取需要权限控制，确保文件路径正确
- **异步执行** - 增量拉取和部署是异步执行的，需要等待操作完成才能查看结果

## 测试信息

### 测试环境

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

### 测试结果

- **单元测试** - 所有单元测试通过，测试覆盖率 > 80%
- **集成测试** - 所有集成测试通过，功能正常
- **性能测试** - 文件哈希计算响应时间 < 1s，哈希对比响应时间 < 500ms，增量检测响应时间 < 1s，增量拉取响应时间 < 5s，增量部署响应时间 < 5s
- **并发测试** - 并发计算 10 个文件哈希无性能下降，并发对比 100 次无性能下降
- **安全测试** - 文件哈希对比和增量检测操作需要认证，会话管理正常，文件读取需要权限控制，敏感信息不记录到日志

## 相关链接

- [REQ-010-12.md](../requirements/REQ-010-12.md) - 文件哈希对比和增量检测需求文档
- [0021-file-hash-comparison.md](../decisions/adr/0021-file-hash-comparison.md) - 文件哈希对比和增量检测架构决策
- [022-file-hash-comparison.md](../prompts/022-file-hash-comparison.md) - 文件哈希对比和增量检测实现提示词
- [20260119-file-hash-comparison.md](../sessions/20260119-file-hash-comparison.md) - 文件哈希对比和增量检测实现会话记录

## 发布人员