# API 文档 - 批量操作

## 元数据
- 需求编号：001-03
- 创建时间：2026-01-30
- 创建人：AI Assistant
- 版本号：v1.0.0
- 模块：datai-salesforce-partner

## API 概述

批量操作 API 提供对 Salesforce 记录进行批量操作的能力，支持批量创建、批量更新、批量删除、批量 Upsert 四个核心操作。

### 核心特性
- 支持最多 1000 条记录
- 自动分批处理（每批最多 200 条）
- 支持部分失败情况
- 提供详细的成功/失败统计
- 支持 AllOrNoneHeader 控制
- 使用 DisableFeedTrackingHeader 提高性能
- 批次间休眠时间可配置

### 基础信息
- **Base URL**：`/partner/batch`
- **认证方式**：JWT Token（通过 Authorization Header 传递）
- **权限要求**：需要登录权限（`@PreAuthorize("@ss.hasLogin()")`）
- **Content-Type**：`application/json`

## 接口列表

### 1. 批量创建记录

#### 接口说明
批量创建 Salesforce 记录，支持最多 1000 条记录，自动分批处理（每批最多 200 条）。

#### 请求信息
- **请求方式**：POST
- **请求路径**：`/partner/batch/create`
- **权限要求**：`@ss.hasLogin()`

#### 请求参数

**Body 参数**：

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| objectType | String | 是 | 对象类型 | "Account" |
| records | List<Map<String, Object>> | 是 | 记录列表，最多 1000 条 | [{"Name": "Test Account"}] |
| allOrNone | Boolean | 否 | 是否全部成功或全部失败，默认 false | false |
| sleepTime | Long | 否 | 批次间休眠时间（毫秒），默认 100 | 100 |

#### 响应参数

**成功响应**（HTTP 200）：

| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| code | Integer | 状态码 | 200 |
| msg | String | 提示信息 | "批量创建成功" |
| data | Object | 响应数据 | - |
| data.success | Boolean | 是否全部成功 | true |
| data.successCount | Integer | 成功数量 | 100 |
| data.failureCount | Integer | 失败数量 | 0 |
| data.totalCount | Integer | 总数量 | 100 |
| data.results | List | 结果列表 | - |
| data.results[].success | Boolean | 单项是否成功 | true |
| data.results[].id | String | 记录 ID | "001xx000003GWFjAAO" |
| data.results[].errors | List | 错误列表 | [] |
| data.results[].index | Integer | 索引 | 0 |

**失败响应**（HTTP 200，业务失败）：

| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| code | Integer | 状态码 | 200 |
| msg | String | 提示信息 | "批量创建部分失败" |
| data | Object | 响应数据（包含失败详情） | - |

**错误响应**（HTTP 500）：

| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| code | Integer | 状态码 | 500 |
| msg | String | 错误信息 | "批量创建记录失败: ..." |

#### 请求示例

```json
{
  "objectType": "Account",
  "records": [
    {
      "Name": "Test Account 1",
      "BillingCity": "San Francisco"
    },
    {
      "Name": "Test Account 2",
      "BillingCity": "New York"
    }
  ],
  "allOrNone": false,
  "sleepTime": 100
}
```

#### 响应示例

**成功示例**：

```json
{
  "code": 200,
  "msg": "批量创建成功",
  "data": {
    "success": true,
    "successCount": 2,
    "failureCount": 0,
    "totalCount": 2,
    "results": [
      {
        "success": true,
        "id": "001xx000003GWFjAAO",
        "errors": [],
        "index": 0
      },
      {
        "success": true,
        "id": "001xx000003GWFkAAP",
        "errors": [],
        "index": 1
      }
    ]
  }
}
```

**部分失败示例**：

```json
{
  "code": 200,
  "msg": "批量创建部分失败",
  "data": {
    "success": false,
    "successCount": 1,
    "failureCount": 1,
    "totalCount": 2,
    "results": [
      {
        "success": true,
        "id": "001xx000003GWFjAAO",
        "errors": [],
        "index": 0
      },
      {
        "success": false,
        "id": null,
        "errors": [
          {
            "statusCode": "REQUIRED_FIELD_MISSING",
            "message": "Required fields are missing: [Name]",
            "fields": ["Name"]
          }
        ],
        "index": 1
      }
    ]
  }
}
```

