@czxingyu/feishu-auth-vue 0.1.0

package/README.md

@@ -0,0 +1,240 @@
+# @czxingyu/feishu-auth-vue
+
+飞书登录 + JWT + 三角色 RBAC 的 Vue 前端 npm 包,与后端 `feishu-auth-spring-boot-starter`
+或同契约的后端配套使用。
+
+它提供新项目接飞书登录时最常重复写的部分:token 存取、飞书 OAuth 登录链路、认证 API、
+axios 请求认证拦截、登录态路由守卫、角色门控、Pinia 用户 store 工厂、开发切号工具。
+菜单白名单、业务错误 toast、zod 响应校验、业务扩展字段仍留在各 app 自己实现。
+
+## 安装
+
+发布后新项目前端直接安装:
+
+```bash
+npm install @czxingyu/feishu-auth-vue
+```
+
+或使用 pnpm:
+
+```bash
+pnpm add @czxingyu/feishu-auth-vue
+```
+
+包已经构建为 `dist` 产物,消费方不需要把它排除出 Vite 预构建,也不需要编译它的源码。
+
+Peer 依赖:
+
+```bash
+npm install vue vue-router pinia
+```
+
+`axios` 只有使用 `createAuthRequestInterceptor` 时需要。
+
+## 后端契约
+
+默认端点与 `feishu-auth-spring-boot-starter` 对齐:
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | `/fs/get_authorizeUrl_v1` | 返回飞书授权 URL |
+| POST | `/fsLogin?code=xxx` | 飞书 code 换 JWT |
+| GET | `/getFsInfo` | 当前登录用户信息 |
+| POST | `/dev/switchUserByUnionId` | 开发/超管切号 |
+
+成功响应码兼容 `code: 200` 和 `code: 0`,方便新旧后端共用同一个前端包。
+
+## 新项目最小接入
+
+### 1. 配置 token
+
+```ts
+// src/auth/token.ts
+import { createTokenStore } from '@czxingyu/feishu-auth-vue/token'
+
+export const tokens = createTokenStore({
+  tokenKey: 'MY_APP_TOKEN',
+  usernameKey: 'MY_APP_USERNAME',
+})
+```
+
+### 2. 配置请求实例
+
+```ts
+// src/api/request.ts
+import axios from 'axios'
+import {
+  createAuthRequestInterceptor,
+  isAuthFailureBody,
+  redirectToLogin,
+} from '@czxingyu/feishu-auth-vue/http'
+import { tokens } from '@/auth/token'
+
+export const request = axios.create({ baseURL: '/api' })
+
+request.interceptors.request.use(
+  createAuthRequestInterceptor({ getToken: tokens.getToken }),
+)
+
+request.interceptors.response.use(
+  (response) => {
+    if (isAuthFailureBody(response.data)) {
+      return redirectToLogin({ clearAuth: tokens.clearAuth })
+    }
+    return response.data
+  },
+  (error) => {
+    if (error.response?.status === 401) {
+      return redirectToLogin({ clearAuth: tokens.clearAuth })
+    }
+    return Promise.reject(error)
+  },
+)
+```
+
+### 3. 创建认证 API
+
+```ts
+// src/api/auth.ts
+import { createAuthApi } from '@czxingyu/feishu-auth-vue/api'
+import { request } from './request'
+
+export const authApi = createAuthApi(request)
+```
+
+端点不同可以覆盖:
+
+```ts
+createAuthApi(request, {
+  endpoints: {
+    fsInfo: '/api/me',
+  },
+})
+```
+
+### 4. 登录页
+
+```vue
+<script setup lang="ts">
+import { useFeishuLogin } from '@czxingyu/feishu-auth-vue/useFeishuLogin'
+import { authApi } from '@/api/auth'
+import { tokens } from '@/auth/token'
+
+const { status, tip } = useFeishuLogin({
+  api: authApi,
+  tokens,
+  defaultRedirect: '/',
+})
+</script>
+
+<template>
+  <main>
+    <p :data-status="status">{{ tip.message }}</p>
+  </main>
+</template>
+```
+
+登录页会自动完成:
+
+1. 无 `code` 时请求 `/fs/get_authorizeUrl_v1` 并跳转飞书。
+2. 飞书回调带 `code` 时调用 `/fsLogin?code=xxx`。
+3. 成功写入 token。
+4. 回跳 `redirect` 指向的站内路径。
+
+`redirect` 会被安全归一化,外部地址、`//evil.com`、坏百分号编码都会回落到 `defaultRedirect`。
+
+### 5. 路由守卫
+
+```ts
+import { getLoginRedirect, getPublicOnlyRedirect } from '@czxingyu/feishu-auth-vue/guard'
+import { tokens } from '@/auth/token'
+
+router.beforeEach((to) => {
+  if (to.path === '/login') {
+    return getPublicOnlyRedirect({ isLogin: tokens.isLogin, query: to.query })
+  }
+
+  const redirect = getLoginRedirect({
+    isLogin: tokens.isLogin,
+    pathname: to.path,
+    search: location.search,
+  })
+  if (redirect) return redirect
+
+  return true
+})
+```
+
+### 6. 当前用户 store
+
+```ts
+import { defineAuthUserStore } from '@czxingyu/feishu-auth-vue/store'
+import type { AuthUserInfo } from '@czxingyu/feishu-auth-vue'
+
+export const useUserInfoStore = defineAuthUserStore<AuthUserInfo>('userInfo', () => ({
+  id: null,
+  userId: null,
+  name: null,
+  unionId: null,
+  avatar: null,
+  employeeNo: null,
+  isExist: null,
+  roleLevel: null,
+}))
+```
+
+角色门控:
+
+```ts
+import { isAdmin, isSuperAdmin } from '@czxingyu/feishu-auth-vue/roles'
+
+isAdmin(user.roleLevel)
+isSuperAdmin(user.roleLevel)
+```
+
+### 7. 开发切号
+
+```ts
+import { useUserSwitch } from '@czxingyu/feishu-auth-vue/useUserSwitch'
+import { authApi } from '@/api/auth'
+import { tokens } from '@/auth/token'
+
+const { switching, switchTo } = useUserSwitch({ api: authApi, tokens })
+```
+
+准入由后端控制。开发环境可以放行,生产环境建议仅超管允许。
+
+## 子入口
+
+推荐新项目按需从子入口导入,这样依赖边界更清楚:
+
+```ts
+import { createTokenStore } from '@czxingyu/feishu-auth-vue/token'
+import { createAuthApi } from '@czxingyu/feishu-auth-vue/api'
+import { useFeishuLogin } from '@czxingyu/feishu-auth-vue/useFeishuLogin'
+```
+
+根入口也可用:
+
+```ts
+import { createTokenStore, useFeishuLogin } from '@czxingyu/feishu-auth-vue'
+```
+
+## 包维护
+
+```bash
+pnpm install
+pnpm test
+pnpm run type-check
+pnpm run build
+npm pack --dry-run
+```
+
+发布到 npm:
+
+```bash
+npm login
+npm publish --access public
+```
+
+如果发布到公司私有 npm registry,请在项目或 CI 中配置对应 registry 后再 `npm publish`。

