datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-01-30-002-api.md

# API 文档

## 元数据
- 需求编号：001
- 子需求编号：001-02
- 创建时间：2026-01-30
- 创建人：AI Assistant
- 版本号：v1.0.0

## API 概述

本 API 文档描述了 Salesforce Partner API 的 CRUD 操作接口，包括 Create（创建）、Retrieve（查询）、Update（更新）、Delete（删除）、Upsert（更新或插入）、Merge（合并）六个核心操作。所有接口都支持单条记录和批量记录操作（最多 200 条），并提供完整的参数验证、异常处理、权限控制和 Swagger 文档。

### 核心功能

- **创建记录（Create）**：创建新的 Salesforce 记录，支持单条记录和批量记录创建
- **查询记录（Retrieve）**：查询 Salesforce 记录，支持单条记录和批量记录查询
- **更新记录（Update）**：更新现有的 Salesforce 记录，支持单条记录和批量记录更新
- **删除记录（Delete）**：删除 Salesforce 记录，支持单条记录和批量记录删除
- **更新或插入记录（Upsert）**：更新或插入 Salesforce 记录，支持单条记录和批量记录 Upsert
- **合并记录（Merge）**：合并三条 Salesforce 记录

### 技术栈

- **框架**：Spring Boot 3.x、Spring Security 6.x、若依框架
- **API 规范**：RESTful API
- **文档工具**：Swagger/OpenAPI
- **权限控制**：Spring Security（@PreAuthorize）
- **参数验证**：Spring Boot Validation
- **异常处理**：datai-salesforce-common 模块异常体系

### 认证方式

所有接口都需要用户认证，使用 Spring Security 的 `@PreAuthorize("@ss.hasLogin()")` 注解进行权限控制。用户必须登录后才能访问这些接口。

### 基础 URL

```
http://localhost:8080/partner/crud
```

### 响应格式

