# Salesforce 策略模式登录 API 文档

## 元数据
- 需求编号：2026-01-21-003-02
- 创建时间：2026-01-22
- 创建人：SSOT 架构师
- 版本：1.0.0

## API 概述
Salesforce 策略模式登录 API 提供了 Salesforce 系统登录的完整功能，支持四种登录策略（OAuth2 Password、OAuth2 Client Credentials、OAuth2 Authorization Code、Session ID），支持刷新令牌、登出、登录类型查询等功能。

## 基础信息
- API 名称：Salesforce 策略模式登录 API
- API 版本：1.0.0
- 描述：提供 Salesforce 系统登录功能，支持多种登录策略
- 认证方式：JWT Token
- 基础路径：/api/salesforce/auth

## 端点列表

### 接口 1：登录
- **请求方式**：POST
- **请求路径**：/api/salesforce/auth/login
- **功能描述**：使用指定的登录策略登录 Salesforce 系统
- **权限要求**：无
- **请求参数**：
  | 参数名 | 类型 | 必填 | 描述 | 示例值 |
  | ------ | ---- | ---- | ---- | ------ |
  | systemName | String | 是 | 系统名称 | production |
  | loginType | String | 是 | 登录类型（oauth2_password/oauth2_client_credentials/oauth2_authorization_code/session_id） | oauth2_password |
  | grantType | String | 否 | 授权类型（OAuth2 登录时必填） | password |
  | code | String | 否 | 授权码（OAuth2 Authorization Code 登录时必填） | auth_code_123 |
  | redirectUri | String | 否 | 重定向 URI（OAuth2 Authorization Code 登录时必填） | https://example.com/callback |
  | sessionId | String | 否 | Session ID（Session ID 登录时必填） | 00D... |
  | serverUrl | String | 否 | 服务器 URL（Session ID 登录时必填） | https://example.salesforce.com |

#### OAuth2 Password 登录请求体
```json
{
  "systemName": "production",
  "loginType": "oauth2_password",
  "grantType": "password"
}
```

#### OAuth2 Client Credentials 登录请求体
```json
{
  "systemName": "production",
  "loginType": "oauth2_client_credentials",
  "grantType": "client_credentials"
}
```

#### OAuth2 Authorization Code 登录请求体
```json
{
  "systemName": "production",
  "loginType": "oauth2_authorization_code",
  "grantType": "authorization_code",
  "code": "auth_code_123",
  "redirectUri": "https://example.com/callback"
}
```

#### Session ID 登录请求体
```json
{
  "systemName": "production",
  "loginType": "session_id",
  "sessionId": "00D...",
  "serverUrl": "https://example.salesforce.com"
}
```

- **响应参数**：
  | 参数名 | 类型 | 描述 |
  | ------ | ---- | ---- |
  | code | Integer | 响应码 |
  | message | String | 响应信息 |
  | data | Object | 响应数据 |
  | data.sessionId | String | 会话 ID |
  | data.serverUrl | String | 服务器 URL |
  | data.userInfo | Object | 用户信息 |
  | data.userInfo.userId | String | 用户 ID |
  | data.userInfo.username | String | 用户名 |
  | data.userInfo.orgId | String | 组织 ID |
  | data.userInfo.orgName | String | 组织名称 |

- **成功响应示例**：
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "sessionId": "00D...",
    "serverUrl": "https://example.salesforce.com",
    "userInfo": {
      "userId": "005...",
      "username": "user@example.com",
      "orgId": "00D...",
      "orgName": "Example Organization"
    }
  }
}
```

- **错误响应示例**：
```json
{
  "code": 500,
  "message": "登录失败: 系统配置不存在",
  "data": null
}
```

- **状态码**：
  | 状态码 | 描述 |
  | ------ | ---- |
  | 200 | 成功 |
  | 400 | 请求参数错误 |
  | 401 | 未认证 |
  | 403 | 无权限 |
  | 500 | 服务器内部错误 |

- **注意事项**：
  - OAuth2 登录成功后，登录信息会回写到 datai_sf_system_config 表
  - Session ID 登录不会回写到数据库
  - 系统配置必须存在且状态为正常

### 接口 2：刷新令牌
- **请求方式**：POST
- **请求路径**：/api/salesforce/auth/refresh-token
- **功能描述**：使用刷新令牌获取新的访问令牌
- **权限要求**：无
- **请求参数**：
  | 参数名 | 类型 | 必填 | 描述 | 示例值 |
  | ------ | ---- | ---- | ---- | ------ |
  | systemName | String | 是 | 系统名称 | production |
  | loginType | String | 是 | 登录类型 | oauth2_password |

- **请求体**：
```json
{
  "systemName": "production",
  "loginType": "oauth2_password"
}
```

- **响应参数**：
  | 参数名 | 类型 | 描述 |
  | ------ | ---- | ---- |
  | code | Integer | 响应码 |
  | message | String | 响应信息 |
  | data | Object | 响应数据 |
  | data.sessionId | String | 会话 ID |
  | data.serverUrl | String | 服务器 URL |

- **成功响应示例**：
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "sessionId": "00D...",
    "serverUrl": "https://example.salesforce.com"
  }
}
```

