齐鲁风云统一认证登录插件 (qlfy-ca-login)

简介

齐鲁风云统一认证登录插件是一个专为齐鲁风云项目内部使用的前端Vue组件插件，实现了与统一认证CA系统的无缝集成。该插件提供了完整的登录状态管理、token自动刷新、登录监听等功能，无需渲染任何UI元素，专注于登录逻辑处理。

核心特性

• 🔐 统一认证集成：完整支持齐鲁风云CA认证系统
• 🚀 无UI渲染：纯逻辑组件，不影响页面布局
• 🔄 自动token管理：支持token自动刷新和失效检测
• 📱 多模式支持：支持强制模式和非强制模式
• 🌐 路由兼容：支持hash和history路由模式
• 💾 智能存储：自动选择IndexedDB或LocalStorage存储
• ⚡ 单例模式：全局仅可使用一次，确保状态统一

安装

npm install qlfy-ca-login

快速开始

1. 注册：全局注册或局部进行导入

（1）在main.ts中注册插件

import { createApp } from 'vue'
import App from './App.vue'
import qlfyCaLogin from 'qlfy-ca-login'

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

（2）在app.vue中导入插件

<template>
  <!-- 页面内容 -->
    <RouterView v-if="!isLoading" />
</template>

<script setup lang="ts">
import { qlfyCaLogin } from 'qlfy-ca-login'
</script>

2. 在App.vue中使用组件

<template>
  <!-- 统一认证接入 -->
  <qlfyCaLogin
    client-id="your-client-id"
    client-secret="your-client-secret"
    entity-id="sdPLUGIN"
    client-name="系统名称"
    :use-router="useRouter()"
    login-page-base-address="http://sd.uts.cma:18010"
    login-service-base-address="http://10.76.91.87:28888"
    login-service-base-address-proxy="ca服务的代理字段"
    :force-mode="true"
    @logging-in="handleLoggingIn"
    @login-success="handleLoginSuccess"
    @login-fail="handleLoginFail"
  />

  <!-- 页面内容 -->
  <div class="app-container" v-loading="isLoading">
    <RouterView v-if="!isLoading" />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { RouterView, useRouter } from 'vue-router'
import { qlfyCaLogin, logout, goLogin, getToken, getLoginInfo } from 'qlfy-ca-login'

const isLoading = ref(true)

// 登录状态处理
const handleLoggingIn = (code: string, loginInfo?: any) => {
  console.log('正在登录...', { code, loginInfo })
  isLoading.value = true
}

const handleLoginSuccess = (loginInfo: any) => {
  console.log('登录成功', loginInfo)
  isLoading.value = false
  // 在此处理登录成功后的业务逻辑
}

const handleLoginFail = (failInfo: any) => {
  console.error('登录失败', failInfo)
  isLoading.value = false
  // 在此处理登录失败的业务逻辑
}
</script>

API 参考

组件属性 (Props)

| 属性名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | clientId | string | ✅ | - | 应用ID，由统一认证平台提供 | | clientSecret | string | ✅ | - | 应用密钥，由统一认证平台提供 | | loginPageBaseAddress | string | ✅ | - | CA登录页面基础地址例：http://sd.uts.cma:18010 | | loginServiceBaseAddress | string | ✅ | - | CA登录服务基础地址例：http://10.76.91.87:28888 | | loginServiceBaseAddressProxy | string | ❌ | - | CA登录服务基础地址代理字段如未配置或配置的字段无效则token刷新功能不可用例：/api该字段的代理地址为:http://10.76.91.87:28888 | | entityId | 'sdPLUGIN' \| 'multClient' | ✅ | - | 实体ID，内网使用sdPLUGIN，外网使用multClient | | useRouter | Router | ✅ | - | Vue Router实例，传入useRouter()的返回值 | | isCa | boolean | ❌ | false | 是否使用原生ca登陆默认为false，支持ca及备选登录模式的自动判断 | | clientName | string | ❌ | '' | 应用名称，用于权限验证 | | forceMode | boolean | ❌ | true | 强制模式，启用时自动跳转登录页 | | outLoginInfo | LoginInfo | ❌ | - | 外部登录信息，传入时直接使用该信息 | | isEnabled | boolean | ❌ | true | 是否启用组件，支持动态控制 | | listenToken | boolean | ❌ | false | 是否监听token状态变化 | | redirectPath | string | ❌ | '' | 登录成功后的重定向路径，默认为触发登陆的地址 |

组件事件 (Events)