所有接口使用统一的响应格式：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}
```

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 返回数据 |

## 接口列表

### 接口 1：创建记录

#### 功能描述
创建新的 Salesforce 记录，支持单条记录和批量记录创建（最多 200 条）。

#### 请求方式
POST

#### 请求路径
`/partner/crud/create`

#### 请求参数

**单条记录创建**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectType | String | 是 | 对象类型（如 "Account"、"Contact"） |
| fields | Map<String, Object> | 是 | 字段值（如 {"Name": "Test Account", "BillingCity": "San Francisco"}） |
| records | List<Map<String, Object>> | 否 | 批量创建记录列表（如果提供，则忽略 objectType 和 fields） |

**批量记录创建**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| records | List<Map<String, Object>> | 是 | 批量创建记录列表（最多 200 条） |

#### 请求示例

**单条记录创建**：

```json
{
  "objectType": "Account",
  "fields": {
    "Name": "Test Account",
    "BillingCity": "San Francisco",
    "BillingState": "CA",
    "AnnualRevenue": 1000000.00
  }
}
```

**批量记录创建**：

```json
{
  "records": [
    {
      "Name": "Account 1",
      "BillingCity": "San Francisco"
    },
    {
      "Name": "Account 2",
      "BillingCity": "New York"
    },
    {
      "Name": "Account 3",
      "BillingCity": "Los Angeles"
    }
  ]
}
```

#### 响应参数

**单条记录创建**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 记录 ID |
| success | Boolean | 是否成功 |
| errors | List<ErrorVo> | 错误信息列表 |
| created | Boolean | 是否创建 |

**批量记录创建**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| - | List<RecordResultVo> | 记录操作结果列表 |

#### 响应示例

**成功示例（单条记录）**：

```json
{
  "code": 200,
  "msg": "创建成功",
  "data": {
    "id": "001xx000003DHb2AAG",
    "success": true,
    "errors": [],
    "created": true
  }
}
```

**成功示例（批量记录）**：

```json
{
  "code": 200,
  "msg": "批量创建成功",
  "data": [
    {
      "id": "001xx000003DHb2AAG",
      "success": true,
      "errors": [],
      "created": true
    },
    {
      "id": "001xx000003DHb3AAH",
      "success": true,
      "errors": [],
      "created": true
    },
    {
      "id": "001xx000003DHb4AAI",
      "success": true,
      "errors": [],
      "created": true
    }
  ]
}
```

**失败示例**：

```json
{
  "code": 500,
  "msg": "创建记录失败: INVALID_FIELD: No such column 'InvalidField' on sobject of type Account",
  "data": null
}
```

#### 错误码

| 错误码 | 说明 |
|--------|------|
| 500 | 创建记录失败 |
| INVALID_FIELD | 字段不存在或无效 |
| INVALID_ID | ID 无效 |
| MALFORMED_QUERY | 查询语法错误 |
| INVALID_OPERATION | 操作无效 |
| DUPLICATE_VALUE | 值重复 |
| ENTITY_IS_DELETED | 记录已删除 |
| INSUFFICIENT_ACCESS | 权限不足 |
| INVALID_CROSS_REFERENCE_KEY | 跨引用键无效 |

---

### 接口 2：查询记录

#### 功能描述
查询 Salesforce 记录，支持单条记录和批量记录查询（最多 200 条）。

#### 请求方式
GET

#### 请求路径
`/partner/crud/retrieve`

#### 请求参数

**单条记录查询**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectType | String | 是 | 对象类型（如 "Account"、"Contact"） |
| id | String | 是 | 记录 ID |
| fieldNames | String | 否 | 字段名称列表（逗号分隔，如 "Name,BillingCity,BillingState"） |

**批量记录查询**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectType | String | 是 | 对象类型（如 "Account"、"Contact"） |
| ids | String | 是 | 记录 ID 列表（逗号分隔，最多 200 条） |
| fieldNames | String | 否 | 字段名称列表（逗号分隔，如 "Name,BillingCity,BillingState"） |

#### 请求示例

**单条记录查询**：

```
GET /partner/crud/retrieve?objectType=Account&id=001xx000003DHb2AAG&fieldNames=Name,BillingCity,BillingState
```

**批量记录查询**：

```
GET /partner/crud/retrieve?objectType=Account&ids=001xx000003DHb2AAG,001xx000003DHb3AAH,001xx000003DHb4AAI&fieldNames=Name,BillingCity,BillingState
```

#### 响应参数

**单条记录查询**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| objectType | String | 对象类型 |
| id | String | 记录 ID |
| fields | Map<String, Object> | 字段值 |
| success | Boolean | 是否成功 |
| errors | List<ErrorVo> | 错误信息列表 |

**批量记录查询**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| - | List<RetrieveResultVo> | 查询结果列表 |

#### 响应示例

**成功示例（单条记录）**：

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "objectType": "Account",
    "id": "001xx000003DHb2AAG",
    "fields": {
      "Name": "Test Account",
      "BillingCity": "San Francisco",
      "BillingState": "CA"
    },
    "success": true,
    "errors": []
  }
}
```

