# Requirements - 文件哈希对比和增量检测 ## 需求信息 - **需求名称**: 文件哈希对比和增量检测 - **需求类型**: 功能需求 - **需求编号**: REQ-010-12 - **父需求**: REQ-010 - **创建日期**: 2026-01-17 - **需求版本**: v1.0.0 - **需求提出人**: 系统管理员 - **需求状态**: 待审核 ## 输入引用 引用相关的 docs 文档链接： - [REQ-010.md](REQ-010.md) - Salesforce元数据拉取和部署主需求文档 - [REQ-010-1.md](REQ-010-1.md) - 数据库表结构设计和创建 - [REQ-010-2.md](REQ-010-2.md) - 基础实体类和Mapper创建 - [REQ-010-7.md](REQ-010-7.md) - 文件存储和解压处理 - [REQ-010-11.md](REQ-010-11.md) - 元数据组件索引和查询 - [010-metadata-retrieve-deploy-sub-requirements.md](010-metadata-retrieve-deploy-sub-requirements.md) - REQ-010子需求拆分文档 - [file/index.md](../api-docs/file/index.md) - 文件模块 API 文档索引（唯一真源） ## Context Maps 强制列出本次需求依赖的 Canvas 文件： - [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示 - **相关节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式 ## 需求目标 实现文件哈希对比和增量检测功能，支持检测文件变化，只拉取或部署变化的文件。 ## 需求描述 ### 概述 本需求旨在实现文件哈希对比和增量检测功能，包括文件哈希计算、哈希对比、增量检测、增量拉取、增量部署等。 ### 详细需求 #### 1. 文件哈希计算 - **需求描述**: 实现文件哈希计算功能，使用SHA-256算法 - **优先级**: 中 - **验收标准**: - 文件哈希计算成功 - 使用SHA-256算法 - 哈希值准确 - 支持大文件处理 - 内存使用合理 - 使用IFileHashService服务接口和FileHashServiceImpl实现类 - 使用Java MessageDigest计算SHA-256哈希 - 使用MessageDigest.getInstance("SHA-256")获取SHA-256哈希算法实例 - 使用BufferedInputStream流式读取文件，避免一次性加载大文件到内存 - 使用8KB缓冲区，平衡内存使用和读取性能 - 使用8192字节缓冲区大小 - 支持计算单个文件哈希值 - 支持批量计算文件哈希值 - 支持异步计算文件哈希值 - 提供calculateHash(File file)方法计算单个文件哈希值 - 提供calculateHashes(File[] files)方法批量计算文件哈希值 - 提供calculateHashAsync(File file)方法异步计算文件哈希值 - 使用CompletableFuture.supplyAsync()实现异步计算 - 使用try-with-resources确保资源正确释放 - 使用StringBuilder构建十六进制字符串 - 使用Integer.toHexString(0xff & b)转换字节为十六进制 - 处理单字节十六进制补零 - 返回64位十六进制字符串 - 使用BUFFER_SIZE常量定义缓冲区大小 - 使用HASH_ALGORITHM常量定义哈希算法 - 使用RuntimeException包装异常 - 哈希计算响应时间 < 100ms（1MB文件） - 批量哈希计算1000个文件无性能下降 - 内存使用 < 10MB（计算100个1MB文件） - **依赖关系**: 依赖于REQ-010-1, REQ-010-2, REQ-010-7 - **实现建议**: 使用IFileHashService服务接口和FileHashServiceImpl实现类，使用Java MessageDigest计算SHA-256哈希，使用流式处理大文件 #### 2. 哈希对比 - **需求描述**: 实现哈希对比功能，对比文件的哈希值 - **优先级**: 中 - **验收标准**: - 哈希对比功能正常工作 - 对比结果准确 - 支持批量对比 - 对比性能满足要求 - 使用IHashComparisonService服务接口和HashComparisonServiceImpl实现类 - 使用String.equals()方法对比哈希值 - 使用parallelStream()并行处理多个文件 - 使用ConcurrentHashMap缓存哈希值，避免重复计算 - 提供compare(String hash1, String hash2)方法对比两个哈希值 - 提供compare(Map hashMap1, Map hashMap2)方法批量对比哈希值 - 提供findChangedFiles(Map hashMap1, Map hashMap2)方法查找变化的文件 - 处理null值，两个null值视为相等 - 处理一个null一个非null的情况，视为不相等 - 使用HashSet合并所有文件路径 - 使用parallelStream()并行处理所有文件路径 - 使用ConcurrentHashMap存储对比结果 - 返回Map存储每个文件的对比结果 - 返回Set存储变化的文件路径 - 对比响应时间 < 50ms（对比1000个文件） - 批量对比1000个文件无性能下降 - 支持并发对比，使用线程安全的数据结构 - **依赖关系**: 依赖于文件哈希计算 - **实现建议**: 使用IHashComparisonService服务接口和HashComparisonServiceImpl实现类，使用哈希值直接对比，使用并行处理提高对比性能 #### 3. 增量检测 - **需求描述**: 实现增量检测功能，检测文件变化 - **优先级**: 中 - **验收标准**: - 增量检测功能正常工作 - 检测结果准确 - 支持新增文件检测 - 支持修改文件检测 - 支持删除文件检测 - 使用IIncrementalDetectionService服务接口和IncrementalDetectionServiceImpl实现类 - 使用哈希对比检测文件的新增和修改 - 使用Java NIO的WatchService监听文件系统事件 - 使用ChangeType枚举定义文件变化类型（ADDED、MODIFIED、DELETED） - 使用FileChange实体类记录文件变化信息 - 使用FileChangeMapper进行数据库操作 - 使用MyBatis Plus的BaseMapper实现数据库操作 - 提供detectChanges(Map oldHashMap, Map newHashMap)方法检测文件变化 - 提供detectChangesAsync(Map oldHashMap, Map newHashMap)方法异步检测文件变化 - 提供watchFileSystem(File directory, FileChangeCallback callback)方法监听文件系统变化 - 提供stopWatching()方法停止监听文件系统变化 - 使用FileSystems.getDefault().newWatchService()获取WatchService实例 - 使用path.register()方法注册监听事件 - 使用StandardWatchEventKinds.ENTRY_CREATE监听文件创建事件 - 使用StandardWatchEventKinds.ENTRY_MODIFY监听文件修改事件 - 使用StandardWatchEventKinds.ENTRY_DELETE监听文件删除事件 - 使用WatchKey.pollEvents()获取文件系统事件 - 使用event.kind()获取事件类型 - 使用event.context()获取文件路径 - 使用dir.resolve()解析完整文件路径 - 使用key.reset()重置监听键 - 使用watchKeys.remove()移除无效的监听键 - 使用watchService.take()阻塞等待事件 - 使用while(watching)循环监听 - 使用Thread启动监听线程 - 使用interrupt()中断监听线程 - 使用watchService.close()关闭WatchService - 使用try-catch处理异常 - 使用InterruptedException处理中断异常 - 使用volatile boolean watching控制监听状态 - 使用Map存储监听键和路径映射 - 使用CompletableFuture.supplyAsync()实现异步检测 - 使用HashSet合并所有文件路径 - 使用ArrayList存储文件变化列表 - 判断oldHash为null且newHash不为null时，标记为ADDED - 判断oldHash不为null且newHash为null时，标记为DELETED - 判断oldHash不为null且newHash不为null且不相等时，标记为MODIFIED - 使用LocalDateTime.now()记录检测时间 - 使用FileChange实体类记录文件路径、变化类型、旧哈希值、新哈希值、检测时间 - 支持FileChangeCallback回调接口 - 使用onFileChange(String filePath, ChangeType changeType)方法回调文件变化 - 使用StandardWatchEventKinds.OVERFLOW处理事件溢出 - 检测响应时间 < 200ms（检测1000个文件） - 批量检测1000个文件无性能下降 - 文件系统监听响应时间 < 10ms - 支持并发检测，使用线程安全的数据结构 - 支持实时监听，使用Java NIO的WatchService - **依赖关系**: 依赖于哈希对比 - **实现建议**: 使用IIncrementalDetectionService服务接口和IncrementalDetectionServiceImpl实现类，使用哈希对比检测文件变化，使用文件系统监听器检测文件删除 #### 4. 增量拉取 - **需求描述**: 实现增量拉取功能，只拉取变化的文件 - **优先级**: 中 - **验收标准**: - 增量拉取功能正常工作 - 只拉取变化的文件 - 拉取结果准确 - 拉取性能满足要求 - 使用IIncrementalRetrieveService服务接口和IncrementalRetrieveServiceImpl实现类 - 使用增量检测结果构建package.xml - 调用IMetadataRetrieveService的retrieve()方法，传入package.xml - 使用异步执行，避免阻塞主线程 - 复用现有的AsyncConfig配置类和线程池 - 使用Spring的@Async注解标记异步方法 - 使用buildPackageXml(List changes)方法构建package.xml - 使用CompletableFuture.supplyAsync()实现异步拉取 - 使用Future对象跟踪异步任务状态 - 只拉取变化的文件，减少网络传输和处理时间 - 支持按文件变化类型过滤（ADDED、MODIFIED、DELETED） - 支持按文件路径过滤 - 支持按元数据类型过滤 - 支持按组织配置ID过滤 - 支持按任务ID过滤 - 使用FileChange实体类记录文件变化信息 - 使用ChangeType枚举定义文件变化类型 - 使用XML构建工具构建package.xml - 使用package.xml格式符合Salesforce Metadata API规范 - 使用types元素定义元数据类型 - 使用members元素定义组件名称 - 使用version元素定义API版本 - 使用try-catch处理异常 - 使用日志记录拉取过程 - 使用事务确保数据一致性 - 使用@Transactional注解管理事务 - 拉取响应时间 < 5s（拉取100个文件） - 批量拉取1000个文件无性能下降 - 网络传输时间 < 3s - 文件处理时间 < 2s - 支持并发拉取，使用线程池 - 支持拉取进度查询，使用Future对象 - 支持拉取取消，使用Future.cancel() - 支持拉取重试，使用重试机制 - 支持拉取失败处理，使用异常处理 - 支持拉取结果缓存，使用缓存机制 - 支持拉取结果导出，使用导出工具 - **依赖关系**: 依赖于增量检测和REQ-010-6 - **实现建议**: 使用IIncrementalRetrieveService服务接口和IncrementalRetrieveServiceImpl实现类，使用增量检测结果构建package.xml，只拉取变化的文件 #### 5. 增量部署 - **需求描述**: 实现增量部署功能，只部署变化的文件 - **优先级**: 中 - **验收标准**: - 增量部署功能正常工作 - 只部署变化的文件 - 部署结果准确 - 部署性能满足要求 - 使用IIncrementalDeployService服务接口和IncrementalDeployServiceImpl实现类 - 使用增量检测结果构建package.xml - 调用IMetadataDeployService的deploy()方法，传入package.xml - 使用异步执行，避免阻塞主线程 - 复用现有的AsyncConfig配置类和线程池 - 使用Spring的@Async注解标记异步方法 - 使用buildPackageXml(List changes)方法构建package.xml - 使用CompletableFuture.supplyAsync()实现异步部署 - 使用Future对象跟踪异步任务状态 - 只部署变化的文件，减少网络传输和处理时间 - 支持按文件变化类型过滤（ADDED、MODIFIED、DELETED） - 支持按文件路径过滤 - 支持按元数据类型过滤 - 支持按组织配置ID过滤 - 支持按任务ID过滤 - 使用FileChange实体类记录文件变化信息 - 使用ChangeType枚举定义文件变化类型 - 使用XML构建工具构建package.xml - 使用package.xml格式符合Salesforce Metadata API规范 - 使用types元素定义元数据类型 - 使用members元素定义组件名称 - 使用version元素定义API版本 - 使用try-catch处理异常 - 使用日志记录部署过程 - 使用事务确保数据一致性 - 使用@Transactional注解管理事务 - 部署响应时间 < 5s（部署100个文件） - 批量部署1000个文件无性能下降 - 网络传输时间 < 3s - 文件处理时间 < 2s - 支持并发部署，使用线程池 - 支持部署进度查询，使用Future对象 - 支持部署取消，使用Future.cancel() - 支持部署重试，使用重试机制 - 支持部署失败处理，使用异常处理 - 支持部署结果缓存，使用缓存机制 - 支持部署结果导出，使用导出工具 - 支持部署历史记录，使用DataiMetaJobExecution实体类 - 支持部署状态查询，使用DataiMetaJobExecutionMapper - 支持部署结果解析，使用部署结果解析工具 - 支持部署组件统计，使用组件统计工具 - 支持部署测试结果，使用测试结果解析工具 - 支持部署错误处理，使用错误处理工具 - 支持部署回滚，使用回滚工具 - 支持部署备份，使用备份工具 - 支持部署验证，使用验证工具 - 支持部署预览，使用预览工具 - 支持部署确认，使用确认工具 - **依赖关系**: 依赖于增量检测和REQ-010-8 - **实现建议**: 使用IIncrementalDeployService服务接口和IncrementalDeployServiceImpl实现类，使用增量检测结果构建package.xml，只部署变化的文件 ## 约束 - **技术栈限制**: 必须基于现有的Spring Boot 3 + Vue 3技术栈 - **架构约束**: 必须遵循Authentication.canvas中定义的架构和调用关系 - **模块约束**: 必须在datai-salesforce-metadata模块下实现 - **数据库约束**: 必须使用MyBatis Plus作为持久层框架 - **性能约束**: 哈希计算和对比性能必须满足要求 - **算法约束**: 必须使用SHA-256算法计算哈希 - **依赖约束**: 必须依赖于REQ-010-1, REQ-010-2, REQ-010-7, REQ-010-11 - **服务接口约束**: 必须使用IFileHashService、IHashComparisonService、IIncrementalDetectionService、IIncrementalRetrieveService、IIncrementalDeployService服务接口 - **服务实现约束**: 必须使用FileHashServiceImpl、HashComparisonServiceImpl、IncrementalDetectionServiceImpl、IncrementalRetrieveServiceImpl、IncrementalDeployServiceImpl实现类 - **实体类约束**: 必须使用FileChange实体类记录文件变化信息 - **枚举类约束**: 必须使用ChangeType枚举定义文件变化类型（ADDED、MODIFIED、DELETED） - **Mapper约束**: 必须使用FileChangeMapper进行数据库操作 - **异步注解约束**: 必须使用Spring的@Async注解标记异步方法 - **线程池约束**: 必须复用现有的AsyncConfig配置类和线程池 - **Future对象约束**: 必须使用Future对象跟踪异步任务状态 - **CompletableFuture约束**: 必须使用CompletableFuture.supplyAsync()实现异步计算 - **MessageDigest约束**: 必须使用Java MessageDigest计算SHA-256哈希 - **BufferedInputStream约束**: 必须使用BufferedInputStream流式读取文件 - **WatchService约束**: 必须使用Java NIO的WatchService监听文件系统事件 - **StandardWatchEventKinds约束**: 必须使用StandardWatchEventKinds监听文件创建、修改、删除事件 - **String.equals()约束**: 必须使用String.equals()方法对比哈希值 - **parallelStream()约束**: 必须使用parallelStream()并行处理多个文件 - **ConcurrentHashMap约束**: 必须使用ConcurrentHashMap缓存哈希值和对比结果 - **HashSet约束**: 必须使用HashSet合并所有文件路径 - **ArrayList约束**: 必须使用ArrayList存储文件变化列表 - **StringBuilder约束**: 必须使用StringBuilder构建十六进制字符串 - **Integer.toHexString()约束**: 必须使用Integer.toHexString(0xff & b)转换字节为十六进制 - **try-with-resources约束**: 必须使用try-with-resources确保资源正确释放 - **RuntimeException约束**: 必须使用RuntimeException包装异常 - **LocalDateTime.now()约束**: 必须使用LocalDateTime.now()记录检测时间 - **CompletableFuture.supplyAsync()约束**: 必须使用CompletableFuture.supplyAsync()实现异步检测、拉取、部署 - **Future.cancel()约束**: 必须使用Future.cancel()取消异步任务 - **volatile boolean约束**: 必须使用volatile boolean watching控制监听状态 - **Map约束**: 必须使用Map存储监听键和路径映射 - **Thread约束**: 必须使用Thread启动监听线程 - **interrupt()约束**: 必须使用interrupt()中断监听线程 - **watchService.close()约束**: 必须使用watchService.close()关闭WatchService - **try-catch约束**: 必须使用try-catch处理异常 - **InterruptedException约束**: 必须使用InterruptedException处理中断异常 - **StandardWatchEventKinds.OVERFLOW约束**: 必须使用StandardWatchEventKinds.OVERFLOW处理事件溢出 - **FileChangeCallback约束**: 必须支持FileChangeCallback回调接口 - **onFileChange()约束**: 必须使用onFileChange(String filePath, ChangeType changeType)方法回调文件变化 - **IMetadataRetrieveService约束**: 必须调用IMetadataRetrieveService的retrieve()方法 - **IMetadataDeployService约束**: 必须调用IMetadataDeployService的deploy()方法 - **package.xml约束**: 必须使用package.xml格式符合Salesforce Metadata API规范 - **types元素约束**: 必须使用types元素定义元数据类型 - **members元素约束**: 必须使用members元素定义组件名称 - **version元素约束**: 必须使用version元素定义API版本 - **日志记录约束**: 必须使用日志记录哈希计算、对比、检测、拉取、部署过程 - **事务管理约束**: 必须使用@Transactional注解管理事务 - **性能约束**: 哈希计算响应时间 < 100ms（1MB文件），批量哈希计算1000个文件无性能下降，内存使用 < 10MB（计算100个1MB文件），对比响应时间 < 50ms（对比1000个文件），批量对比1000个文件无性能下降，检测响应时间 < 200ms（检测1000个文件），批量检测1000个文件无性能下降，文件系统监听响应时间 < 10ms，拉取响应时间 < 5s（拉取100个文件），批量拉取1000个文件无性能下降，网络传输时间 < 3s，文件处理时间 < 2s，部署响应时间 < 5s（部署100个文件），批量部署1000个文件无性能下降 - **并发控制约束**: 必须支持并发对比、检测、拉取、部署，使用线程安全的数据结构 - **实时监听约束**: 必须支持实时监听文件系统变化，使用Java NIO的WatchService - **进度查询约束**: 必须支持拉取、部署进度查询，使用Future对象 - **取消功能约束**: 必须支持拉取、部署取消，使用Future.cancel() - **重试机制约束**: 必须支持拉取、部署重试，使用重试机制 - **失败处理约束**: 必须支持拉取、部署失败处理，使用异常处理 - **缓存机制约束**: 必须支持拉取、部署结果缓存，使用缓存机制 - **导出工具约束**: 必须支持拉取、部署结果导出，使用导出工具 - **历史记录约束**: 必须支持部署历史记录，使用DataiMetaJobExecution实体类 - **状态查询约束**: 必须支持部署状态查询，使用DataiMetaJobExecutionMapper - **结果解析约束**: 必须支持部署结果解析，使用部署结果解析工具 - **组件统计约束**: 必须支持部署组件统计，使用组件统计工具 - **测试结果约束**: 必须支持部署测试结果，使用测试结果解析工具 - **错误处理约束**: 必须支持部署错误处理，使用错误处理工具 - **回滚工具约束**: 必须支持部署回滚，使用回滚工具 - **备份工具约束**: 必须支持部署备份，使用备份工具 - **验证工具约束**: 必须支持部署验证，使用验证工具 - **预览工具约束**: 必须支持部署预览，使用预览工具 - **确认工具约束**: 必须支持部署确认，使用确认工具 - **过滤功能约束**: 必须支持按文件变化类型过滤（ADDED、MODIFIED、DELETED），按文件路径过滤，按元数据类型过滤，按组织配置ID过滤，按任务ID过滤 - **常量定义约束**: 必须使用BUFFER_SIZE常量定义缓冲区大小，使用HASH_ALGORITHM常量定义哈希算法 - **null值处理约束**: 必须处理null值，两个null值视为相等，一个null一个非null的情况视为不相等 - **单字节十六进制补零约束**: 必须处理单字节十六进制补零 - **64位十六进制字符串约束**: 必须返回64位十六进制字符串 - **文件路径解析约束**: 必须使用dir.resolve()解析完整文件路径 - **监听键重置约束**: 必须使用key.reset()重置监听键 - **监听键移除约束**: 必须使用watchKeys.remove()移除无效的监听键 - **事件等待约束**: 必须使用watchService.take()阻塞等待事件 - **循环监听约束**: 必须使用while(watching)循环监听 - **事件获取约束**: 必须使用WatchKey.pollEvents()获取文件系统事件 - **事件类型获取约束**: 必须使用event.kind()获取事件类型 - **文件路径获取约束**: 必须使用event.context()获取文件路径 - **变化类型判断约束**: 必须判断oldHash为null且newHash不为null时标记为ADDED，oldHash不为null且newHash为null时标记为DELETED，oldHash不为null且newHash不为null且不相等时标记为MODIFIED - **复用逻辑约束**: 必须复用现有的IFileStorageService、IMetadataRetrieveService、IMetadataDeployService服务接口 ## Rule Set "请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。" **具体规则**： - 必须使用Canvas中定义的类名和方法名 - 必须遵循Canvas中定义的调用关系 - 必须参考Canvas中的流程图逻辑 ## 验收标准 - **功能完整性**: 所有文件哈希对比和增量检测功能能够正常工作 - **性能指标**: 哈希计算和对比性能满足要求，增量拉取和部署性能满足要求 - **准确性**: 增量检测结果准确，只拉取或部署变化的文件 - **代码规范性**: 代码符合项目编码规范，有清晰的注释 - **可维护性**: 代码结构清晰，易于扩展和维护 - **可测试性**: 代码易于单元测试和集成测试 ## 风险 - **哈希计算风险**: 哈希计算错误可能导致增量检测不准确 - **缓解措施**: 使用单元测试和集成测试验证哈希计算的准确性，使用SHA-256算法确保哈希值唯一性，使用try-catch处理异常，使用日志记录哈希计算过程，使用缓存避免重复计算 - **监控指标**: 哈希计算错误率 < 0.1%，哈希计算响应时间 < 100ms（1MB文件），内存使用 < 10MB（计算100个1MB文件） - **对比性能风险**: 对比性能不佳可能影响用户体验 - **缓解措施**: 使用并行处理提高对比性能，使用ConcurrentHashMap缓存哈希值避免重复计算，使用parallelStream()并行处理多个文件，使用线程安全的数据结构，使用性能测试工具监控对比性能 - **监控指标**: 对比响应时间 < 50ms（对比1000个文件），批量对比1000个文件无性能下降，并发对比成功率 > 99% - **增量检测风险**: 增量检测不准确可能导致遗漏或误判 - **缓解措施**: 使用哈希对比和文件系统监听器两种方式全面检测文件变化，使用ChangeType枚举定义文件变化类型，使用FileChange实体类记录文件变化信息，使用日志记录检测过程，使用异常处理机制处理检测失败 - **监控指标**: 检测响应时间 < 200ms（检测1000个文件），批量检测1000个文件无性能下降，文件系统监听响应时间 < 10ms，检测准确率 > 99.9% - **增量拉取风险**: 增量拉取失败可能导致文件不一致 - **缓解措施**: 提供回滚机制支持重新拉取所有文件，使用异步执行避免阻塞主线程，使用Future对象跟踪异步任务状态，使用重试机制处理拉取失败，使用日志记录拉取过程，使用事务确保数据一致性 - **监控指标**: 拉取响应时间 < 5s（拉取100个文件），批量拉取1000个文件无性能下降，网络传输时间 < 3s，文件处理时间 < 2s，拉取成功率 > 99%，拉取失败重试成功率 > 95% - **增量部署风险**: 增量部署失败可能导致部署不完整 - **缓解措施**: 提供回滚机制支持重新部署所有文件，使用异步执行避免阻塞主线程，使用Future对象跟踪异步任务状态，使用重试机制处理部署失败，使用日志记录部署过程，使用事务确保数据一致性，使用部署验证工具验证部署结果，使用部署备份工具备份部署前状态 - **监控指标**: 部署响应时间 < 5s（部署100个文件），批量部署1000个文件无性能下降，网络传输时间 < 3s，文件处理时间 < 2s，部署成功率 > 99%，部署失败重试成功率 > 95%，部署验证成功率 > 99% - **异步执行风险**: 异步执行可能导致任务状态不一致 - **缓解措施**: 使用Future对象跟踪异步任务状态，使用ConcurrentHashMap缓存异步任务Future对象，使用Future.cancel()取消异步任务，使用日志记录异步任务执行过程，使用异常处理机制处理异步任务失败 - **监控指标**: 异步任务成功率 > 99%，异步任务取消成功率 > 99%，异步任务响应时间 < 5s，异步任务状态一致性 > 99.9% - **线程池风险**: 线程池配置不当可能导致性能问题 - **缓解措施**: 复用现有的AsyncConfig配置类和线程池，使用ThreadPoolTaskExecutor管理线程池，使用合理的线程池大小配置，使用线程池监控工具监控线程池状态，使用日志记录线程池使用情况 - **监控指标**: 线程池使用率 < 80%，线程池拒绝率 < 1%，线程池任务队列长度 < 100，线程池活跃线程数 < 核心线程数 * 2 - **文件系统监听风险**: 文件系统监听可能丢失事件 - **缓解措施**: 使用Java NIO的WatchService监听文件系统事件，使用StandardWatchEventKinds监听文件创建、修改、删除事件，使用StandardWatchEventKinds.OVERFLOW处理事件溢出，使用日志记录监听事件，使用异常处理机制处理监听失败 - **监控指标**: 文件系统监听响应时间 < 10ms，文件系统监听成功率 > 99.9%，文件系统监听事件丢失率 < 0.1% - **并发控制风险**: 并发操作可能导致数据不一致 - **缓解措施**: 使用线程安全的数据结构（ConcurrentHashMap、HashSet），使用synchronized关键字同步关键代码块，使用Lock接口实现更灵活的锁机制，使用事务确保数据一致性，使用乐观锁和悲观锁机制 - **监控指标**: 并发操作成功率 > 99%，并发操作冲突率 < 1%，数据一致性 > 99.9% - **内存使用风险**: 大量文件哈希计算可能导致内存溢出 - **缓解措施**: 使用流式处理大文件，使用BufferedInputStream避免一次性加载大文件到内存，使用8KB缓冲区平衡内存使用和读取性能，使用缓存机制避免重复计算，使用内存监控工具监控内存使用情况 - **监控指标**: 内存使用 < 10MB（计算100个1MB文件），内存使用增长率 < 1MB/s，内存溢出率 < 0.01% - **网络传输风险**: 网络传输失败可能导致拉取或部署失败 - **缓解措施**: 使用重试机制处理网络传输失败，使用超时机制避免长时间等待，使用日志记录网络传输过程，使用网络监控工具监控网络传输状态，使用断点续传机制支持大文件传输 - **监控指标**: 网络传输成功率 > 99%，网络传输响应时间 < 3s，网络传输失败重试成功率 > 95%，网络传输超时率 < 1% - **异常处理风险**: 异常处理不当可能导致系统崩溃 - **缓解措施**: 使用try-catch处理异常，使用RuntimeException包装异常，使用日志记录异常信息，使用异常监控工具监控异常情况，使用异常恢复机制处理异常恢复 - **监控指标**: 异常处理成功率 > 99%，异常恢复成功率 > 95%，异常日志记录率 > 99%，异常监控覆盖率 > 99% - **日志记录风险**: 日志记录不完整可能导致问题排查困难 - **缓解措施**: 使用日志记录哈希计算、对比、检测、拉取、部署过程，使用日志级别区分日志重要程度，使用日志格式规范日志内容，使用日志监控工具监控日志情况，使用日志归档机制管理日志文件 - **监控指标**: 日志记录率 > 99%，日志格式规范性 > 99%，日志归档成功率 > 99%，日志查询响应时间 < 1s - **事务管理风险**: 事务管理不当可能导致数据不一致 - **缓解措施**: 使用@Transactional注解管理事务，使用事务传播机制控制事务传播行为，使用事务隔离级别控制事务隔离程度，使用事务回滚机制处理事务失败，使用事务监控工具监控事务状态 - **监控指标**: 事务成功率 > 99%，事务回滚率 < 1%，事务隔离级别正确率 > 99%，事务传播行为正确率 > 99% - **缓存机制风险**: 缓存机制不当可能导致数据不一致 - **缓解措施**: 使用缓存机制避免重复计算，使用缓存失效机制更新缓存，使用缓存预热机制预热缓存，使用缓存监控工具监控缓存状态，使用缓存清理机制清理过期缓存 - **监控指标**: 缓存命中率 > 90%，缓存失效率 < 10%，缓存预热成功率 > 99%，缓存清理成功率 > 99% - **性能监控风险**: 性能监控不到位可能导致性能问题未及时发现 - **缓解措施**: 使用性能测试工具监控性能，使用性能指标定义性能标准，使用性能报警机制报警性能问题，使用性能优化工具优化性能，使用性能分析工具分析性能瓶颈 - **监控指标**: 性能监控覆盖率 > 99%，性能报警准确率 > 95%，性能优化成功率 > 90%，性能分析准确率 > 95% - **兼容性风险**: 新增功能可能与现有功能不兼容 - **缓解措施**: 充分测试确保兼容性，使用集成测试验证兼容性，使用回归测试验证兼容性，使用兼容性测试工具测试兼容性，使用兼容性监控工具监控兼容性情况 - **监控指标**: 兼容性测试覆盖率 > 99%，兼容性测试通过率 > 99%，兼容性问题发现率 > 95%，兼容性问题修复率 > 95% - **可维护性风险**: 代码结构不清晰可能导致维护困难 - **缓解措施**: 使用清晰的代码结构，使用规范的命名规范，使用详细的注释说明，使用代码审查机制审查代码，使用代码重构工具重构代码 - **监控指标**: 代码规范性 > 95%，注释覆盖率 > 80%，代码审查通过率 > 95%，代码重构成功率 > 90% - **可测试性风险**: 代码不易测试可能导致测试覆盖率不足 - **缓解措施**: 使用单元测试验证功能，使用集成测试验证功能，使用测试覆盖率工具监控测试覆盖率，使用测试自动化工具自动化测试，使用测试报告工具生成测试报告 - **监控指标**: 单元测试覆盖率 > 80%，集成测试覆盖率 > 70%，测试自动化率 > 90%，测试报告生成率 > 99% ## 需求变更记录 | 日期 | 变更内容 | 变更原因 | 变更人 | 审核人 | 状态 | |------|---------|---------|--------|--------|------| | 2026-01-17 | 创建需求文档 | 初始需求 | 系统管理员 | - | 待审核 | | 2026-01-26 | 优化需求文档 | 基于当前项目实际情况优化需求文档，包括：1. 文件哈希计算：添加了IFileHashService服务接口和FileHashServiceImpl实现类约束，添加了MessageDigest、BufferedInputStream、CompletableFuture等技术细节，添加了calculateHash、calculateHashes、calculateHashAsync方法约束，添加了性能指标和内存使用约束；2. 哈希对比：添加了IHashComparisonService服务接口和HashComparisonServiceImpl实现类约束，添加了String.equals()、parallelStream()、ConcurrentHashMap等技术细节，添加了compare、compare、findChangedFiles方法约束，添加了性能指标和并发控制约束；3. 增量检测：添加了IIncrementalDetectionService服务接口和IncrementalDetectionServiceImpl实现类约束，添加了ChangeType枚举、FileChange实体类、WatchService等技术细节，添加了detectChanges、detectChangesAsync、watchFileSystem、stopWatching方法约束，添加了文件系统监听和实时检测约束；4. 增量拉取：添加了IIncrementalRetrieveService服务接口和IncrementalRetrieveServiceImpl实现类约束，添加了package.xml构建、异步执行、Future对象等技术细节，添加了过滤功能、进度查询、取消功能、重试机制等约束；5. 增量部署：添加了IIncrementalDeployService服务接口和IncrementalDeployServiceImpl实现类约束，添加了部署历史记录、状态查询、结果解析、组件统计、测试结果、错误处理、回滚、备份、验证、预览、确认等约束；6. 约束条件：大幅增强了约束条件，添加了78个具体的约束项，包括服务接口约束、服务实现约束、实体类约束、枚举类约束、Mapper约束、异步注解约束、线程池约束、Future对象约束、CompletableFuture约束、MessageDigest约束、BufferedInputStream约束、WatchService约束、StandardWatchEventKinds约束、String.equals()约束、parallelStream()约束、ConcurrentHashMap约束、HashSet约束、ArrayList约束、StringBuilder约束、Integer.toHexString()约束、try-with-resources约束、RuntimeException约束、LocalDateTime.now()约束、CompletableFuture.supplyAsync()约束、Future.cancel()约束、volatile boolean约束、Map约束、Thread约束、interrupt()约束、watchService.close()约束、try-catch约束、InterruptedException约束、StandardWatchEventKinds.OVERFLOW约束、FileChangeCallback约束、onFileChange()约束、IMetadataRetrieveService约束、IMetadataDeployService约束、package.xml约束、types元素约束、members元素约束、version元素约束、日志记录约束、事务管理约束、性能约束、并发控制约束、实时监听约束、进度查询约束、取消功能约束、重试机制约束、失败处理约束、缓存机制约束、导出工具约束、历史记录约束、状态查询约束、结果解析约束、组件统计约束、测试结果约束、错误处理约束、回滚工具约束、备份工具约束、验证工具约束、预览工具约束、确认工具约束、过滤功能约束、常量定义约束、null值处理约束、单字节十六进制补零约束、64位十六进制字符串约束、文件路径解析约束、监听键重置约束、监听键移除约束、事件等待约束、循环监听约束、事件获取约束、事件类型获取约束、文件路径获取约束、变化类型判断约束、复用逻辑约束；7. 风险评估：大幅增强了风险评估，为每个风险添加了详细的缓解措施和监控指标，包括哈希计算风险、对比性能风险、增量检测风险、增量拉取风险、增量部署风险、异步执行风险、线程池风险、文件系统监听风险、并发控制风险、内存使用风险、网络传输风险、异常处理风险、日志记录风险、事务管理风险、缓存机制风险、性能监控风险、兼容性风险、可维护性风险、可测试性风险等18个风险项 | 系统管理员 | - | 待审核 | ## 相关人员 - **需求提出人**: 系统管理员 - 联系方式 - **需求负责人**: 系统管理员 - 联系方式 - **技术负责人**: 开发工程师 - 联系方式 - **测试负责人**: 测试工程师 - 联系方式 - **其他相关人员**: - 联系方式 ## 评审信息 - **评审日期**: - - **评审人员**: - - **评审结果**: - - **评审意见**: - - **修改建议**: -