- **错误响应示例**：
```json
{
  "code": 500,
  "message": "刷新令牌失败: Session ID 登录不支持刷新令牌",
  "data": null
}
```

- **状态码**：
  | 状态码 | 描述 |
  | ------ | ---- |
  | 200 | 成功 |
  | 400 | 请求参数错误 |
  | 401 | 未认证 |
  | 403 | 无权限 |
  | 500 | 服务器内部错误 |

- **注意事项**：
  - 只有 OAuth2 登录支持刷新令牌
  - Session ID 登录不支持刷新令牌
  - 系统配置必须存在且状态为正常
  - 系统配置中必须有有效的 refresh_token

### 接口 3：登出
- **请求方式**：POST
- **请求路径**：/api/salesforce/auth/logout
- **功能描述**：登出 Salesforce 系统，清空登录信息
- **权限要求**：无
- **请求参数**：
  | 参数名 | 类型 | 必填 | 描述 | 示例值 |
  | ------ | ---- | ---- | ---- | ------ |
  | systemName | String | 是 | 系统名称 | production |
  | loginType | String | 是 | 登录类型 | oauth2_password |

- **请求体**：
```json
{
  "systemName": "production",
  "loginType": "oauth2_password"
}
```

- **响应参数**：
  | 参数名 | 类型 | 描述 |
  | ------ | ---- | ---- |
  | code | Integer | 响应码 |
  | message | String | 响应信息 |
  | data | Object | 响应数据 |

- **成功响应示例**：
```json
{
  "code": 200,
  "message": "操作成功",
  "data": null
}
```

- **错误响应示例**：
```json
{
  "code": 500,
  "message": "登出失败: 系统配置不存在",
  "data": null
}
```

- **状态码**：
  | 状态码 | 描述 |
  | ------ | ---- |
  | 200 | 成功 |
  | 400 | 请求参数错误 |
  | 401 | 未认证 |
  | 403 | 无权限 |
  | 500 | 服务器内部错误 |

- **注意事项**：
  - OAuth2 登录登出后，会清空 datai_sf_system_config 表中的登录信息
  - Session ID 登录登出后，不会清空数据库中的登录信息
  - 系统配置必须存在且状态为正常

### 接口 4：获取支持的登录类型
- **请求方式**：GET
- **请求路径**：/api/salesforce/auth/login-types
- **功能描述**：获取系统支持的所有登录类型
- **权限要求**：无
- **请求参数**：无

- **响应参数**：
  | 参数名 | 类型 | 描述 |
  | ------ | ---- | ---- |
  | code | Integer | 响应码 |
  | message | String | 响应信息 |
  | data | Array | 响应数据 |
  | data[].loginType | String | 登录类型 |
  | data[].loginTypeName | String | 登录类型名称 |
  | data[].description | String | 描述 |

- **成功响应示例**：
```json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "loginType": "oauth2_password",
      "loginTypeName": "OAuth2 Password 登录",
      "description": "使用用户名、密码、安全令牌进行登录"
    },
    {
      "loginType": "oauth2_client_credentials",
      "loginTypeName": "OAuth2 Client Credentials 登录",
      "description": "使用客户端凭证进行登录"
    },
    {
      "loginType": "oauth2_authorization_code",
      "loginTypeName": "OAuth2 Authorization Code 登录",
      "description": "使用授权码进行登录"
    },
    {
      "loginType": "session_id",
      "loginTypeName": "Session ID 登录",
      "description": "使用已有的 Session ID 进行登录"
    }
  ]
}
```

