datai/docs/archive/REQ-010-11.md

Requirements - 元数据组件索引和查询

需求信息

• 需求名称: 元数据组件索引和查询
• 需求类型: 功能需求
• 需求编号: REQ-010-11
• 父需求: REQ-010
• 创建日期: 2026-01-17
• 需求版本: v1.0.0
• 需求提出人: 系统管理员
• 需求状态: 待审核

输入引用

引用相关的 docs 文档链接：

• REQ-010.md - Salesforce元数据拉取和部署主需求文档
• REQ-010-1.md - 数据库表结构设计和创建
• REQ-010-2.md - 基础实体类和Mapper创建
• REQ-010-7.md - 文件存储和解压处理
• 010-metadata-retrieve-deploy-sub-requirements.md - REQ-010子需求拆分文档
• file/index.md - 文件模块 API 文档索引（唯一真源）

Context Maps

强制列出本次需求依赖的 Canvas 文件：

• Authentication.canvas - 项目架构视觉化展示
• 相关节点: 集成核心 - 提供与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<String, Long>存储统计结果
  • 使用List<Map<String, Object>>存储多维度统计结果
  • 使用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<String, Long>存储统计结果
• 多维度统计约束: 必须使用List<Map<String, Object>>存储多维度统计结果
• 批量插入约束: 必须使用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<String, Long>存储统计结果；68. 明确了使用List<Map<String, Object>>存储多维度统计结果；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. 增加了详细的风险评估和缓解措施	根据架构决策文档和提示词文档优化需求文档，确保需求与实际实现一致	系统管理员	-

相关人员

• 需求提出人: 系统管理员 - 联系方式
• 需求负责人: 系统管理员 - 联系方式
• 技术负责人: 开发工程师 - 联系方式
• 测试负责人: 测试工程师 - 联系方式
• 其他相关人员: - 联系方式

评审信息

• 评审日期: -
• 评审人员: -
• 评审结果: -
• 评审意见: -
• 修改建议: -