package/dist/api.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 认证相关 API 封装。给定一个「请求实例」(响应已解包成 body),
+ * 返回绑定到后端标准登录端点的方法集。端点路径可覆盖。
+ *
+ * 默认端点与 feishu-auth-spring-boot-starter 的 Controller 对齐:
+ *   - /fsLogin?code=xxx                 POST  飞书 code 换 token
+ *   - /getFsInfo                        GET   当前登录用户信息
+ *   - /fs/get_authorizeUrl_v1           GET   飞书授权跳转地址
+ *   - /dev/switchUserByUnionId          POST  按 unionId 切号
+ */
+import type { ApiEnvelope, AuthRequest, AuthUserInfo, FsLoginResult } from './types';
+export interface AuthEndpoints {
+    fsLogin: string;
+    fsInfo: string;
+    authorizeUrl: string;
+    devSwitch: string;
+}
+declare const DEFAULT_ENDPOINTS: AuthEndpoints;
+export interface AuthApi {
+    /** 飞书授权码换 token。 */
+    fsLogin(code: string): Promise<FsLoginResult>;
+    /** 当前登录用户信息。U 默认 AuthUserInfo,可传系统扩展后的用户类型。 */
+    getFsInfo<U = AuthUserInfo>(): Promise<ApiEnvelope<U>>;
+    /** 飞书授权跳转地址。 */
+    getAuthorizeUrl(): Promise<ApiEnvelope<string>>;
+    /** 按 unionId 切号(后端按 dev/超管准入)。 */
+    devSwitchUser(unionId: string): Promise<FsLoginResult>;
+}
+export interface CreateAuthApiOptions {
+    /** 覆盖部分端点路径。 */
+    endpoints?: Partial<AuthEndpoints>;
+}
+export declare function createAuthApi(request: AuthRequest, options?: CreateAuthApiOptions): AuthApi;
+/**
+ * 从登录/切号返回壳里提取 token。兼容三种结构:
+ *   { token }              顶层(后端 FsLoginResponse)
+ *   { data: "<token>" }    data 直接是字符串
+ *   { data: { token } }    data 里嵌 token
+ */
+export declare function extractLoginToken(res: FsLoginResult | undefined | null): string | undefined;
+export { DEFAULT_ENDPOINTS };

package/dist/api.js

@@ -0,0 +1,30 @@
+const i = {
+  fsLogin: "/fsLogin",
+  fsInfo: "/getFsInfo",
+  authorizeUrl: "/fs/get_authorizeUrl_v1",
+  devSwitch: "/dev/switchUserByUnionId"
+};
+function r(o, t = {}) {
+  const n = { ...i, ...t.endpoints };
+  return {
+    fsLogin: (e) => o.post(`${n.fsLogin}?code=${encodeURIComponent(e)}`, {}),
+    getFsInfo: () => o.get(n.fsInfo),
+    getAuthorizeUrl: () => o.get(n.authorizeUrl),
+    devSwitchUser: (e) => o.post(n.devSwitch, { unionId: e })
+  };
+}
+function f(o) {
+  if (!o) return;
+  const t = o;
+  if (typeof t.data == "string") return t.data;
+  if (t.data && typeof t.data == "object") {
+    const n = t.data.token;
+    if (typeof n == "string") return n;
+  }
+  if (typeof t.token == "string") return t.token;
+}
+export {
+  i as DEFAULT_ENDPOINTS,
+  r as createAuthApi,
+  f as extractLoginToken
+};

