# API 文档 - 高级功能

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

## API 概述
高级功能 API 提供了对 Salesforce 高级操作的支持，包括线索转换、清空回收站、流程提交、获取用户信息、获取服务器时间戳等。这些 API 可以帮助开发人员实现复杂的业务场景，如销售流程管理、数据清理、审批流程等。

## 接口列表

### 1. 转换线索

#### 接口说明
将线索转换为账户、联系人和商机。支持指定现有账户和联系人进行关联，支持覆盖线索来源选项，支持不创建商机选项，支持发送通知邮件选项。

- **接口名称**：ConvertLead
- **请求方式**：POST
- **请求路径**：`/partner/advanced/convert-lead`
- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:convertLead')")`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| leadId | String | 是 | 线索 ID，格式为 18 位 Salesforce ID |
| convertedStatus | String | 是 | 转换状态，如 "Qualified" |
| accountId | String | 否 | 账户 ID，指定要关联的现有账户 |
| contactId | String | 否 | 联系人 ID，指定要关联的现有联系人 |
| opportunityId | String | 否 | 商机 ID，指定要关联的现有商机 |
| overwriteLeadSource | Boolean | 否 | 是否覆盖线索来源，默认为 false |
| doNotCreateOpportunity | Boolean | 否 | 是否不创建商机，默认为 false |
| sendNotificationEmail | Boolean | 否 | 是否发送通知邮件，默认为 false |

#### 请求示例
```json
{
  "leadId": "00Qxx0000001Gw2EAE",
  "convertedStatus": "Qualified",
  "accountId": "001xx0000001Gw2EAA",
  "contactId": "003xx0000001Gw2EAA",
  "opportunityId": "006xx0000001Gw2EAA",
  "overwriteLeadSource": true,
  "doNotCreateOpportunity": false,
  "sendNotificationEmail": true
}
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.accountId | String | 转换后的账户 ID |
| data.contactId | String | 转换后的联系人 ID |
| data.opportunityId | String | 转换后的商机 ID |
| data.leadId | String | 原线索 ID |
| data.success | Boolean | 是否成功 |
| data.errors | Array | 错误信息列表 |
| data.errors[].message | String | 错误消息 |
| data.errors[].statusCode | String | 错误状态码 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "线索转换成功",
  "data": {
    "accountId": "001xx0000001Gw2EAA",
    "contactId": "003xx0000001Gw2EAA",
    "opportunityId": "006xx0000001Gw2EAA",
    "leadId": "00Qxx0000001Gw2EAE",
    "success": true,
    "errors": []
  }
}
```

#### 失败示例
```json
{
  "code": 200,
  "msg": "线索转换失败",
  "data": {
    "accountId": null,
    "contactId": null,
    "opportunityId": null,
    "leadId": "00Qxx0000001Gw2EAE",
    "success": false,
    "errors": [
      {
        "message": "Invalid lead status",
        "statusCode": "INVALID_LEAD_STATUS"
      }
    ]
  }
}
```

---

### 2. 清空回收站

#### 接口说明
永久删除回收站中的记录。支持批量操作，最多 200 个记录。返回每个记录的删除结果，支持部分失败情况。

- **接口名称**：EmptyRecycleBin
- **请求方式**：POST
- **请求路径**：`/partner/advanced/empty-recycle-bin`
- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:emptyRecycleBin')")`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | Array<String> | 是 | 记录 ID 列表，最多 200 个，每个 ID 格式为 18 位 Salesforce ID |

#### 请求示例
```json
{
  "ids": [
    "001xx0000001Gw2EAA",
    "001xx0000001Gw3EAA",
    "001xx0000001Gw4EAA"
  ]
}
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.results | Array | 结果列表 |
| data.results[].id | String | 记录 ID |
| data.results[].success | Boolean | 是否成功 |
| data.results[].errors | Array | 错误信息列表 |
| data.results[].errors[].message | String | 错误消息 |
| data.results[].errors[].statusCode | String | 错误状态码 |
| data.success | Boolean | 是否全部成功（部分失败时为 false） |
| data.errors | Array | 整体错误信息列表 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "清空回收站成功",
  "data": {
    "results": [
      {
        "id": "001xx0000001Gw2EAA",
        "success": true,
        "errors": []
      },
      {
        "id": "001xx0000001Gw3EAA",
        "success": true,
        "errors": []
      },
      {
        "id": "001xx0000001Gw4EAA",
        "success": true,
        "errors": []
      }
    ],
    "success": true,
    "errors": []
  }
}
```

#### 部分失败示例
```json
{
  "code": 200,
  "msg": "清空回收站部分失败",
  "data": {
    "results": [
      {
        "id": "001xx0000001Gw2EAA",
        "success": true,
        "errors": []
      },
      {
        "id": "001xx0000001Gw3EAA",
        "success": false,
        "errors": [
          {
            "message": "Record not found in recycle bin",
            "statusCode": "ENTITY_IS_NOT_IN_RECYCLE_BIN"
          }
        ]
      }
    ],
    "success": false,
    "errors": []
  }
}
```

---

### 3. 流程提交

#### 接口说明
提交记录到审批流程，触发审批流程或其他自动化流程。支持添加审批评论。

- **接口名称**：ProcessSubmitRequest
- **请求方式**：POST
- **请求路径**：`/partner/advanced/process-submit-request`
- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:processSubmit')")`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectId | String | 是 | 对象 ID，格式为 18 位 Salesforce ID |
| comments | String | 否 | 审批评论，可选 |

#### 请求示例
```json
{
  "objectId": "001xx0000001Gw2EAA",
  "comments": "请审批此记录"
}
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.processInstanceId | String | 流程实例 ID |
| data.success | Boolean | 是否成功 |
| data.errors | Array | 错误信息列表 |
| data.errors[].message | String | 错误消息 |
| data.errors[].statusCode | String | 错误状态码 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "流程提交成功",
  "data": {
    "processInstanceId": "04gxx0000001Gw2EAA",
    "success": true,
    "errors": []
  }
}
```

