datai/datai-scenes/datai-scene-salesforce/docs/changelog/2026-02-02-005-changelog.md

变更日志 - 描述功能

元数据

• 需求编号：001-05
• 创建时间：2026-02-02
• 创建人：AI Assistant
• 版本号：v1.0.0
• 关联需求：描述功能

变更概述

实现 Salesforce Partner API 的描述功能，包括 DescribeGlobal、DescribeSObject、DescribeSObjects、DescribeLayout、DescribeTabs、DescribeQuickActions 六个核心功能。提供 RESTful API 接口，支持获取 Salesforce 对象的元数据信息，包括字段定义、布局信息、标签页信息、快速操作信息等。

变更内容

新增功能

• 实现 DescribeGlobal 功能：

  • 获取所有可用的 Salesforce 对象列表
  • 返回对象的基本信息（名称、标签、是否可创建、是否可更新等）
  • 支持按对象类型过滤

• 实现 DescribeSObject 功能：

  • 获取单个对象的详细元数据信息
  • 返回字段定义（类型、长度、精度、必填性等）
  • 返回子对象列表
  • 返回记录类型信息
  • 返回支持的 SOQL 功能

• 实现 DescribeSObjects 功能：

  • 批量获取多个对象的元数据信息
  • 支持最多 100 个对象同时描述
  • 使用批量 API 提高效率
  • 返回每个对象的详细元数据

• 实现 DescribeLayout 功能：

  • 获取对象的页面布局信息
  • 返回字段布局（编辑布局、详情布局等）
  • 返回按钮布局
  • 返回相关列表布局
  • 支持按记录类型获取布局

• 实现 DescribeTabs 功能：

  • 获取所有可用的标签页列表
  • 返回标签页的基本信息（名称、标签、图标、URL等）
  • 返回标签页关联的对象类型
  • 返回标签页的显示顺序

• 实现 DescribeQuickActions 功能：

  • 获取快速操作的定义信息
  • 返回快速操作的字段列表
  • 返回快速操作的布局信息
  • 返回快速操作的可用性规则
  • 支持按对象类型过滤

新增文档

• 需求文档 - 描述功能需求文档
• 设计文档 - 描述功能技术方案设计
• 决策记录 - 描述功能技术选型决策记录
• 提示词 - 描述功能代码生成提示词
• 变更日志 - 本文档

新增代码文件（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 - 测试描述结果转换器

相关文档

• 需求文档
• 设计文档
• 决策记录
• 提示词
• 会话记录

注意事项

1. DescribeGlobal 限制：

   • 返回所有用户有权限访问的对象
   • 不包含系统内部对象
   • 结果按对象名称字母顺序排序

2. DescribeSObject 限制：

   • 只返回用户有权限查看的字段
   • 包含字段的详细元数据信息
   • 支持递归获取子对象信息

3. DescribeSObjects 限制：

   • 最多支持 100 个对象同时描述
   • 批量 API 提高效率
   • 部分失败时返回成功和失败的结果

4. DescribeLayout 限制：

   • 需要指定对象类型
   • 可选指定记录类型
   • 返回所有布局类型（编辑、详情等）

5. DescribeTabs 限制：

   • 返回所有用户可见的标签页
   • 包含自定义标签页
   • 按显示顺序排序

6. DescribeQuickActions 限制：

   • 支持按对象类型过滤
   • 返回快速操作的完整定义
   • 包含字段和布局信息

后续优化建议

1. 性能优化：

   • 考虑添加 Describe 结果缓存机制
   • 优化批量描述的分批策略
   • 考虑异步处理大批量描述请求

2. 功能扩展：

   • 支持自定义字段的元数据获取
   • 支持验证规则的元数据获取
   • 支持工作流规则的元数据获取

3. 安全性增强：

   • 添加字段级别的权限检查
   • 添加对象级别的权限检查
   • 记录敏感操作的审计日志