@litianxiang/portal-core 0.1.8 → 0.1.10

package/README.md

@@ -1,11 +1,12 @@
 # @litianxiang/portal-core 使用说明
 
-`@litianxiang/portal-core` 是一套门户子系统通用的路由/认证内核，负责统一处理：
+`@litianxiang/portal-core` 是一套门户子系统通用的路由 / 认证 / 请求 内核，负责统一处理：
 
 - 登录态校验 + SSO 恢复
 - 菜单加载与动态路由挂载
 - 根路径重定向到第一个业务页面
 - 统一退出到认证站、空闲超时判断等通用认证逻辑
+- http 请求拦截（包含全局 Loading、Token 过期刷新、401 统一退出等）
 
 各子系统只需注入自己的静态路由、用户 Store、（可选）Tab Store 和“第一个页面”的计算函数，即可接入。
 
@@ -32,7 +33,9 @@ npm install @litianxiang/portal-core
 import {
   createAppRouter,
   createLogoutToAuth,
-  calcInactivityAction
+  calcInactivityAction,
+  createAuthHttpClient,
+  createPermissionHelper
 } from '@litianxiang/portal-core'
 ```
 
@@ -80,6 +83,49 @@ function calcInactivityAction(
   bufferMs: number
 }
 ```
+
+`http` 相关工具简化说明：
+
+```ts
+interface CreateAuthHttpClientOptions {
+  axios: any
+  baseURL?: string
+  timeout?: number
+  getUserStore: () => any
+  getLoadingStore: () => any
+  authLoginUrl?: string
+  ssoStorageKey?: string
+  refreshUrl: string
+  inactiveExpireMs?: number
+  inactiveBufferMs?: number
+  onShowError?: (msg: string) => void
+}
+
+function createAuthHttpClient(options: CreateAuthHttpClientOptions): {
+  http: any                // 已挂好请求/响应拦截器的 axios 实例
+  logoutToAuth: () => void // 同 createLogoutToAuth，便于复用
+}
+```
+
+`permission` 相关工具简化说明：
+
+```ts
+interface PermissionHelperOptions {
+  // 返回用户 Store 实例，需至少提供 getUserALLMenu 或 getUserPageMenu
+  getUserStore: () => any
+}
+
+interface PermissionHelper {
+  // 判断是否拥有某个页面（路由）权限
+  hasPagePermission: (path: string) => boolean
+  // 判断是否拥有某个按钮权限（约定使用菜单 path 作为唯一标识）
+  hasButtonPermission: (codeOrPath: string) => boolean
+  // 判断是否拥有给定列表中的任意一个权限
+  hasAnyPermission: (codesOrPaths: string[]) => boolean
+}
+
+function createPermissionHelper(options: PermissionHelperOptions): PermissionHelper
+```
 ```
 
 ## 子系统接入步骤
@@ -159,19 +205,19 @@ export const useUserStore = defineStore('user', {
 
 ### 3. 准备 Tab Store（可选）
 
-Tab Store 主要用于和各系统的 Tab 控件协作，例如在“手动退出”时统一清理 Tab。当前路由内核在菜单加载 / 刷新场景下不会自动清空 Tab。
+Tab Store 主要用于和各系统的 Tab 控件协作，例如在“手动退出”时统一关闭所有可关闭的 Tab。当前路由内核在菜单加载 / 刷新场景下不会自动清空 Tab。
 
 建议至少包含：
 
-- `clearAll()`：清空当前系统的所有 Tab
+- `closeAll()`：关闭所有可关闭的 Tab（保留固定首页等不可关闭项）
 
 示例：
 
 ```ts
 export const useTabStore = defineStore('tab', {
   actions: {
-    clearAll() {
-      // 清空当前系统的所有 Tab
+    closeAll() {
+      // 关闭所有可关闭的 Tab（保留固定首页等不可关闭项）
     }
   }
 })
@@ -211,61 +257,84 @@ const router = createAppRouter({
 
 export default router
 ```
-### 6.（可选）接入统一退出与空闲超时控制
+### 6. 使用 createAuthHttpClient 统一封装 http（推荐）
 
-在各子系统的 http 封装中，可以结合 `createLogoutToAuth` 和 `calcInactivityAction` 实现统一退出与“2 小时未操作自动退出”的逻辑。例如：
+在各子系统的 http 封装中，推荐直接使用 `createAuthHttpClient`，即可一次性接入：
+
+- 全局 Loading 控制（基于 `getLoadingStore` 的 `startLoading/stopLoading`）
+- 基于最后操作时间的“2 小时未操作自动退出”
+- 距离过期 5 分钟以内自动刷新 access_token
+- 401 统一退出到认证站并弹出错误提示
+
+示例：
 
 ```ts
 // src/utils/http.ts
 import axios from 'axios'
-import { createLogoutToAuth, calcInactivityAction } from '@litianxiang/portal-core'
+import { ElMessage } from 'element-plus'
+import { createAuthHttpClient } from '@litianxiang/portal-core'
 import { useUserStore } from '@/stores/user'
 import { useLoadingStore } from '@/stores/loading'
 
-const logoutToAuth = createLogoutToAuth({
+const AUTH_LOGIN_URL =
+  import.meta.env.VITE_AUTH_LOGIN_URL || `${window.location.origin}/auth/#/login`
+
+const { http, logoutToAuth } = createAuthHttpClient({
+  axios,
+  baseURL: '',
+  timeout: 10000,
   getUserStore: () => useUserStore(),
   getLoadingStore: () => useLoadingStore(),
-  authLoginUrl: import.meta.env.VITE_AUTH_LOGIN_URL
+  authLoginUrl: AUTH_LOGIN_URL,
+  ssoStorageKey: 'user-store',
+  refreshUrl: '/proxy/auth/api/token/refresh',
+  inactiveExpireMs: 2 * 60 * 60 * 1000,
+  inactiveBufferMs: 5 * 60 * 1000,
+  onShowError: (msg: string) => {
+    ElMessage.error(msg)
+  }
 })
 
-axios.interceptors.request.use(async config => {
-  const userStore = useUserStore()
-  const { shouldLogout, shouldRefresh } = calcInactivityAction(
-    userStore.lastActiveTime,
-    Date.now()
-  )
+// 业务代码直接使用 http 即可
+// http.post('/api/demo', data)
 
-  if (shouldLogout) {
-    logoutToAuth()
-    return Promise.reject(new Error('登录已过期'))
-  }
+export default http
+export { logoutToAuth }
+```
 
-  if (shouldRefresh) {
-    // 此处调用后端刷新 token 接口，成功后更新 userStore 中的 token
-  }
+如需完全自定义 http 行为，也可以直接基于前面的 `auth` 工具自行编写拦截器。
 
-  // 正常附带 Authorization 头，并更新 lastActiveTime
-  if (userStore.getUserAccessToken) {
-    config.headers = config.headers || {}
-    config.headers.Authorization = `Bearer ${userStore.getUserAccessToken}`
-    userStore.updateLastActiveTime?.()
-  }
+### 7.（可选）接入菜单 / 按钮权限判断
+
+在需要做“是否显示某个按钮”或“是否放行某个页面”时，可以使用 `createPermissionHelper` 来基于菜单数据做权限判断：
 
-  return config
+```ts
+// 例如在某个业务系统的全局 helper 中：
+import { createPermissionHelper } from '@litianxiang/portal-core'
+import { useUserStore } from '@/stores/user'
+
+const permission = createPermissionHelper({
+  getUserStore: () => useUserStore()
 })
 
-axios.interceptors.response.use(
-  res => res,
-  error => {
-    if (error.response?.status === 401) {
-      logoutToAuth()
-    }
-    return Promise.reject(error)
-  }
-)
+// 页面/路由级权限判断（基于菜单的 path，忽略 query 部分）
+permission.hasPagePermission('/system/menu')
+
+// 按钮权限判断（约定后台为按钮类型菜单配置唯一的 path 作为权限码）
+permission.hasButtonPermission('/system/menu:add')
+
+// 任一权限命中即通过（可用于复杂场景）
+permission.hasAnyPermission([
+  '/system/menu:add',
+  '/system/menu:edit'
+])
 ```
 
-### 7. 项目视图目录约定
+> 说明：
+> - `createPermissionHelper` 内部会优先使用 `userStore.getUserPageMenu`（包含 page + button），若不存在则退回 `userStore.getUserALLMenu`；
+> - 匹配时仅按基础路径（去掉 `?query`）比较，避免 query 影响权限判断。
+
+### 8. 项目视图目录约定
 
 `portal-core` 会根据后端菜单返回的 `path` 去匹配前端视图，规则如下：
 

package/dist/index.d.ts

@@ -50,4 +50,44 @@ interface InactivityResult {
  */
 declare function calcInactivityAction(lastActiveTime: number | null | undefined, now: number, config?: InactivityConfig): InactivityResult;
 
-export { type AppRouterOptions, type InactivityConfig, type InactivityResult, type LogoutToAuthOptions, calcInactivityAction, createAppRouter, createLogoutToAuth };
+interface CreateAuthHttpClientOptions {
+    axios: any;
+    baseURL?: string;
+    timeout?: number;
+    getUserStore: () => any;
+    getLoadingStore: () => any;
+    authLoginUrl?: string;
+    ssoStorageKey?: string;
+    refreshUrl: string;
+    inactiveExpireMs?: number;
+    inactiveBufferMs?: number;
+    onShowError?: (msg: string) => void;
+}
+declare function createAuthHttpClient(options: CreateAuthHttpClientOptions): {
+    http: any;
+    logoutToAuth: () => void;
+};
+
+interface PermissionHelperOptions {
+    /** 返回用户 Store 实例，需至少提供 getUserALLMenu 或 getUserPageMenu */
+    getUserStore: () => any;
+}
+interface PermissionHelper {
+    /**
+     * 判断当前用户是否拥有某个页面（路由）权限
+     * @param path 完整路径，支持携带 query（内部只按基础路径匹配）
+     */
+    hasPagePermission: (path: string) => boolean;
+    /**
+     * 判断当前用户是否拥有某个按钮权限
+     * 约定：按钮权限同样使用菜单的 path 字段作为唯一标识
+     */
+    hasButtonPermission: (codeOrPath: string) => boolean;
+    /**
+     * 判断当前用户是否拥有给定列表中的任意一个权限（页面或按钮）
+     */
+    hasAnyPermission: (codesOrPaths: string[]) => boolean;
+}
+declare function createPermissionHelper(options: PermissionHelperOptions): PermissionHelper;
+
+export { type AppRouterOptions, type CreateAuthHttpClientOptions, type InactivityConfig, type InactivityResult, type LogoutToAuthOptions, type PermissionHelper, type PermissionHelperOptions, calcInactivityAction, createAppRouter, createAuthHttpClient, createLogoutToAuth, createPermissionHelper };

package/dist/index.js

@@ -222,8 +222,214 @@ function calcInactivityAction(lastActiveTime, now, config = {}) {
     bufferMs
   };
 }
+
+// src/http.ts
+function createAuthHttpClient(options) {
+  const {
+    axios,
+    baseURL = "",
+    timeout = 1e4,
+    getUserStore,
+    getLoadingStore,
+    authLoginUrl,
+    ssoStorageKey = "user-store",
+    refreshUrl,
+    inactiveExpireMs,
+    inactiveBufferMs,
+    onShowError
+  } = options;
+  const http = axios.create({
+    baseURL,
+    timeout
+  });
+  const logoutToAuth = createLogoutToAuth({
+    getUserStore,
+    getLoadingStore,
+    authLoginUrl,
+    ssoStorageKey
+  });
+  let isRefreshing = false;
+  let isHandling401 = false;
+  http.interceptors.request.use(async (config) => {
+    const loadingStore = getLoadingStore();
+    loadingStore?.startLoading?.();
+    const userStore = getUserStore();
+    const accessToken = userStore.getUserAccessToken;
+    const refreshToken = userStore.getUserRefreshToken;
+    if (!accessToken || !refreshToken) {
+      return config;
+    }
+    const lastActiveTime = userStore.getUserLastActiveTime ?? 0;
+    const currentTime = Date.now();
+    const { shouldLogout, shouldRefresh } = calcInactivityAction(lastActiveTime, currentTime, {
+      expireMs: inactiveExpireMs,
+      bufferMs: inactiveBufferMs
+    });
+    if (shouldLogout) {
+      logoutToAuth();
+      return Promise.reject(new Error("INACTIVE_LOGOUT"));
+    }
+    if (!lastActiveTime) {
+      userStore.setUserLastActiveTime?.(currentTime);
+    } else {
+      if (shouldRefresh && !isRefreshing) {
+        isRefreshing = true;
+        try {
+          const response = await axios.post(refreshUrl, {}, {
+            headers: { Authorization: `Bearer ${refreshToken}` }
+          });
+          const result = response.data;
+          if (result.code === 200 && result.data?.access_token) {
+            const newAccessToken = result.data.access_token;
+            config.headers = config.headers || {};
+            config.headers.Authorization = `Bearer ${newAccessToken}`;
+            userStore.setUserAccessToken?.(newAccessToken);
+            userStore.setUserLastActiveTime?.(Date.now());
+          }
+        } catch (error) {
+          logoutToAuth();
+          return Promise.reject(error);
+        } finally {
+          isRefreshing = false;
+        }
+      }
+    }
+    config.headers = config.headers || {};
+    config.headers.Authorization = `Bearer ${accessToken}`;
+    userStore.setUserLastActiveTime?.(Date.now());
+    return config;
+  });
+  function buildErrorMessage(status, message, statusText) {
+    let msg = "";
+    switch (status) {
+      case 400:
+        msg = "\u8BF7\u6C42\u53C2\u6570\u9519\u8BEF";
+        break;
+      case 401:
+        msg = "\u672A\u6388\u6743\uFF0C\u8BF7\u767B\u5F55";
+        break;
+      case 403:
+        msg = "\u65E0\u6743\u9650\u8BBF\u95EE\u6216\u670D\u52A1\u6682\u4E0D\u53EF\u7528";
+        break;
+      case 404:
+        msg = "\u8BF7\u6C42\u5730\u5740\u51FA\u9519";
+        break;
+      case 408:
+        msg = "\u8BF7\u6C42\u8D85\u65F6";
+        break;
+      case 500:
+        msg = "\u670D\u52A1\u5668\u5185\u90E8\u9519\u8BEF";
+        break;
+      case 501:
+        msg = "\u670D\u52A1\u672A\u5B9E\u73B0";
+        break;
+      case 502:
+        msg = "\u7F51\u5173\u9519\u8BEF";
+        break;
+      case 503:
+        msg = "\u670D\u52A1\u4E0D\u53EF\u7528";
+        break;
+      case 504:
+        msg = "\u7F51\u5173\u8D85\u65F6";
+        break;
+      case 505:
+        msg = "HTTP\u7248\u672C\u4E0D\u53D7\u652F\u6301";
+        break;
+      default:
+        msg = "\u8BF7\u6C42\u9519\u8BEF";
+        break;
+    }
+    const baseMsg = message || msg;
+    if (!status) return baseMsg;
+    return `\u8BF7\u6C42\u72B6\u6001\uFF1A${status}\uFF0C${baseMsg}\u3002\u9519\u8BEF\u4FE1\u606F\uFF1A${statusText || ""}`;
+  }
+  http.interceptors.response.use(
+    (response) => {
+      const loadingStore = getLoadingStore();
+      loadingStore?.stopLoading?.();
+      return response.data;
+    },
+    (error) => {
+      const loadingStore = getLoadingStore();
+      loadingStore?.stopLoading?.();
+      const status = error.response?.status;
+      const rawMsg = error.response?.data?.message;
+      const statusText = error.response?.statusText;
+      const fullMsg = buildErrorMessage(status, rawMsg, statusText);
+      if (status === 401) {
+        if (!isHandling401) {
+          isHandling401 = true;
+          onShowError?.(fullMsg);
+          logoutToAuth();
+        }
+        return Promise.reject(error);
+      }
+      onShowError?.(fullMsg);
+      return Promise.reject(error);
+    }
+  );
+  return { http, logoutToAuth };
+}
+
+// src/permission.ts
+function normalizePath(raw) {
+  if (!raw) return "";
+  const [base] = raw.split("?");
+  if (!base) return "";
+  return base.startsWith("/") ? base : `/${base}`;
+}
+function findMenuByPath(menuList, targetPath, category) {
+  const target = normalizePath(targetPath);
+  if (!target || !Array.isArray(menuList)) return null;
+  for (const item of menuList) {
+    const current = normalizePath(item?.path);
+    if (current === target) {
+      if (!category || item?.category === category) {
+        return item;
+      }
+    }
+    if (item?.children && item.children.length > 0) {
+      const found = findMenuByPath(item.children, targetPath, category);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+function createPermissionHelper(options) {
+  const { getUserStore } = options;
+  const getMenuTree = () => {
+    const userStore = getUserStore();
+    const pageMenu = userStore?.getUserPageMenu;
+    const allMenu = userStore?.getUserALLMenu;
+    if (Array.isArray(pageMenu)) return pageMenu;
+    if (Array.isArray(allMenu)) return allMenu;
+    return [];
+  };
+  const hasPagePermission = (path) => {
+    const menuTree = getMenuTree();
+    const item = findMenuByPath(menuTree, path);
+    if (!item) return false;
+    return item.category === "page" || item.category === "flow-page";
+  };
+  const hasButtonPermission = (codeOrPath) => {
+    const menuTree = getMenuTree();
+    const item = findMenuByPath(menuTree, codeOrPath, "button");
+    return !!item;
+  };
+  const hasAnyPermission = (codesOrPaths) => {
+    if (!Array.isArray(codesOrPaths) || codesOrPaths.length === 0) return false;
+    return codesOrPaths.some((code) => hasPagePermission(code) || hasButtonPermission(code));
+  };
+  return {
+    hasPagePermission,
+    hasButtonPermission,
+    hasAnyPermission
+  };
+}
 export {
   calcInactivityAction,
   createAppRouter,
-  createLogoutToAuth
+  createAuthHttpClient,
+  createLogoutToAuth,
+  createPermissionHelper
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litianxiang/portal-core",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "private": false,
   "type": "module",
   "main": "dist/index.js",