**成功示例（批量记录）**：

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "objectType": "Account",
      "id": "001xx000003DHb2AAG",
      "fields": {
        "Name": "Account 1",
        "BillingCity": "San Francisco",
        "BillingState": "CA"
      },
      "success": true,
      "errors": []
    },
    {
      "objectType": "Account",
      "id": "001xx000003DHb3AAH",
      "fields": {
        "Name": "Account 2",
        "BillingCity": "New York",
        "BillingState": "NY"
      },
      "success": true,
      "errors": []
    },
    {
      "objectType": "Account",
      "id": "001xx000003DHb4AAI",
      "fields": {
        "Name": "Account 3",
        "BillingCity": "Los Angeles",
        "BillingState": "CA"
      },
      "success": true,
      "errors": []
    }
  ]
}
```

**失败示例**：

```json
{
  "code": 500,
  "msg": "查询记录失败: INVALID_ID: Invalid ID: 001xx000003DHb2AAG",
  "data": null
}
```

#### 错误码

| 错误码 | 说明 |
|--------|------|
| 500 | 查询记录失败 |
| INVALID_ID | ID 无效 |
| INVALID_FIELD | 字段不存在或无效 |
| ENTITY_IS_DELETED | 记录已删除 |
| INSUFFICIENT_ACCESS | 权限不足 |

---

### 接口 3：更新记录

#### 功能描述
更新现有的 Salesforce 记录，支持单条记录和批量记录更新（最多 200 条）。

#### 请求方式
PUT

#### 请求路径
`/partner/crud/update`

#### 请求参数

**单条记录更新**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectType | String | 是 | 对象类型（如 "Account"、"Contact"） |
| id | String | 是 | 记录 ID |
| fields | Map<String, Object> | 是 | 字段值（如 {"BillingCity": "New York"}） |
| records | List<UpdateRecordItem> | 否 | 批量更新记录列表（如果提供，则忽略 objectType、id 和 fields） |

**批量记录更新**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| records | List<UpdateRecordItem> | 是 | 批量更新记录列表（最多 200 条） |

**UpdateRecordItem**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | String | 是 | 记录 ID |
| fields | Map<String, Object> | 是 | 字段值 |

#### 请求示例

**单条记录更新**：

```json
{
  "objectType": "Account",
  "id": "001xx000003DHb2AAG",
  "fields": {
    "BillingCity": "New York",
    "BillingState": "NY",
    "AnnualRevenue": 2000000.00
  }
}
```

**批量记录更新**：

```json
{
  "records": [
    {
      "id": "001xx000003DHb2AAG",
      "fields": {
        "BillingCity": "New York",
        "BillingState": "NY"
      }
    },
    {
      "id": "001xx000003DHb3AAH",
      "fields": {
        "BillingCity": "Los Angeles",
        "BillingState": "CA"
      }
    },
    {
      "id": "001xx000003DHb4AAI",
      "fields": {
        "BillingCity": "Chicago",
        "BillingState": "IL"
      }
    }
  ]
}
```

#### 响应参数

**单条记录更新**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 记录 ID |
| success | Boolean | 是否成功 |
| errors | List<ErrorVo> | 错误信息列表 |

**批量记录更新**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| - | List<RecordResultVo> | 记录操作结果列表 |

#### 响应示例

**成功示例（单条记录）**：

```json
{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "id": "001xx000003DHb2AAG",
    "success": true,
    "errors": []
  }
}
```

**成功示例（批量记录）**：

```json
{
  "code": 200,
  "msg": "批量更新成功",
  "data": [
    {
      "id": "001xx000003DHb2AAG",
      "success": true,
      "errors": []
    },
    {
      "id": "001xx000003DHb3AAH",
      "success": true,
      "errors": []
    },
    {
      "id": "001xx000003DHb4AAI",
      "success": true,
      "errors": []
    }
  ]
}
```

**失败示例**：

```json
{
  "code": 500,
  "msg": "更新记录失败: INVALID_ID: Invalid ID: 001xx000003DHb2AAG",
  "data": null
}
```

#### 错误码

| 错误码 | 说明 |
|--------|------|
| 500 | 更新记录失败 |
| INVALID_ID | ID 无效 |
| INVALID_FIELD | 字段不存在或无效 |
| ENTITY_IS_DELETED | 记录已删除 |
| INSUFFICIENT_ACCESS | 权限不足 |

---

### 接口 4：删除记录

#### 功能描述
删除 Salesforce 记录，支持单条记录和批量记录删除（最多 200 条）。

#### 请求方式
DELETE

#### 请求路径
`/partner/crud/delete`

#### 请求参数

**单条记录删除**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectType | String | 是 | 对象类型（如 "Account"、"Contact"） |
| id | String | 是 | 记录 ID |
| ids | String | 否 | 记录 ID 列表（逗号分隔，最多 200 条） |

**批量记录删除**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectType | String | 是 | 对象类型（如 "Account"、"Contact"） |
| ids | String | 是 | 记录 ID 列表（逗号分隔，最多 200 条） |

#### 请求示例

**单条记录删除**：

```
DELETE /partner/crud/delete?objectType=Account&id=001xx000003DHb2AAG
```

**批量记录删除**：

```
DELETE /partner/crud/delete?objectType=Account&ids=001xx000003DHb2AAG,001xx000003DHb3AAH,001xx000003DHb4AAI
```

#### 响应参数

**单条记录删除**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 记录 ID |
| success | Boolean | 是否成功 |
| errors | List<ErrorVo> | 错误信息列表 |

**批量记录删除**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| - | List<RecordResultVo> | 记录操作结果列表 |

#### 响应示例

**成功示例（单条记录）**：

```json
{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "id": "001xx000003DHb2AAG",
    "success": true,
    "errors": []
  }
}
```

**成功示例（批量记录）**：

```json
{
  "code": 200,
  "msg": "批量删除成功",
  "data": [
    {
      "id": "001xx000003DHb2AAG",
      "success": true,
      "errors": []
    },
    {
      "id": "001xx000003DHb3AAH",
      "success": true,
      "errors": []
    },
    {
      "id": "001xx000003DHb4AAI",
      "success": true,
      "errors": []
    }
  ]
}
```

**失败示例**：

```json
{
  "code": 500,
  "msg": "删除记录失败: INVALID_ID: Invalid ID: 001xx000003DHb2AAG",
  "data": null
}
```

#### 错误码

| 错误码 | 说明 |
|--------|------|
| 500 | 删除记录失败 |
| INVALID_ID | ID 无效 |
| ENTITY_IS_DELETED | 记录已删除 |
| ENTITY_IS_LOCKED_FOR_DELETION | 记录被锁定，无法删除 |
| INSUFFICIENT_ACCESS | 权限不足 |

---

### 接口 5：更新或插入记录

#### 功能描述
更新或插入 Salesforce 记录，支持单条记录和批量记录 Upsert（最多 200 条）。如果记录存在则更新，如果不存在则创建。

#### 请求方式
POST

#### 请求路径
`/partner/crud/upsert`

#### 请求参数

**单条记录 Upsert**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectType | String | 是 | 对象类型（如 "Account"、"Contact"） |
| externalIdField | String | 是 | 外部 ID 字段名称（如 "ExternalId__c"） |
| fields | Map<String, Object> | 是 | 字段值（必须包含外部 ID 字段的值） |
| records | List<Map<String, Object>> | 否 | 批量 Upsert 记录列表（如果提供，则忽略 objectType、externalIdField 和 fields） |

**批量记录 Upsert**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectType | String | 是 | 对象类型（如 "Account"、"Contact"） |
| externalIdField | String | 是 | 外部 ID 字段名称（如 "ExternalId__c"） |
| records | List<Map<String, Object>> | 是 | 批量 Upsert 记录列表（最多 200 条，每条记录必须包含外部 ID 字段的值） |

#### 请求示例

**单条记录 Upsert**：

```json
{
  "objectType": "Account",
  "externalIdField": "ExternalId__c",
  "fields": {
    "ExternalId__c": "EXT001",
    "Name": "Test Account",
    "BillingCity": "San Francisco"
  }
}
```

**批量记录 Upsert**：

```json
{
  "objectType": "Account",
  "externalIdField": "ExternalId__c",
  "records": [
    {
      "ExternalId__c": "EXT001",
      "Name": "Account 1",
      "BillingCity": "San Francisco"
    },
    {
      "ExternalId__c": "EXT002",
      "Name": "Account 2",
      "BillingCity": "New York"
    },
    {
      "ExternalId__c": "EXT003",
      "Name": "Account 3",
      "BillingCity": "Los Angeles"
    }
  ]
}
```

#### 响应参数

**单条记录 Upsert**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 记录 ID |
| success | Boolean | 是否成功 |
| errors | List<ErrorVo> | 错误信息列表 |
| created | Boolean | 是否创建 |

**批量记录 Upsert**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| - | List<RecordResultVo> | 记录操作结果列表 |

#### 响应示例

**成功示例（单条记录，创建）**：

```json
{
  "code": 200,
  "msg": "Upsert 成功",
  "data": {
    "id": "001xx000003DHb2AAG",
    "success": true,
    "errors": [],
    "created": true
  }
}
```

**成功示例（单条记录，更新）**：

```json
{
  "code": 200,
  "msg": "Upsert 成功",
  "data": {
    "id": "001xx000003DHb2AAG",
    "success": true,
    "errors": [],
    "created": false
  }
}
```

**成功示例（批量记录）**：

```json
{
  "code": 200,
  "msg": "批量 Upsert 成功",
  "data": [
    {
      "id": "001xx000003DHb2AAG",
      "success": true,
      "errors": [],
      "created": true
    },
    {
      "id": "001xx000003DHb3AAH",
      "success": true,
      "errors": [],
      "created": false
    },
    {
      "id": "001xx000003DHb4AAI",
      "success": true,
      "errors": [],
      "created": true
    }
  ]
}
```

**失败示例**：

```json
{
  "code": 500,
  "msg": "Upsert 记录失败: INVALID_FIELD: No such column 'ExternalId__c' on sobject of type Account",
  "data": null
}
```

#### 错误码

| 错误码 | 说明 |
|--------|------|
| 500 | Upsert 记录失败 |
| INVALID_FIELD | 字段不存在或无效 |
| INVALID_ID | ID 无效 |
| ENTITY_IS_DELETED | 记录已删除 |
| INSUFFICIENT_ACCESS | 权限不足 |
| DUPLICATE_VALUE | 值重复 |

---

### 接口 6：合并记录

#### 功能描述
合并三条 Salesforce 记录，将两条记录合并到主记录中。

#### 请求方式
POST

#### 请求路径
`/partner/crud/merge`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectType | String | 是 | 对象类型（如 "Account"、"Contact"） |
| masterRecordId | String | 是 | 主记录 ID |
| recordToMergeIds | List<String> | 是 | 待合并记录 ID 列表（最多 2 条） |

#### 请求示例

```json
{
  "objectType": "Account",
  "masterRecordId": "001xx000003DHb2AAG",
  "recordToMergeIds": [
    "001xx000003DHb3AAH",
    "001xx000003DHb4AAI"
  ]
}
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 记录 ID |
| success | Boolean | 是否成功 |
| errors | List<ErrorVo> | 错误信息列表 |