- **错误响应示例**：
```json
{
  "code": 500,
  "message": "服务器内部错误",
  "data": null
}
```

- **状态码**：
  | 状态码 | 描述 |
  | ------ | ---- |
  | 200 | 成功 |
  | 500 | 服务器内部错误 |

- **注意事项**：
  - 该接口不需要认证
  - 返回的登录类型列表是系统支持的所有登录类型

## 登录类型说明

### OAuth2 Password 登录
- **登录类型**：oauth2_password
- **授权类型**：password
- **描述**：使用用户名、密码、安全令牌进行登录
- **支持刷新令牌**：是
- **登录信息回写**：是
- **适用场景**：适用于有用户名、密码、安全令牌的场景

### OAuth2 Client Credentials 登录
- **登录类型**：oauth2_client_credentials
- **授权类型**：client_credentials
- **描述**：使用客户端凭证进行登录
- **支持刷新令牌**：是
- **登录信息回写**：是
- **适用场景**：适用于只有客户端凭证的场景

### OAuth2 Authorization Code 登录
- **登录类型**：oauth2_authorization_code
- **授权类型**：authorization_code
- **描述**：使用授权码进行登录
- **支持刷新令牌**：是
- **登录信息回写**：是
- **适用场景**：适用于需要用户授权的场景

### Session ID 登录
- **登录类型**：session_id
- **授权类型**：无
- **描述**：使用已有的 Session ID 进行登录
- **支持刷新令牌**：否
- **登录信息回写**：否
- **适用场景**：适用于已有 Session ID 的临时访问场景

## 错误码说明

| 错误码 | 错误信息 | 描述 |
| ------ | -------- | ---- |
| 200 | 操作成功 | 请求成功 |
| 400 | 请求参数错误 | 请求参数不正确 |
| 401 | 未认证 | 未进行身份认证 |
| 403 | 无权限 | 无权限访问该资源 |
| 500 | 服务器内部错误 | 服务器内部错误 |

## 使用示例

### 示例 1：OAuth2 Password 登录
```bash
curl -X POST http://localhost:8080/api/salesforce/auth/login \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "systemName": "production",
    "loginType": "oauth2_password",
    "grantType": "password"
  }'
```

### 示例 2：OAuth2 Client Credentials 登录
```bash
curl -X POST http://localhost:8080/api/salesforce/auth/login \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "systemName": "production",
    "loginType": "oauth2_client_credentials",
    "grantType": "client_credentials"
  }'
```

### 示例 3：OAuth2 Authorization Code 登录
```bash
curl -X POST http://localhost:8080/api/salesforce/auth/login \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "systemName": "production",
    "loginType": "oauth2_authorization_code",
    "grantType": "authorization_code",
    "code": "auth_code_123",
    "redirectUri": "https://example.com/callback"
  }'
```

### 示例 4：Session ID 登录
```bash
curl -X POST http://localhost:8080/api/salesforce/auth/login \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "systemName": "production",
    "loginType": "session_id",
    "sessionId": "00D...",
    "serverUrl": "https://example.salesforce.com"
  }'
```

### 示例 5：刷新令牌
```bash
curl -X POST http://localhost:8080/api/salesforce/auth/refresh-token \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "systemName": "production",
    "loginType": "oauth2_password"
  }'
```

### 示例 6：登出
```bash
curl -X POST http://localhost:8080/api/salesforce/auth/logout \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "systemName": "production",
    "loginType": "oauth2_password"
  }'
```

### 示例 7：获取支持的登录类型
```bash
curl -X GET http://localhost:8080/api/salesforce/auth/login-types \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## 相关文档
- [需求文档](../requirements/2026-01-21-003-02-salesforce-strategy-login.md)
- [设计文档](../design/2026-01-21-003-02-salesforce-strategy-login-design.md)
- [架构决策](../decisions/2026-01-21-003-02-ADR-salesforce-strategy-login.md)
- [数据库文档](../sql/2026-01-21-003-02-salesforce-strategy-login-database.md)
- [代码生成提示词](../prompts/2026-01-21-003-02-salesforce-strategy-login代码生成提示词.md)
- [会话记录](../sessions/2026-01-21-003-02-session.md)
- [变更日志](../changelog/2026-01-21-003-02-changelog.md)
- [复盘文档](../retros/2026-01-21-003-02-retro.md)