# Requirements - 元数据组件索引和查询 ## 需求信息 - **需求名称**: 元数据组件索引和查询 - **需求类型**: 功能需求 - **需求编号**: REQ-010-11 - **父需求**: 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) - 文件存储和解压处理 - [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. 组件索引创建 - **需求描述**: 实现组件索引创建功能，解析解压后的元数据文件 - **优先级**: 中 - **验收标准**: - 组件索引创建成功 - 支持多种元数据类型解析 - 索引信息完整准确 - 索引创建性能满足要求 - 使用DataiMetaComponent实体类存储组件索引信息 - 使用DataiMetaComponentVersion实体类存储组件版本信息 - 使用IDataiMetaComponentService服务接口和DataiMetaComponentServiceImpl实现类 - 使用DataiMetaComponentMapper进行数据库操作 - 使用MyBatis Plus的BaseMapper实现批量插入 - 使用MyBatis Plus的saveBatch()方法批量插入索引数据 - 支持异步索引创建，提高索引创建性能 - 使用Spring的@Async注解标记异步方法 - 使用自定义线程池（ThreadPoolTaskExecutor）管理异步任务 - 使用Future对象跟踪异步任务状态 - 使用Java文件解析库（如Jackson、DOM4J）解析元数据文件 - 支持解析ApexClass、VisualforcePage、CustomObject、CustomField等多种元数据类型 - 使用MetadataComponentParser接口定义解析器规范 - 使用ApexClassParser、VisualforcePageParser、CustomObjectParser、CustomFieldParser等实现类解析不同类型的元数据文件 - 使用IFileStorageService获取解压后的文件路径 - 记录组件的元数据类型（metadataType） - 记录组件的全名（fullName） - 记录组件的文件路径名（fileName） - 记录最后一次拉取时间（lastRetrievedAt） - 记录最新版本ID（latestVersionId） - 记录组件版本号（versionNumber） - 记录组件内容哈希值（contentHash） - 记录组件代码内容（contentBody） - 记录是否为二进制文件（isBinary） - 记录提交信息（commitMessage） - 记录作业执行ID（jobExecutionId） - 支持索引创建进度回调，实时反馈索引创建进度 - 支持索引创建重试 - 支持索引创建失败处理 - 索引创建响应时间 < 5s - 批量插入1000条记录无性能下降 - **依赖关系**: 依赖于REQ-010-1, REQ-010-2, REQ-010-7 - **实现建议**: 使用DataiMetaComponent实体类存储组件索引信息，使用DataiMetaComponentVersion实体类存储组件版本信息，使用IDataiMetaComponentService服务接口和DataiMetaComponentServiceImpl实现类，使用MyBatis Plus的saveBatch()方法批量插入索引数据，使用Java文件解析库（如Jackson、DOM4J）解析元数据文件，使用异步索引创建提高性能 #### 2. 组件查询 - **需求描述**: 实现组件查询功能，支持按类型、名称、版本等条件查询 - **优先级**: 中 - **验收标准**: - 组件查询功能正常工作 - 支持按类型查询 - 支持按名称查询 - 支持按版本查询 - 支持多条件组合查询 - 支持分页查询 - API接口符合RESTful规范 - 使用DataiMetaComponentController控制器 - 使用IDataiMetaComponentService服务接口和DataiMetaComponentServiceImpl实现类 - 使用DataiMetaComponentMapper进行数据库操作 - 使用MyBatis Plus的QueryWrapper实现多条件查询 - 使用MyBatis Plus的分页插件实现分页查询 - 使用Page对象实现分页查询 - 使用QueryWrapper实现条件查询 - 提供GET /metadata/component/list接口 - 使用DataiMetaComponentDto接收查询请求 - 使用DataiMetaComponentVo返回查询响应 - 支持按组织配置ID（orgConfigId）查询 - 支持按元数据类型（metadataType）查询 - 支持按组件全名（fullName）模糊查询 - 支持按文件路径名（fileName）查询 - 支持按最后一次拉取时间（lastRetrievedAt）查询 - 支持按最新版本ID（latestVersionId）查询 - 支持按创建时间（createTime）查询 - 支持按更新时间（updateTime）查询 - 支持按创建人（createBy）查询 - 支持按更新人（updateBy）查询 - 按createTime降序排列 - 返回总记录数、当前页、每页大小、记录列表 - 使用startPage()方法启动分页 - 使用getDataTableByPage()方法返回分页数据 - 使用PageUtils.getTotal()方法获取总记录数 - 使用DataiMetaComponentVo.objToVo()方法转换实体到VO - 使用DataiMetaComponentDto.toObj()方法转换DTO到实体 - 支持模糊查询（like） - 支持精确查询（eq） - 支持范围查询（between） - 支持排序查询（orderBy） - 查询响应时间 < 1s - 分页查询100条记录无性能下降 - 支持导出Excel功能 - 提供POST /metadata/component/export接口 - 使用ExcelUtil导出Excel - **依赖关系**: 依赖于组件索引创建 - **实现建议**: 使用DataiMetaComponentController控制器，使用IDataiMetaComponentService服务接口和DataiMetaComponentServiceImpl实现类，使用MyBatis Plus的QueryWrapper实现多条件查询，使用MyBatis Plus的分页插件实现分页查询 #### 3. 组件详情查看 - **需求描述**: 实现组件详情查看功能，查看组件的完整信息 - **优先级**: 中 - **验收标准**: - 组件详情查看成功 - 组件信息完整准确 - 支持查看组件文件内容 - 支持查看组件依赖关系 - 使用DataiMetaComponentController控制器 - 使用IDataiMetaComponentService服务接口和DataiMetaComponentServiceImpl实现类 - 使用DataiMetaComponentMapper进行数据库操作 - 使用DataiMetaComponentVersion实体类查询组件版本信息 - 使用IDataiMetaComponentVersionService服务接口和DataiMetaComponentVersionServiceImpl实现类 - 使用DataiMetaComponentVersionMapper进行数据库操作 - 提供GET /metadata/component/{id}接口 - 使用DataiMetaComponentVo返回详情响应 - 支持按组件ID查询组件详情 - 支持查询组件的元数据类型（metadataType） - 支持查询组件的全名（fullName） - 支持查询组件的文件路径名（fileName） - 支持查询组件的最后一次拉取时间（lastRetrievedAt） - 支持查询组件的最新版本ID（latestVersionId） - 支持查询组件的创建时间（createTime） - 支持查询组件的更新时间（updateTime） - 支持查询组件的创建人（createBy） - 支持查询组件的更新人（updateBy） - 支持查询组件的备注（remark） - 支持查询组件版本信息 - 支持查询组件版本号（versionNumber） - 支持查询组件内容哈希值（contentHash） - 支持查询组件代码内容（contentBody） - 支持查询组件是否为二进制文件（isBinary） - 支持查询组件提交信息（commitMessage） - 支持查询组件作业执行ID（jobExecutionId） - 使用IFileStorageService读取组件文件内容 - 使用Files.readAllBytes()方法读取文件内容 - 使用Paths.get()方法获取文件路径 - 支持查看组件文件内容 - 支持查看组件依赖关系 - 使用关系查询获取组件依赖关系 - 支持查看组件历史版本 - 支持查看组件版本对比 - 详情查看响应时间 < 500ms - 文件内容读取响应时间 < 1s - 支持权限控制，使用@PreAuthorize注解 - 使用@PreAuthorize("@ss.hasPermi('metadata:component:query')")控制查询权限 - 使用success()方法返回成功响应 - 使用toAjax()方法返回操作结果 - **依赖关系**: 依赖于组件查询 - **实现建议**: 使用DataiMetaComponentController控制器，使用IDataiMetaComponentService服务接口和DataiMetaComponentServiceImpl实现类，使用IFileStorageService读取组件文件内容，使用关系查询获取组件依赖关系 #### 4. 组件统计 - **需求描述**: 实现组件统计功能，统计组件数量、类型分布等 - **优先级**: 中 - **验收标准**: - 组件统计功能正常工作 - 统计信息准确 - 支持按类型统计 - 支持按版本统计 - 支持按组织统计 - 使用DataiMetaComponentController控制器 - 使用IDataiMetaComponentService服务接口和DataiMetaComponentServiceImpl实现类 - 使用DataiMetaComponentMapper进行数据库操作 - 使用MyBatis Plus的聚合查询实现统计功能 - 使用QueryWrapper实现条件查询 - 使用selectCount()方法统计总数 - 使用selectList()方法查询列表 - 使用Java 8 Stream API进行分组统计 - 使用Collectors.groupingBy()方法分组 - 使用Collectors.counting()方法计数 - 提供组件总数统计接口 - 提供组件类型分布统计接口 - 提供组件版本分布统计接口 - 提供组件组织分布统计接口 - 支持按元数据类型（metadataType）统计 - 支持按组件全名（fullName）统计 - 支持按组织配置ID（orgConfigId）统计 - 支持按最后一次拉取时间（lastRetrievedAt）统计 - 支持按最新版本ID（latestVersionId）统计 - 支持按创建时间（createTime）统计 - 支持按更新时间（updateTime）统计 - 支持按创建人（createBy）统计 - 支持按更新人（updateBy）统计 - 统计响应时间 < 1s - 统计10000条记录无性能下降 - 支持多维度组合统计 - 支持统计结果导出 - 支持统计结果缓存 - 支持统计结果实时更新 - 支持统计结果可视化 - 使用Map存储统计结果 - 使用List>存储多维度统计结果 - 使用DTO封装统计响应 - 使用VO封装统计结果 - 支持权限控制，使用@PreAuthorize注解 - 使用@PreAuthorize("@ss.hasPermi('metadata:component:query')")控制查询权限 - 使用success()方法返回成功响应 - **依赖关系**: 依赖于组件索引创建 - **实现建议**: 使用DataiMetaComponentController控制器，使用IDataiMetaComponentService服务接口和DataiMetaComponentServiceImpl实现类，使用MyBatis Plus的聚合查询实现统计功能，使用Java 8 Stream API进行分组统计 ## 约束 - **技术栈限制**: 必须基于现有的Spring Boot 3 + Vue 3技术栈 - **架构约束**: 必须遵循Authentication.canvas中定义的架构和调用关系 - **模块约束**: 必须在datai-salesforce-metadata模块下实现 - **数据库约束**: 必须使用MyBatis Plus作为持久层框架 - **性能约束**: 索引创建和查询性能必须满足要求 - **依赖约束**: 必须依赖于REQ-010-1, REQ-010-2, REQ-010-7 - **控制器约束**: 必须使用DataiMetaComponentController控制器 - **服务接口约束**: 必须实现IDataiMetaComponentService和IDataiMetaComponentVersionService接口 - **服务实现约束**: 必须实现DataiMetaComponentServiceImpl和DataiMetaComponentVersionServiceImpl实现类 - **实体类约束**: 必须使用DataiMetaComponent实体类存储组件索引信息 - **版本实体类约束**: 必须使用DataiMetaComponentVersion实体类存储组件版本信息 - **Mapper约束**: 必须使用DataiMetaComponentMapper和DataiMetaComponentVersionMapper进行数据库操作 - **异步注解约束**: 必须使用Spring的@Async注解标记异步方法 - **线程池约束**: 必须使用自定义线程池（ThreadPoolTaskExecutor）管理异步任务 - **线程池配置约束**: 核心线程数5，最大线程数10，队列容量100，线程名称前缀index-async-，拒绝策略CallerRunsPolicy - **Future对象约束**: 必须使用Future对象跟踪异步任务状态 - **文件解析库约束**: 必须使用Java文件解析库（如Jackson、DOM4J）解析元数据文件 - **解析器接口约束**: 必须使用MetadataComponentParser接口定义解析器规范 - **解析器实现约束**: 必须实现ApexClassParser、VisualforcePageParser、CustomObjectParser、CustomFieldParser等解析器实现类 - **文件存储服务约束**: 必须使用IFileStorageService获取解压后的文件路径 - **事务管理约束**: 必须使用@Transactional注解管理事务 - **RESTful API约束**: 必须符合RESTful规范 - **接口路径约束**: 必须使用/metadata/component作为基础路径 - **查询接口约束**: 必须实现GET /metadata/component/list接口 - **详情接口约束**: 必须实现GET /metadata/component/{id}接口 - **新增接口约束**: 必须实现POST /metadata/component接口 - **修改接口约束**: 必须实现PUT /metadata/component接口 - **删除接口约束**: 必须实现DELETE /metadata/component/{ids}接口 - **导出接口约束**: 必须实现POST /metadata/component/export接口 - **响应格式约束**: 必须使用R统一响应格式 - **DTO约束**: 必须实现DataiMetaComponentDto和DataiMetaComponentVersionDto等DTO类 - **VO约束**: 必须实现DataiMetaComponentVo和DataiMetaComponentVersionVo等VO类 - **日志记录约束**: 必须遵循现有的日志记录规范 - **异常处理约束**: 必须遵循现有的异常处理机制 - **Lombok约束**: 必须使用Lombok的@Data、@Slf4j等注解简化代码 - **Swagger约束**: 必须使用Swagger注解（@Schema）标注API文档 - **Excel约束**: 必须使用@Excel注解标注导出字段 - **Jackson约束**: 必须使用Jackson的@JsonFormat注解格式化日期时间 - **分页查询约束**: 必须使用Page对象实现分页查询 - **条件查询约束**: 必须使用QueryWrapper实现条件查询 - **查询条件约束**: 必须支持按组织配置ID、元数据类型、组件全名、文件路径名、最后一次拉取时间、最新版本ID、创建时间、更新时间、创建人、更新人查询 - **模糊查询约束**: 必须支持模糊查询（like） - **精确查询约束**: 必须支持精确查询（eq） - **范围查询约束**: 必须支持范围查询（between） - **排序查询约束**: 必须支持排序查询（orderBy） - **分页方法约束**: 必须使用startPage()方法启动分页 - **分页数据方法约束**: 必须使用getDataTableByPage()方法返回分页数据 - **总记录数方法约束**: 必须使用PageUtils.getTotal()方法获取总记录数 - **实体转换方法约束**: 必须使用DataiMetaComponentVo.objToVo()方法转换实体到VO - **DTO转换方法约束**: 必须使用DataiMetaComponentDto.toObj()方法转换DTO到实体 - **文件读取方法约束**: 必须使用Files.readAllBytes()方法读取文件内容 - **文件路径方法约束**: 必须使用Paths.get()方法获取文件路径 - **聚合查询约束**: 必须使用selectCount()方法统计总数 - **列表查询约束**: 必须使用selectList()方法查询列表 - **分组统计约束**: 必须使用Java 8 Stream API进行分组统计 - **分组方法约束**: 必须使用Collectors.groupingBy()方法分组 - **计数方法约束**: 必须使用Collectors.counting()方法计数 - **统计结果存储约束**: 必须使用Map存储统计结果 - **多维度统计约束**: 必须使用List>存储多维度统计结果 - **批量插入约束**: 必须使用MyBatis Plus的saveBatch()方法批量插入索引数据 - **BaseMapper约束**: 必须使用MyBatis Plus的BaseMapper实现数据库操作 - **权限控制约束**: 必须使用@PreAuthorize注解控制权限 - **查询权限约束**: 必须使用@PreAuthorize("@ss.hasPermi('metadata:component:query')")控制查询权限 - **新增权限约束**: 必须使用@PreAuthorize("@ss.hasPermi('metadata:component:add')")控制新增权限 - **修改权限约束**: 必须使用@PreAuthorize("@ss.hasPermi('metadata:component:edit')")控制修改权限 - **删除权限约束**: 必须使用@PreAuthorize("@ss.hasPermi('metadata:component:remove')")控制删除权限 - **导出权限约束**: 必须使用@PreAuthorize("@ss.hasPermi('metadata:component:export')")控制导出权限 - **成功响应约束**: 必须使用success()方法返回成功响应 - **操作结果约束**: 必须使用toAjax()方法返回操作结果 - **性能约束**: 索引创建响应时间 < 5s，组件查询响应时间 < 1s，组件详情查看响应时间 < 500ms，组件统计响应时间 < 1s，批量插入1000条记录无性能下降，分页查询100条记录无性能下降，统计10000条记录无性能下降 - **安全性约束**: 组件索引和查询操作需要认证，组件数据传输加密，敏感信息不记录到日志，组件索引和查询历史记录权限控制 - **兼容性约束**: 必须使用现有的集成核心功能进行Salesforce API调用，必须使用现有的认证模块进行OAuth认证，必须遵循现有的异常处理机制，必须遵循现有的日志记录规范 - **复用约束**: 必须复用现有的文件存储和解压处理功能，必须复用现有的查询机制，必须复用现有的分页插件 - **元数据类型约束**: 必须支持解析ApexClass、VisualforcePage、CustomObject、CustomField等多种元数据类型 - **索引字段约束**: 必须记录组件的元数据类型（metadataType）、组件的全名（fullName）、组件的文件路径名（fileName）、最后一次拉取时间（lastRetrievedAt）、最新版本ID（latestVersionId） - **版本字段约束**: 必须记录组件版本号（versionNumber）、组件内容哈希值（contentHash）、组件代码内容（contentBody）、是否为二进制文件（isBinary）、提交信息（commitMessage）、作业执行ID（jobExecutionId） - **索引创建进度约束**: 必须支持索引创建进度回调，实时反馈索引创建进度 - **索引创建重试约束**: 必须支持索引创建重试 - **索引创建失败处理约束**: 必须支持索引创建失败处理 - **Excel导出约束**: 必须使用ExcelUtil导出Excel - **统计结果导出约束**: 必须支持统计结果导出 - **统计结果缓存约束**: 必须支持统计结果缓存 - **统计结果实时更新约束**: 必须支持统计结果实时更新 - **统计结果可视化约束**: 必须支持统计结果可视化 - **多维度组合统计约束**: 必须支持多维度组合统计 - **组件历史版本约束**: 必须支持查看组件历史版本 - **组件版本对比约束**: 必须支持查看组件版本对比 - **组件依赖关系约束**: 必须支持查看组件依赖关系 - **组件文件内容约束**: 必须支持查看组件文件内容 ## Rule Set "请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。" **具体规则**： - 必须使用Canvas中定义的类名和方法名 - 必须遵循Canvas中定义的调用关系 - 必须参考Canvas中的流程图逻辑 ## 验收标准 - **功能完整性**: 所有组件索引和查询功能能够正常工作 - **性能指标**: 索引创建和查询性能满足要求 - **代码规范性**: 代码符合项目编码规范，有清晰的注释 - **可维护性**: 代码结构清晰，易于扩展和维护 - **可测试性**: 代码易于单元测试和集成测试 ## 风险 - **索引创建风险**: 索引创建失败可能导致组件查询失败 - **缓解措施**: 提供索引创建进度回调，实时反馈索引创建进度，支持索引创建重试，使用异常处理和重试机制，使用超时设置，使用降级机制 - **监控指标**: 监控索引创建的成功率和失败原因，监控索引创建进度，监控索引创建时间 - **查询性能风险**: 查询性能不佳可能影响用户体验 - **缓解措施**: 使用MyBatis Plus的分页插件实现分页查询，使用索引优化查询性能，使用缓存提高查询性能，监控查询性能，优化慢查询 - **监控指标**: 监控查询的响应时间，监控数据库负载，监控慢查询数量 - **文件解析风险**: 文件解析错误可能导致索引信息不准确 - **缓解措施**: 使用成熟的文件解析库，提供文件解析错误处理，支持文件解析重试，验证文件格式，提供详细的错误信息 - **监控指标**: 监控文件解析的成功率和错误率，监控文件解析时间 - **统计风险**: 统计逻辑错误可能导致统计信息不准确 - **缓解措施**: 使用MyBatis Plus的聚合查询实现统计功能，确保统计逻辑的正确性，验证统计结果，提供统计结果对比 - **监控指标**: 监控统计的成功率和失败原因，监控统计结果的一致性 - **异步执行风险**: 异步执行失败可能导致索引创建失败 - **缓解措施**: 使用Future对象跟踪异步任务状态，提供状态同步机制，提供异常处理和重试机制，监控异步任务状态 - **监控指标**: 监控异步任务的成功率和失败原因，监控异步任务的执行时间 - **线程池风险**: 线程池参数配置不当可能导致资源耗尽或任务积压 - **缓解措施**: 根据实际负载调整线程池参数，监控线程池状态，使用拒绝策略，使用队列容量限制 - **监控指标**: 监控线程池的活跃线程数、队列大小、拒绝任务数 - **文件存储服务风险**: 文件存储服务失效可能导致索引创建失败 - **缓解措施**: 复用现有的文件存储服务，使用自动重试机制，提供文件存储服务状态检查，使用降级机制 - **监控指标**: 监控文件存储服务的成功率和错误率，监控文件存储服务的响应时间 - **元数据类型风险**: 元数据类型不支持可能导致索引创建失败 - **缓解措施**: 支持多种元数据类型，提供元数据类型列表，支持自动补全，提供元数据类型验证 - **监控指标**: 监控元数据类型的支持情况，监控不支持的元数据类型数量 - **组件版本风险**: 组件版本管理不当可能导致版本信息不准确 - **缓解措施**: 使用版本号管理，使用内容哈希值验证，使用提交信息记录，支持版本对比 - **监控指标**: 监控组件版本的一致性，监控组件版本的冲突率 - **二进制文件风险**: 二进制文件解析失败可能导致索引创建失败 - **缓解措施**: 识别二进制文件，使用isBinary字段标记，跳过二进制文件解析，提供二进制文件处理建议 - **监控指标**: 监控二进制文件的处理情况，监控二进制文件的解析失败率 - **批量插入风险**: 批量插入失败可能导致索引创建失败 - **缓解措施**: 使用MyBatis Plus的saveBatch()方法批量插入，使用事务确保批量插入的原子性，提供批量插入重试，监控批量插入性能 - **监控指标**: 监控批量插入的成功率和失败原因，监控批量插入的性能 - **分页查询风险**: 分页查询参数不当可能导致查询性能下降 - **缓解措施**: 限制分页大小，使用索引优化查询，监控查询性能，使用缓存提高查询性能 - **监控指标**: 监控分页查询的响应时间，监控数据库负载 - **条件查询风险**: 条件查询过于复杂可能导致查询性能下降 - **缓解措施**: 限制查询条件数量，使用索引优化查询，监控查询性能，使用缓存提高查询性能 - **监控指标**: 监控条件查询的响应时间，监控数据库负载 - **模糊查询风险**: 模糊查询性能不佳可能影响用户体验 - **缓解措施**: 使用索引优化模糊查询，限制模糊查询范围，使用缓存提高查询性能，监控模糊查询性能 - **监控指标**: 监控模糊查询的响应时间，监控数据库负载 - **统计结果缓存风险**: 统计结果缓存失效可能导致统计信息不准确 - **缓解措施**: 使用缓存失效策略，使用缓存更新机制，提供缓存一致性检查，监控缓存命中率 - **监控指标**: 监控缓存的命中率和一致性，监控缓存的失效频率 - **统计结果实时更新风险**: 统计结果实时更新失败可能导致统计信息不准确 - **缓解措施**: 使用实时更新机制，使用增量更新，提供统计结果对比，监控更新性能 - **监控指标**: 监控统计结果更新的成功率和失败原因，监控更新性能 - **统计结果可视化风险**: 统计结果可视化失败可能导致用户体验差 - **缓解措施**: 使用成熟的可视化库，提供多种可视化方式，支持导出可视化结果，监控可视化性能 - **监控指标**: 监控可视化的成功率和失败原因，监控可视化的性能 - **多维度组合统计风险**: 多维度组合统计过于复杂可能导致性能下降 - **缓解措施**: 限制统计维度数量，使用预计算，使用缓存提高统计性能，监控统计性能 - **监控指标**: 监控多维度组合统计的响应时间，监控数据库负载 - **组件历史版本风险**: 组件历史版本管理不当可能导致版本信息不准确 - **缓解措施**: 使用版本号管理，使用内容哈希值验证，使用提交信息记录，支持版本对比 - **监控指标**: 监控组件历史版本的一致性，监控组件历史版本的冲突率 - **组件版本对比风险**: 组件版本对比失败可能导致用户体验差 - **缓解措施**: 使用版本对比算法，提供差异高亮，支持版本回滚，监控对比性能 - **监控指标**: 监控组件版本对比的成功率和失败原因，监控对比性能 - **组件依赖关系风险**: 组件依赖关系解析失败可能导致依赖信息不准确 - **缓解措施**: 使用依赖关系解析算法，提供依赖关系可视化，支持依赖关系查询，监控解析性能 - **监控指标**: 监控组件依赖关系解析的成功率和失败原因，监控解析性能 - **组件文件内容风险**: 组件文件内容读取失败可能导致详情查看失败 - **缓解措施**: 使用文件读取API，提供文件内容缓存，支持文件内容预览，监控读取性能 - **监控指标**: 监控组件文件内容读取的成功率和失败原因，监控读取性能 - **Excel导出风险**: Excel导出失败可能导致数据丢失 - **缓解措施**: 使用ExcelUtil导出Excel，使用事务确保导出的原子性，提供导出重试，监控导出性能 - **监控指标**: 监控Excel导出的成功率和失败原因，监控导出性能 - **统计结果导出风险**: 统计结果导出失败可能导致数据丢失 - **缓解措施**: 使用导出工具，使用事务确保导出的原子性，提供导出重试，监控导出性能 - **监控指标**: 监控统计结果导出的成功率和失败原因，监控导出性能 - **权限控制风险**: 权限控制不当可能导致数据泄露 - **缓解措施**: 使用@PreAuthorize注解控制权限，使用角色权限管理，提供权限审计，监控权限使用情况 - **监控指标**: 监控权限控制的成功率和失败原因，监控权限的使用情况 - **索引信息不准确风险**: 索引信息不准确可能导致组件查询失败 - **缓解措施**: 提供索引创建进度回调，实时反馈索引创建进度，支持索引创建重试，验证索引信息，提供索引信息对比 - **监控指标**: 监控索引信息的准确性和一致性，监控索引信息的更新频率 - **查询结果不准确风险**: 查询结果不准确可能影响用户体验 - **缓解措施**: 使用MyBatis Plus的QueryWrapper实现多条件查询，确保查询逻辑的正确性，验证查询结果，提供查询结果对比 - **监控指标**: 监控查询结果的准确性和一致性，监控查询结果的更新频率 - **统计信息不准确风险**: 统计信息不准确可能影响决策 - **缓解措施**: 使用MyBatis Plus的聚合查询实现统计功能，确保统计逻辑的正确性，验证统计结果，提供统计结果对比 - **监控指标**: 监控统计信息的准确性和一致性，监控统计信息的更新频率 - **内存使用风险**: 内存使用不当可能导致内存溢出 - **缓解措施**: 限制内存使用，监控内存使用情况，使用内存优化技术，使用缓存策略 - **监控指标**: 监控内存使用情况和GC频率 - **CPU使用风险**: CPU使用过高可能导致系统性能下降 - **缓解措施**: 限制并发数，优化算法，监控CPU使用情况，使用异步处理 - **监控指标**: 监控CPU使用情况和系统负载 - **网络风险**: 网络不稳定可能导致文件读取失败 - **缓解措施**: 使用重试机制，使用超时设置，使用降级机制，监控网络状态 - **监控指标**: 监控网络延迟和丢包率 - **并发控制风险**: 并发控制不当可能导致数据不一致 - **缓解措施**: 使用锁机制，使用事务管理，监控并发操作，使用乐观锁 - **监控指标**: 监控并发操作的成功率和冲突率 - **日志记录风险**: 日志记录不当可能导致问题排查困难 - **缓解措施**: 使用结构化日志，记录关键信息，提供日志查询功能，监控日志质量 - **监控指标**: 监控日志的完整性和可读性 - **异常处理风险**: 异常处理不当可能导致系统崩溃 - **缓解措施**: 使用统一的异常处理机制，提供异常恢复机制，监控异常情况，使用异常重试 - **监控指标**: 监控异常的发生率和类型分布 - **性能风险**: 性能不佳可能导致用户体验差 - **缓解措施**: 使用缓存，使用异步处理，监控性能指标，优化慢查询 - **监控指标**: 监控响应时间、吞吐量、资源使用情况 - **可扩展性风险**: 可扩展性不佳可能导致系统难以扩展 - **缓解措施**: 使用模块化设计，使用接口抽象，监控扩展能力，支持插件化 - **监控指标**: 监控系统的扩展能力和扩展成本 - **可维护性风险**: 可维护性不佳可能导致代码难以维护 - **缓解措施**: 使用清晰的代码结构，使用注释，提供维护文档，监控代码质量 - **监控指标**: 监控代码的复杂度和可读性 - **可测试性风险**: 可测试性不佳可能导致测试困难 - **缓解措施**: 使用依赖注入，使用接口抽象，提供测试文档，监控测试覆盖率 - **监控指标**: 监控测试覆盖率和测试成功率 - **安全性风险**: 安全性不佳可能导致数据泄露 - **缓解措施**: 使用认证和授权，使用加密，监控安全事件，使用安全审计 - **监控指标**: 监控安全事件和漏洞扫描结果 - **兼容性风险**: 兼容性不佳可能导致系统无法运行 - **缓解措施**: 使用版本控制，使用兼容性测试，监控兼容性问题，使用降级机制 - **监控指标**: 监控兼容性问题和降级触发频率 - **可靠性风险**: 可靠性不佳可能导致系统不稳定 - **缓解措施**: 使用冗余设计，使用故障恢复，监控系统可用性，使用健康检查 - **监控指标**: 监控系统的可用性和故障恢复时间 - **可观测性风险**: 可观测性不佳可能导致问题排查困难 - **缓解措施**: 使用日志，使用监控，使用追踪，监控可观测性指标，提供监控仪表板 - **监控指标**: 监控日志的完整性，监控的覆盖率，追踪的成功率 - **复用逻辑风险**: 复用逻辑不当可能导致组件索引和查询功能异常 - **缓解措施**: 充分测试复用逻辑，确保复用逻辑的正确性，提供复用逻辑文档，监控复用逻辑的成功率 - **监控指标**: 监控复用逻辑的成功率和错误率 - **依赖风险**: 依赖于REQ-010-1, REQ-010-2, REQ-010-7可能导致依赖问题 - **缓解措施**: 确保依赖的需求已经完成，避免依赖问题，提供依赖检查机制，监控依赖的可用性 - **监控指标**: 监控依赖的可用性和兼容性 ## 需求变更记录 | 日期 | 变更内容 | 变更原因 | 变更人 | 审核人 | 状态 | |------|---------|---------|--------|--------|------| | 2026-01-17 | 创建需求文档 | 初始需求 | 系统管理员 | - | 待审核 | | 2026-01-26 | 优化需求文档 | 基于当前项目实际情况，优化需求文档，包括：1. 明确了使用DataiMetaComponent实体类存储组件索引信息；2. 明确了使用DataiMetaComponentVersion实体类存储组件版本信息；3. 明确了使用IDataiMetaComponentService服务接口和DataiMetaComponentServiceImpl实现类；4. 明确了使用IDataiMetaComponentVersionService服务接口和DataiMetaComponentVersionServiceImpl实现类；5. 明确了使用DataiMetaComponentController控制器；6. 明确了使用DataiMetaComponentMapper和DataiMetaComponentVersionMapper进行数据库操作；7. 明确了使用MyBatis Plus的BaseMapper实现批量插入；8. 明确了使用MyBatis Plus的saveBatch()方法批量插入索引数据；9. 明确了支持异步索引创建，提高索引创建性能；10. 明确了使用Spring的@Async注解标记异步方法；11. 明确了使用自定义线程池（ThreadPoolTaskExecutor）管理异步任务；12. 明确了使用Future对象跟踪异步任务状态；13. 明确了使用Java文件解析库（如Jackson、DOM4J）解析元数据文件；14. 明确了支持解析ApexClass、VisualforcePage、CustomObject、CustomField等多种元数据类型；15. 明确了使用MetadataComponentParser接口定义解析器规范；16. 明确了使用ApexClassParser、VisualforcePageParser、CustomObjectParser、CustomFieldParser等实现类解析不同类型的元数据文件；17. 明确了使用IFileStorageService获取解压后的文件路径；18. 明确了记录组件的元数据类型（metadataType）、组件的全名（fullName）、组件的文件路径名（fileName）、最后一次拉取时间（lastRetrievedAt）、最新版本ID（latestVersionId）；19. 明确了记录组件版本号（versionNumber）、组件内容哈希值（contentHash）、组件代码内容（contentBody）、是否为二进制文件（isBinary）、提交信息（commitMessage）、作业执行ID（jobExecutionId）；20. 明确了支持索引创建进度回调，实时反馈索引创建进度；21. 明确了支持索引创建重试；22. 明确了支持索引创建失败处理；23. 明确了索引创建响应时间 < 5s，批量插入1000条记录无性能下降；24. 明确了使用MyBatis Plus的QueryWrapper实现多条件查询；25. 明确了使用MyBatis Plus的分页插件实现分页查询；26. 明确了使用Page对象实现分页查询；27. 明确了使用QueryWrapper实现条件查询；28. 明确了提供GET /metadata/component/list接口；29. 明确了使用DataiMetaComponentDto接收查询请求；30. 明确了使用DataiMetaComponentVo返回查询响应；31. 明确了支持按组织配置ID、元数据类型、组件全名、文件路径名、最后一次拉取时间、最新版本ID、创建时间、更新时间、创建人、更新人查询；32. 明确了按createTime降序排列；33. 明确了返回总记录数、当前页、每页大小、记录列表；34. 明确了使用startPage()方法启动分页；35. 明确了使用getDataTableByPage()方法返回分页数据；36. 明确了使用PageUtils.getTotal()方法获取总记录数；37. 明确了使用DataiMetaComponentVo.objToVo()方法转换实体到VO；38. 明确了使用DataiMetaComponentDto.toObj()方法转换DTO到实体；39. 明确了支持模糊查询（like）、精确查询（eq）、范围查询（between）、排序查询（orderBy）；40. 明确了查询响应时间 < 1s，分页查询100条记录无性能下降；41. 明确了支持导出Excel功能；42. 明确了提供POST /metadata/component/export接口；43. 明确了使用ExcelUtil导出Excel；44. 明确了提供GET /metadata/component/{id}接口；45. 明确了支持按组件ID查询组件详情；46. 明确了支持查询组件版本信息；47. 明确了使用IFileStorageService读取组件文件内容；48. 明确了使用Files.readAllBytes()方法读取文件内容；49. 明确了使用Paths.get()方法获取文件路径；50. 明确了支持查看组件历史版本和组件版本对比；51. 明确了详情查看响应时间 < 500ms，文件内容读取响应时间 < 1s；52. 明确了支持权限控制，使用@PreAuthorize注解；53. 明确了使用@PreAuthorize("@ss.hasPermi('metadata:component:query')")控制查询权限；54. 明确了使用success()方法返回成功响应；55. 明确了使用toAjax()方法返回操作结果；56. 明确了使用MyBatis Plus的聚合查询实现统计功能；57. 明确了使用QueryWrapper实现条件查询；58. 明确了使用selectCount()方法统计总数；59. 明确了使用selectList()方法查询列表；60. 明确了使用Java 8 Stream API进行分组统计；61. 明确了使用Collectors.groupingBy()方法分组；62. 明确了使用Collectors.counting()方法计数；63. 明确了提供组件总数统计接口、组件类型分布统计接口、组件版本分布统计接口、组件组织分布统计接口；64. 明确了支持按元数据类型、组件全名、组织配置ID、最后一次拉取时间、最新版本ID、创建时间、更新时间、创建人、更新人统计；65. 明确了统计响应时间 < 1s，统计10000条记录无性能下降；66. 明确了支持多维度组合统计、统计结果导出、统计结果缓存、统计结果实时更新、统计结果可视化；67. 明确了使用Map存储统计结果；68. 明确了使用List>存储多维度统计结果；69. 明确了使用DTO封装统计响应；70. 明确了使用VO封装统计结果；71. 明确了提供GET /metadata/component/{id}接口、POST /metadata/component接口、PUT /metadata/component接口、DELETE /metadata/component/{ids}接口；72. 明确了使用@PreAuthorize("@ss.hasPermi('metadata:component:query')")控制查询权限；73. 明确了使用@PreAuthorize("@ss.hasPermi('metadata:component:add')")控制新增权限；74. 明确了使用@PreAuthorize("@ss.hasPermi('metadata:component:edit')")控制修改权限；75. 明确了使用@PreAuthorize("@ss.hasPermi('metadata:component:remove')")控制删除权限；76. 明确了使用@PreAuthorize("@ss.hasPermi('metadata:component:export')")控制导出权限；77. 增加了详细的约束条件；78. 增加了详细的风险评估和缓解措施 | 根据架构决策文档和提示词文档优化需求文档，确保需求与实际实现一致 | 系统管理员 | - | 待审核 | ## 相关人员 - **需求提出人**: 系统管理员 - 联系方式 - **需求负责人**: 系统管理员 - 联系方式 - **技术负责人**: 开发工程师 - 联系方式 - **测试负责人**: 测试工程师 - 联系方式 - **其他相关人员**: - 联系方式 ## 评审信息 - **评审日期**: - - **评审人员**: - - **评审结果**: - - **评审意见**: - - **修改建议**: -