219 lines
9.8 KiB
Markdown
219 lines
9.8 KiB
Markdown
# 变更日志 - 描述功能
|
||
|
||
## 元数据
|
||
- 需求编号：001-05
|
||
- 创建时间：2026-02-02
|
||
- 创建人：AI Assistant
|
||
- 版本号：v1.0.0
|
||
- 关联需求：[描述功能](../requirements/sub/2026-01-28-001-05-描述功能.md)
|
||
|
||
## 变更概述
|
||
实现 Salesforce Partner API 的描述功能，包括 DescribeGlobal、DescribeSObject、DescribeSObjects、DescribeLayout、DescribeTabs、DescribeQuickActions 六个核心功能。提供 RESTful API 接口，支持获取 Salesforce 对象的元数据信息，包括字段定义、布局信息、标签页信息、快速操作信息等。
|
||
|
||
## 变更内容
|
||
|
||
### 新增功能
|
||
- 实现 DescribeGlobal 功能：
|
||
- 获取所有可用的 Salesforce 对象列表
|
||
- 返回对象的基本信息（名称、标签、是否可创建、是否可更新等）
|
||
- 支持按对象类型过滤
|
||
|
||
- 实现 DescribeSObject 功能：
|
||
- 获取单个对象的详细元数据信息
|
||
- 返回字段定义（类型、长度、精度、必填性等）
|
||
- 返回子对象列表
|
||
- 返回记录类型信息
|
||
- 返回支持的 SOQL 功能
|
||
|
||
- 实现 DescribeSObjects 功能：
|
||
- 批量获取多个对象的元数据信息
|
||
- 支持最多 100 个对象同时描述
|
||
- 使用批量 API 提高效率
|
||
- 返回每个对象的详细元数据
|
||
|
||
- 实现 DescribeLayout 功能：
|
||
- 获取对象的页面布局信息
|
||
- 返回字段布局（编辑布局、详情布局等）
|
||
- 返回按钮布局
|
||
- 返回相关列表布局
|
||
- 支持按记录类型获取布局
|
||
|
||
- 实现 DescribeTabs 功能：
|
||
- 获取所有可用的标签页列表
|
||
- 返回标签页的基本信息（名称、标签、图标、URL等）
|
||
- 返回标签页关联的对象类型
|
||
- 返回标签页的显示顺序
|
||
|
||
- 实现 DescribeQuickActions 功能：
|
||
- 获取快速操作的定义信息
|
||
- 返回快速操作的字段列表
|
||
- 返回快速操作的布局信息
|
||
- 返回快速操作的可用性规则
|
||
- 支持按对象类型过滤
|
||
|
||
### 新增文档
|
||
- [需求文档](../requirements/sub/2026-01-28-001-05-描述功能.md) - 描述功能需求文档
|
||
- [设计文档](../design/2026-02-02-005-描述功能-设计.md) - 描述功能技术方案设计
|
||
- [决策记录](../decisions/2026-02-02-005-ADR-描述功能技术选型.md) - 描述功能技术选型决策记录
|
||
- [提示词](../prompts/2026-02-02-005-prompt-描述功能.md) - 描述功能代码生成提示词
|
||
- [变更日志](./2026-02-02-005-changelog.md) - 本文档
|
||
|
||
### 新增代码文件（15 个）
|
||
|
||
#### DTO 类（4 个）
|
||
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/DescribeSObjectDto.java` - 描述单个对象请求 DTO
|
||
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/DescribeSObjectsDto.java` - 描述多个对象请求 DTO
|
||
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/DescribeLayoutDto.java` - 描述对象布局请求 DTO
|
||
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/DescribeQuickActionsDto.java` - 描述快速操作请求 DTO
|
||
|
||
#### VO 类（5 个）
|
||
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/DescribeGlobalResultVo.java` - DescribeGlobal 结果 VO
|
||
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/DescribeSObjectResultVo.java` - DescribeSObject 结果 VO
|
||
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/DescribeLayoutResultVo.java` - DescribeLayout 结果 VO
|
||
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/DescribeTabResultVo.java` - DescribeTabs 结果 VO
|
||
- `datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/DescribeQuickActionResultVo.java` - DescribeQuickActions 结果 VO
|
||
|
||
#### Service 层（2 个）
|
||
- `datai-salesforce-partner/src/main/java/com/datai/partner/service/IPartnerDescribeService.java` - 描述服务接口（6 个方法）
|
||
- `datai-salesforce-partner/src/main/java/com/datai/partner/service/impl/PartnerDescribeServiceImpl.java` - 描述服务实现
|
||
|
||
#### Controller（1 个）
|
||
- `datai-salesforce-partner/src/main/java/com/datai/partner/controller/PartnerDescribeController.java` - 描述控制器（6 个 REST API 接口）
|
||
|
||
#### 工具类（1 个）
|
||
- `datai-salesforce-partner/src/main/java/com/datai/partner/util/DescribeResultConverter.java` - 描述结果转换工具类
|
||
|
||
#### 单元测试（1 个）
|
||
- `datai-salesforce-partner/src/test/java/com/datai/partner/service/impl/PartnerDescribeServiceImplTest.java` - 描述服务单元测试（18 个测试用例）
|
||
|
||
### REST API 接口（6 个）
|
||
- `GET /partner/describe/global` - 描述所有可用对象
|
||
- `POST /partner/describe/sobject` - 描述特定对象
|
||
- `POST /partner/describe/sobjects` - 描述多个对象
|
||
- `POST /partner/describe/layout` - 描述对象布局
|
||
- `GET /partner/describe/tabs` - 描述标签页
|
||
- `POST /partner/describe/quick-actions` - 描述快速操作
|
||
|
||
## 影响范围
|
||
|
||
### 模块级别
|
||
- **模块**：`datai-salesforce-partner`
|
||
- **功能**：Salesforce 元数据描述功能
|
||
- **文件**：15 个新文件（4 个 DTO + 5 个 VO + 2 个 Service + 1 个 Controller + 1 个工具类 + 1 个单元测试 + 1 个变更日志）
|
||
|
||
### 功能级别
|
||
- 新增 6 个 REST API 接口
|
||
- 新增 6 个 Service 方法
|
||
- 新增 18 个单元测试用例
|
||
- 支持字段信息处理（类型、长度、精度、必填性等）
|
||
- 支持 Picklist 字段处理（选项值、默认值、有效性规则）
|
||
- 支持关系字段处理（引用对象、关系名称、级联删除）
|
||
- 支持布局信息处理（字段布局、按钮布局、相关列表）
|
||
- 支持批量描述优化（DescribeSObjects 批量 API）
|
||
|
||
### 依赖关系
|
||
- 依赖 `datai-salesforce-auth` 模块的 `SessionManager` 获取会话信息
|
||
- 依赖 `datai-salesforce-common` 模块的异常处理体系
|
||
- 依赖 `partner.jar` 的 Salesforce Partner API 客户端
|
||
- 依赖 `PartnerConnectionFactory` 获取连接
|
||
|
||
## 技术实现
|
||
|
||
### 核心特性
|
||
1. **描述结果转换**：使用 `DescribeResultConverter` 将 Salesforce 描述结果转换为 `Map<String, Object>` 格式
|
||
2. **字段信息处理**：支持字段类型、长度、精度、必填性等属性
|
||
3. **Picklist 字段处理**：支持选项值、默认值、有效性规则
|
||
4. **关系字段处理**：支持引用对象、关系名称、级联删除
|
||
5. **布局信息处理**：支持字段布局、按钮布局、相关列表
|
||
6. **批量描述优化**：使用 `DescribeSObjects` 批量 API 提高效率
|
||
7. **完整的异常处理**：使用 `SalesforceOperationException` 统一处理异常
|
||
8. **日志记录**：使用 SLF4J 记录操作日志
|
||
9. **固定使用 source org 类型**：所有连接均使用 `getConnection("source")`
|
||
|
||
### 代码规范
|
||
- 遵循 Spring Boot 3.x 和 Spring Security 6.x 规范
|
||
- 遵循若依框架规范
|
||
- 使用 Lombok 简化代码
|
||
- 使用 Swagger 注解生成 API 文档
|
||
- 使用 Jakarta Validation 进行参数验证
|
||
- 单元测试覆盖率不低于 80%
|
||
|
||
## 测试覆盖
|
||
|
||
### 单元测试（18 个测试用例）
|
||
- `describeGlobalSuccess` - 测试 DescribeGlobal 成功场景
|
||
- `describeGlobalWithFilter` - 测试 DescribeGlobal 带过滤条件场景
|
||
- `describeGlobalConnectionException` - 测试 DescribeGlobal 连接异常场景
|
||
- `describeSObjectSuccess` - 测试 DescribeSObject 成功场景
|
||
- `describeSObjectWithFieldDetails` - 测试 DescribeSObject 带字段详情场景
|
||
- `describeSObjectNotFound` - 测试 DescribeSObject 对象不存在场景
|
||
- `describeSObjectsSuccess` - 测试 DescribeSObjects 成功场景
|
||
- `describeSObjectsWithMultipleObjects` - 测试 DescribeSObjects 多个对象场景
|
||
- `describeSObjectsPartialFailure` - 测试 DescribeSObjects 部分失败场景
|
||
- `describeLayoutSuccess` - 测试 DescribeLayout 成功场景
|
||
- `describeLayoutWithRecordType` - 测试 DescribeLayout 带记录类型场景
|
||
- `describeLayoutNotFound` - 测试 DescribeLayout 布局不存在场景
|
||
- `describeTabsSuccess` - 测试 DescribeTabs 成功场景
|
||
- `describeTabsWithFilter` - 测试 DescribeTabs 带过滤条件场景
|
||
- `describeQuickActionsSuccess` - 测试 DescribeQuickActions 成功场景
|
||
- `describeQuickActionsWithObjectType` - 测试 DescribeQuickActions 带对象类型场景
|
||
- `describeQuickActionsNotFound` - 测试 DescribeQuickActions 快速操作不存在场景
|
||
- `describeResultConverterTest` - 测试描述结果转换器
|
||
|
||
## 相关文档
|
||
|
||
- [需求文档](../requirements/sub/2026-01-28-001-05-描述功能.md)
|
||
- [设计文档](../design/2026-02-02-005-描述功能-设计.md)
|
||
- [决策记录](../decisions/2026-02-02-005-ADR-描述功能技术选型.md)
|
||
- [提示词](../prompts/2026-02-02-005-prompt-描述功能.md)
|
||
- [会话记录](../sessions/2026-01-28-001-session.md)
|
||
|
||
## 注意事项
|
||
|
||
1. **DescribeGlobal 限制**：
|
||
- 返回所有用户有权限访问的对象
|
||
- 不包含系统内部对象
|
||
- 结果按对象名称字母顺序排序
|
||
|
||
2. **DescribeSObject 限制**：
|
||
- 只返回用户有权限查看的字段
|
||
- 包含字段的详细元数据信息
|
||
- 支持递归获取子对象信息
|
||
|
||
3. **DescribeSObjects 限制**：
|
||
- 最多支持 100 个对象同时描述
|
||
- 批量 API 提高效率
|
||
- 部分失败时返回成功和失败的结果
|
||
|
||
4. **DescribeLayout 限制**：
|
||
- 需要指定对象类型
|
||
- 可选指定记录类型
|
||
- 返回所有布局类型（编辑、详情等）
|
||
|
||
5. **DescribeTabs 限制**：
|
||
- 返回所有用户可见的标签页
|
||
- 包含自定义标签页
|
||
- 按显示顺序排序
|
||
|
||
6. **DescribeQuickActions 限制**：
|
||
- 支持按对象类型过滤
|
||
- 返回快速操作的完整定义
|
||
- 包含字段和布局信息
|
||
|
||
## 后续优化建议
|
||
|
||
1. **性能优化**：
|
||
- 考虑添加 Describe 结果缓存机制
|
||
- 优化批量描述的分批策略
|
||
- 考虑异步处理大批量描述请求
|
||
|
||
2. **功能扩展**：
|
||
- 支持自定义字段的元数据获取
|
||
- 支持验证规则的元数据获取
|
||
- 支持工作流规则的元数据获取
|
||
|
||
3. **安全性增强**：
|
||
- 添加字段级别的权限检查
|
||
- 添加对象级别的权限检查
|
||
- 记录敏感操作的审计日志
|