datai-vue/doc/salesforce/SalesforceLoginControllerAPI.md

# SalesforceLoginController 方法调用说明文档

## 1. 概述

SalesforceLoginController提供了一套完整的Salesforce登录相关API，支持多种登录方式，包括用户名密码登录、JWT登录、客户端凭证登录和OAuth登录。

## 2. API基础信息

- 基础URL: `/salesforce/login`
- 请求格式: JSON (POST请求)
- 响应格式: JSON
- 统一响应格式: 
  ```json
  {
    "code": 200,          // 响应状态码
    "msg": "Success",      // 响应消息
    "data": {}            // 响应数据
  }
  ```

## 3. 详细方法说明

### 3.1 登录Salesforce

**方法名称**: `login`

**HTTP请求**: `POST /salesforce/login/login`

**功能说明**: 支持多种登录方式，根据loginType动态选择

**请求参数**:

| 参数名 | 类型 | 必须 | 说明 | 示例值 |
|--------|------|------|------|--------|
| loginType | String | 是 | 登录类型，可选值：password, jwt, client_credentials, oauth | "password" |
| username | String | 否 | 用户名，password和jwt登录方式必填 | "user@example.com" |
| password | String | 否 | 密码，password登录方式必填 | "password123" |
| securityToken | String | 否 | 安全令牌，password登录方式可选 | "SECURITY_TOKEN" |
| clientId | String | 否 | 客户端ID，jwt和client_credentials登录方式必填 | "CLIENT_ID" |
| clientSecret | String | 否 | 客户端密钥，client_credentials登录方式必填 | "CLIENT_SECRET" |
| jwtToken | String | 否 | JWT令牌，jwt登录方式可选 | "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." |
| privateKeyPath | String | 否 | 私钥路径，jwt登录方式可选 | "/path/to/private.key" |
| privateKeyPassword | String | 否 | 私钥密码，jwt登录方式可选 | "KEY_PASSWORD" |
| environment | String | 否 | 环境类型，可选值：production, sandbox, custom，默认production | "production" |
| customDomain | String | 否 | 自定义域名，environment为custom时必填 | "custom.salesforce.com" |

**响应示例**:

```json
{
  "code": 200,
  "msg": "Login successful",
  "data": {
    "accessToken": "00D5f0000000001!AQwAQG...",
    "instanceUrl": "https://na152.salesforce.com",
    "idToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "5Aep861q6x...",
    "expiresAt": "2025-12-10T12:00:00",
    "success": true,
    "loginType": "password",
    "username": "user@example.com"
  }
}
```

**调用示例**:

```javascript
// 用户名密码登录
fetch('/salesforce/login/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    loginType: 'password',
    username: 'user@example.com',
    password: 'password123',
    environment: 'production'
  })
})
.then(response => response.json())
.then(data => console.log(data));
```

### 3.2 刷新访问令牌

**方法名称**: `refreshToken`

**HTTP请求**: `POST /salesforce/login/refresh-token`

**功能说明**: 根据登录类型刷新访问令牌

**请求参数**:

| 参数名 | 类型 | 必须 | 说明 | 示例值 |
|--------|------|------|------|--------|
| refreshToken | String | 是 | 刷新令牌 | "5Aep861q6x..." |
| loginType | String | 是 | 登录类型 | "password" |

**响应示例**:

```json
{
  "code": 200,
  "msg": "Token refreshed successfully",
  "data": {
    "accessToken": "00D5f0000000001!AQwAQG...",
    "instanceUrl": "https://na152.salesforce.com",
    "expiresAt": "2025-12-10T12:00:00",
    "success": true,
    "loginType": "password"
  }
}
```

**调用示例**:

```javascript
fetch('/salesforce/login/refresh-token?refreshToken=5Aep861q6x...&loginType=password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));
```

### 3.3 登出Salesforce

**方法名称**: `logout`