---

### 2. 批量更新记录

#### 接口说明
批量更新 Salesforce 记录，支持最多 1000 条记录，自动分批处理（每批最多 200 条）。每条记录必须包含 `id` 字段。

#### 请求信息
- **请求方式**：POST
- **请求路径**：`/partner/batch/update`
- **权限要求**：`@ss.hasLogin()`

#### 请求参数

**Body 参数**：

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| objectType | String | 是 | 对象类型 | "Account" |
| records | List<Map<String, Object>> | 是 | 记录列表，每条记录必须包含 id，最多 1000 条 | [{"id": "001xx...", "Name": "Updated"}] |
| allOrNone | Boolean | 否 | 是否全部成功或全部失败，默认 false | false |
| sleepTime | Long | 否 | 批次间休眠时间（毫秒），默认 100 | 100 |

#### 响应参数

**成功响应**（HTTP 200）：

| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| code | Integer | 状态码 | 200 |
| msg | String | 提示信息 | "批量更新成功" |
| data | Object | 响应数据 | - |
| data.success | Boolean | 是否全部成功 | true |
| data.successCount | Integer | 成功数量 | 100 |
| data.failureCount | Integer | 失败数量 | 0 |
| data.totalCount | Integer | 总数量 | 100 |
| data.results | List | 结果列表 | - |
| data.results[].success | Boolean | 单项是否成功 | true |
| data.results[].id | String | 记录 ID | "001xx000003GWFjAAO" |
| data.results[].errors | List | 错误列表 | [] |
| data.results[].index | Integer | 索引 | 0 |

#### 请求示例

```json
{
  "objectType": "Account",
  "records": [
    {
      "id": "001xx000003GWFjAAO",
      "Name": "Updated Account 1",
      "BillingCity": "Los Angeles"
    },
    {
      "id": "001xx000003GWFkAAP",
      "Name": "Updated Account 2",
      "BillingCity": "Chicago"
    }
  ],
  "allOrNone": false,
  "sleepTime": 100
}
```

#### 响应示例

**成功示例**：

```json
{
  "code": 200,
  "msg": "批量更新成功",
  "data": {
    "success": true,
    "successCount": 2,
    "failureCount": 0,
    "totalCount": 2,
    "results": [
      {
        "success": true,
        "id": "001xx000003GWFjAAO",
        "errors": [],
        "index": 0
      },
      {
        "success": true,
        "id": "001xx000003GWFkAAP",
        "errors": [],
        "index": 1
      }
    ]
  }
}
```

---

### 3. 批量删除记录

#### 接口说明
批量删除 Salesforce 记录，支持最多 1000 条记录，自动分批处理（每批最多 200 条）。

#### 请求信息
- **请求方式**：POST
- **请求路径**：`/partner/batch/delete`
- **权限要求**：`@ss.hasLogin()`

#### 请求参数

**Body 参数**：

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| objectType | String | 是 | 对象类型 | "Account" |
| ids | List<String> | 是 | 记录 ID 列表，最多 1000 条 | ["001xx...", "001xx..."] |
| allOrNone | Boolean | 否 | 是否全部成功或全部失败，默认 false | false |
| sleepTime | Long | 否 | 批次间休眠时间（毫秒），默认 100 | 100 |

#### 响应参数

**成功响应**（HTTP 200）：

| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| code | Integer | 状态码 | 200 |
| msg | String | 提示信息 | "批量删除成功" |
| data | Object | 响应数据 | - |
| data.success | Boolean | 是否全部成功 | true |
| data.successCount | Integer | 成功数量 | 100 |
| data.failureCount | Integer | 失败数量 | 0 |
| data.totalCount | Integer | 总数量 | 100 |
| data.results | List | 结果列表 | - |
| data.results[].success | Boolean | 单项是否成功 | true |
| data.results[].id | String | 记录 ID | "001xx000003GWFjAAO" |
| data.results[].errors | List | 错误列表 | [] |
| data.results[].index | Integer | 索引 | 0 |

#### 请求示例

```json
{
  "objectType": "Account",
  "ids": [
    "001xx000003GWFjAAO",
    "001xx000003GWFkAAP"
  ],
  "allOrNone": false,
  "sleepTime": 100
}
```

#### 响应示例

**成功示例**：

