kris/datai-vue

Fork 0

Kris 39b80c307a 【feat】优化时间组件样式

2025-12-14 18:16:08 +08:00

12 KiB

Raw Blame History

SalesforceLoginController 方法调用说明文档

1. 概述

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

2. API基础信息

基础URL: /salesforce/login
请求格式: JSON (POST请求)
响应格式: 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"

响应示例:

{
  "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"
  }
}

调用示例:

// 用户名密码登录
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"

响应示例:

{
  "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"
  }
}

调用示例:

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"

响应示例:

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

调用示例:

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

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

请求参数: 无

响应示例:

{
  "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
  }
}

调用示例:

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

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

请求参数: 无

响应示例:

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

调用示例:

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

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

请求参数: 无

响应示例:

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

调用示例:

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

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

请求参数: 无

响应示例:

{
  "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
  }
}

调用示例:

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

4. 前端调用最佳实践

4.1 登录流程

获取支持的登录类型：GET /salesforce/login/supported-types
根据用户选择的登录方式，构建相应的登录请求
调用登录接口：POST /salesforce/login/login
保存登录结果中的accessToken和refreshToken
定期调用会话验证接口：GET /salesforce/login/validate-session
当token过期时，调用刷新token接口：POST /salesforce/login/refresh-token
用户登出时，调用登出接口：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）

<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）

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，此时需要：

调用POST /salesforce/login/refresh-token接口刷新token
如果刷新失败，需要重新登录

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

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

6.4 如何处理不同环境？

通过environment参数指定环境类型：

production：生产环境
sandbox：沙盒环境
custom：自定义环境，需要同时提供customDomain参数

7. 版本说明

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

8. 联系方式

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

12 KiB Raw Blame History Unescape Escape

SalesforceLoginController 方法调用说明文档

1. 概述

2. API基础信息

3. 详细方法说明

3.1 登录Salesforce

3.2 刷新访问令牌

3.3 登出Salesforce

3.4 获取当前登录状态

3.5 清除登录状态

3.6 获取支持的登录类型

3.7 验证会话有效性

4. 前端调用最佳实践

4.1 登录流程

4.2 错误处理

4.3 安全建议

5. 示例代码

5.1 登录示例（Vue 3）

5.2 会话验证示例（React）

6. 常见问题

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

6.2 token过期怎么办？

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

6.4 如何处理不同环境？

7. 版本说明

8. 联系方式

12 KiB

Raw Blame History