kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/requirements/2026-01-28-003-MetadataAPI源org实现.md

5.1 KiB
Raw Permalink Blame History

需求文档

元数据

  • 需求编号：003
  • 创建时间：2026-01-28
  • 创建人：AI Assistant
  • 状态：进行中
  • 优先级：高

需求概述

在 datai-salesforce-metadata 模块中实现 Salesforce Metadata API 的完整功能，提供对 Salesforce 源 org（Source Org）的元数据操作能力，包括元数据类型定义、部署操作、异步操作、删除操作、检索操作、检查部署状态、描述元数据、列出元数据等功能。

目标

  1. 实现 Metadata API 的所有核心功能，提供完整的元数据操作能力
  2. 集成 datai-salesforce-auth 模块的会话管理功能
  3. 提供 REST API 接口，支持外部系统调用
  4. 创建数据库表，存储部署结果、检索结果等数据
  5. 默认实现源 org（Source Org）类型的数据操作
  6. 删除现有 Mapper 文件，重新实现所有功能

功能需求

核心功能

1. 元数据类型定义

  • 核心组件类型：ApexClass、ApexTrigger、ApexPage、ApexComponent、CustomObject、CustomField、CustomTab
  • 配置类型：AppSettings、ApprovalProcess、AssignmentRules、Workflow、ValidationRule、SharingRule
  • 分析类型：AnalyticsDashboard、AnalyticsDataset、AnalyticsWorkspace、Report、Dashboard
  • AI 和自动化类型：AIApplication、Bot、Flow、ProcessBuilder
  • UI 和用户体验类型：CustomTab、CompactLayout、PageLayout、ListView、QuickAction

2. 部署操作

  • DeployOptions: 部署选项配置
  • DeployResult: 部署结果
  • DeployMessage: 部署消息
  • DeployDetails: 部署详细信息
  • DeployStatus: 部署状态

3. 异步操作

  • AsyncResult: 异步操作结果
  • AsyncRequestState: 异步请求状态

4. 删除操作

  • DeleteResult: 删除操作结果

5. 检索操作

  • RetrieveRequest: 检索请求配置
  • RetrieveResult: 检索结果
  • RetrieveMessage: 检索消息

6. 检查部署状态

  • CheckDeployStatus: 检查部署状态
  • CheckRetrieveStatus: 检查检索状态

7. 描述元数据

  • DescribeMetadataResult: 描述元数据结果
  • DescribeValueType: 描述值类型

8. 列出元数据

  • ListMetadataQuery: 列出元数据查询
  • ListMetadataResult: 列出元数据结果
  • ListMetadata: 列出元数据项

次要功能

  • 错误处理和异常管理
  • 结果封装和返回
  • 异步操作轮询机制

非功能需求

性能要求

  • 暂不考虑连接池、并发控制、缓存等性能优化
  • 每次调用都创建新连接
  • 异步操作需要轮询检查状态

安全要求

  • 集成 datai-salesforce-auth 模块的会话管理
  • 使用 SessionManager 获取 Session ID 和 Server URL
  • 优先使用 datai-salesforce-common 模块中的现有异常

兼容性要求

  • 支持 Salesforce Metadata API v65.0
  • 兼容 Java 22
  • 兼容 Spring Boot 框架

数据存储要求

  • 创建数据库表存储部署结果、检索结果等数据
  • 支持历史记录查询
  • 支持结果统计和分析
  • 删除现有 Mapper 文件，重新实现所有功能

技术约束

必须使用的框架或库

  • metadata.jar: Salesforce Metadata API 客户端（Metadata、CustomObject、CustomField、DeployOptions、DeployResult 等）
  • datai-salesforce-auth: 使用 SessionManager 管理会话
  • datai-salesforce-common: 使用现有异常类

必须遵循的设计模式

  • Service 层模式：提供业务逻辑封装
  • Controller 层模式：提供 REST API 接口
  • 直接使用 metadata.jar 中的现有类，不进行不必要的二次封装

必须继承的基类

  • 无特殊基类要求

自定义类原则

  • 优先使用 metadata.jar 中的现有类
  • 如果确实有需求需要使用自定义类，则新增
  • 新增前需要严格判断必要性

数据库设计原则

  • 需要创建表存储部署结果、检索结果等数据
  • 表结构在设计阶段确定
  • 支持历史记录查询和统计分析
  • 删除现有 Mapper 文件，重新实现所有功能

成功标准

  1. 功能完整性: 所有 Metadata API 核心功能都已实现并通过测试
  2. 认证集成: 成功集成 SessionManager，能够获取 Session ID 和 Server URL
  3. API 接口: 提供 REST API 接口，支持外部系统调用
  4. 数据存储: 成功创建数据库表，能够存储和查询部署结果、检索结果等数据
  5. 代码重构: 删除现有 Mapper 文件，重新实现所有功能
  6. 异常处理: 正确处理各种异常情况，使用合适的异常类
  7. 代码质量: 代码符合项目规范，无编译错误和警告

相关文档