```json
{
  "code": 200,
  "msg": "批量删除成功",
  "data": {
    "success": true,
    "successCount": 2,
    "failureCount": 0,
    "totalCount": 2,
    "results": [
      {
        "success": true,
        "id": "001xx000003GWFjAAO",
        "errors": [],
        "index": 0
      },
      {
        "success": true,
        "id": "001xx000003GWFkAAP",
        "errors": [],
        "index": 1
      }
    ]
  }
}
```

---

### 4. 批量 Upsert 记录

#### 接口说明
批量 Upsert（更新或插入）Salesforce 记录，支持最多 1000 条记录，自动分批处理（每批最多 200 条）。根据指定的外部 ID 字段，如果记录存在则更新，不存在则创建。

#### 请求信息
- **请求方式**：POST
- **请求路径**：`/partner/batch/upsert`
- **权限要求**：`@ss.hasLogin()`

#### 请求参数

**Body 参数**：

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| objectType | String | 是 | 对象类型 | "Account" |
| externalIdField | String | 是 | 外部 ID 字段 | "ExternalId__c" |
| records | List<Map<String, Object>> | 是 | 记录列表，每条记录必须包含外部 ID 字段，最多 1000 条 | [{"ExternalId__c": "EXT001", "Name": "Test"}] |
| allOrNone | Boolean | 否 | 是否全部成功或全部失败，默认 false | false |
| sleepTime | Long | 否 | 批次间休眠时间（毫秒），默认 100 | 100 |

#### 响应参数

**成功响应**（HTTP 200）：

| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| code | Integer | 状态码 | 200 |
| msg | String | 提示信息 | "批量 Upsert 成功" |
| data | Object | 响应数据 | - |
| data.success | Boolean | 是否全部成功 | true |
| data.successCount | Integer | 成功数量 | 100 |
| data.failureCount | Integer | 失败数量 | 0 |
| data.createdCount | Integer | 创建数量 | 50 |
| data.updatedCount | Integer | 更新数量 | 50 |
| data.totalCount | Integer | 总数量 | 100 |
| data.results | List | 结果列表 | - |
| data.results[].success | Boolean | 单项是否成功 | true |
| data.results[].id | String | 记录 ID | "001xx000003GWFjAAO" |
| data.results[].created | Boolean | 是否创建（true 创建，false 更新） | true |
| data.results[].errors | List | 错误列表 | [] |
| data.results[].index | Integer | 索引 | 0 |

#### 请求示例

```json
{
  "objectType": "Account",
  "externalIdField": "ExternalId__c",
  "records": [
    {
      "ExternalId__c": "EXT001",
      "Name": "Upsert Account 1",
      "BillingCity": "Seattle"
    },
    {
      "ExternalId__c": "EXT002",
      "Name": "Upsert Account 2",
      "BillingCity": "Boston"
    }
  ],
  "allOrNone": false,
  "sleepTime": 100
}
```

#### 响应示例

**成功示例**：

```json
{
  "code": 200,
  "msg": "批量 Upsert 成功",
  "data": {
    "success": true,
    "successCount": 2,
    "failureCount": 0,
    "createdCount": 1,
    "updatedCount": 1,
    "totalCount": 2,
    "results": [
      {
        "success": true,
        "id": "001xx000003GWFjAAO",
        "created": true,
        "errors": [],
        "index": 0
      },
      {
        "success": true,
        "id": "001xx000003GWFkAAP",
        "created": false,
        "errors": [],
        "index": 1
      }
    ]
  }
}
```

---

## 错误码

### 系统错误码

| 错误码 | 错误消息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 200 | 操作成功 | 请求处理成功 | - |
| 500 | 操作失败 | 服务器内部错误 | 检查服务器日志，联系管理员 |
| 401 | 未授权 | 用户未登录或 Token 无效 | 重新登录获取 Token |
| 403 | 禁止访问 | 用户没有权限执行该操作 | 检查用户权限配置 |

### 业务错误码

