@litianxiang/portal-core 0.1.22 → 0.1.24

package/README.md

@@ -1,373 +1,424 @@
-# @litianxiang/portal-core 使用说明
+# @litianxiang/portal-core
 
-`@litianxiang/portal-core` 是一套门户子系统通用的路由 / 认证 / 请求 内核，负责统一处理：
+门户子系统通用内核，统一提供：
 
-- 登录态校验 + SSO 恢复
-- 菜单加载与动态路由挂载
-- 根路径重定向到第一个业务页面
-- 统一退出到认证站、空闲超时判断等通用认证逻辑
-- http 请求拦截（包含全局 Loading、Token 过期刷新、401 统一退出等）
-
-各子系统只需注入自己的静态路由、用户 Store、（可选）Tab Store 和“第一个页面”的计算函数，即可接入。
+- 路由守卫与动态菜单挂载
+- SSO 登录态恢复与统一退出
+- 认证 HTTP 拦截器（Loading、401、自动刷新 token）
+- 菜单/权限/用户状态工具
+- Tab、Loading、时间、数字、主题、i18n 工具
 
 ## 安装
 
 ```bash
 pnpm add @litianxiang/portal-core
 # 或
-pnpm update @litianxiang/portal-core
-# 或
-npm install @litianxiang/portal-core
+npm i @litianxiang/portal-core
 ```
 
-要求：
+## 快速开始
 
-- Vue 3
-- vue-router 4（hash 模式）
+### 1) 路由接入
 
-## 导出的能力
+```ts
+import { createAppRouter } from '@litianxiang/portal-core'
+import { staticRoutes } from './routes'
+import { useUserStore } from '@/stores/user'
 
-当前主要导出以下能力：
+const router = createAppRouter({
+  staticRoutes,
+  getUserStore: () => useUserStore(),
+  getFirstPage: (allMenu) => allMenu.find((i: any) => i.category === 'page')?.path,
+  authLoginUrl: import.meta.env.VITE_AUTH_LOGIN_URL
+})
 
-```ts
-import {
-  createAppRouter,
-  createLogoutToAuth,
-  calcInactivityAction,
-  createAuthHttpClient,
-  createPermissionHelper
-} from '@litianxiang/portal-core'
+export default router
 ```
 
-`createAppRouter` 类型签名简化说明：
+### 2) HTTP 接入
 
 ```ts
-interface AppRouterOptions {
-  staticRoutes: RouteRecordRaw[]            // 各系统自己的静态路由（含 main 布局）
-  getUserStore: () => any                  // 返回用户 Store 实例
-  getTabStore: () => any                   // 返回 Tab Store 实例
-  getFirstPage: (allMenu: any[]) => string | null | undefined
-  authLoginUrl?: string                    // 统一登录地址（可选，不传则默认 /auth/#/login）
-}
+import axios from 'axios'
+import { createAuthHttpClient } from '@litianxiang/portal-core'
+import { useUserStore } from '@/stores/user'
+import { useLoadingStore } from '@/stores/loading'
+
+export const { http, logoutToAuth } = createAuthHttpClient({
+  axios,
+  getUserStore: () => useUserStore(),
+  getLoadingStore: () => useLoadingStore(),
+  onShowError: (msg) => console.error(msg)
+})
+```
 
-function createAppRouter(options: AppRouterOptions): Router
+## 导出方法说明（逐方法）
 
-`auth` 相关工具简化说明：
+### app
+
+- `setupPortalApp(options)`：统一执行应用启动编排（插件注册、图标注册、beforeMount、mount）。
+
+最小示例：
 
 ```ts
-interface LogoutOptions {
-  getUserStore: () => any          // 返回当前系统的 userStore（需提供 clearUserInfo 等方法）
-  getLoadingStore?: () => any      // 返回 loadingStore（可选，用于全局 loading 结束）
-  authLoginUrl?: string            // 统一登录地址（不传则默认 /auth/#/login）
-  ssoStorageKey?: string           // 统一登录本地缓存 key，默认 'user-store'
-}
+import { setupPortalApp } from '@litianxiang/portal-core'
+
+setupPortalApp({
+  app,
+  plugins: [router, pinia],
+  elementIcons: ElementPlusIconsVue,
+  mountSelector: '#app'
+})
+```
 
-// 生成一个“退出到统一登录”的函数，一般在 http 拦截器或手动退出按钮中调用
-function createLogoutToAuth(options: LogoutOptions): () => void
+### router
 
-// 计算基于最后一次操作时间的“是否需要退出/刷新 token”等动作
-interface InactivityOptions {
-  expireMs?: number   // token 允许的最大空闲时间，默认 2 小时
-  bufferMs?: number   // 提前刷新 token 的缓冲时间，默认 5 分钟
-}
+- `createAppRouter(options)`：创建统一路由实例，内置登录态校验、菜单动态挂载、首屏跳转逻辑。
 
-function calcInactivityAction(
-  lastActiveTime: number | null | undefined,
-  now: number,
-  options?: InactivityOptions
-): {
-  shouldLogout: boolean
-  shouldRefresh: boolean
-  inactiveMs: number
-  expireMs: number
-  bufferMs: number
-}
+最小示例：
+
+```ts
+import { createAppRouter } from '@litianxiang/portal-core'
+
+const router = createAppRouter({
+  staticRoutes,
+  getUserStore: () => useUserStore(),
+  getFirstPage: (allMenu) => allMenu.find((m: any) => m.category === 'page')?.path
+})
 ```
 
-`http` 相关工具简化说明：
+### auth
+
+- `createLogoutToAuth(options)`：生成统一退出函数，负责清理用户态并跳转到认证站。
+- `calcInactivityAction(lastActiveTime, now, config)`：根据空闲时长计算是否应刷新 token 或强制退出。
+
+最小示例：
 
 ```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