package/dist/guard.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 路由守卫助手——只负责通用的「登录态」判断:
+ *   - 未登录 → 跳登录页(带 redirect 回跳)
+ *   - 已登录 → 放行
+ *
+ * 菜单白名单这类「系统专属」的权限校验不在这里,留给各 app 自己实现
+ * (与后端把 SecurityFilterChain 留给使用方同理)。
+ */
+export interface LoginRedirectOptions {
+    /** 是否已登录(通常传 tokenStore.isLogin)。 */
+    isLogin: () => boolean;
+    /** 当前路径(不含 query),如 route.path / location.pathname。 */
+    pathname: string;
+    /** 当前 query 串(以 ? 开头或空串),如 location.search。 */
+    search: string;
+    /** 登录页路径,默认 /login。 */
+    loginPath?: string;
+}
+/**
+ * 权限守卫的「登录态」部分:
+ *  - 未登录且 URL 带飞书回调 code → 跳 `${loginPath}${search}`(让登录页消费 code)
+ *  - 未登录且无 code → 跳 `${loginPath}?redirect=<当前路径>`
+ *  - 已登录 → 返回 null(放行,后续菜单/业务校验由 app 自己接)
+ */
+export declare function getLoginRedirect(options: LoginRedirectOptions): string | null;
+export interface PublicOnlyRedirectOptions {
+    isLogin: () => boolean;
+    /** 当前路由 query;带 code(飞书回调)时即使已登录也放行。 */
+    query?: Record<string, unknown>;
+    /** 已登录时重定向到的首页,默认 /。 */
+    home?: string;
+}
+/**
+ * 「仅未登录可访问」守卫(用于登录页):
+ *  - 带飞书回调 code → null(放行,确保 code 能被换 token)
+ *  - 已登录 → 返回首页路径
+ *  - 未登录 → null(放行)
+ */
+export declare function getPublicOnlyRedirect(options: PublicOnlyRedirectOptions): string | null;

package/dist/guard.js

@@ -0,0 +1,14 @@
+function t(e) {
+  const r = e.loginPath ?? "/login";
+  if (e.isLogin()) return null;
+  if (new URLSearchParams(e.search).get("code")) return `${r}${e.search}`;
+  const n = encodeURIComponent(e.pathname + e.search);
+  return `${r}?redirect=${n}`;
+}
+function u(e) {
+  return e.query?.code ? null : e.isLogin() ? e.home ?? "/" : null;
+}
+export {
+  t as getLoginRedirect,
+  u as getPublicOnlyRedirect
+};

package/dist/http.d.ts

