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

# 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<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<T>统一响应格式
- **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. 明确了详情查看响应时间 <

## 相关人员

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

## 评审信息

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