| 事件名 | 参数 | 说明 | |--------|------|------| | loggingIn | (code: string, loginInfo?: any) | 开始登录验证时触发 | | loginSuccess | (loginInfo: LoginInfo) | 登录成功时触发 | | tokenRefresh | (loginInfo: LoginInfo) | token刷新时触发 | | loginFail | (failInfo: any) | 登录失败时触发 |

组件暴露方法

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

// 获取组件引用
const loginRef = ref<InstanceType<typeof qlfyCaLogin>>()

// 调用方法
await loginRef.value?.logout()        // 退出登录
await loginRef.value?.goLogin()       // 跳转登录页
const token = await loginRef.value?.getToken()      // 获取token
const info = await loginRef.value?.getLoginInfo()   // 获取登录信息

| 方法名 | 返回值 | 说明 | |--------|--------|------| | logout() | Promise<void> | 退出登录并跳转到CA认证页 | | goLogin() | Promise<void> | 跳转到CA认证页面 | | getToken() | Promise<string> | 获取当前访问token | | getLoginInfo() | Promise<LoginInfo> | 获取当前登录用户信息 |

工具方法

可在任意位置导入使用的工具方法：

import { logout, goLogin, getToken, getLoginInfo } from 'qlfy-ca-login'

// 使用示例
const handleLogout = async () => {
  await logout()
}

const getCurrentToken = async () => {
  const token = await getToken()
  console.log('当前token:', token)
}

| 方法名 | 返回值 | 说明 | |--------|--------|------| | logout() | Promise<void> | 全局退出登录方法 | | goLogin() | Promise<void> | 全局跳转登录方法 | | getToken() | Promise<string> | 全局获取token方法 | | getLoginInfo() | Promise<LoginInfo> | 全局获取登录信息方法 |

类型定义

LoginInfo 接口

interface LoginInfo {
  access_token: string      // 访问token
  refresh_token: string     // 刷新token
  account: string          // 账户名
  nick_name: string        // 昵称
  real_name: string        // 真实姓名
  role_name: string        // 角色名称
  role_id: string          // 角色ID
  user_id: string          // 用户ID
  user_name: string        // 用户名
  tenant_id: string        // 租户ID
  [key: string]: any       // 其他扩展字段
}

使用注意事项

1. 单例限制

• 组件在全局范围内只能使用一次
• 多次使用时，仅第一次使用有效
• 建议在App.vue中使用

2. 路由模式支持

• 自动检测并支持hash和history路由模式
• 自动处理登录回调时的URL参数清理

3. 存储策略

• 优先使用IndexedDB存储登录信息
• 不支持时自动降级到LocalStorage
• 支持跨标签页数据同步

4. 强制模式说明

• forceMode: true：登录失败时自动跳转到登录页
• forceMode: false：登录失败时仅触发事件，不自动跳转

5. Token管理

• 支持自动token刷新
• 支持token失效检测
• 支持实时token状态监听

常见问题

Q: 如何处理登录失败？

A: 监听loginFail事件，根据forceMode设置决定是否自动跳转登录页。

Q: 如何获取当前登录状态？

A: 使用getToken()或getLoginInfo()方法检查登录状态。

Q: 如何实现自动登录？

A: 组件会自动检查缓存的token并验证有效性，无需额外处理。

Q: 如何在多个页面间共享登录状态？

A: 组件使用统一的数据存储，登录状态在整个应用中自动共享。

更新日志

v1.1.0

• 插件内部数据管控机制重构，
  • 为减少对系统的干扰，插件优先使用indexDB数据库进行数据管理
• 插件部分冗余参数清除
  • tokenName、tokenValidity
• 新增对同ip端口的多个系统间的状态隔离机制

v1.1.1

• 插件声明文件缺失问题修复

v1.1.2

• 登陆逻辑变更，支持CA备选登陆模式
  • 跳转登录接口变更，修改为支持动态判断跳转的新接口
  • code使用逻辑变更，自动判断code类型，当为备选登陆的code时请求备选登陆接口获取登陆信息

v1.1.3

• 组件新增isCa参数，可选择使用兼容登陆或原生CA登陆模式，默认为兼容登陆模式

• 完善插件的token自动刷新功能

  • 完善刷新机制
  • token刷新成功触发tokenRefresh事件

v1.1.4

• 组件参数问题优化，增加登陆服务代理参数loginServiceBaseAddressProxy，处理token刷新操作
  • 因token刷新功能不允许跨域，所以如需token自动刷新功能，需手动诶之代理，并将代理字段传入

v1.1.5

• 接收外部登陆状态数据登录时的数据格式bug修复

v1.1.6

• 代理字段内部使用bug修复

v1.1.8

• 修复vue历史模式下重定向地址解析问题