**HTTP请求**: `POST /salesforce/login/logout`

**功能说明**: 登出并清除登录状态

**请求参数**:

| 参数名 | 类型 | 必须 | 说明 | 示例值 |
|--------|------|------|------|--------|
| accessToken | String | 是 | 访问令牌 | "00D5f0000000001!AQwAQG..." |
| loginType | String | 是 | 登录类型 | "password" |

**响应示例**:

```json
{
  "code": 200,
  "msg": "Logout successful",
  "data": null
}
```

**调用示例**:

```javascript
fetch('/salesforce/login/logout?accessToken=00D5f0000000001!AQwAQG...&loginType=password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));
```

### 3.4 获取当前登录状态

**方法名称**: `getLoginStatus`

**HTTP请求**: `GET /salesforce/login/status`

**功能说明**: 获取当前的登录状态信息

**请求参数**: 无

**响应示例**:

```json
{
  "code": 200,
  "msg": "Login status retrieved",
  "data": {
    "accessToken": "00D5f0000000001!AQwAQG...",
    "instanceUrl": "https://na152.salesforce.com",
    "loginType": "password",
    "username": "user@example.com",
    "success": true,
    "sessionValid": true
  }
}
```

**调用示例**:

```javascript
fetch('/salesforce/login/status', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));
```

### 3.5 清除登录状态

**方法名称**: `clearLoginStatus`

**HTTP请求**: `POST /salesforce/login/clear-status`

**功能说明**: 清除当前的登录状态信息

**请求参数**: 无

**响应示例**:

```json
{
  "code": 200,
  "msg": "Login status cleared successfully",
  "data": null
}
```

**调用示例**:

```javascript
fetch('/salesforce/login/clear-status', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));
```

### 3.6 获取支持的登录类型

**方法名称**: `getSupportedLoginTypes`

**HTTP请求**: `GET /salesforce/login/supported-types`

**功能说明**: 获取系统支持的所有登录方式类型

**请求参数**: 无

**响应示例**:

```json
{
  "code": 200,
  "msg": "Supported login types retrieved",
  "data": ["password", "jwt", "client_credentials", "oauth"]
}
```

**调用示例**:

```javascript
fetch('/salesforce/login/supported-types', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));
```

### 3.7 验证会话有效性

**方法名称**: `validateSession`

**HTTP请求**: `GET /salesforce/login/validate-session`

**功能说明**: 验证当前会话是否有效

**请求参数**: 无

**响应示例**:

```json
{
  "code": 200,
  "msg": "Session is valid",
  "data": {
    "accessToken": "00D5f0000000001!AQwAQG...",
    "instanceUrl": "https://na152.salesforce.com",
    "loginType": "password",
    "username": "user@example.com",
    "success": true,
    "sessionValid": true
  }
}
```

**调用示例**:

```javascript
fetch('/salesforce/login/validate-session', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));
```

## 4. 前端调用最佳实践

### 4.1 登录流程

1. 获取支持的登录类型：`GET /salesforce/login/supported-types`
2. 根据用户选择的登录方式，构建相应的登录请求
3. 调用登录接口：`POST /salesforce/login/login`
4. 保存登录结果中的accessToken和refreshToken
5. 定期调用会话验证接口：`GET /salesforce/login/validate-session`
6. 当token过期时，调用刷新token接口：`POST /salesforce/login/refresh-token`
7. 用户登出时，调用登出接口：`POST /salesforce/login/logout`

### 4.2 错误处理

- 检查响应的code字段，非200表示错误
- 处理常见错误：
  - 401 Unauthorized：登录信息无效
  - 403 Forbidden：权限不足
  - 500 Internal Server Error：服务器内部错误
  - 503 Service Unavailable：服务不可用

### 4.3 安全建议

- 敏感信息（如密码、token）不要明文存储在前端
- 使用HTTPS协议传输所有请求
- 定期更新token，避免token过期
- 登出时确保清除所有本地存储的token信息

