qlfy-ecological-login

山东生态统一登录Vue3组件 - 提供完整的OAuth2统一认证解决方案

简介

qlfy-ecological-login 是一个专为山东生态系统设计的Vue3统一登录组件，基于OAuth2协议实现，提供了完整的用户认证流程管理。该组件支持自动token管理、权限获取、登录状态监听等功能，可以快速集成到Vue3项目中。

特性

• 🔐 OAuth2认证 - 基于标准OAuth2协议的统一登录
• 🚀 Vue3支持 - 完全基于Vue3 Composition API开发
• 📦 TypeScript - 完整的TypeScript类型支持
• 🔄 自动Token管理 - 自动处理token存储和校验
• 👥 权限管理 - 获取和管理用户权限信息
• 🎯 灵活配置 - 支持多种配置模式和自定义参数
• ️ 安全可靠 - 内置安全机制和错误处理
• 📝 日志调试 - 支持开启日志和调试模式

安装

npm install qlfy-ecological-login

快速开始

1. 全局注册

import { createApp } from 'vue'
import App from './App.vue'
import qlfyEcologicalLogin from 'qlfy-ecological-login'

const app = createApp(App)
app.use(qlfyEcologicalLogin)
app.mount('#app')

2. 组件使用

<template>
  <div>
    <!-- 统一登录组件 -->
    <qlfy-ecological-login
      :client-id="clientId"
      :client-secret="clientSecret"
      login-page-base-address="https://sdocen.weathermate.cn:15029/auth"
      login-service-base-address="http://10.76.34.53:48080"
      :use-router="router"
      :show-log="true"
      @login-success="handleLoginSuccess"
      @login-fail="handleLoginFail"
      @logging-in="handleLoggingIn"
    />
    
    <!-- 你的应用内容 -->
    <router-view />
  </div>
</template>

<script setup>
import { useRouter } from 'vue-router'

const router = useRouter()

// 配置参数
const clientId = 'your-client-id'
const clientSecret = 'your-client-secret'

// 事件处理
const handleLoginSuccess = (loginInfo) => {
  console.log('登录成功:', loginInfo)
}

const handleLoginFail = (error) => {
  console.log('登录失败:', error)
}

const handleLoggingIn = (token) => {
  console.log('正在登录:', token)
}
</script>

API 文档

组件属性 (Props)

| 属性名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | clientId | string | ✅ | - | 应用ID，由平台提供 | | clientSecret | string | ✅ | - | 应用密钥，由平台提供 | | loginPageBaseAddress | string | ✅ | - | 统一登录页面的基础地址 | | loginServiceBaseAddress | string | ✅ | - | 登录服务的基础地址 | | useRouter | Router | ✅ | - | Vue Router实例 | | forceMode | boolean | ❌ | true | 强制登录模式 | | clientName | string | ❌ | - | 应用名称 | | token | string | ❌ | - | 外部传入的token | | isEnabled | boolean | ❌ | true | 是否启用组件，支持动态控制 | | redirectPath | string | ❌ | '' | 认证成功后的重定向路径 | | tenantId | number \| string | ❌ | 168 | 租户ID | | showLog | boolean | ❌ | false | 是否显示执行日志 | | openDebugger | boolean | ❌ | false | 是否开启调试模式 |

组件事件 (Events)

| 事件名 | 参数 | 说明 | |--------|------|------| | loggingIn | (code: String, loginInfo?: any) | 正在登录时触发 | | loginSuccess | (loginInfo: { [x: string]: any } \| null) | 登录成功时触发 | | loginFail | (failInfo: any) | 登录失败时触发 | | tokenRefresh | (loginInfo: { [x: string]: any } \| null) | Token刷新时触发 |

事件触发机制详解

1. loggingIn 事件

• 触发时机: 组件初始化加载或路由变化时检测到token
• 触发条件: 可从插件参数、url或缓存中获取到token
• 参数说明: 当前获取到的token值
• 使用场景: 显示登录加载状态

2. loginSuccess 事件

• 触发时机: 插件首次完成完整登录流程后，包括token验证和用户权限获取
• 触发条件:
  • token验证通过
  • 用户权限信息获取成功
• 参数说明: 包含用户权限和配置信息的完整对象
• 使用场景: 保存用户信息到全局状态，初始化应用权限

3. loginFail 事件

• 触发时机: 登录流程中任何步骤失败时
• 触发条件:
  • Token验证失败
  • 用户权限获取失败
  • 网络请求异常
  • 在非强制模式下无有效token时
• 参数说明: 包含错误信息的对象
• 使用场景: 显示错误提示，记录错误日志

组件方法 (Exposed Methods)

通过组件ref可以调用以下方法：

// 获取组件实例
const loginRef = ref()

// 退出登录
await loginRef.value.logout()

// 获取当前token
const token = await loginRef.value.getToken()

// 获取登录信息
const loginInfo = await loginRef.value.getLoginInfo()

// 跳转到统一登录页面
await loginRef.value.goLogin()

全局工具函数

组件还提供了一系列全局工具函数，可以在应用的任何地方使用：

import { 
  logout, 
  goLogin, 
  getToken, 
  getRefreshToken, 
  getUserPermission 
} from 'qlfy-ecological-login'

// 退出登录
// isGoLog: 是否跳转到登录页，默认为true
// success: 成功回调
// error: 失败回调
logout(true, 
  (res) => console.log('退出成功', res),
  (err) => console.log('退出失败', err)
)

// 跳转到登录页
goLogin()

// 获取当前token (Promise)
getToken().then(token => {
  console.log('Token:', token)
})

// 获取刷新token (Promise)
getRefreshToken().then(refreshToken => {
  console.log('RefreshToken:', refreshToken)
})

// 获取用户权限信息 (Promise)
getUserPermission().then(permissions => {
  console.log('Permissions:', permissions)
})

登录流程

组件实现了完整的OAuth2登录流程：

1. 初始化检查 - 检查组件是否启用
2. Token优先级 - 按优先级检查token来源：
   • 外部传入的token（最高优先级）
   • URL参数中的token（从登录页返回）
   • 本地缓存的token
3. Token验证 - 调用后端接口验证token有效性
4. 用户信息获取 - 获取用户权限和配置信息
5. 状态管理 - 管理登录状态和token生命周期
6. 路由拦截 - 根据登录状态和强制模式进行路由拦截

注意事项

1. 路由依赖 - 组件依赖Vue Router，请确保正确传入router实例，且路由模式（Hash/History）会自动检测。
2. 数据存储 - 组件内置了IndexedDB和LocalStorage的数据存储管理器，自动处理跨域和存储限制。
3. 安全性 - 请妥善保管clientId和clientSecret。
4. 跨域问题 - 请确保登录服务支持跨域请求或配置代理。

许可证

MIT License