kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
8b1e7d78a3
datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0020-metadata-component-index.md
Kris 2e6f087732 docs: 完成REQ-010-17和REQ-010-2的文档创建 
- 完成REQ-010-17（性能优化和限流处理）的所有6个阶段
  - 创建ADR文档：0026-performance-optimization.md
  - 创建Prompt文档：027-performance-optimization.md
  - 创建会话记录：20260119-performance-optimization.md
  - 创建变更记录：20260119-performance-optimization.md
  - 创建复盘报告：20260119-performance-optimization-retro.md
  - 更新index.md和CHANGELOG.md

- 完成REQ-010-2（基础实体类和Mapper创建）的前3个阶段
  - 更新ADR文档：0011-entity-mapper-create.md
  - 创建Prompt文档：002-entity-mapper-create.md
  - 更新index.md

所有文档均按照SSOT方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
2026-01-19 10:06:09 +08:00

10 KiB
Raw Blame History

架构决策记录 - 元数据组件索引和查询

背景

REQ-010-11 要求实现元数据组件索引和查询功能，支持按类型、名称、版本等条件查询元数据组件。元数据组件索引和查询是 Salesforce 元数据管理的重要功能，可以帮助用户快速查找和管理元数据组件。

当前系统已经实现了文件存储和解压处理（REQ-010-7），包括 Zip 文件存储、文件解压、文件路径管理。元数据组件索引和查询功能需要基于现有的文件存储和解压处理，提供元数据组件的索引和查询能力。

决策

1. 组件索引创建方案

决策: 使用文件解析库解析元数据文件，使用 MyBatis Plus 批量插入索引数据，支持多种元数据类型解析。

理由:

  • 文件解析库可以方便地解析各种格式的元数据文件（XML、JSON、Apex、Visualforce 等）
  • MyBatis Plus 批量插入可以提高索引创建的性能
  • 支持多种元数据类型解析，满足不同的索引需求
  • 索引信息完整准确，便于后续查询
  • 与现有的文件存储和解压处理保持一致的设计模式

实现方案:

  • 创建 IMetadataComponentIndexService 服务接口
  • 创建 MetadataComponentIndexServiceImpl 服务实现
  • 使用 Java 文件解析库（如 Jackson、DOM4J）解析元数据文件
  • 使用 MyBatis Plus 的 saveBatch() 方法批量插入索引数据
  • 支持异步索引创建，提高索引创建性能
  • 提供索引创建进度回调，实时反馈索引创建进度

2. 组件查询方案

决策: 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询，使用分页插件实现分页，支持按类型、名称、版本等条件查询。

理由:

  • MyBatis Plus 是项目现有的持久层框架，符合技术栈要求
  • QueryWrapper 提供了丰富的查询方法，易于使用
  • 支持多条件组合查询，灵活满足不同的查询需求
  • 支持分页查询，避免一次性加载大量数据
  • 与现有的查询机制保持一致的设计模式
  • 易于扩展和维护

实现方案:

  • 创建 IMetadataComponentQueryService 服务接口
  • 创建 MetadataComponentQueryServiceImpl 服务实现
  • 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询
  • 使用 MyBatis Plus 的分页插件实现分页查询
  • 支持按类型查询
  • 支持按名称查询
  • 支持按版本查询
  • 支持多条件组合查询
  • 支持模糊查询

3. 组件详情查看方案

决策: 使用文件读取 API 读取组件文件内容，使用关系查询获取组件依赖关系，支持查看组件文件内容和依赖关系。

理由:

  • 文件读取 API 可以方便地读取组件文件内容
  • 关系查询可以获取组件依赖关系，提供完整的组件信息
  • 支持查看组件文件内容，便于用户了解组件的详细信息
  • 支持查看组件依赖关系，便于用户了解组件的依赖情况
  • 与现有的文件存储和查询机制保持一致的设计模式
  • 易于扩展和维护

实现方案:

  • 创建 IMetadataComponentDetailService 服务接口
  • 创建 MetadataComponentDetailServiceImpl 服务实现
  • 使用文件读取 API 读取组件文件内容
  • 使用关系查询获取组件依赖关系
  • 提供组件详情查询接口
  • 提供组件文件内容查询接口
  • 提供组件依赖关系查询接口

4. 组件统计方案

决策: 使用 MyBatis Plus 的聚合查询实现统计功能，支持按类型、版本、组织等维度统计。

理由:

  • MyBatis Plus 是项目现有的持久层框架，符合技术栈要求
  • 聚合查询可以方便地实现统计功能
  • 支持按类型统计，了解组件类型分布
  • 支持按版本统计，了解组件版本分布
  • 支持按组织统计，了解不同组织的组件情况
  • 与现有的查询机制保持一致的设计模式
  • 易于扩展和维护

实现方案:

  • 创建 IMetadataComponentStatisticsService 服务接口
  • 创建 MetadataComponentStatisticsServiceImpl 服务实现
  • 使用 MyBatis Plus 的聚合查询实现统计功能
  • 提供组件总数统计接口
  • 提供组件类型分布统计接口
  • 提供组件版本分布统计接口
  • 提供组件组织分布统计接口

备选方案

方案 1: 使用搜索引擎实现组件查询

优点:

  • 查询性能更好
  • 支持全文搜索
  • 支持复杂的查询条件

缺点:

  • 增加系统复杂度
  • 需要额外的搜索引擎基础设施
  • 增加运维成本
  • 与现有的查询机制不一致