#### 失败示例
```json
{
  "code": 200,
  "msg": "流程提交失败",
  "data": {
    "processInstanceId": null,
    "success": false,
    "errors": [
      {
        "message": "Process not found",
        "statusCode": "INVALID_OPERATION"
      }
    ]
  }
}
```

---

### 4. 获取用户信息

#### 接口说明
获取当前登录用户的详细信息。**注意：此接口复用认证和会话管理子需求的实现。**

- **接口名称**：GetUserInfo
- **请求方式**：GET
- **请求路径**：`/partner/advanced/user-info`
- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:userInfo')")`

#### 请求参数
无

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.userId | String | 用户 ID |
| data.userName | String | 用户名 |
| data.userFullName | String | 用户全名 |
| data.userEmail | String | 用户邮箱 |
| data.organizationId | String | 组织 ID |
| data.organizationName | String | 组织名称 |
| data.userLanguage | String | 用户语言 |
| data.userTimeZone | String | 用户时区 |
| data.currencySymbol | String | 货币符号 |
| data.success | Boolean | 是否成功 |
| data.errors | Array | 错误信息列表 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "获取用户信息成功",
  "data": {
    "userId": "005xx0000001Gw2EAA",
    "userName": "john.doe@example.com",
    "userFullName": "John Doe",
    "userEmail": "john.doe@example.com",
    "organizationId": "00Dxx0000001Gw2EAA",
    "organizationName": "Your Organization",
    "userLanguage": "en_US",
    "userTimeZone": "America/Los_Angeles",
    "currencySymbol": "$",
    "success": true,
    "errors": []
  }
}
```

---

### 5. 获取服务器时间戳

#### 接口说明
获取 Salesforce 服务器的当前时间戳，返回 ISO 8601 格式的时间戳和时区信息。

- **接口名称**：GetServerTimestamp
- **请求方式**：GET
- **请求路径**：`/partner/advanced/server-timestamp`
- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:serverTimestamp')")`

#### 请求参数
无

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.timestamp | String | 服务器时间戳，ISO 8601 格式（yyyy-MM-dd'T'HH:mm:ss.SSS'Z'） |
| data.timeZone | String | 服务器时区 |
| data.success | Boolean | 是否成功 |
| data.errors | Array | 错误信息列表 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "获取服务器时间戳成功",
  "data": {
    "timestamp": "2026-02-02T10:30:00.000Z",
    "timeZone": "America/Los_Angeles",
    "success": true,
    "errors": []
  }
}
```

## 错误码

| 错误码 | 错误消息 | 说明 |
|--------|----------|------|
| CANNOT_UPDATE_CONVERTED_LEAD | 无法更新已转换的线索 | 线索已被转换，无法再次转换 |
| INVALID_LEAD_ID | 无效的线索 ID | 线索 ID 格式不正确或线索不存在 |
| INVALID_ACCOUNT_ID | 无效的账户 ID | 账户 ID 格式不正确或账户不存在 |
| INVALID_CONTACT_ID | 无效的联系人 ID | 联系人 ID 格式不正确或联系人不存在 |
| INVALID_OPPORTUNITY_ID | 无效的商机 ID | 商机 ID 格式不正确或商机不存在 |
| INVALID_CONVERTED_STATUS | 无效的转换状态 | 转换状态不存在或无效 |
| INVALID_ID | 无效的记录 ID | 记录 ID 格式不正确或记录不存在 |
| ENTITY_IS_DELETED | 记录已删除 | 记录已被删除 |
| ENTITY_IS_NOT_IN_RECYCLE_BIN | 记录不在回收站中 | 记录不在回收站中，无法清空 |
| INVALID_OPERATION | 无效操作 | 该操作不支持或无效 |
| INSUFFICIENT_ACCESS | 权限不足 | 当前用户没有执行该操作的权限 |
| OPERATION_FAILED | 操作失败 | 操作执行失败 |
| PROCESS_SUBMISSION_FAILED | 流程提交失败 | 流程提交失败 |
| INVALID_OBJECT_ID | 无效的对象 ID | 对象 ID 格式不正确或对象不存在 |

## 注意事项

1. **线索转换**：
   - 线索转换后，原线索将被标记为已转换，无法再次转换
   - 如果未指定 accountId、contactId、opportunityId，系统将自动创建新记录
   - overwriteLeadSource 为 true 时，将覆盖线索的来源字段
   - doNotCreateOpportunity 为 true 时，将不创建商机

2. **清空回收站**：
   - 只能删除已在回收站中的记录
   - 删除后记录将永久删除，无法恢复
   - 最多支持 200 个记录同时删除
   - 支持部分失败情况，返回每个记录的删除结果

3. **流程提交**：
   - 用于触发审批流程或其他自动化流程
   - 返回流程实例 ID，可用于查询流程状态
   - 评论参数可选

4. **获取用户信息**：
   - 复用认证和会话管理子需求的实现
   - 返回当前登录用户的详细信息

5. **获取服务器时间戳**：
   - 返回 ISO 8601 格式的时间戳
   - 时区为 Salesforce 组织的时区
   - 用于同步本地时间与服务器时间

## 相关文档
- [需求文档](../requirements/sub/2026-01-28-001-06-高级功能.md)
- [设计文档](../design/2026-02-02-006-高级功能-设计.md)
- [决策记录](../decisions/2026-02-02-006-ADR-高级功能技术选型.md)
- [变更日志](../changelog/2026-02-02-006-changelog.md)
- [复盘文档](../retros/2026-02-02-006-retro.md)