# API 文档 - 描述功能

## 元数据
- 需求编号：001-05
- 创建时间：2026-02-02
- 创建人：AI Assistant
- 版本号：v1.0.0
- 关联需求：[描述功能](../requirements/sub/2026-01-28-001-05-描述功能.md)

## API 概述
描述功能 API 提供了对 Salesforce 对象元数据的查询能力，包括获取所有可用对象列表、获取对象详细定义、获取对象布局信息、获取标签页信息、获取快速操作信息等。这些 API 可以帮助开发人员了解 Salesforce 对象的结构和属性，为数据操作和界面开发提供支持。

## 接口列表

### 1. 描述所有可用对象

#### 接口说明
获取 Salesforce 组织中所有用户有权限访问的对象列表。

- **接口名称**：DescribeGlobal
- **请求方式**：GET
- **请求路径**：`/partner/describe/global`
- **权限要求**：`@PreAuthorize("@ss.hasLogin()")`

#### 请求参数
无

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.encoding | String | 编码格式 |
| data.maxBatchSize | Integer | 最大批处理大小 |
| data.sobjects | Array | 对象列表 |
| data.sobjects[].activateable | Boolean | 是否可激活 |
| data.sobjects[].createable | Boolean | 是否可创建 |
| data.sobjects[].custom | Boolean | 是否自定义对象 |
| data.sobjects[].customSetting | Boolean | 是否自定义设置 |
| data.sobjects[].deletable | Boolean | 是否可删除 |
| data.sobjects[].deprecatedAndHidden | Boolean | 是否已弃用并隐藏 |
| data.sobjects[].feedEnabled | Boolean | 是否启用 Feed |
| data.sobjects[].hasSubtypes | Boolean | 是否有子类型 |
| data.sobjects[].isSubtype | Boolean | 是否为子类型 |
| data.sobjects[].keyPrefix | String | 键前缀 |
| data.sobjects[].label | String | 对象标签 |
| data.sobjects[].labelPlural | String | 对象复数标签 |
| data.sobjects[].layoutable | Boolean | 是否有布局 |
| data.sobjects[].mergeable | Boolean | 是否可合并 |
| data.sobjects[].mruEnabled | Boolean | 是否启用 MRU |
| data.sobjects[].name | String | 对象名称 |
| data.sobjects[].queryable | Boolean | 是否可查询 |
| data.sobjects[].replicateable | Boolean | 是否可复制 |
| data.sobjects[].retrieveable | Boolean | 是否可检索 |
| data.sobjects[].searchable | Boolean | 是否可搜索 |
| data.sobjects[].triggerable | Boolean | 是否可触发 |
| data.sobjects[].undeletable | Boolean | 是否可恢复 |
| data.sobjects[].updateable | Boolean | 是否可更新 |
| data.sobjects[].urls | Object | 对象 URL 集合 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "encoding": "UTF-8",
    "maxBatchSize": 200,
    "sobjects": [
      {
        "activateable": false,
        "createable": true,
        "custom": false,
        "customSetting": false,
        "deletable": true,
        "deprecatedAndHidden": false,
        "feedEnabled": true,
        "hasSubtypes": false,
        "isSubtype": false,
        "keyPrefix": "001",
        "label": "客户",
        "labelPlural": "客户",
        "layoutable": true,
        "mergeable": true,
        "mruEnabled": true,
        "name": "Account",
        "queryable": true,
        "replicateable": true,
        "retrieveable": true,
        "searchable": true,
        "triggerable": true,
        "undeletable": true,
        "updateable": true,
        "urls": {
          "rowTemplate": "/services/data/v65.0/sobjects/Account/{ID}",
          "describe": "/services/data/v65.0/sobjects/Account/describe",
          "sobject": "/services/data/v65.0/sobjects/Account"
        }
      }
    ]
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "获取对象列表失败：连接超时"
}
```

---

### 2. 描述特定对象

#### 接口说明
获取指定 Salesforce 对象的详细元数据信息，包括字段定义、子对象、记录类型等。

- **接口名称**：DescribeSObject
- **请求方式**：POST
- **请求路径**：`/partner/describe/sobject`
- **权限要求**：`@PreAuthorize("@ss.hasLogin()")`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectType | String | 是 | 对象类型（如 Account、Contact 等） |

#### 请求示例
```json
{
  "objectType": "Account"
}
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.activateable | Boolean | 是否可激活 |
| data.childRelationships | Array | 子对象关系列表 |
| data.createable | Boolean | 是否可创建 |
| data.custom | Boolean | 是否自定义对象 |
| data.deletable | Boolean | 是否可删除 |
| data.deprecatedAndHidden | Boolean | 是否已弃用并隐藏 |
| data.feedEnabled | Boolean | 是否启用 Feed |
| data.fields | Array | 字段定义列表 |
| data.fields[].autoNumber | Boolean | 是否自动编号 |
| data.fields[].byteLength | Integer | 字节长度 |
| data.fields[].calculated | Boolean | 是否计算字段 |
| data.fields[].caseSensitive | Boolean | 是否区分大小写 |
| data.fields[].createable | Boolean | 是否可创建 |
| data.fields[].custom | Boolean | 是否自定义字段 |
| data.fields[].defaultedOnCreate | Boolean | 创建时是否有默认值 |
| data.fields[].deprecatedAndHidden | Boolean | 是否已弃用并隐藏 |
| data.fields[].digits | Integer | 数字位数 |
| data.fields[].externalId | Boolean | 是否为外部 ID |
| data.fields[].filterable | Boolean | 是否可过滤 |
| data.fields[].groupable | Boolean | 是否可分组 |
| data.fields[].idLookup | Boolean | 是否可用于 ID 查找 |
| data.fields[].label | String | 字段标签 |
| data.fields[].length | Integer | 字段长度 |
| data.fields[].name | String | 字段名称 |
| data.fields[].nameField | Boolean | 是否为名称字段 |
| data.fields[].nillable | Boolean | 是否可为空 |
| data.fields[].picklistValues | Array | 选项值列表（Picklist 字段） |
| data.fields[].precision | Integer | 精度 |
| data.fields[].referenceTo | Array | 引用对象列表（关系字段） |
| data.fields[].relationshipName | String | 关系名称 |
| data.fields[].required | Boolean | 是否必填 |
| data.fields[].scale | Integer | 小数位数 |
| data.fields[].soapType | String | SOAP 类型 |
| data.fields[].sortable | Boolean | 是否可排序 |
| data.fields[].type | String | 字段类型 |
| data.fields[].unique | Boolean | 是否唯一 |
| data.fields[].updateable | Boolean | 是否可更新 |
| data.keyPrefix | String | 键前缀 |
| data.label | String | 对象标签 |
| data.labelPlural | String | 对象复数标签 |
| data.layoutable | Boolean | 是否有布局 |
| data.mergeable | Boolean | 是否可合并 |
| data.mruEnabled | Boolean | 是否启用 MRU |
| data.name | String | 对象名称 |
| data.queryable | Boolean | 是否可查询 |
| data.recordTypeInfos | Array | 记录类型信息列表 |
| data.replicateable | Boolean | 是否可复制 |
| data.retrieveable | Boolean | 是否可检索 |
| data.searchable | Boolean | 是否可搜索 |
| data.triggerable | Boolean | 是否可触发 |
| data.undeletable | Boolean | 是否可恢复 |
| data.updateable | Boolean | 是否可更新 |
| data.urls | Object | 对象 URL 集合 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "activateable": false,
    "childRelationships": [...],
    "createable": true,
    "custom": false,
    "deletable": true,
    "deprecatedAndHidden": false,
    "feedEnabled": true,
    "fields": [
      {
        "autoNumber": false,
        "byteLength": 18,
        "calculated": false,
        "caseSensitive": false,
        "createable": false,
        "custom": false,
        "defaultedOnCreate": false,
        "deprecatedAndHidden": false,
        "digits": 0,
        "externalId": false,
        "filterable": true,
        "groupable": true,
        "idLookup": true,
        "label": "客户 ID",
        "length": 18,
        "name": "Id",
        "nameField": false,
        "nillable": false,
        "precision": 0,
        "required": true,
        "scale": 0,
        "soapType": "tns:ID",
        "sortable": true,
        "type": "id",
        "unique": false,
        "updateable": false
      }
    ],
    "keyPrefix": "001",
    "label": "客户",
    "labelPlural": "客户",
    "layoutable": true,
    "mergeable": true,
    "mruEnabled": true,
    "name": "Account",
    "queryable": true,
    "recordTypeInfos": [...],
    "replicateable": true,
    "retrieveable": true,
    "searchable": true,
    "triggerable": true,
    "undeletable": true,
    "updateable": true,
    "urls": {...}
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "描述对象失败：对象类型 'InvalidObject' 不存在"
}
```

---

### 3. 描述多个对象

#### 接口说明
批量获取多个 Salesforce 对象的元数据信息，最多支持 100 个对象。

- **接口名称**：DescribeSObjects
- **请求方式**：POST
- **请求路径**：`/partner/describe/sobjects`
- **权限要求**：`@PreAuthorize("@ss.hasLogin()")`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectTypes | Array | 是 | 对象类型列表，最多 100 个 |
| objectTypes[] | String | 是 | 对象类型（如 Account、Contact 等） |

#### 请求示例
```json
{
  "objectTypes": ["Account", "Contact", "Opportunity"]
}
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Array | 对象描述结果列表 |
| data[] | Object | 单个对象的描述结果（同 DescribeSObject 的 data） |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "name": "Account",
      "label": "客户",
      "fields": [...]
    },
    {
      "name": "Contact",
      "label": "联系人",
      "fields": [...]
    },
    {
      "name": "Opportunity",
      "label": "业务机会",
      "fields": [...]
    }
  ]
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "批量描述对象失败：对象类型列表不能为空"
}
```

---

### 4. 描述对象布局

#### 接口说明
获取指定 Salesforce 对象的页面布局信息，包括字段布局、按钮布局、相关列表等。

- **接口名称**：DescribeLayout
- **请求方式**：POST
- **请求路径**：`/partner/describe/layout`
- **权限要求**：`@PreAuthorize("@ss.hasLogin()")`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectType | String | 是 | 对象类型（如 Account、Contact 等） |
| recordTypeId | String | 否 | 记录类型 ID，不传则返回默认布局 |

#### 请求示例
```json
{
  "objectType": "Account",
  "recordTypeId": "012000000000000AAA"
}
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.id | String | 布局 ID |
| data.buttonLayoutSection | Object | 按钮布局部分 |
| data.detailLayoutSections | Array | 详情布局部分列表 |
| data.editLayoutSections | Array | 编辑布局部分列表 |
| data.quickActionList | Object | 快速操作列表 |
| data.relatedLists | Array | 相关列表 |
| data.relatedLists[].columns | Array | 列定义 |
| data.relatedLists[].custom | Boolean | 是否自定义 |
| data.relatedLists[].field | String | 字段名称 |
| data.relatedLists[].label | String | 标签 |
| data.relatedLists[].limitRows | Integer | 行数限制 |
| data.relatedLists[].name | String | 名称 |
| data.relatedLists[].sobject | String | 关联对象 |
| data.relatedLists[].sort | Array | 排序定义 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "00h000000000000",
    "buttonLayoutSection": {...},
    "detailLayoutSections": [...],
    "editLayoutSections": [...],
    "quickActionList": {...},
    "relatedLists": [
      {
        "columns": [...],
        "custom": false,
        "field": "AccountId",
        "label": "联系人",
        "limitRows": 5,
        "name": "Contacts",
        "sobject": "Contact",
        "sort": [...]
      }
    ]
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "描述布局失败：对象类型 'InvalidObject' 不存在"
}
```

---

### 5. 描述标签页

#### 接口说明
获取 Salesforce 组织中所有用户可见的标签页列表。

- **接口名称**：DescribeTabs
- **请求方式**：GET
- **请求路径**：`/partner/describe/tabs`
- **权限要求**：`@PreAuthorize("@ss.hasLogin()")`

#### 请求参数
无

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Array | 标签页列表 |
| data[].colors | Array | 颜色定义列表 |
| data[].custom | Boolean | 是否自定义 |
| data[].iconUrl | String | 图标 URL |
| data[].icons | Array | 图标定义列表 |
| data[].label | String | 标签 |
| data[].miniIconUrl | String | 小图标 URL |
| data[].name | String | 名称 |
| data[].sobjectName | String | 关联对象名称 |
| data[].url | String | URL |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "colors": [
        {
          "color": "0070D1",
          "context": "primary",
          "theme": "theme4"
        }
      ],
      "custom": false,
      "iconUrl": "https://example.com/img/icon/accounts32.png",
      "icons": [...],
      "label": "客户",
      "miniIconUrl": "https://example.com/img/icon/accounts16.png",
      "name": "standard-Account",
      "sobjectName": "Account",
      "url": "/001/o"
    }
  ]
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "获取标签页失败：连接超时"
}
```

