@litianxiang/portal-core 0.1.21 → 0.1.23

package/README.md

@@ -1,373 +1,416 @@
-# @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
+### app
 
-`auth` 相关工具简化说明：
+- `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'
 
-// 生成一个“退出到统一登录”的函数，一般在 http 拦截器或手动退出按钮中调用
-function createLogoutToAuth(options: LogoutOptions): () => void
+setupPortalApp({
+  app,
+  plugins: [router, pinia],
+  elementIcons: ElementPlusIconsVue,
+  mountSelector: '#app'
+})
+```
 
-// 计算基于最后一次操作时间的“是否需要退出/刷新 token”等动作
-interface InactivityOptions {
-  expireMs?: number   // token 允许的最大空闲时间，默认 2 小时
-  bufferMs?: number   // 提前刷新 token 的缓冲时间，默认 5 分钟
-}
+### router
 
-function calcInactivityAction(
-  lastActiveTime: number | null | undefined,
-  now: number,
-  options?: InactivityOptions
-): {
-  shouldLogout: boolean
-  shouldRefresh: boolean
-  inactiveMs: number
-  expireMs: number
-  bufferMs: number
-}
+- `createAppRouter(options)`：创建统一路由实例，内置登录态校验、菜单动态挂载、首屏跳转逻辑。
+
+最小示例：
+
+```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'
 
-function createAuthHttpClient(options: CreateAuthHttpClientOptions): {
-  http: any                // 已挂好请求/响应拦截器的 axios 实例
-  logoutToAuth: () => void // 同 createLogoutToAuth，便于复用
+const logoutToAuth = createLogoutToAuth({
+  getUserStore: () => useUserStore(),
+  getLoadingStore: () => useLoadingStore()
+})
+
+const { shouldLogout, shouldRefresh } = calcInactivityAction(lastActiveTime, Date.now())
+if (shouldLogout) logoutToAuth()
+if (shouldRefresh) {
+  // 执行刷新 token
 }
 ```
 
-`permission` 相关工具简化说明：
+### http
+
+- `createAuthHttpClient(options)`：创建带认证拦截器的 HTTP 客户端（Loading、token 注入、401 处理、刷新 token）。
+
+最小示例：
 
 ```ts
-interface PermissionHelperOptions {
-  // 返回用户 Store 实例，需至少提供 getUserALLMenu 或 getUserPageMenu
-  getUserStore: () => any
-}
+import axios from 'axios'
+import { createAuthHttpClient } 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', {})
 ```
-```
-
-## 子系统接入步骤
 
-以某业务系统为例（如 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
 
-- `createAppRouter` 会把所有菜单对应的动态路由挂到 `name: 'main'` 下面，请确保静态路由中存在 `name: 'main'`。
+- `createPermissionHelper(options)`：创建权限判断工具（页面权限、按钮权限、任一权限命中）。
 
-### 2. 准备 Pinia 的 userStore
+最小示例：
 
-userStore 需要提供以下能力（命名可自定义）：
+```ts
+import { createPermissionHelper } from '@litianxiang/portal-core'
+
+const permission = createPermissionHelper({ getUserStore: () => useUserStore() })
+const canVisit = permission.hasPagePermission('/system/user')
+const canCreate = permission.hasButtonPermission('/system/user:add')
+```
 
-- `getUserAccessToken`：当前用户的访问 token（getter）
-- `syncFromAuthStore()`：从统一登录站点恢复登录态，返回 boolean
-- `isMenuLoaded`：菜单是否已加载（boolean）
-- `getUserALLMenu`：拍平后的菜单数组（用于 `getFirstPage`、挂载动态路由）
-- `resetMenuLoaded()`：重置菜单加载状态
-- `fetchUserMenu()`：拉取菜单并填充 `getUserALLMenu`、`isMenuLoaded`，返回 boolean 是否成功
+### menu
 
-示例（仅展示接口形态）：
+- `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
 
-根据拍平的菜单数组 `allMenu`，返回“第一个业务页面”的完整路径（可带 query）：
+- `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 配置。
+
+最小示例：
 
 ```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
 
-### 5. 在 router/index.ts 中使用 createAppRouter
+- `createLoadingStoreOptions()`：生成可直接用于 Pinia 的 Loading Store 配置。
+
+最小示例：
 
 ```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
+
+- `initTheme()`：从本地缓存读取主题配置并初始化。
+- `applyTheme(config)`：将主题变量应用到根节点 CSS 变量。
+- `useThemeWatcher(config)`：监听主题变化并自动持久化。
 
-// 业务代码直接使用 http 即可
-// http.post('/api/demo', data)
+最小示例：
 
-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 影响权限判断。
+- `isMenuLoaded`
+- `resetMenuLoaded()`
+- `fetchUserMenu()`
+- `getUserALLMenu`
 
-### 8. 项目视图目录约定
+### 路由结构约定
 
-`portal-core` 会根据后端菜单返回的 `path` 去匹配前端视图，规则如下：
+`createAppRouter` 会把动态菜单路由挂到 `name: 'main'` 的节点下，业务静态路由需提供该节点。
 
-- 优先从 `/src/views/main` 下查找：`/src/views/main${path}.vue`
-- 若找不到，再从 `/src/views` 根目录查找：`/src/views${path}.vue`
+### 视图解析约定
 
-例如：
+菜单 path 会按以下优先级解析视图：
 
-- 菜单 path 为 `/system/user`，会尝试匹配：
-  - `/src/views/main/system/user.vue`
-  - `/src/views/system/user.vue`
-- 若都不存在，会默认认为在 `/src/views/main/system/user.vue`，方便排查。
+1. `/src/views/main${path}.vue`
+2. `/src/views${path}.vue`
 
-请保证你的业务页面按上述规则存放文件。
+## 常见问题
 
-## 路由行为概要
+### 1) 刷新后跳登录
 
-接入后，路由的关键行为如下：
+先检查 `syncFromAuthStore()` 是否正确从统一登录缓存恢复 token。
 
-- 每次路由跳转前：
-  - 若本地无 token，会尝试通过 `syncFromAuthStore()` 从统一登录站点恢复；
-  - 若仍无 token，则跳转到 `authLoginUrl`，并携带当前地址作为 `redirect`；
-- 若用户已登录但菜单未加载：
-  - 会清空之前的动态路由，并通过 `resetMenuLoaded()` 重置菜单状态；
-  - 调用 `fetchUserMenu()` 拉取菜单，成功后：
-    - 按菜单生成动态路由并挂到 `main` 下；
-    - 若当前访问的是根路径 `/`，会根据 `getFirstPage(allMenu)` 计算首页路径并重定向过去；
-    - 若当前访问的是具体业务路径（例如刷新了某个子页面），则保持在当前路径，不强制跳转，Tab 也不会被清空；
-- 若菜单已加载且访问根路径 `/`：
-  - 仅将 `/` 映射到 `getFirstPage(allMenu)` 对应的页面，不再清空 Tab。
+### 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/`