-}
+import { createLogoutToAuth, calcInactivityAction } from '@litianxiang/portal-core'
+
+const logoutToAuth = createLogoutToAuth({
+  getUserStore: () => useUserStore(),
+  getLoadingStore: () => useLoadingStore()
+})
 
-function createAuthHttpClient(options: CreateAuthHttpClientOptions): {
-  http: any                // 已挂好请求/响应拦截器的 axios 实例
-  logoutToAuth: () => void // 同 createLogoutToAuth，便于复用
+const { shouldLogout, shouldRefresh } = calcInactivityAction(lastActiveTime, Date.now())
+if (shouldLogout) logoutToAuth()
+if (shouldRefresh) {
+  // 执行刷新 token
 }
 ```
 
-`permission` 相关工具简化说明：
+### http
+
+- `createAuthHttpClient(options)`：创建带认证拦截器的 HTTP 客户端（Loading、token 注入、401 处理、刷新 token）。
+- `createPortalHttpClient(options)`：业务项目 HTTP 初始化便捷封装，减少重复模板代码。
+
+最小示例：
 
 ```ts
-interface PermissionHelperOptions {
-  // 返回用户 Store 实例，需至少提供 getUserALLMenu 或 getUserPageMenu
-  getUserStore: () => any
-}
+import axios from 'axios'
+import { createAuthHttpClient, createPortalHttpClient } from '@litianxiang/portal-core'
 
-interface PermissionHelper {
-  // 判断是否拥有某个页面（路由）权限
-  hasPagePermission: (path: string) => boolean
-  // 判断是否拥有某个按钮权限（约定使用菜单 path 作为唯一标识）
-  hasButtonPermission: (codeOrPath: string) => boolean
-  // 判断是否拥有给定列表中的任意一个权限
-  hasAnyPermission: (codesOrPaths: string[]) => boolean
-}
+const { http } = createAuthHttpClient({
+  axios,
+  getUserStore: () => useUserStore(),
+  getLoadingStore: () => useLoadingStore()
+})
 
-function createPermissionHelper(options: PermissionHelperOptions): PermissionHelper
-```
-```
+await http.post('/api/demo', {})
 
-## 子系统接入步骤
+// 业务项目推荐直接使用便捷封装
+const { http: portalHttp } = createPortalHttpClient({
+  axios,
+  getUserStore: () => useUserStore(),
+  getLoadingStore: () => useLoadingStore()
+})
+```
 
-以某业务系统为例（如 hr.kq）：
+### config
 
-### 1. 定义静态路由 staticRoutes
+- `getDefaultAuthLoginUrl()`：基于当前域名生成默认统一登录地址。
 
-静态路由中至少包含主布局 `main`，后续所有菜单页面都会挂到 `main` 下面：
+最小示例：
 
 ```ts
-// src/router/routes.ts
-import type { RouteRecordRaw } from 'vue-router'
-
-export const staticRoutes: RouteRecordRaw[] = [
-  {
-    path: '/',
-    name: 'layout',
-    component: () => import('@/views/layout/index.vue'),
-    children: [
-      {
-        path: '',
-        name: 'main',
-        component: () => import('@/views/main/index.vue')
-      }
-    ]
-  }
-]
+import { getDefaultAuthLoginUrl } from '@litianxiang/portal-core'
+
+const authLoginUrl = getDefaultAuthLoginUrl()
 ```
 
-注意：
+### permission
+
+- `createPermissionHelper(options)`：创建权限判断工具（页面权限、按钮权限、任一权限命中）。
+
+最小示例：
 
-- `createAppRouter` 会把所有菜单对应的动态路由挂到 `name: 'main'` 下面，请确保静态路由中存在 `name: 'main'`。
+```ts
+import { createPermissionHelper } from '@litianxiang/portal-core'
 
-### 2. 准备 Pinia 的 userStore
+const permission = createPermissionHelper({ getUserStore: () => useUserStore() })
+const canVisit = permission.hasPagePermission('/system/user')
+const canCreate = permission.hasButtonPermission('/system/user:add')
+```
 
-userStore 需要提供以下能力（命名可自定义）：
+### menu
 
-- `getUserAccessToken`：当前用户的访问 token（getter）
-- `syncFromAuthStore()`：从统一登录站点恢复登录态，返回 boolean
-- `isMenuLoaded`：菜单是否已加载（boolean）
-- `getUserALLMenu`：拍平后的菜单数组（用于 `getFirstPage`、挂载动态路由）
-- `resetMenuLoaded()`：重置菜单加载状态
-- `fetchUserMenu()`：拉取菜单并填充 `getUserALLMenu`、`isMenuLoaded`，返回 boolean 是否成功
+- `createMenuHelper(options)`：创建菜单辅助工具，提供路径查找、标题、父链、面包屑能力。
+- `transformMenuTree(menuList, options)`：将后端菜单转换为标准 `CoreMenuItem` 结构。
+- `buildAllMenuTree(menuList)`：构建完整菜单树（含页面与按钮）。
+- `buildPageMenuList(menuList)`：从完整树裁剪 page/button 结构。
+- `findFirstPagePath(menuList)`：递归查找第一个可访问页面路径。
 
-示例（仅展示接口形态）：
+最小示例：
 
 ```ts
-export const useUserStore = defineStore('user', {
-  state: () => ({
-    accessToken: '',
-    menuLoaded: false,
-    allMenu: []
-  }),
-  getters: {
-    getUserAccessToken: state => state.accessToken,
-    isMenuLoaded: state => state.menuLoaded,
-    getUserALLMenu: state => state.allMenu
-  },
-  actions: {
-    syncFromAuthStore() {
-      // 从统一认证站点恢复 token，成功返回 true
-    },
-    resetMenuLoaded() {
-      this.menuLoaded = false
-      this.allMenu = []
-    },
-    async fetchUserMenu() {
-      // 1. 请求后端菜单树
-      // 2. 转成拍平的 allMenu
-      // 3. this.menuLoaded = true
-      // 返回 true / false 表示是否成功
-    }
-  }
-})
-```
+import {
+  createMenuHelper,
+  transformMenuTree,
+  buildAllMenuTree,
+  buildPageMenuList,
+  findFirstPagePath
+} from '@litianxiang/portal-core'
 
-### 3. 准备 Tab Store（可选）
+const tree = transformMenuTree(rawMenu)
+const allMenu = buildAllMenuTree(tree)
+const pageMenu = buildPageMenuList(allMenu)
+const firstPath = findFirstPagePath(allMenu)
 
-Tab Store 主要用于和各系统的 Tab 控件协作，例如在“手动退出”时统一关闭所有可关闭的 Tab。当前路由内核在菜单加载 / 刷新场景下不会自动清空 Tab。
+const helper = createMenuHelper({ getMenuTree: () => allMenu })
+const breadcrumb = helper.getBreadcrumb('/system/user')
+```
 
-建议至少包含：
+### user
 
-- `closeAll()`：关闭所有可关闭的 Tab（保留固定首页等不可关闭项）
+- `createBaseUserState()`：创建基础用户状态（不含菜单）。
+- `createBaseUserGetters()`：创建基础用户 getters（工号/姓名/token/最后活跃时间）。
+- `createBaseUserActions(options?)`：创建基础用户 actions（set/clear/syncFromAuthStore）。
+- `createMenuUserState()`：创建管理站点用户状态（含 all_menu/sidebar_menu/menuLoaded）。
+- `createMenuUserGetters()`：创建管理站点用户 getters（含菜单相关 getters）。
+- `createMenuUserActions(options)`：创建管理站点 actions（菜单加载、SSO 恢复、状态维护）。
+- `filterSidebarMenu(menus, options?)`：递归过滤不应在侧边栏展示的菜单类别。
+- `syncFromAuthStoreToStore(store, options?)`：从统一登录缓存恢复用户信息到 store。
+- `fetchUserMenuForStore(store, options)`：请求后端菜单并写入 `all_menu/sidebar_menu`。
 
-示例：
+最小示例：
 
 ```ts
-export const useTabStore = defineStore('tab', {
-  actions: {
-    closeAll() {
-      // 关闭所有可关闭的 Tab（保留固定首页等不可关闭项）
-    }
-  }
-})
+import {
+  createBaseUserState,
+  createBaseUserGetters,
+  createBaseUserActions,
+  createMenuUserState,
+  createMenuUserGetters,
+  createMenuUserActions,
+  filterSidebarMenu,
+  syncFromAuthStoreToStore,
+  fetchUserMenuForStore
+} from '@litianxiang/portal-core'
+
+// 轻量站点
+const baseState = createBaseUserState()
+const baseGetters = createBaseUserGetters()
+const baseActions = createBaseUserActions()
+
+// 管理站点
+const menuState = createMenuUserState()
+const menuGetters = createMenuUserGetters()
+const menuActions = createMenuUserActions({ http, site: 'manage', transformMenuData, getALLMenu })
+
+const restored = syncFromAuthStoreToStore(menuState)
+const sidebar = filterSidebarMenu(menuState.all_menu)
+await fetchUserMenuForStore(menuState, { http, site: 'manage', transformMenuData, getALLMenu })
 ```
 
-### 4. 实现 getFirstPage
+### tab
+
+- `addTab(tabs, tab)`：新增标签页（同路径不重复）。
+- `removeTab(tabs, path)`：按路径删除标签页。
+- `closeOthers(tabs, path, homePath?)`：关闭除当前与首页外的标签页。
+- `closeLeft(tabs, path, homePath?)`：关闭当前左侧标签页（首页保留）。
+- `closeRight(tabs, path, homePath?)`：关闭当前右侧标签页（首页保留）。
+- `closeAll(tabs)`：关闭全部可关闭标签页。
+- `createTabStoreOptions(homePath?)`：生成可直接用于 Pinia 的 Tab Store 配置。
 
-根据拍平的菜单数组 `allMenu`，返回“第一个业务页面”的完整路径（可带 query）：
+最小示例：
 
 ```ts
-export function getFirstPage(allMenu: any[]): string | null {
-  // 例如：返回第一个 category === 'page' 的 path
-  const item = allMenu.find(m => m.category === 'page')
-  return item?.path || null
-}
+import {
+  addTab,
+  removeTab,
+  closeOthers,
+  closeLeft,
+  closeRight,
+  closeAll,
+  createTabStoreOptions
+} from '@litianxiang/portal-core'
+
+let tabs = addTab([], { title: '首页', path: '/main/home', closable: false, keepAlive: true })
+tabs = addTab(tabs, { title: '用户管理', path: '/system/user', closable: true, keepAlive: true })
+tabs = closeOthers(tabs, '/system/user')
+tabs = closeLeft(tabs, '/system/user')
+tabs = closeRight(tabs, '/system/user')
+tabs = removeTab(tabs, '/system/user')
+tabs = closeAll(tabs)
+
+const tabStoreOptions = createTabStoreOptions('/main/home')
 ```
 
-> 注意：如果返回值中包含查询参数（例如 `'/kq/leave?type=1'`），`createAppRouter` 会自动帮你拆分 path 和 query。
+### loading
+
+- `createLoadingStoreOptions()`：生成可直接用于 Pinia 的 Loading Store 配置。
 
-### 5. 在 router/index.ts 中使用 createAppRouter
+最小示例：
 
 ```ts
-// src/router/index.ts
-import { createAppRouter } from '@litianxiang/portal-core'
-import { useUserStore } from '@/stores/user'
-import { useTabStore } from '@/stores/tab'
-import { staticRoutes } from './routes'
-import { getFirstPage } from '@/utils/menu'
+import { createLoadingStoreOptions } from '@litianxiang/portal-core'
 
-const router = createAppRouter({
-  staticRoutes,
-  getUserStore: () => useUserStore(),
-  getTabStore: () => useTabStore(),
-  getFirstPage,
-  authLoginUrl: import.meta.env.VITE_AUTH_LOGIN_URL // 可选
-})
+const loadingStoreOptions = createLoadingStoreOptions()
+```
 
-export default router
+### time
+
+- `formatTime(date, format?)`：按指定格式输出时间字符串。
+- `humanizeTime(date)`：输出相对时间（如“3分钟前”）。
+- `timeDiff(start, end?)`：计算时间差（毫秒）。
+- `formatToMonthDay(date)`：格式化为 `MM-DD`。
+- `createRange(start, end)`：生成有序时间区间（自动处理先后）。
+- `formatRange(start, end, format?)`：格式化时间区间字符串。
+- `getPresetRange(key, now?)`：获取常用预设区间（今日/近7天/本月等）。
+- `isInRange(value, range)`：判断时间是否落在区间内（含边界）。
+- `useTime()`：组合导出以上时间工具。
+
+最小示例：
+
+```ts
+import {
+  formatTime,
+  humanizeTime,
+  timeDiff,
+  formatToMonthDay,
+  createRange,
+  formatRange,
+  getPresetRange,
+  isInRange,
+  useTime
+} from '@litianxiang/portal-core'
+
+const t1 = formatTime(new Date())
+const t2 = humanizeTime(Date.now() - 60 * 1000)
+const diff = timeDiff('2026-01-01')
+const md = formatToMonthDay(new Date())
+const range = createRange('2026-01-01', '2026-01-31')
+const text = formatRange('2026-01-01', '2026-01-31')
+const preset = getPresetRange('last7days')
+const inRange = isInRange(new Date(), range)
+const timeUtils = useTime()
 ```
-### 6. 使用 createAuthHttpClient 统一封装 http（推荐）
 
-在各子系统的 http 封装中，推荐直接使用 `createAuthHttpClient`，即可一次性接入：
+### number
 
-- 全局 Loading 控制（基于 `getLoadingStore` 的 `startLoading/stopLoading`）
-- 基于最后操作时间的“2 小时未操作自动退出”
-- 距离过期 5 分钟以内自动刷新 access_token
-- 401 统一退出到认证站并弹出错误提示
+- `formatToYi(value, decimals?)`：按“亿元”单位格式化数值。
+- `formatToWanShou(value, decimals?)`：按“万手”单位格式化数值。
+- `formatWanYuanToYi(value, decimals?)`：将“万元”转换并格式化为“亿元”。
 
-示例：
+最小示例：
 
 ```ts
-// src/utils/http.ts
-import axios from 'axios'
-import { ElMessage } from 'element-plus'
-import { createAuthHttpClient } from '@litianxiang/portal-core'
-import { useUserStore } from '@/stores/user'
-import { useLoadingStore } from '@/stores/loading'
+import { formatToYi, formatToWanShou, formatWanYuanToYi } from '@litianxiang/portal-core'
 
-const AUTH_LOGIN_URL =
-  import.meta.env.VITE_AUTH_LOGIN_URL || `${window.location.origin}/auth/#/login`
+const a = formatToYi(123000000)
+const b = formatToWanShou(560000)
+const c = formatWanYuanToYi(50000)
+```
 
-const { http, logoutToAuth } = createAuthHttpClient({
-  axios,
-  baseURL: '',
-  timeout: 10000,
-  getUserStore: () => useUserStore(),
-  getLoadingStore: () => useLoadingStore(),
-  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)
-  }
-})
+### theme
 
-// 业务代码直接使用 http 即可
-// http.post('/api/demo', data)
+- `initTheme()`：从本地缓存读取主题配置并初始化。
+- `applyTheme(config)`：将主题变量应用到根节点 CSS 变量。
+- `useThemeWatcher(config)`：监听主题变化并自动持久化。
 
-export default http
-export { logoutToAuth }
+最小示例：
+
+```ts
+import { initTheme, applyTheme, useThemeWatcher } from '@litianxiang/portal-core'
+
+const theme = initTheme()
+applyTheme(theme)
+useThemeWatcher(theme)
 ```
 
-如需完全自定义 http 行为，也可以直接基于前面的 `auth` 工具自行编写拦截器。
+### i18n
 
-### 7.（可选）接入菜单 / 按钮权限判断
+- `createPortalI18n(options)`：创建并返回统一配置的 `vue-i18n` 实例。
 
-在需要做“是否显示某个按钮”或“是否放行某个页面”时，可以使用 `createPermissionHelper` 来基于菜单数据做权限判断：
+最小示例：
 
 ```ts
-// 例如在某个业务系统的全局 helper 中：
-import { createPermissionHelper } from '@litianxiang/portal-core'
-import { useUserStore } from '@/stores/user'
+import { createPortalI18n } from '@litianxiang/portal-core'
 
-const permission = createPermissionHelper({
-  getUserStore: () => useUserStore()
+const i18n = createPortalI18n({
+  messages: {
+    'zh-CN': { common: { ok: '确定' } },
+    'en-US': { common: { ok: 'OK' } }
+  }
 })
+```
 
-// 页面/路由级权限判断（基于菜单的 path，忽略 query 部分）
-permission.hasPagePermission('/system/menu')
+## 业务方约定
 
-// 按钮权限判断（约定后台为按钮类型菜单配置唯一的 path 作为权限码）
-permission.hasButtonPermission('/system/menu:add')
+### userStore（最小能力）
 
-// 任一权限命中即通过（可用于复杂场景）
-permission.hasAnyPermission([
-  '/system/menu:add',
-  '/system/menu:edit'
-])
-```
+- `getUserAccessToken`
+- `getUserRefreshToken`
+- `getUserLastActiveTime`
+- `setUserAccessToken(token)`
+- `setUserRefreshToken(token)`
+- `setUserLastActiveTime(ts)`
+- `syncFromAuthStore()`
+- `clearUserInfo()`
 
-> 说明：
-> - `createPermissionHelper` 内部会优先使用 `userStore.getUserPageMenu`（包含 page + button），若不存在则退回 `userStore.getUserALLMenu`；
-> - 匹配时仅按基础路径（去掉 `?query`）比较，避免 query 影响权限判断。
+管理站点再补充：
 
-### 8. 项目视图目录约定
+- `isMenuLoaded`
+- `resetMenuLoaded()`
+- `fetchUserMenu()`
+- `getUserALLMenu`
 
-`portal-core` 会根据后端菜单返回的 `path` 去匹配前端视图，规则如下：
+### 路由结构约定
 
-- 优先从 `/src/views/main` 下查找：`/src/views/main${path}.vue`
-- 若找不到，再从 `/src/views` 根目录查找：`/src/views${path}.vue`
+`createAppRouter` 会把动态菜单路由挂到 `name: 'main'` 的节点下，业务静态路由需提供该节点。
 
-例如：
+### 视图解析约定
 
-- 菜单 path 为 `/system/user`，会尝试匹配：
-  - `/src/views/main/system/user.vue`
-  - `/src/views/system/user.vue`
-- 若都不存在，会默认认为在 `/src/views/main/system/user.vue`，方便排查。
+菜单 path 会按以下优先级解析视图：
 
-请保证你的业务页面按上述规则存放文件。
+1. `/src/views/main${path}.vue`
+2. `/src/views${path}.vue`
 
-## 路由行为概要
+## 常见问题
 
-接入后，路由的关键行为如下：
+### 1) 刷新后跳登录
 
-- 每次路由跳转前：
-  - 若本地无 token，会尝试通过 `syncFromAuthStore()` 从统一登录站点恢复；
-  - 若仍无 token，则跳转到 `authLoginUrl`，并携带当前地址作为 `redirect`；
-- 若用户已登录但菜单未加载：
-  - 会清空之前的动态路由，并通过 `resetMenuLoaded()` 重置菜单状态；
-  - 调用 `fetchUserMenu()` 拉取菜单，成功后：
-    - 按菜单生成动态路由并挂到 `main` 下；
-    - 若当前访问的是根路径 `/`，会根据 `getFirstPage(allMenu)` 计算首页路径并重定向过去；
-    - 若当前访问的是具体业务路径（例如刷新了某个子页面），则保持在当前路径，不强制跳转，Tab 也不会被清空；
-- 若菜单已加载且访问根路径 `/`：
-  - 仅将 `/` 映射到 `getFirstPage(allMenu)` 对应的页面，不再清空 Tab。
+先检查 `syncFromAuthStore()` 是否正确从统一登录缓存恢复 token。
+
+### 2) 401 循环跳转
+
+检查是否重复创建多个 http 实例，或在 401 处理中重复手动跳转。
+
+### 3) 菜单加载后白屏
+
+检查菜单 path 与实际视图文件是否匹配（含 `/main` 约定）。
+
+## 本地开发
+
+```bash
+pnpm install
+pnpm run build
+pnpm run pack:check
+```
 
-这样可以保证：
+## 发布流程
 
-- 登录后总是落在第一个业务页面；
-- 刷新页面或重新打开浏览器时，能自动恢复登录并重新加载菜单，同时尽量停留在当前业务页面和已有 Tab 上；
-- 不同子系统之间互不干扰，只共享统一登录站点。
+1. 更新版本号（patch 递增）
+2. 执行 `pnpm run pack:check`
+3. 发布：`npm publish --access public --registry=https://registry.npmjs.org/`

package/dist/index.d.ts

@@ -69,6 +69,30 @@ interface CreateAuthHttpClientOptions {
     inactiveBufferMs?: number;
     onShowError?: (msg: string) => void;
 }
+interface CreatePortalHttpClientOptions {
+    axios?: any;
+    baseURL?: string;
+    timeout?: number;
+    getUserStore: () => any;
+    getLoadingStore: () => any;
+    authLoginUrl?: string;
+    ssoStorageKey?: string;
+    refreshUrl?: string;
+    inactiveExpireMs?: number;
+    inactiveBufferMs?: number;
+    onShowError?: (msg: string) => void;
+}
+/**
+ * 创建业务项目通用 HTTP 客户端（createAuthHttpClient 的便捷封装）。
+ *
+ * 作用：
+ * - 统一管理端项目中的标准 HTTP 初始化写法
+ * - 复用 portal-core 认证拦截器能力
+ */
+declare function createPortalHttpClient(options: CreatePortalHttpClientOptions): {
+    http: any;
+    logoutToAuth: () => void;
+};
 declare function createAuthHttpClient(options: CreateAuthHttpClientOptions): {
     http: any;
     logoutToAuth: () => void;
@@ -94,6 +118,9 @@ interface PermissionHelper {
      */
     hasAnyPermission: (codesOrPaths: string[]) => boolean;
 }
+/**
+ * 创建统一权限判断工具，提供页面权限、按钮权限和任意权限判断。
+ */
 declare function createPermissionHelper(options: PermissionHelperOptions): PermissionHelper;
 
 interface MenuHelperOptions {
@@ -126,6 +153,9 @@ interface MenuHelper {
      */
     getBreadcrumb: (path: string) => BreadcrumbItem[];
 }
+/**
+ * 创建菜单辅助工具，统一提供查找、标题、链路、父级与面包屑能力。
+ */
 declare function createMenuHelper(options: MenuHelperOptions): MenuHelper;
 /**
  * 标准化后的菜单节点结构，供各前端站点复用
@@ -212,6 +242,9 @@ declare function getPresetRange(key: PresetRangeKey, now?: TimeInput): TimeRange
  * 判断某个时间是否在区间内（含边界）
  */
 declare function isInRange(value: TimeInput, range: TimeRange<TimeInput>): boolean;
+/**
+ * 组合导出时间工具方法，便于在业务中按对象方式使用。
+ */
 declare function useTime(): {
     formatTime: typeof formatTime;
     humanizeTime: typeof humanizeTime;
@@ -262,11 +295,29 @@ interface TabItem {
     keepAlive: boolean;
 }
 declare const DEFAULT_HOME_PATH = "/main/home";
+/**
+ * 向标签页列表追加新标签；若路径已存在则保持原列表。
+ */
 declare function addTab(tabs: TabItem[], tab: TabItem): TabItem[];
+/**
+ * 根据路径移除指定标签页。
+ */
 declare function removeTab(tabs: TabItem[], path: string): TabItem[];
+/**
+ * 关闭除当前与首页外的其他标签页。
+ */
 declare function closeOthers(tabs: TabItem[], path: string, homePath?: string): TabItem[];
+/**
+ * 关闭当前标签左侧的标签页（首页始终保留）。
+ */
 declare function closeLeft(tabs: TabItem[], path: string, homePath?: string): TabItem[];
+/**
+ * 关闭当前标签右侧的标签页（首页始终保留）。
+ */
 declare function closeRight(tabs: TabItem[], path: string, homePath?: string): TabItem[];
+/**
+ * 关闭所有可关闭标签，仅保留不可关闭项。
+ */
 declare function closeAll(tabs: TabItem[]): TabItem[];
 /**
  * 为 Pinia 创建通用的 Tab Store 配置
@@ -305,7 +356,14 @@ interface BaseUserStoreLike {
     refresh_token: string;
     lastActiveTime: number | null;
 }
+/**
+ * 创建基础用户状态（不含菜单）。
+ * 适用于 portal.web、portal.auth.web 等轻量站点。
+ */
 declare function createBaseUserState(): BaseUserStoreLike;
+/**
+ * 创建基础用户 getters（不含菜单）。
+ */
 declare function createBaseUserGetters(): {
     getUserInfo: (state: any) => {
         userno: any;
@@ -324,6 +382,9 @@ interface CreateBaseUserActionsOptions {
     /** SSO 缓存 key，默认读取 AUTH_CONFIG.ssoStorageKey */
     ssoStorageKey?: string;
 }
+/**
+ * 创建基础用户 actions（不含菜单）。
+ */
 declare function createBaseUserActions(options?: CreateBaseUserActionsOptions): {
     setUserInfo(this: BaseUserStoreLike, userInfo: any): void;
     setUserAccessToken(this: BaseUserStoreLike, access_token: string): void;
@@ -341,7 +402,14 @@ interface CoreMenuUserState<TMenu = any> extends CoreUserStoreLike {
     all_menu: TMenu[];
     sidebar_menu: TMenu[];
 }
+/**
+ * 创建管理站点用户状态（含菜单）。
+ * 适用于带动态菜单的后台系统。
+ */
 declare function createMenuUserState<TMenu = any>(): CoreMenuUserState<TMenu>;
+/**
+ * 创建管理站点用户 getters（含菜单）。
+ */
 declare function createMenuUserGetters<TUserInfo = any>(): {
     getUserInfo: (state: any) => TUserInfo;
     getUserNo: (state: any) => any;
@@ -388,6 +456,9 @@ interface CreateMenuUserActionsOptions {
     filterOptions?: SidebarMenuFilterOptions;
     ssoStorageKey?: string;
 }
+/**
+ * 创建管理站点用户 actions（含菜单请求、菜单状态维护、SSO 恢复）。
+ */
 declare function createMenuUserActions(options: CreateMenuUserActionsOptions): {
     setUserInfo(this: CoreUserStoreLike, userInfo: any): void;
     setUserAccessToken(this: CoreUserStoreLike, access_token: string): void;
@@ -455,6 +526,13 @@ interface SetupPortalAppOptions {
     beforeMount?: () => void;
     mountSelector?: string;
 }
+/**
+ * 按 Portal 约定完成应用启动编排：
+ * 1. 注册插件
+ * 2. 注册 Element Plus 图标
+ * 3. 执行挂载前回调
+ * 4. 挂载应用
+ */
 declare function setupPortalApp(options: SetupPortalAppOptions): void;
 
 interface CreateI18nOptions {
@@ -473,4 +551,4 @@ interface CreateI18nOptions {
  */
 declare function createPortalI18n(options: CreateI18nOptions): vue_i18n.I18n<Record<string, any>, {}, {}, string, false>;
 
-export { AUTH_CONFIG, type AppRouterOptions, type AuthConfig, type BaseUserStoreLike, type BreadcrumbItem, type CoreMenuItem, type CoreMenuUserState, type CoreUserStoreLike, type CreateAuthHttpClientOptions, type CreateBaseUserActionsOptions, type CreateI18nOptions, type CreateMenuUserActionsOptions, DEFAULT_AUTH_LOGIN_ENV_KEY, DEFAULT_AUTH_LOGIN_PATH, DEFAULT_HOME_PATH, DEFAULT_SSO_STORAGE_KEY, type FetchUserMenuForStoreOptions, type FontSize, type InactivityConfig, type InactivityResult, type LoadingState, type LogoutToAuthOptions, type MenuHelper, type MenuHelperOptions, type PermissionHelper, type PermissionHelperOptions, type PresetRangeKey, type SetupPortalAppOptions, type SidebarMenuFilterOptions, type SyncFromAuthStoreOptions, type TabItem, type ThemeConfig, type ThemeMode, type TimeInput, type TimeRange, type TransformMenuOptions, addTab, applyTheme, buildAllMenuTree, buildPageMenuList, calcInactivityAction, closeAll, closeLeft, closeOthers, closeRight, createAppRouter, createAuthHttpClient, createBaseUserActions, createBaseUserGetters, createBaseUserState, createLoadingStoreOptions, createLogoutToAuth, createMenuHelper, createMenuUserActions, createMenuUserGetters, createMenuUserState, createPermissionHelper, createPortalI18n, createRange, createTabStoreOptions, fetchUserMenuForStore, filterSidebarMenu, findFirstPagePath, formatRange, formatTime, formatToMonthDay, formatToWanShou, formatToYi, formatWanYuanToYi, getDefaultAuthLoginUrl, getPresetRange, humanizeTime, initTheme, isInRange, removeTab, setupPortalApp, syncFromAuthStoreToStore, timeDiff, transformMenuTree, useThemeWatcher, useTime };
+export { AUTH_CONFIG, type AppRouterOptions, type AuthConfig, type BaseUserStoreLike, type BreadcrumbItem, type CoreMenuItem, type CoreMenuUserState, type CoreUserStoreLike, type CreateAuthHttpClientOptions, type CreateBaseUserActionsOptions, type CreateI18nOptions, type CreateMenuUserActionsOptions, type CreatePortalHttpClientOptions, DEFAULT_AUTH_LOGIN_ENV_KEY, DEFAULT_AUTH_LOGIN_PATH, DEFAULT_HOME_PATH, DEFAULT_SSO_STORAGE_KEY, type FetchUserMenuForStoreOptions, type FontSize, type InactivityConfig, type InactivityResult, type LoadingState, type LogoutToAuthOptions, type MenuHelper, type MenuHelperOptions, type PermissionHelper, type PermissionHelperOptions, type PresetRangeKey, type SetupPortalAppOptions, type SidebarMenuFilterOptions, type SyncFromAuthStoreOptions, type TabItem, type ThemeConfig, type ThemeMode, type TimeInput, type TimeRange, type TransformMenuOptions, addTab, applyTheme, buildAllMenuTree, buildPageMenuList, calcInactivityAction, closeAll, closeLeft, closeOthers, closeRight, createAppRouter, createAuthHttpClient, createBaseUserActions, createBaseUserGetters, createBaseUserState, createLoadingStoreOptions, createLogoutToAuth, createMenuHelper, createMenuUserActions, createMenuUserGetters, createMenuUserState, createPermissionHelper, createPortalHttpClient, createPortalI18n, createRange, createTabStoreOptions, fetchUserMenuForStore, filterSidebarMenu, findFirstPagePath, formatRange, formatTime, formatToMonthDay, formatToWanShou, formatToYi, formatWanYuanToYi, getDefaultAuthLoginUrl, getPresetRange, humanizeTime, initTheme, isInRange, removeTab, setupPortalApp, syncFromAuthStoreToStore, timeDiff, transformMenuTree, useThemeWatcher, useTime };

package/dist/index.js

@@ -458,6 +458,13 @@ function calcInactivityAction(lastActiveTime, now, config = {}) {
 
 // src/http/http.ts
 import axiosLib from "axios";
+function createPortalHttpClient(options) {
+  return createAuthHttpClient({
+    baseURL: "",
+    timeout: 1e4,
+    ...options
+  });
+}
 function createAuthHttpClient(options) {
   const {
     axios,
@@ -1200,6 +1207,7 @@ export {
   createMenuUserGetters,
   createMenuUserState,
   createPermissionHelper,
+  createPortalHttpClient,
   createPortalI18n,
   createRange,
   createTabStoreOptions,

package/package.json

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