## 5. 示例代码

### 5.1 登录示例（Vue 3）

```vue
<template>
  <div>
    <h1>Salesforce Login</h1>
    <div>
      <label for="loginType">Login Type:</label>
      <select v-model="loginType">
        <option value="password">Password</option>
        <option value="jwt">JWT</option>
        <option value="client_credentials">Client Credentials</option>
      </select>
    </div>
    
    <div v-if="loginType === 'password'">
      <div>
        <label for="username">Username:</label>
        <input type="text" v-model="username" />
      </div>
      <div>
        <label for="password">Password:</label>
        <input type="password" v-model="password" />
      </div>
    </div>
    
    <button @click="login">Login</button>
    <div v-if="error" class="error">{{ error }}</div>
    <div v-if="success" class="success">{{ success }}</div>
  </div>
</template>

<script setup>
import { ref } from 'vue';

const loginType = ref('password');
const username = ref('');
const password = ref('');
const error = ref('');
const success = ref('');

const login = async () => {
  try {
    const response = await fetch('/salesforce/login/login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        loginType: loginType.value,
        username: username.value,
        password: password.value
      })
    });
    
    const data = await response.json();
    
    if (data.code === 200) {
      success.value = 'Login successful';
      error.value = '';
      // 保存token等信息
      localStorage.setItem('salesforceAccessToken', data.data.accessToken);
      localStorage.setItem('salesforceRefreshToken', data.data.refreshToken);
    } else {
      error.value = data.msg;
      success.value = '';
    }
  } catch (err) {
    error.value = 'Login failed: ' + err.message;
    success.value = '';
  }
};
</script>
```

### 5.2 会话验证示例（React）

```javascript
import React, { useEffect, useState } from 'react';

const SessionValidator = () => {
  const [sessionValid, setSessionValid] = useState(false);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const validateSession = async () => {
      try {
        const response = await fetch('/salesforce/login/validate-session', {
          method: 'GET',
          headers: {
            'Content-Type': 'application/json'
          }
        });
        
        const data = await response.json();
        setSessionValid(data.code === 200 && data.data.sessionValid);
      } catch (err) {
        setSessionValid(false);
      } finally {
        setLoading(false);
      }
    };

    validateSession();
    // 每5分钟验证一次会话
    const interval = setInterval(validateSession, 5 * 60 * 1000);
    
    return () => clearInterval(interval);
  }, []);

  if (loading) {
    return <div>Checking session...</div>;
  }

  return (
    <div>
      <h2>Session Status: {sessionValid ? 'Valid' : 'Invalid'}</h2>
      {!sessionValid && (
        <button onClick={() => window.location.href = '/login'}>
          Login Again
        </button>
      )}
    </div>
  );
};

export default SessionValidator;
```

## 6. 常见问题

### 6.1 如何选择合适的登录方式？

- **password登录**：适用于开发测试环境，需要用户名和密码
- **jwt登录**：适用于机器到机器的集成，安全性较高
- **client_credentials登录**：适用于服务器到服务器的集成
- **oauth登录**：适用于第三方应用集成，支持授权码流程

### 6.2 token过期怎么办？

当token过期时，系统会自动检测并返回sessionValid: false，此时需要：
1. 调用`POST /salesforce/login/refresh-token`接口刷新token
2. 如果刷新失败，需要重新登录

### 6.3 如何获取当前登录用户信息？

调用`GET /salesforce/login/status`接口，响应中包含username和其他用户信息

### 6.4 如何处理不同环境？

通过environment参数指定环境类型：
- production：生产环境
- sandbox：沙盒环境
- custom：自定义环境，需要同时提供customDomain参数

## 7. 版本说明

- 当前版本：1.0.0
- 支持的Salesforce API版本：61.0.0

## 8. 联系方式

如有问题，请联系系统管理员或开发团队。