@@ -0,0 +1,34 @@
+/**
+ * axios 认证拦截助手——刻意做成「可组合」而非「接管整个拦截器」:
+ * 各 app 的响应拦截器里往往还塞了信封校验、错误 toast 等业务逻辑,本包不抢这些,
+ * 只提供登录态相关的几块,让 app 拼进自己的拦截器(与后端不替使用方配 SecurityFilterChain 同理)。
+ */
+import type { InternalAxiosRequestConfig } from 'axios';
+export interface AuthRequestInterceptorOptions {
+    /** 取当前 token(通常传 tokenStore.getToken)。 */
+    getToken: () => string | null;
+    /** URL 命中其中任一子串则不带 token(默认 ['/fsLogin'],避免旧 token 干扰登录)。 */
+    noAuthUrls?: string[];
+    /** 注入的请求头名,默认 Authorization。 */
+    headerName?: string;
+    /** token 前缀,默认 Bearer。 */
+    scheme?: string;
+}
+/**
+ * 生成「请求拦截器」函数:自动给请求带上 Authorization: Bearer <token>。
+ * 用法:instance.interceptors.request.use(createAuthRequestInterceptor({ getToken }))
+ */
+export declare function createAuthRequestInterceptor(options: AuthRequestInterceptorOptions): (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig;
+/** 后端习惯把认证失败放在 HTTP 200 响应体的 code 字段里(如 {code:401})。 */
+export declare function isAuthFailureBody(body: unknown): boolean;
+export interface RedirectToLoginOptions {
+    /** 清除本地认证信息(通常传 tokenStore.clearAuth)。 */
+    clearAuth: () => void;
+    /** 登录页路径,默认 /login。 */
+    loginPath?: string;
+}
+/**
+ * 认证失败统一处理:清 token、整页跳登录(带 redirect 回跳)、返回永远 pending 的 Promise,
+ * 让调用方的 .catch 不再继续(页面即将整页跳转)。
+ */
+export declare function redirectToLogin(options: RedirectToLoginOptions): Promise<never>;

package/dist/http.js

@@ -0,0 +1,27 @@
+function u(e) {
+  const o = e.noAuthUrls ?? ["/fsLogin"], n = e.headerName ?? "Authorization", s = e.scheme ?? "Bearer";
+  return (t) => {
+    const a = t.url ?? "";
+    if (o.some((r) => a.includes(r))) return t;
+    const i = e.getToken();
+    if (i) {
+      const r = `${s} ${i}`, c = t.headers;
+      typeof c.set == "function" ? c.set(n, r) : c[n] = r;
+    }
+    return t;
+  };
+}
+function h(e) {
+  return !!e && typeof e == "object" && e.code === 401;
+}
+function l(e) {
+  e.clearAuth();
+  const o = e.loginPath ?? "/login", n = window.location.pathname + window.location.search, t = n.startsWith(o) ? "" : `?redirect=${encodeURIComponent(n)}`;
+  return window.location.href = `${o}${t}`, new Promise(() => {
+  });
+}
+export {
+  u as createAuthRequestInterceptor,
+  h as isAuthFailureBody,
+  l as redirectToLogin
+};

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @xy/feishu-auth-vue —— 飞书登录 + JWT + 三角色 RBAC 的前端可复用件。
+ *
+ * 与后端 feishu-auth-spring-boot-starter 配套:抽出 token 存取、登录 OAuth 链路、
+ * 切号、axios 认证拦截、登录态守卫、角色门控、用户 store 工厂等通用件;
+ * 菜单白名单、错误 toast、信封校验等系统专属逻辑留给各 app。
+ */
+export type { ApiEnvelope, FsLoginResult, AuthUserInfo, RoleAware, AuthRequest, LoginStatus, LoginTip, } from './types';
+export { parseJwtPayload, createTokenStore, defaultTokenStore, setToken, getToken, removeToken, clearAuth, isLogin, getUsername, } from './token';
+export type { TokenStore, TokenStoreOptions } from './token';
+export { createAuthApi, extractLoginToken, DEFAULT_ENDPOINTS } from './api';
+export type { AuthApi, AuthEndpoints, CreateAuthApiOptions } from './api';
+export { isSuccessCode, isSuccessEnvelope } from './response';
+export { createAuthRequestInterceptor, isAuthFailureBody, redirectToLogin } from './http';
+export type { AuthRequestInterceptorOptions, RedirectToLoginOptions } from './http';
+export { getLoginRedirect, getPublicOnlyRedirect } from './guard';
+export type { LoginRedirectOptions, PublicOnlyRedirectOptions } from './guard';
+export { normalizeSafeRedirect, safeDecodeURIComponent, stripQueryParam } from './redirect';
+export { isAdmin, isSuperAdmin, isAdminUser, isSuperAdminUser } from './roles';
+export { defineAuthUserStore } from './store';
+export { useFeishuLogin } from './useFeishuLogin';
+export type { UseFeishuLoginOptions, UseFeishuLoginReturn } from './useFeishuLogin';
+export { useUserSwitch } from './useUserSwitch';
+export type { UseUserSwitchOptions } from './useUserSwitch';

package/dist/index.js

@@ -0,0 +1,41 @@
+import { clearAuth as o, createTokenStore as t, defaultTokenStore as i, getToken as s, getUsername as n, isLogin as m, parseJwtPayload as p, removeToken as c, setToken as u } from "./token.js";
+import { DEFAULT_ENDPOINTS as d, createAuthApi as f, extractLoginToken as x } from "./api.js";
+import { isSuccessCode as S, isSuccessEnvelope as g } from "./response.js";
+import { createAuthRequestInterceptor as l, isAuthFailureBody as h, redirectToLogin as U } from "./http.js";
+import { getLoginRedirect as L, getPublicOnlyRedirect as R } from "./guard.js";
+import { normalizeSafeRedirect as P, safeDecodeURIComponent as D, stripQueryParam as E } from "./redirect.js";
+import { isAdmin as I, isAdminUser as v, isSuperAdmin as w, isSuperAdminUser as C } from "./roles.js";
+import { defineAuthUserStore as O } from "./store.js";
+import { useFeishuLogin as q } from "./useFeishuLogin.js";
+import { useUserSwitch as B } from "./useUserSwitch.js";
+export {
+  d as DEFAULT_ENDPOINTS,
+  o as clearAuth,
+  f as createAuthApi,
+  l as createAuthRequestInterceptor,
+  t as createTokenStore,
+  i as defaultTokenStore,
+  O as defineAuthUserStore,
+  x as extractLoginToken,
+  L as getLoginRedirect,
+  R as getPublicOnlyRedirect,
+  s as getToken,
+  n as getUsername,
+  I as isAdmin,
+  v as isAdminUser,
+  h as isAuthFailureBody,
+  m as isLogin,
+  S as isSuccessCode,
+  g as isSuccessEnvelope,
+  w as isSuperAdmin,
+  C as isSuperAdminUser,
+  P as normalizeSafeRedirect,
+  p as parseJwtPayload,
+  U as redirectToLogin,
+  c as removeToken,
+  D as safeDecodeURIComponent,
+  u as setToken,
+  E as stripQueryParam,
+  q as useFeishuLogin,
+  B as useUserSwitch
+};

package/dist/redirect.d.ts

@@ -0,0 +1,13 @@
+/** 安全解码 URL 组件,坏编码直接返回 null。 */
+export declare function safeDecodeURIComponent(value: string): string | null;
+/** 从相对路径里删除一个 query 参数,不改变其它参数。 */
+export declare function stripQueryParam(path: string, paramName: string): string;
+/**
+ * 把登录后跳转地址归一成安全的站内路径:
+ * - 接受 /path 和被 encodeURIComponent 过的 /path
+ * - 拒绝 //evil、http(s)://evil、坏百分号编码
+ * - 默认剔除飞书回调 code,避免回到业务页时重复消费 code
+ */
+export declare function normalizeSafeRedirect(redirect: string | undefined | null, fallback?: string, options?: {
+    stripCode?: boolean;
+}): string;

package/dist/redirect.js

@@ -0,0 +1,26 @@
+function a(t) {
+  try {
+    return decodeURIComponent(t);
+  } catch {
+    return null;
+  }
+}
+function i(t, e) {
+  const [s, r = ""] = t.split("?", 2);
+  if (!r) return t;
+  const n = new URLSearchParams(r);
+  n.delete(e);
+  const o = n.toString();
+  return o ? `${s}?${o}` : s;
+}
+function u(t, e = "/", s = {}) {
+  const r = e.startsWith("/") && !e.startsWith("//") ? e : "/";
+  if (!t) return r;
+  const n = t.startsWith("/") && !t.startsWith("//") ? t : a(t);
+  return !n || !n.startsWith("/") || n.startsWith("//") ? r : s.stripCode === !1 ? n : i(n, "code");
+}
+export {
+  u as normalizeSafeRedirect,
+  a as safeDecodeURIComponent,
+  i as stripQueryParam
+};

package/dist/response.d.ts

@@ -0,0 +1,4 @@
+import type { ApiEnvelope } from './types';
+/** 后端 starter 历史上出现过两种成功码:LightFlow 用 200,一些新项目用 0。 */
+export declare function isSuccessCode(code: unknown): boolean;
+export declare function isSuccessEnvelope<T = unknown>(value: unknown): value is ApiEnvelope<T>;

package/dist/response.js

@@ -0,0 +1,10 @@
+function c(e) {
+  return e === 0 || e === 200;
+}
+function n(e) {
+  return !!e && typeof e == "object" && c(e.code);
+}
+export {
+  c as isSuccessCode,
+  n as isSuccessEnvelope
+};

package/dist/roles.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 角色等级门控助手。纯函数,无依赖。
+ *
+ * roleLevel 约定(与后端三角色一致):0 普通用户 / 1 管理员 / 2 超管。
+ * 仅用于前端 UI 门控(隐藏修改类按钮/入口);后端仍走 @PreAuthorize 独立校验。
+ */
+import type { RoleAware } from './types';
+/** >=1 视为管理员(有"修改"权限)。 */
+export declare function isAdmin(roleLevel: number | null | undefined): boolean;
+/** >=2 视为超级管理员。 */
+export declare function isSuperAdmin(roleLevel: number | null | undefined): boolean;
+/** 从带 roleLevel 的用户对象读门控。 */
+export declare function isAdminUser(user: RoleAware | null | undefined): boolean;
+export declare function isSuperAdminUser(user: RoleAware | null | undefined): boolean;

package/dist/roles.js

@@ -0,0 +1,18 @@
+function e(n) {
+  return (n ?? 0) >= 1;
+}
+function r(n) {
+  return (n ?? 0) >= 2;
+}
+function i(n) {
+  return e(n?.roleLevel);
+}
+function u(n) {
+  return r(n?.roleLevel);
+}
+export {
+  e as isAdmin,
+  i as isAdminUser,
+  r as isSuperAdmin,
+  u as isSuperAdminUser
+};

package/dist/store.d.ts

@@ -0,0 +1,17 @@
+import type { RoleAware } from './types';
+export declare function defineAuthUserStore<U extends RoleAware>(storeId: string, createInitialUser: () => U): import("pinia").StoreDefinition<string, {
+    userInfo: U;
+}, {
+    isAdmin: (state: {
+        userInfo: import("vue").UnwrapRef<U>;
+    } & import("pinia").PiniaCustomStateProperties<{
+        userInfo: U;
+    }>) => boolean;
+    isSuperAdmin: (state: {
+        userInfo: import("vue").UnwrapRef<U>;
+    } & import("pinia").PiniaCustomStateProperties<{
+        userInfo: U;
+    }>) => boolean;
+}, {
+    setUserInfo(data: U): void;
+}>;

package/dist/store.js

@@ -0,0 +1,22 @@
+import { defineStore as i } from "pinia";
+import { isSuperAdmin as n, isAdmin as s } from "./roles.js";
+function u(r, o) {
+  return i(r, {
+    state: () => ({
+      userInfo: o()
+    }),
+    getters: {
+      // 仅用于前端 UI 门控(隐藏修改类按钮/入口);后端走 @PreAuthorize 独立校验,不依赖此值。
+      isAdmin: (e) => s(e.userInfo.roleLevel),
+      isSuperAdmin: (e) => n(e.userInfo.roleLevel)
+    },
+    actions: {
+      setUserInfo(e) {
+        this.userInfo = e;
+      }
+    }
+  });
+}
+export {
+  u as defineAuthUserStore
+};

package/dist/token.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Token 存取 + JWT 解析。完全通用,不含任何业务/路由耦合。
+ *
+ * 默认用 localStorage,key 为 LF_TOKEN / LF_USERNAME(与 LightFlow 既有一致,
+ * 迁移后老会话不丢)。需要隔离多套系统时,用 createTokenStore 传不同 key。
+ */
+/** 解析 JWT payload,失败返回 null。 */
+export declare function parseJwtPayload(token: string): Record<string, unknown> | null;
+export interface TokenStoreOptions {
+    /** token 存储 key,默认 LF_TOKEN */
+    tokenKey?: string;
+    /** 用户名存储 key,默认 LF_USERNAME */
+    usernameKey?: string;
+    /** 存储介质,默认 localStorage */
+    storage?: Storage;
+}
+export interface TokenStore {
+    setToken(token: string): void;
+    /** 取 token;已过期则自动清除并返回 null,避免带死 token 请求后端。 */
+    getToken(): string | null;
+    removeToken(): void;
+    clearAuth(): void;
+    isLogin(): boolean;
+    getUsername(): string;
+    setUsername(name: string): void;
+}
+/** 创建一个带独立 key 的 token 存取器。 */
+export declare function createTokenStore(options?: TokenStoreOptions): TokenStore;
+/** 默认 token 存取器(LF_TOKEN / LF_USERNAME + localStorage)。 */
+export declare const defaultTokenStore: TokenStore;
+export declare const setToken: (token: string) => void;
+export declare const getToken: () => string | null;
+export declare const removeToken: () => void;
+export declare const clearAuth: () => void;
+export declare const isLogin: () => boolean;
+export declare const getUsername: () => string;

package/dist/token.js

@@ -0,0 +1,65 @@
+function m(e) {
+  try {
+    const t = e.split(".");
+    if (t.length < 2) return null;
+    const o = t[1];
+    if (!o) return null;
+    const n = o.replace(/-/g, "+").replace(/_/g, "/"), c = n + "=".repeat((4 - n.length % 4) % 4), a = decodeURIComponent(
+      atob(c).split("").map((l) => "%" + l.charCodeAt(0).toString(16).padStart(2, "0")).join("")
+    );
+    return JSON.parse(a);
+  } catch {
+    return null;
+  }
+}
+function g() {
+  const e = /* @__PURE__ */ new Map();
+  return {
+    get length() {
+      return e.size;
+    },
+    clear: () => e.clear(),
+    getItem: (t) => e.get(t) ?? null,
+    key: (t) => Array.from(e.keys())[t] ?? null,
+    removeItem: (t) => {
+      e.delete(t);
+    },
+    setItem: (t, o) => {
+      e.set(t, o);
+    }
+  };
+}
+function i(e) {
+  return e || (typeof globalThis.localStorage < "u" ? globalThis.localStorage : g());
+}
+function k(e = {}) {
+  const t = e.tokenKey ?? "LF_TOKEN", o = e.usernameKey ?? "LF_USERNAME", n = i(e.storage), c = (r) => n.setItem(t, r), a = () => {
+    const r = n.getItem(t);
+    if (!r) return null;
+    const u = m(r);
+    return u && typeof u.exp == "number" && u.exp * 1e3 < Date.now() ? (n.removeItem(t), n.removeItem(o), null) : r;
+  }, l = () => {
+    n.removeItem(t), n.removeItem(o);
+  };
+  return {
+    setToken: c,
+    getToken: a,
+    removeToken: l,
+    clearAuth: l,
+    isLogin: () => !!a(),
+    getUsername: () => n.getItem(o) || "",
+    setUsername: (r) => n.setItem(o, r)
+  };
+}
+const s = k(), p = s.setToken, T = s.getToken, f = s.removeToken, d = s.clearAuth, y = s.isLogin, I = s.getUsername;
+export {
+  d as clearAuth,
+  k as createTokenStore,
+  s as defaultTokenStore,
+  T as getToken,
+  I as getUsername,
+  y as isLogin,
+  m as parseJwtPayload,
+  f as removeToken,
+  p as setToken
+};

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * auth-vue 的公共类型。
+ *
+ * 与后端 feishu-auth-spring-boot-starter 的 HTTP 契约对齐:
+ *   - ApiEnvelope 对应后端 ApiResponse {code,data,msg}
+ *   - FsLoginResult 对应 FsLoginResponse(顶层带 token)
+ *   - AuthUserInfo 对应 UserInfoResponse(/getFsInfo 返回)
+ */
+/** 通用接口返回信封 {code,data,msg}。 */
+export interface ApiEnvelope<T = unknown> {
+    code: number;
+    data: T;
+    msg: string;
+}
+/** 飞书登录返回壳:除信封外顶层再带一个 token,方便登录页直接读取。 */
+export interface FsLoginResult {
+    code?: number;
+    data?: unknown;
+    msg?: string;
+    token?: string;
+}
+/**
+ * 当前登录用户信息(库的稳定契约,最小集)。
+ * roleLevel:0 普通用户 / 1 管理员 / 2 超管,前端据此做 UI 门控(后端独立校验)。
+ *
+ * 使用方可以用 TS 交叉类型在此基础上扩展自己的字段。
+ */
+export interface AuthUserInfo {
+    id: number | null;
+    userId: number | null;
+    name: string | null;
+    unionId: string | null;
+    avatar: string | null;
+    employeeNo: string | null;
+    isExist: boolean | null;
+    roleLevel: number | null;
+}
+/** 任何带 roleLevel 的对象都能用角色助手做门控。 */
+export interface RoleAware {
+    roleLevel?: number | null;
+}
+/**
+ * 包内对「请求实例」的最小依赖。
+ *
+ * 约定响应拦截器已把 AxiosResponse 解包成 body(与 LightFlow 的 request 实例一致),
+ * 所以方法返回 Promise<T>(T=body)而非 Promise<AxiosResponse<T>>。
+ */
+export interface AuthRequest {
+    get<T = unknown>(url: string, config?: unknown): Promise<T>;
+    post<T = unknown>(url: string, data?: unknown, config?: unknown): Promise<T>;
+}
+/** 登录流程状态(供登录页 UI 用)。 */
+export type LoginStatus = 'idle' | 'processing' | 'success' | 'error';
+/** 登录流程提示信息。 */
+export interface LoginTip {
+    message: string;
+    type: 'info' | 'success' | 'error';
+}

package/dist/useFeishuLogin.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 飞书登录 Composable:处理「拿授权链接 → 跳飞书 → code 换 token」整条 OAuth 链路,
+ * 含飞书回调把 query 冲掉时的 redirect 暂存/回收。与具体 UI 无关,登录页用 status/tip 渲染即可。
+ *
+ * 依赖通过 options 注入(api / tokens),所以不绑定任何具体 app 的请求实例或 token 实现。
+ */
+import { ref } from 'vue';
+import type { AuthApi } from './api';
+import type { TokenStore } from './token';
+import type { LoginStatus, LoginTip } from './types';
+export interface UseFeishuLoginOptions {
+    api: Pick<AuthApi, 'fsLogin' | 'getAuthorizeUrl'>;
+    tokens: Pick<TokenStore, 'setToken' | 'getToken' | 'clearAuth'>;
+    /** 登录成功后无 redirect 时的兜底跳转,默认 /。 */
+    defaultRedirect?: string;
+    /** 暂存 redirect 的 sessionStorage key,默认 lf:postLoginRedirect。 */
+    stashKey?: string;
+}
+export interface UseFeishuLoginReturn {
+    status: ReturnType<typeof ref<LoginStatus>>;
+    tip: ReturnType<typeof ref<LoginTip>>;
+}
+export declare function useFeishuLogin(options: UseFeishuLoginOptions): {
+    status: import("vue").Ref<LoginStatus, LoginStatus>;
+    tip: import("vue").Ref<{
+        message: string;
+        type: "info" | "success" | "error";
+    }, LoginTip | {
+        message: string;
+        type: "info" | "success" | "error";
+    }>;
+};

package/dist/useFeishuLogin.js

@@ -0,0 +1,80 @@
+import { ref as g, watch as q } from "vue";
+import { useRouter as S, useRoute as w } from "vue-router";
+import { extractLoginToken as L } from "./api.js";
+import { normalizeSafeRedirect as d } from "./redirect.js";
+import { isSuccessEnvelope as m } from "./response.js";
+function E(s) {
+  const l = S(), n = w(), i = s.stashKey ?? "lf:postLoginRedirect", a = s.defaultRedirect ?? "/", t = g("idle"), o = g({ message: "正在跳转到飞书授权...", type: "info" });
+  function y(e) {
+    const r = d(e, "", { stripCode: !1 });
+    if (r)
+      try {
+        sessionStorage.setItem(i, r);
+      } catch {
+      }
+  }
+  function f() {
+    try {
+      const e = sessionStorage.getItem(i);
+      return sessionStorage.removeItem(i), e;
+    } catch {
+      return null;
+    }
+  }
+  async function h(e) {
+    t.value = "processing", o.value = { message: "正在登录...", type: "info" };
+    try {
+      const r = await s.api.fsLogin(e), c = L(r);
+      if (m(r) && c) {
+        s.tokens.clearAuth(), s.tokens.setToken(c), t.value = "success", o.value = { message: "登录成功", type: "success" };
+        const u = n.query.redirect, R = f(), k = d(u || R || a, a);
+        setTimeout(() => {
+          window.location.href = k;
+        }, 200);
+      } else
+        t.value = "error", o.value = { message: `登录失败: ${r?.msg || "未知错误"}`, type: "error" };
+    } catch (r) {
+      t.value = "error";
+      const c = r instanceof Error ? r.message : "登录失败，请重试";
+      o.value = { message: c, type: "error" };
+    }
+  }
+  async function p() {
+    t.value = "processing";
+    try {
+      y(n.query.redirect);
+      const e = await s.api.getAuthorizeUrl(), r = e?.data;
+      m(e) && r ? window.location.href = r : (t.value = "error", o.value = { message: `获取授权链接失败: ${e?.msg || "未知错误"}`, type: "error" });
+    } catch {
+      t.value = "error", o.value = { message: "获取授权链接失败，请重试", type: "error" };
+    }
+  }
+  function v() {
+    if (s.tokens.getToken()) {
+      const e = n.query.redirect, r = f(), c = e || r;
+      if (c) {
+        const u = d(c, a);
+        l.replace(u);
+      } else
+        l.replace(a);
+      return !0;
+    }
+    return !1;
+  }
+  return q(
+    () => [n.query.code, n.query.redirect],
+    () => {
+      if (t.value === "processing" || t.value === "success") return;
+      const e = n.query.code;
+      if (typeof e == "string" && e) {
+        h(e);
+        return;
+      }
+      v() || p();
+    },
+    { immediate: !0 }
+  ), { status: t, tip: o };
+}
+export {
+  E as useFeishuLogin
+};

package/dist/useUserSwitch.d.ts

@@ -0,0 +1,12 @@
+import type { AuthApi } from './api';
+import type { TokenStore } from './token';
+export interface UseUserSwitchOptions {
+    api: Pick<AuthApi, 'devSwitchUser'>;
+    tokens: Pick<TokenStore, 'setToken'>;
+    /** 切号成功后的回调,默认整页刷新 location.reload()。 */
+    onSwitched?: (token: string) => void;
+}
+export declare function useUserSwitch(options: UseUserSwitchOptions): {
+    switching: import("vue").Ref<boolean, boolean>;
+    switchTo: (unionId: string) => Promise<boolean>;
+};

package/dist/useUserSwitch.js

@@ -0,0 +1,19 @@
+import { ref as a } from "vue";
+import { extractLoginToken as c } from "./api.js";
+function l(e) {
+  const t = a(!1);
+  async function i(n) {
+    if (!n) return !1;
+    t.value = !0;
+    try {
+      const o = await e.api.devSwitchUser(n), r = c(o);
+      return r ? (e.tokens.setToken(r), e.onSwitched ? e.onSwitched(r) : window.location.reload(), !0) : !1;
+    } finally {
+      t.value = !1;
+    }
+  }
+  return { switching: t, switchTo: i };
+}
+export {
+  l as useUserSwitch
+};

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@czxingyu/feishu-auth-vue",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "飞书登录 + JWT + 三角色 RBAC 的 Vue 前端 npm 包,与 feishu-auth-spring-boot-starter 配套",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "import": "./dist/api.js"
+    },
+    "./guard": {
+      "types": "./dist/guard.d.ts",
+      "import": "./dist/guard.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js"
+    },
+    "./roles": {
+      "types": "./dist/roles.d.ts",
+      "import": "./dist/roles.js"
+    },
+    "./redirect": {
+      "types": "./dist/redirect.d.ts",
+      "import": "./dist/redirect.js"
+    },
+    "./response": {
+      "types": "./dist/response.d.ts",
+      "import": "./dist/response.js"
+    },
+    "./store": {
+      "types": "./dist/store.d.ts",
+      "import": "./dist/store.js"
+    },
+    "./token": {
+      "types": "./dist/token.d.ts",
+      "import": "./dist/token.js"
+    },
+    "./useFeishuLogin": {
+      "types": "./dist/useFeishuLogin.d.ts",
+      "import": "./dist/useFeishuLogin.js"
+    },
+    "./useUserSwitch": {
+      "types": "./dist/useUserSwitch.d.ts",
+      "import": "./dist/useUserSwitch.js"
+    },
+    "./package.json": {
+      "default": "./package.json"
+    }
+  },
+  "module": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "type-check": "vue-tsc --noEmit"
+  },
+  "peerDependencies": {
+    "axios": "^1.0.0",
+    "pinia": "^2.0.0 || ^3.0.0",
+    "vue": "^3.4.0",
+    "vue-router": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "axios": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.1",
+    "@vue/tsconfig": "^0.8.1",
+    "axios": "^1.13.6",
+    "jsdom": "^27.3.0",
+    "pinia": "^3.0.3",
+    "typescript": "~5.9.0",
+    "vite": "^7.1.11",
+    "vitest": "^4.0.16",
+    "vue": "^3.5.22",
+    "vue-router": "^4.6.3",
+    "vue-tsc": "^3.1.1"
+  }
+}