kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
refactor-20260121
datai/docs/api-docs/2026-01-21-003-01-api.md

561 lines
16 KiB
Markdown
Raw Permalink Normal View History

【feat】 提交被忽略代码
2026-01-22 10:52:30 +08:00
# 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)
Reference in New Issue Copy Permalink