未选择原因: MyBatis Plus 的查询性能已经能够满足需求，使用搜索引擎会增加不必要的复杂度。

方案 2: 使用缓存提高查询性能

优点:

  • 查询性能更好
  • 减少数据库查询
  • 提高系统响应速度

缺点:

  • 增加系统复杂度
  • 需要额外的缓存基础设施
  • 增加运维成本
  • 缓存一致性难以保证

未选择原因: MyBatis Plus 的查询性能已经能够满足需求，使用缓存会增加不必要的复杂度。

方案 3: 使用 NoSQL 数据库存储组件索引

优点:

  • 存储性能更好
  • 支持灵活的数据结构
  • 易于扩展

缺点:

  • 不符合项目现有的技术栈
  • 需要额外的 NoSQL 数据库基础设施
  • 增加运维成本
  • 与现有的数据库架构不一致

未选择原因: MyBatis Plus 的查询性能已经能够满足需求，使用 NoSQL 数据库会增加不必要的复杂度。

影响

系统架构影响

  • 新增模块: MetadataComponentIndexController、IMetadataComponentIndexService、MetadataComponentIndexServiceImpl、IMetadataComponentQueryService、MetadataComponentQueryServiceImpl、IMetadataComponentDetailService、MetadataComponentDetailServiceImpl、IMetadataComponentStatisticsService、MetadataComponentStatisticsServiceImpl
  • 现有模块: 复用现有的文件存储和解压处理功能
  • 数据库: 新增 datai_metadata_component_index 表，存储组件索引信息
  • API: 新增 10 个 RESTful API 接口

开发流程影响

  • 开发工作量: 中等，复用现有的文件存储和解压处理代码
  • 测试工作量: 中等，需要测试索引创建、查询、详情查看、统计等功能
  • 文档工作量: 低，复用现有的文档模板

运维管理影响

  • 部署复杂度: 低，与现有部署流程一致
  • 监控复杂度: 低，复用现有的监控机制
  • 日志复杂度: 低，复用现有的日志机制

风险

技术风险

  • 索引创建风险: 索引创建失败可能导致组件查询失败
    • 缓解措施: 提供索引创建进度回调，实时反馈索引创建进度，支持索引创建重试
  • 查询性能风险: 查询性能不佳可能影响用户体验
    • 缓解措施: 使用 MyBatis Plus 的分页插件实现分页查询，使用索引优化查询性能
  • 文件解析风险: 文件解析错误可能导致索引信息不准确
    • 缓解措施: 使用成熟的文件解析库，提供文件解析错误处理，支持文件解析重试
  • 统计风险: 统计逻辑错误可能导致统计信息不准确
    • 缓解措施: 使用 MyBatis Plus 的聚合查询实现统计功能，确保统计逻辑的正确性

业务风险

  • 索引信息不准确风险: 索引信息不准确可能导致组件查询失败
    • 缓解措施: 提供索引创建进度回调，实时反馈索引创建进度，支持索引创建重试
  • 查询结果不准确风险: 查询结果不准确可能影响用户体验
    • 缓解措施: 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询，确保查询逻辑的正确性
  • 统计信息不准确风险: 统计信息不准确可能影响决策
    • 缓解措施: 使用 MyBatis Plus 的聚合查询实现统计功能，确保统计逻辑的正确性

实施风险

  • 依赖风险: 依赖于 REQ-010-1, REQ-010-2, REQ-010-7
    • 缓解措施: 确保依赖的需求已经完成，避免依赖问题

回滚策略

如果元数据组件索引和查询功能实施后出现问题，可以采取以下回滚策略：

  1. 禁用组件索引和查询功能: 通过配置开关禁用组件索引和查询功能，回退到文件查询
  2. 删除组件索引和查询相关代码: 删除 MetadataComponentIndexController、IMetadataComponentIndexService、MetadataComponentIndexServiceImpl、IMetadataComponentQueryService、MetadataComponentQueryServiceImpl、IMetadataComponentDetailService、MetadataComponentDetailServiceImpl、IMetadataComponentStatisticsService、MetadataComponentStatisticsServiceImpl 等代码
  3. 清理组件索引数据: 清理 datai_metadata_component_index 表中的组件索引数据
  4. 恢复 API: 删除组件索引和查询相关的 API 接口

验收标准

功能验收标准

  • 组件索引创建成功，支持多种元数据类型解析
  • 索引信息完整准确
  • 索引创建性能满足要求
  • 组件查询功能正常工作
  • 支持按类型查询
  • 支持按名称查询
  • 支持按版本查询
  • 支持多条件组合查询
  • 支持分页查询
  • API 接口符合 RESTful 规范
  • 组件详情查看成功
  • 组件信息完整准确
  • 支持查看组件文件内容
  • 支持查看组件依赖关系
  • 组件统计功能正常工作
  • 统计信息准确
  • 支持按类型统计
  • 支持按版本统计
  • 支持按组织统计

性能验收标准

  • 组件索引创建响应时间 < 5s
  • 组件查询响应时间 < 1s
  • 组件详情查看响应时间 < 500ms
  • 组件统计响应时间 < 1s

代码质量验收标准

  • 代码符合项目编码规范，有清晰的注释
  • 单元测试覆盖率 > 80%
  • 集成测试通过率 100%
  • 无严重的代码质量问题

视觉锚点

Visual Reference

引用 Canvas 的具体节点或快照：

Status

  • Draft
  • Accepted
  • Superceded

参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源：