---

### 6. 描述快速操作

#### 接口说明
获取指定 Salesforce 对象的快速操作定义信息，包括字段列表、布局信息等。

- **接口名称**：DescribeQuickActions
- **请求方式**：POST
- **请求路径**：`/partner/describe/quick-actions`
- **权限要求**：`@PreAuthorize("@ss.hasLogin()")`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| actionNames | Array | 是 | 快速操作名称列表 |
| actionNames[] | String | 是 | 快速操作名称（如 Account.NewContact 等） |

#### 请求示例
```json
{
  "actionNames": ["Account.NewContact", "Account.NewOpportunity"]
}
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Array | 快速操作定义列表 |
| data[].actionEnumOrId | String | 操作枚举或 ID |
| data[].canvasEnabled | Boolean | 是否启用 Canvas |
| data[].colors | Array | 颜色定义列表 |
| data[].contextSobjectType | String | 上下文对象类型 |
| data[].defaultValues | Object | 默认值 |
| data[].flowDevName | String | 流程开发名称 |
| data[].flowRecordIdVar | String | 流程记录 ID 变量 |
| data[].height | Integer | 高度 |
| data[].iconUrl | String | 图标 URL |
| data[].icons | Array | 图标定义列表 |
| data[].label | String | 标签 |
| data[].layout | Object | 布局定义 |
| data[].layout.layoutItems | Array | 布局项列表 |
| data[].lightningComponentBundleId | String | Lightning 组件包 ID |
| data[].lightningComponentBundleName | String | Lightning 组件包名称 |
| data[].lightningComponentQualifiedName | String | Lightning 组件限定名称 |
| data[].miniIconUrl | String | 小图标 URL |
| data[].name | String | 名称 |
| data[].showQuickActionLcHeader | Boolean | 是否显示快速操作 LC 头部 |
| data[].showQuickActionVfHeader | Boolean | 是否显示快速操作 VF 头部 |
| data[].targetParentField | String | 目标父字段 |
| data[].targetRecordTypeId | String | 目标记录类型 ID |
| data[].targetSobjectType | String | 目标对象类型 |
| data[].type | String | 类型 |
| data[].visualforcePageName | String | Visualforce 页面名称 |
| data[].visualforcePageUrl | String | Visualforce 页面 URL |
| data[].width | Integer | 宽度 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "actionEnumOrId": "Account.NewContact",
      "canvasEnabled": false,
      "colors": [...],
      "contextSobjectType": "Account",
      "defaultValues": {...},
      "height": 0,
      "iconUrl": "https://example.com/img/icon/newcontact32.png",
      "icons": [...],
      "label": "新建联系人",
      "layout": {
        "layoutItems": [...]
      },
      "miniIconUrl": "https://example.com/img/icon/newcontact16.png",
      "name": "NewContact",
      "showQuickActionLcHeader": false,
      "showQuickActionVfHeader": false,
      "targetParentField": "AccountId",
      "targetSobjectType": "Contact",
      "type": "Create",
      "width": 0
    }
  ]
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "描述快速操作失败：快速操作名称列表不能为空"
}
```

