# 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)