133 lines
4.9 KiB
Markdown
133 lines
4.9 KiB
Markdown
|
# 需求文档
|
|||
|
|
|
|||
|
|
## 元数据
|
|||
|
|
- 需求编号：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. **代码质量**: 代码符合项目规范，无编译错误和警告
|
|||
|
|
|
|||
|
|
## 相关文档
|
|||
|
|
- [子需求索引](./sub/index.md) - 子需求文档索引
|
|||
|
|
- [设计文档](../design/2026-01-28-003-MetadataAPI源org实现设计.md) - 待创建
|
|||
|
|
- [决策记录](../decisions/adr/2026-01-28-003-ADR-MetadataAPI源org实现技术选型.md) - 待创建
|
|||
|
|
- [参考文档](../reference-code/sforce/docs/metadata-module.md) - Metadata API 功能说明
|