---

## 错误码

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 200 | 操作成功 | 无需处理 |
| 400 | 请求参数错误 | 检查请求参数是否符合要求 |
| 401 | 未授权 | 检查用户是否已登录 |
| 403 | 无权限 | 检查用户是否有权限访问该资源 |
| 404 | 资源不存在 | 检查对象类型、记录类型 ID 等是否正确 |
| 500 | 服务器内部错误 | 查看错误消息，检查 Salesforce 连接是否正常 |
| 503 | 服务不可用 | Salesforce 服务暂时不可用，稍后重试 |

## 通用错误响应格式

```json
{
  "code": 500,
  "msg": "错误描述信息",
  "data": null
}
```

## 注意事项

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

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

### 3. DescribeSObjects 限制
- 最多支持 100 个对象同时描述
- 批量 API 提高效率
- 部分失败时返回成功和失败的结果

### 4. DescribeLayout 限制
- 需要指定对象类型
- 可选指定记录类型
- 返回所有布局类型（编辑、详情等）

### 5. DescribeTabs 限制
- 返回所有用户可见的标签页
- 包含自定义标签页
- 按显示顺序排序

### 6. 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)
- [变更日志](../changelog/2026-02-02-005-changelog.md)
- [复盘文档](../retros/2026-02-02-005-retro.md)
- [会话记录](../sessions/2026-01-28-001-session.md)

## 版本历史

| 版本号 | 日期 | 变更内容 | 作者 |
|--------|------|----------|------|
| v1.0.0 | 2026-02-02 | 初始版本，实现六个核心描述功能 API | AI Assistant |