| 错误码 | 错误消息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| INVALID_OBJECT_TYPE | 无效的对象类型 | 对象类型不存在或无权限访问 | 检查对象类型名称是否正确 |
| INVALID_RECORD_ID | 无效的记录 ID | 记录 ID 格式不正确或记录不存在 | 检查记录 ID 是否正确 |
| INVALID_FIELD_NAME | 无效的字段名称 | 字段名称不存在或无权限访问 | 检查字段名称是否正确 |
| INVALID_FIELD_VALUE | 无效的字段值 | 字段值不符合要求 | 检查字段值是否符合要求 |
| MISSING_REQUIRED_FIELD | 缺少必填字段 | 缺少必填字段的值 | 补充必填字段的值 |
| MISSING_RECORD_ID | 缺少记录 ID | Update 操作必须提供记录 ID | 在记录中添加 id 字段 |
| MISSING_EXTERNAL_ID | 缺少外部 ID | Upsert 操作必须提供外部 ID 字段 | 在记录中添加外部 ID 字段 |
| DUPLICATE_VALUE | 重复值 | 字段值已存在，违反唯一性约束 | 检查字段值是否重复 |
| RECORD_LOCKED | 记录已锁定 | 记录被其他用户锁定 | 等待其他用户释放锁定 |
| INSUFFICIENT_PERMISSIONS | 权限不足 | 当前用户没有执行该操作的权限 | 检查用户权限配置 |
| ENTITY_IS_DELETED | 记录已删除 | 记录已被删除 | 检查记录是否存在 |
| BATCH_SIZE_EXCEEDED | 批量大小超出限制 | 单次批量操作最多支持 1000 条记录 | 减少记录数量 |
| OPERATION_FAILED | 操作失败 | 操作执行失败 | 检查错误详情 |

### Salesforce API 错误码

| 错误码 | 说明 |
|--------|------|
| REQUIRED_FIELD_MISSING | 缺少必填字段 |
| INVALID_FIELD | 无效字段 |
| INVALID_ID_FIELD | 无效 ID 字段 |
| INVALID_CROSS_REFERENCE_KEY | 无效交叉引用键 |
| DUPLICATE_VALUE | 重复值 |
| ENTITY_IS_LOCKED | 实体已锁定 |
| INSUFFICIENT_ACCESS_OR_READONLY | 权限不足或只读 |
| INVALID_OPERATION | 无效操作 |
| STORAGE_LIMIT_EXCEEDED | 存储限制超出 |
| SYSTEM_UNAVAILABLE | 系统不可用 |

## 限制与约束

### 数量限制
- 单次请求最多支持 1000 条记录
- 每批最多 200 条记录
- 超出限制将返回 BATCH_SIZE_EXCEEDED 错误

### 性能限制
- 批次间默认休眠 100ms
- 可根据实际情况调整休眠时间
- 建议使用 DisableFeedTrackingHeader 提高性能

### 权限要求
- 需要登录权限（`@ss.hasLogin()`）
- 需要有相应对象的读写权限
- 需要有相应字段的访问权限

## 最佳实践

### 1. 分批处理
对于大规模数据操作，建议使用自动分批处理功能：
- 单次请求最多 1000 条记录
- 系统会自动分批处理（每批 200 条）
- 建议设置适当的批次间休眠时间，避免 API 限流

### 2. 错误处理
- 建议设置 `allOrNone` 为 `false`，允许部分失败
- 检查返回结果中的 `success` 字段，判断是否全部成功
- 对于失败的记录，可以查看 `results` 中的错误详情

### 3. 性能优化
- 使用 `DisableFeedTrackingHeader` 提高性能（已默认启用）
- 设置适当的 `sleepTime`，避免 API 限流
- 避免在高峰期进行大规模批量操作

### 4. Upsert 使用
- 确保外部 ID 字段在对象中已定义
- 确保每条记录都包含外部 ID 字段的值
- 可以使用 `created` 字段判断记录是创建还是更新

## 相关文档

- [需求文档](../requirements/sub/2026-01-28-001-03-批量操作.md) - 批量操作需求文档
- [设计文档](../design/2026-01-30-003-批量操作-设计.md) - 批量操作设计文档
- [决策记录](../decisions/2026-01-30-003-ADR-批量操作技术选型.md) - 批量操作技术选型决策记录
- [变更日志](../changelog/2026-01-30-003-changelog.md) - 批量操作变更日志
- [复盘文档](../retros/2026-01-30-003-retro.md) - 批量操作复盘文档
- [会话记录](../sessions/2026-01-28-001-session.md) - 会话记录