#### 响应示例

**成功示例**：

```json
{
  "code": 200,
  "msg": "合并成功",
  "data": {
    "id": "001xx000003DHb2AAG",
    "success": true,
    "errors": []
  }
}
```

**失败示例**：

```json
{
  "code": 500,
  "msg": "合并记录失败: INVALID_ID: Invalid ID: 001xx000003DHb2AAG",
  "data": null
}
```

#### 错误码

| 错误码 | 说明 |
|--------|------|
| 500 | 合并记录失败 |
| INVALID_ID | ID 无效 |
| ENTITY_IS_DELETED | 记录已删除 |
| INSUFFICIENT_ACCESS | 权限不足 |
| CANNOT_MERGE_RECORD | 无法合并记录（如记录类型不同） |

---

## 数据模型

### RecordResultVo

记录操作结果。

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | String | 记录 ID |
| success | Boolean | 是否成功 |
| errors | List<ErrorVo> | 错误信息列表 |
| created | Boolean | 是否创建（仅 Upsert 操作） |

### RetrieveResultVo

查询结果。

| 字段名 | 类型 | 说明 |
|--------|------|------|
| objectType | String | 对象类型 |
| id | String | 记录 ID |
| fields | Map<String, Object> | 字段值 |
| success | Boolean | 是否成功 |
| errors | List<ErrorVo> | 错误信息列表 |

