561 lines
16 KiB
Markdown
561 lines
16 KiB
Markdown
# Salesforce 多系统配置 API 文档
|
||
|
||
## 元数据
|
||
- 需求编号：2026-01-21-003-01
|
||
- 创建时间：2026-01-22
|
||
- 创建人：SSOT 架构师
|
||
- 版本：1.0.0
|
||
|
||
## API 概述
|
||
Salesforce 多系统配置 API 提供了 Salesforce 系统配置的完整管理功能，包括系统配置的增删改查、启用/停用、源 org 和目标 org 列表查询等功能。
|
||
|
||
## 基础信息
|
||
- API 名称：Salesforce 多系统配置 API
|
||
- API 版本：1.0.0
|
||
- 描述：提供 Salesforce 系统配置的管理功能
|
||
- 认证方式：JWT Token
|
||
- 基础路径：/api/salesforce/system/config
|
||
|
||
## 端点列表
|
||
|
||
### 接口 1：添加系统配置
|
||
- **请求方式**：POST
|
||
- **请求路径**：/api/salesforce/system/config
|
||
- **功能描述**：添加新的 Salesforce 系统配置
|
||
- **权限要求**：salesforce:system:config:add
|
||
- **请求参数**：
|
||
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|
||
| ------ | ---- | ---- | ---- | ------ |
|
||
| systemName | String | 是 | 系统名称（唯一） | production |
|
||
| systemType | String | 是 | 系统类型（用户自定义） | production |
|
||
| orgType | String | 是 | 组织类型（S=源 org T=目标 org） | S |
|
||
| loginType | String | 是 | 登录类型（oauth2/session_id/cli） | oauth2 |
|
||
| clientId | String | 否 | OAuth 客户端 ID | 3MVG9... |
|
||
| clientSecret | String | 否 | OAuth 客户端密钥（加密存储） | 123456... |
|
||
| username | String | 否 | 用户名 | user@example.com |
|
||
| password | String | 否 | 密码（加密存储） | password123 |
|
||
| securityToken | String | 否 | 安全令牌（加密存储） | token123 |
|
||
| sortOrder | Integer | 否 | 排序 | 0 |
|
||
| remark | String | 否 | 备注 | 生产环境 |
|
||
- **请求体**：
|
||
```json
|
||
{
|
||
"systemName": "production",
|
||
"systemType": "production",
|
||
"orgType": "S",
|
||
"loginType": "oauth2",
|
||
"clientId": "3MVG9...",
|
||
"clientSecret": "123456...",
|
||
"username": "user@example.com",
|
||
"password": "password123",
|
||
"securityToken": "token123",
|
||
"sortOrder": 0,
|
||
"remark": "生产环境"
|
||
}
|
||
```
|
||
- **响应参数**：
|
||
| 参数名 | 类型 | 描述 |
|
||
| ------ | ---- | ---- |
|
||
| code | Integer | 响应码 |
|
||
| message | String | 响应信息 |
|
||
| data | Object | 响应数据 |
|
||
- **成功响应示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": null
|
||
}
|
||
```
|
||
- **错误响应示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "新增系统配置'production'失败，系统名称已存在",
|
||
"data": null
|
||
}
|
||
```
|
||
- **状态码**：
|
||
| 状态码 | 描述 |
|
||
| ------ | ---- |
|
||
| 200 | 成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证 |
|
||
| 403 | 无权限 |
|
||
| 500 | 服务器内部错误 |
|
||
- **注意事项**：
|
||
- 系统名称必须唯一
|
||
- 密码、安全令牌等敏感信息会使用 EncryptUtils 加密存储
|
||
|
||
### 接口 2：修改系统配置
|
||
- **请求方式**：PUT
|
||
- **请求路径**：/api/salesforce/system/config
|
||
- **功能描述**：修改现有的 Salesforce 系统配置
|
||
- **权限要求**：salesforce:system:config:edit
|
||
- **请求参数**：
|
||
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|
||
| ------ | ---- | ---- | ---- | ------ |
|
||
| id | Long | 是 | 主键 ID | 1 |
|
||
| systemName | String | 否 | 系统名称 | production |
|
||
| systemType | String | 否 | 系统类型 | production |
|
||
| orgType | String | 否 | 组织类型 | S |
|
||
| loginType | String | 否 | 登录类型 | oauth2 |
|
||
| clientId | String | 否 | OAuth 客户端 ID | 3MVG9... |
|
||
| clientSecret | String | 否 | OAuth 客户端密钥 | 123456... |
|
||
| username | String | 否 | 用户名 | user@example.com |
|
||
| password | String | 否 | 密码 | password123 |
|
||
| securityToken | String | 否 | 安全令牌 | token123 |
|
||
| sortOrder | Integer | 否 | 排序 | 0 |
|
||
| remark | String | 否 | 备注 | 生产环境 |
|
||
- **请求体**：
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"systemName": "production",
|
||
"systemType": "production",
|
||
"orgType": "S",
|
||
"loginType": "oauth2",
|
||
"clientId": "3MVG9...",
|
||
"clientSecret": "123456...",
|
||
"username": "user@example.com",
|
||
"password": "password123",
|
||
"securityToken": "token123",
|
||
"sortOrder": 0,
|
||
"remark": "生产环境"
|
||
}
|
||
```
|
||
- **响应参数**：
|
||
| 参数名 | 类型 | 描述 |
|
||
| ------ | ---- | ---- |
|
||
| code | Integer | 响应码 |
|
||
| message | String | 响应信息 |
|
||
| data | Object | 响应数据 |
|
||
- **成功响应示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": null
|
||
}
|
||
```
|
||
- **错误响应示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "修改系统配置'production'失败，系统名称已存在",
|
||
"data": null
|
||
}
|
||
```
|
||
- **状态码**：
|
||
| 状态码 | 描述 |
|
||
| ------ | ---- |
|
||
| 200 | 成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证 |
|
||
| 403 | 无权限 |
|
||
| 500 | 服务器内部错误 |
|
||
- **注意事项**：
|
||
- 系统名称必须唯一
|
||
- 密码、安全令牌等敏感信息会使用 EncryptUtils 加密存储
|
||
|
||
### 接口 3：删除系统配置
|
||
- **请求方式**：DELETE
|
||
- **请求路径**：/api/salesforce/system/config/{id}
|
||
- **功能描述**：删除指定的 Salesforce 系统配置
|
||
- **权限要求**：salesforce:system:config:remove
|
||
- **请求参数**：
|
||
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|
||
| ------ | ---- | ---- | ---- | ------ |
|
||
| id | Long | 是 | 主键 ID | 1 |
|
||
- **请求体**：无
|
||
- **响应参数**：
|
||
| 参数名 | 类型 | 描述 |
|
||
| ------ | ---- | ---- |
|
||
| code | Integer | 响应码 |
|
||
| message | String | 响应信息 |
|
||
| data | Object | 响应数据 |
|
||
- **成功响应示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": null
|
||
}
|
||
```
|
||
- **错误响应示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "删除系统配置失败",
|
||
"data": null
|
||
}
|
||
```
|
||
- **状态码**：
|
||
| 状态码 | 描述 |
|
||
| ------ | ---- |
|
||
| 200 | 成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证 |
|
||
| 403 | 无权限 |
|
||
| 500 | 服务器内部错误 |
|
||
- **注意事项**：
|
||
- 删除操作不可恢复
|
||
|
||
### 接口 4：查询系统配置详情
|
||
- **请求方式**：GET
|
||
- **请求路径**：/api/salesforce/system/config/{id}
|
||
- **功能描述**：查询指定的 Salesforce 系统配置详情
|
||
- **权限要求**：salesforce:system:config:query
|
||
- **请求参数**：
|
||
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|
||
| ------ | ---- | ---- | ---- | ------ |
|
||
| id | Long | 是 | 主键 ID | 1 |
|
||
- **请求体**：无
|
||
- **响应参数**：
|
||
| 参数名 | 类型 | 描述 |
|
||
| ------ | ---- | ---- |
|
||
| code | Integer | 响应码 |
|
||
| message | String | 响应信息 |
|
||
| data | Object | 响应数据 |
|
||
- **成功响应示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "查询成功",
|
||
"data": {
|
||
"id": 1,
|
||
"systemName": "production",
|
||
"systemType": "production",
|
||
"orgType": "S",
|
||
"loginType": "oauth2",
|
||
"clientId": "3MVG9...",
|
||
"clientSecret": "123456...",
|
||
"username": "user@example.com",
|
||
"status": "0",
|
||
"sortOrder": 0,
|
||
"remark": "生产环境",
|
||
"createBy": "admin",
|
||
"createTime": "2026-01-22 10:00:00",
|
||
"updateBy": "admin",
|
||
"updateTime": "2026-01-22 10:00:00"
|
||
}
|
||
}
|
||
```
|
||
- **错误响应示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "查询系统配置失败",
|
||
"data": null
|
||
}
|
||
```
|
||
- **状态码**：
|
||
| 状态码 | 描述 |
|
||
| ------ | ---- |
|
||
| 200 | 成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证 |
|
||
| 403 | 无权限 |
|
||
| 500 | 服务器内部错误 |
|
||
- **注意事项**：
|
||
- 返回的数据包含敏感字段（clientSecret、password、securityToken）
|
||
|
||
### 接口 5：查询系统配置列表
|
||
- **请求方式**：GET
|
||
- **请求路径**：/api/salesforce/system/config/list
|
||
- **功能描述**：查询 Salesforce 系统配置列表
|
||
- **权限要求**：salesforce:system:config:list
|
||
- **请求参数**：
|
||
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|
||
| ------ | ---- | ---- | ---- | ------ |
|
||
| systemName | String | 否 | 系统名称 | production |
|
||
| systemType | String | 否 | 系统类型 | production |
|
||
| orgType | String | 否 | 组织类型 | S |
|
||
| loginType | String | 否 | 登录类型 | oauth2 |
|
||
| status | String | 否 | 状态（0正常 1停用） | 0 |
|
||
| pageNum | Integer | 否 | 页码 | 1 |
|
||
| pageSize | Integer | 否 | 每页大小 | 10 |
|
||
- **请求体**：无
|
||
- **响应参数**：
|
||
| 参数名 | 类型 | 描述 |
|
||
| ------ | ---- | ---- |
|
||
| code | Integer | 响应码 |
|
||
| message | String | 响应信息 |
|
||
| data | Object | 响应数据 |
|
||
- **成功响应示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "查询成功",
|
||
"data": {
|
||
"total": 2,
|
||
"rows": [
|
||
{
|
||
"id": 1,
|
||
"systemName": "production",
|
||
"systemType": "production",
|
||
"orgType": "S",
|
||
"loginType": "oauth2",
|
||
"clientId": "3MVG9...",
|
||
"username": "user@example.com",
|
||
"status": "0",
|
||
"sortOrder": 0,
|
||
"remark": "生产环境",
|
||
"createBy": "admin",
|
||
"createTime": "2026-01-22 10:00:00",
|
||
"updateBy": "admin",
|
||
"updateTime": "2026-01-22 10:00:00"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"systemName": "sandbox",
|
||
"systemType": "sandbox",
|
||
"orgType": "T",
|
||
"loginType": "oauth2",
|
||
"clientId": "3MVG9...",
|
||
"username": "user@example.com",
|
||
"status": "0",
|
||
"sortOrder": 1,
|
||
"remark": "测试环境",
|
||
"createBy": "admin",
|
||
"createTime": "2026-01-22 10:00:00",
|
||
"updateBy": "admin",
|
||
"updateTime": "2026-01-22 10:00:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
- **错误响应示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "查询系统配置列表失败",
|
||
"data": null
|
||
}
|
||
```
|
||
- **状态码**：
|
||
| 状态码 | 描述 |
|
||
| ------ | ---- |
|
||
| 200 | 成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证 |
|
||
| 403 | 无权限 |
|
||
| 500 | 服务器内部错误 |
|
||
- **注意事项**：
|
||
- 支持分页查询
|
||
- 支持按多个条件筛选
|
||
|
||
### 接口 6：启用系统
|
||
- **请求方式**：PUT
|
||
- **请求路径**：/api/salesforce/system/config/{id}/enable
|
||
- **功能描述**：启用指定的 Salesforce 系统
|
||
- **权限要求**：salesforce:system:config:edit
|
||
- **请求参数**：
|
||
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|
||
| ------ | ---- | ---- | ---- | ------ |
|
||
| id | Long | 是 | 主键 ID | 1 |
|
||
- **请求体**：无
|
||
- **响应参数**：
|
||
| 参数名 | 类型 | 描述 |
|
||
| ------ | ---- | ---- |
|
||
| code | Integer | 响应码 |
|
||
| message | String | 响应信息 |
|
||
| data | Object | 响应数据 |
|
||
- **成功响应示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": null
|
||
}
|
||
```
|
||
- **错误响应示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "启用系统失败",
|
||
"data": null
|
||
}
|
||
```
|
||
- **状态码**：
|
||
| 状态码 | 描述 |
|
||
| ------ | ---- |
|
||
| 200 | 成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证 |
|
||
| 403 | 无权限 |
|
||
| 500 | 服务器内部错误 |
|
||
- **注意事项**：
|
||
- 启用后系统状态变为 0（正常）
|
||
|
||
### 接口 7：停用系统
|
||
- **请求方式**：PUT
|
||
- **请求路径**：/api/salesforce/system/config/{id}/disable
|
||
- **功能描述**：停用指定的 Salesforce 系统
|
||
- **权限要求**：salesforce:system:config:edit
|
||
- **请求参数**：
|
||
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|
||
| ------ | ---- | ---- | ---- | ------ |
|
||
| id | Long | 是 | 主键 ID | 1 |
|
||
- **请求体**：无
|
||
- **响应参数**：
|
||
| 参数名 | 类型 | 描述 |
|
||
| ------ | ---- | ---- |
|
||
| code | Integer | 响应码 |
|
||
| message | String | 响应信息 |
|
||
| data | Object | 响应数据 |
|
||
- **成功响应示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": null
|
||
}
|
||
```
|
||
- **错误响应示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "停用系统失败",
|
||
"data": null
|
||
}
|
||
```
|
||
- **状态码**：
|
||
| 状态码 | 描述 |
|
||
| ------ | ---- |
|
||
| 200 | 成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证 |
|
||
| 403 | 无权限 |
|
||
| 500 | 服务器内部错误 |
|
||
- **注意事项**：
|
||
- 停用后系统状态变为 1（停用）
|
||
|
||
### 接口 8：查询源 org 列表
|
||
- **请求方式**：GET
|
||
- **请求路径**：/api/salesforce/system/config/source
|
||
- **功能描述**：查询所有源 org 列表
|
||
- **权限要求**：salesforce:system:config:list
|
||
- **请求参数**：无
|
||
- **请求体**：无
|
||
- **响应参数**：
|
||
| 参数名 | 类型 | 描述 |
|
||
| ------ | ---- | ---- |
|
||
| code | Integer | 响应码 |
|
||
| message | String | 响应信息 |
|
||
| data | Array | 响应数据 |
|
||
- **成功响应示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "查询成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"systemName": "production",
|
||
"systemType": "production",
|
||
"orgType": "S",
|
||
"loginType": "oauth2",
|
||
"clientId": "3MVG9...",
|
||
"username": "user@example.com",
|
||
"status": "0",
|
||
"sortOrder": 0,
|
||
"remark": "生产环境",
|
||
"createBy": "admin",
|
||
"createTime": "2026-01-22 10:00:00",
|
||
"updateBy": "admin",
|
||
"updateTime": "2026-01-22 10:00:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
- **错误响应示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "查询源 org 列表失败",
|
||
"data": null
|
||
}
|
||
```
|
||
- **状态码**：
|
||
| 状态码 | 描述 |
|
||
| ------ | ---- |
|
||
| 200 | 成功 |
|
||
| 401 | 未认证 |
|
||
| 403 | 无权限 |
|
||
| 500 | 服务器内部错误 |
|
||
- **注意事项**：
|
||
- 只返回 orgType 为 S（源 org）的系统配置
|
||
- 按 sortOrder 升序，createTime 降序排序
|
||
|
||
### 接口 9：查询目标 org 列表
|
||
- **请求方式**：GET
|
||
- **请求路径**：/api/salesforce/system/config/target
|
||
- **功能描述**：查询所有目标 org 列表
|
||
- **权限要求**：salesforce:system:config:list
|
||
- **请求参数**：无
|
||
- **请求体**：无
|
||
- **响应参数**：
|
||
| 参数名 | 类型 | 描述 |
|
||
| ------ | ---- | ---- |
|
||
| code | Integer | 响应码 |
|
||
| message | String | 响应信息 |
|
||
| data | Array | 响应数据 |
|
||
- **成功响应示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "查询成功",
|
||
"data": [
|
||
{
|
||
"id": 2,
|
||
"systemName": "sandbox",
|
||
"systemType": "sandbox",
|
||
"orgType": "T",
|
||
"loginType": "oauth2",
|
||
"clientId": "3MVG9...",
|
||
"username": "user@example.com",
|
||
"status": "0",
|
||
"sortOrder": 1,
|
||
"remark": "测试环境",
|
||
"createBy": "admin",
|
||
"createTime": "2026-01-22 10:00:00",
|
||
"updateBy": "admin",
|
||
"updateTime": "2026-01-22 10:00:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
- **错误响应示例**：
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "查询目标 org 列表失败",
|
||
"data": null
|
||
}
|
||
```
|
||
- **状态码**：
|
||
| 状态码 | 描述 |
|
||
| ------ | ---- |
|
||
| 200 | 成功 |
|
||
| 401 | 未认证 |
|
||
| 403 | 无权限 |
|
||
| 500 | 服务器内部错误 |
|
||
- **注意事项**：
|
||
- 只返回 orgType 为 T（目标 org）的系统配置
|
||
- 按 sortOrder 升序，createTime 降序排序
|
||
|
||
## 变更历史
|
||
| 版本 | 时间 | 变更内容 | 变更人 |
|
||
| ---- | ---- | -------- | ------ |
|
||
| 1.0.0 | 2026-01-22 | 初始版本 | SSOT 架构师 |
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/2026-01-21-003-01-salesforce-multi-system-config.md)
|
||
- [设计文档](../design/2026-01-21-003-01-salesforce-multi-system-config-design.md)
|
||
- [架构决策](../decisions/2026-01-21-003-01-ADR-salesforce-multi-system-config.md)
|
||
- [会话记录](../sessions/2026-01-21-003-01-session.md)
|
||
- [变更日志](../changelog/2026-01-21-003-01-changelog.md)
|
||
- [复盘文档](../retros/2026-01-21-003-01-retro.md)
|