### ErrorVo

错误信息。

| 字段名 | 类型 | 说明 |
|--------|------|------|
| statusCode | String | 状态代码 |
| message | String | 错误消息 |
| fields | List<String> | 相关字段列表 |

## 错误码

### 通用错误码

| 错误码 | 说明 |
|--------|------|
| 200 | 操作成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

### Salesforce 错误码

| 错误码 | 说明 |
|--------|------|
| INVALID_FIELD | 字段不存在或无效 |
| INVALID_ID | ID 无效 |
| MALFORMED_QUERY | 查询语法错误 |
| INVALID_OPERATION | 操作无效 |
| DUPLICATE_VALUE | 值重复 |
| ENTITY_IS_DELETED | 记录已删除 |
| ENTITY_IS_LOCKED_FOR_DELETION | 记录被锁定，无法删除 |
| INSUFFICIENT_ACCESS | 权限不足 |
| INVALID_CROSS_REFERENCE_KEY | 跨引用键无效 |
| CANNOT_MERGE_RECORD | 无法合并记录 |

## 相关文档

- [需求文档](../requirements/sub/2026-01-28-001-02-CRUD操作.md)
- [设计文档](../design/2026-01-30-002-CRUD操作-设计.md)
- [决策记录](../decisions/2026-01-30-002-ADR-CRUD操作技术选型.md)
- [提示词](../prompts/2026-01-30-002-prompt-CRUD操作.md)
- [变更日志](../changelog/2026-01-30-002-changelog.md)
- [复盘文档](../retros/2026-01-30-002-retro.md)
- [会话记录](../sessions/2026-01-28-001-session.md)