create-bubbles 0.1.26 → 0.1.28

package/template-vp-monorepo-react-nestjs/apps/web/src/router/page-registry.tsx

@@ -0,0 +1,94 @@
+import type { AccessContext, AccessScope, MenuNode } from 'shared/types'
+import { accessRoutePath, filterSupportedAccessMenus } from 'shared/utils'
+import { SvgAssetIcon } from '@/components/Icon/SvgAsset'
+import { tr } from '@/i18n'
+
+/** 此表随 Web 发布；服务端下发的 routeKey 不能动态 import 任意组件。 */
+export const pageRegistry = {
+  'platform.home': { path: '', title: () => tr('平台工作台') },
+  'platform.companies': { path: 'companies', title: () => tr('企业管理') },
+  'platform.accounts': { path: 'accounts', title: () => tr('全局账号') },
+  'platform.roles': { path: 'roles', title: () => tr('平台角色') },
+  'platform.menus': { path: 'menus', title: () => tr('菜单管理') },
+  'platform.audit': { path: 'audit', title: () => tr('平台操作日志') },
+  'company.home': { path: '', title: () => tr('企业工作台') },
+  'company.profile': { path: 'profile', title: () => tr('企业资料') },
+  'company.members': { path: 'members', title: () => tr('企业成员') },
+  'company.roles': { path: 'roles', title: () => tr('企业角色') },
+  'company.organization': { path: 'organization', title: () => tr('企业组织架构') },
+  'company.positions': { path: 'positions', title: () => tr('企业岗位') },
+  'company.organization.templates': {
+    path: 'organization/templates',
+    title: () => tr('项目组织模板'),
+  },
+  'company.projects': { path: 'projects', title: () => tr('项目管理') },
+  'company.audit': { path: 'audit', title: () => tr('企业操作日志') },
+  'project.home': { path: '', title: () => tr('项目工作台') },
+  'project.profile': { path: 'profile', title: () => tr('项目资料') },
+  'project.members': { path: 'members', title: () => tr('项目成员') },
+  'project.roles': { path: 'roles', title: () => tr('项目角色') },
+  'project.organization': { path: 'organization', title: () => tr('项目组织架构') },
+  'project.positions': { path: 'positions', title: () => tr('项目岗位') },
+  'project.audit': { path: 'audit', title: () => tr('项目操作日志') },
+} as const
+
+export type RegisteredPage = keyof typeof pageRegistry
+export const registeredRouteKeys = Object.keys(pageRegistry)
+
+/** 仅为前端已注册的页面生成指定作用域路径，未知页面返回 null。 */
+export function pagePath(scope: AccessScope, routeKey: string) {
+  const page = pageRegistry[routeKey as RegisteredPage]
+  return page ? accessRoutePath({ scope, routeKey }) : null
+}
+
+/** 优先按可见菜单顺序寻找授权页面，再从已注册页面中兜底选择。 */
+export function firstAccessiblePagePath(context: AccessContext): string | null {
+  /** 仅为拥有读取权限的页面生成当前工作空间路径。 */
+  const allowedPath = (key: string) =>
+    context.permissionKeys.includes(`${key}.read`) ? pagePath(context.scope, key) : null
+  /** 深度优先遍历可见且启用的菜单，返回首个已授权页面路径。 */
+  const visit = (nodes: MenuNode[]): string | null => {
+    for (const node of nodes) {
+      if (node.hidden || node.status !== 'active' || node.type === 'operation') continue
+      const destination =
+        node.type === 'page' ? allowedPath(node.routeKey ?? '') : visit(node.children)
+      if (destination) return destination
+    }
+    return null
+  }
+  return (
+    visit(context.menus) ??
+    registeredRouteKeys.map(allowedPath).find((destination) => destination !== null) ??
+    null
+  )
+}
+
+interface NavigationItem {
+  key: string
+  name: string
+  path?: string
+  icon: ReactNode
+  routes?: NavigationItem[]
+}
+
+/** 过滤未发布和不可见功能，将有效菜单递归转换为布局导航数据。 */
+export function navigationTree(nodes: MenuNode[], scope: AccessScope): NavigationItem[] {
+  return filterSupportedAccessMenus({
+    menus: nodes,
+    supportedRouteKeys: registeredRouteKeys,
+  }).flatMap(
+    /** 丢弃不可导航节点，解析页面路径或递归生成目录下的有效导航项。 */ (
+      node,
+    ): NavigationItem[] => {
+      if (node.hidden || node.status !== 'active' || node.type === 'operation') return []
+      const icon = <SvgAssetIcon name={node.icon} />
+      if (node.type === 'page') {
+        const path = pagePath(scope, node.routeKey ?? '')
+        const page = pageRegistry[node.routeKey as RegisteredPage]
+        return path ? [{ key: path, path, name: page?.title() ?? node.name, icon }] : []
+      }
+      const routes = navigationTree(node.children, scope)
+      return routes.length ? [{ key: node.id, name: tr(node.name), icon, routes }] : []
+    },
+  )
+}

package/template-vp-monorepo-react-nestjs/apps/web/src/styles/dream.css

@@ -0,0 +1,34 @@
+@layer components {
+  :root {
+    --wanwu-ink: #302b49;
+    --wanwu-muted: #78718e;
+    --wanwu-accent: #7864c4;
+    --wanwu-lilac: #8270db;
+    --wanwu-fog: #f5f3fc;
+    --wanwu-ice: #dceefa;
+    --wanwu-rose: #f2dfef;
+    --wanwu-border: rgba(255, 255, 255, 0.85);
+    --wanwu-glass: rgba(255, 255, 255, 0.76);
+    --wanwu-shadow: 0 12px 40px rgba(91, 70, 144, 0.06);
+    --wanwu-atmosphere:
+      radial-gradient(ellipse at 84% 7%, #e6ddf6 0, transparent 44%),
+      radial-gradient(ellipse at 38% 95%, var(--wanwu-ice) 0, transparent 48%),
+      radial-gradient(ellipse at 2% 26%, var(--wanwu-rose) 0, transparent 44%), var(--wanwu-fog);
+  }
+
+  a:focus-visible,
+  button:focus-visible {
+    outline: 2px solid var(--wanwu-accent);
+    outline-offset: 4px;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+      scroll-behavior: auto !important;
+    }
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/web/src/styles/index.css

@@ -11,4 +11,10 @@
     min-height: 100%;
     margin: 0;
   }
+  body {
+    font-family: 'PingFang SC', 'Microsoft YaHei', 'Segoe UI', sans-serif;
+    color: #302b49;
+    background: #f5f3fc;
+    -webkit-font-smoothing: antialiased;
+  }
 }

package/template-vp-monorepo-react-nestjs/apps/web/src/types/auto-imports.d.ts

@@ -1,5 +1,7 @@
 /* eslint-disable */
 /* prettier-ignore */
+/* oxlint-disable */
+/* oxfmt-ignore */
 // @ts-nocheck
 // noinspection JSUnusedGlobalSymbols
 // Generated by unplugin-auto-import
@@ -8,14 +10,23 @@ export {}
 declare global {
   const Activity: typeof import('react').Activity
   const Fragment: typeof import('react').Fragment
+  const Link: typeof import('react-router').Link
+  const Outlet: typeof import('react-router').Outlet
+  const ReactViewTransition: typeof import('react').ViewTransition
+  const RouterProvider: typeof import('react-router').RouterProvider
   const Suspense: typeof import('react').Suspense
   const cache: typeof import('react').cache
   const cacheSignal: typeof import('react').cacheSignal
+  const createBrowserRouter: typeof import('react-router').createBrowserRouter
   const createContext: typeof import('react').createContext
+  const createMemoryRouter: typeof import('react-router').createMemoryRouter
   const createPortal: typeof import('react-dom').createPortal
   const createRef: typeof import('react').createRef
+  const createRoot: typeof import('react-dom/client').createRoot
+  const createRouterContext: typeof import('react-router').createContext
   const flushSync: typeof import('react-dom').flushSync
   const forwardRef: typeof import('react').forwardRef
+  const isRouteErrorResponse: typeof import('react-router').isRouteErrorResponse
   const lazy: typeof import('react').lazy
   const memo: typeof import('react').memo
   const preconnect: typeof import('react-dom').preconnect
@@ -24,6 +35,7 @@ declare global {
   const preinitModule: typeof import('react-dom').preinitModule
   const preload: typeof import('react-dom').preload
   const preloadModule: typeof import('react-dom').preloadModule
+  const redirect: typeof import('react-router').redirect
   const startTransition: typeof import('react').startTransition
   const use: typeof import('react').use
   const useActionState: typeof import('react').useActionState
@@ -41,8 +53,10 @@ declare global {
   const useInsertionEffect: typeof import('react').useInsertionEffect
   const useLayoutEffect: typeof import('react').useLayoutEffect
   const useLocation: typeof import('react-router').useLocation
+  const useMatches: typeof import('react-router').useMatches
   const useMemo: typeof import('react').useMemo
   const useNavigate: typeof import('react-router').useNavigate
+  const useNavigation: typeof import('react-router').useNavigation
   const useNavigationType: typeof import('react-router').useNavigationType
   const useOptimistic: typeof import('react').useOptimistic
   const useOutlet: typeof import('react-router').useOutlet
@@ -51,8 +65,20 @@ declare global {
   const useReducer: typeof import('react').useReducer
   const useRef: typeof import('react').useRef
   const useResolvedPath: typeof import('react-router').useResolvedPath
+  const useRevalidator: typeof import('react-router').useRevalidator
+  const useRouteError: typeof import('react-router').useRouteError
   const useRoutes: typeof import('react-router').useRoutes
+  const useSearchParams: typeof import('react-router').useSearchParams
   const useState: typeof import('react').useState
   const useSyncExternalStore: typeof import('react').useSyncExternalStore
   const useTransition: typeof import('react').useTransition
 }
+// for type re-export
+declare global {
+  // @ts-ignore
+  export type { ReactNode, ComponentType, SVGProps, PropsWithChildren, Key, Ref, LazyExoticComponent, ReactElement } from 'react'
+  import('react')
+  // @ts-ignore
+  export type { MiddlewareFunction, DataRouter, RouterState, RouteObject } from 'react-router'
+  import('react-router')
+}

package/template-vp-monorepo-react-nestjs/apps/web/src/utils/organization-assignment.ts

@@ -0,0 +1,66 @@
+import type { OrganizationDuty, OrganizationMemberCandidate, OrganizationScope } from 'shared/types'
+import { accessScopeKey } from 'shared/utils'
+
+const dutyOrder: Record<OrganizationDuty, number> = {
+  member: 0,
+  deputy: 1,
+  leader: 2,
+}
+
+interface CandidateAssignmentInput {
+  candidate: OrganizationMemberCandidate
+  scope: OrganizationScope
+}
+
+interface OrganizationAssignmentInput extends CandidateAssignmentInput {
+  unitEffective: boolean
+}
+
+interface OrganizationDutyChangeInput extends OrganizationAssignmentInput {
+  initialDuty?: OrganizationDuty
+  nextDuty: OrganizationDuty
+}
+
+interface PositionAssignmentInput extends CandidateAssignmentInput {
+  positionActive: boolean
+}
+
+/** 判断账号及其当前 URL 作用域成员身份是否都处于有效状态。 */
+export function isCandidateActiveInScope({ candidate, scope }: CandidateAssignmentInput): boolean {
+  if (candidate.accountStatus !== 'active') return false
+  const scopeKey = accessScopeKey(scope)
+  const identity = candidate.identities.find((item) => accessScopeKey(item.scope) === scopeKey)
+  return identity?.scopeStatus === 'active' && identity.memberStatus === 'active'
+}
+
+/** 仅允许有效成员向有效组织单元新增关系。 */
+export function canAddOrganizationAssignment({
+  candidate,
+  scope,
+  unitEffective,
+}: OrganizationAssignmentInput): boolean {
+  return unitEffective && isCandidateActiveInScope({ candidate, scope })
+}
+
+/**
+ * 有效关系可任意调整职责；失效关系只能原样保留或降级，不能新增或升级职责。
+ */
+export function canChangeOrganizationDuty({
+  candidate,
+  scope,
+  unitEffective,
+  initialDuty,
+  nextDuty,
+}: OrganizationDutyChangeInput): boolean {
+  if (canAddOrganizationAssignment({ candidate, scope, unitEffective })) return true
+  return initialDuty !== undefined && dutyOrder[nextDuty] <= dutyOrder[initialDuty]
+}
+
+/** 仅允许可选且当前作用域有效的成员新增到启用岗位。 */
+export function canAddPositionAssignment({
+  candidate,
+  scope,
+  positionActive,
+}: PositionAssignmentInput): boolean {
+  return positionActive && !candidate.disabled && isCandidateActiveInScope({ candidate, scope })
+}

package/template-vp-monorepo-react-nestjs/apps/web/src/utils/request/core/index.ts

@@ -9,9 +9,11 @@ import type {
 } from 'alova'
 import { createAlova } from 'alova'
 import type { AxiosResponse, AxiosResponseHeaders } from 'axios'
+import { tr } from '@/i18n'
 import { deepMergeObject, isPlainObject, isReadableStream, tryParseJsonString } from './utils.ts'
 
 type MaybePromise<T> = T | Promise<T>
+type MessageResolver = string | (() => string)
 type HeaderValue =
   | string
   | number
@@ -55,8 +57,8 @@ export interface BaseRequestOption<
   cacheFor?: GlobalCacheConfig<any> | null
   cacheLogger?: boolean
   statesHook?: StatesHook<SE>
-  successDefaultMessage?: string
-  errorDefaultMessage?: string
+  successDefaultMessage?: MessageResolver
+  errorDefaultMessage?: MessageResolver
   successMessageFunc?: (message: string) => void
   errorMessageFunc?: (message: string) => void
   unAuthorizedResponseFunc?: (response: RE) => void
@@ -112,9 +114,6 @@ type ResolvedRequestOption<RC extends object, RE, RH, SE extends StatesExport<an
 > &
   BaseRequestOption<RC, RE, RH, SE>
 
-const DEFAULT_SUCCESS_MESSAGE = '操作成功'
-const DEFAULT_ERROR_MESSAGE = '服务异常'
-
 const defaultRequestOption: BaseRequestOption<any, any, any, any> = {
   baseUrl: '/',
   timeout: undefined,
@@ -131,24 +130,27 @@ const defaultRequestOption: BaseRequestOption<any, any, any, any> = {
   isWrapped: true,
   isTransformResponse: true,
   isShowSuccessMessage: false,
-  successDefaultMessage: DEFAULT_SUCCESS_MESSAGE,
+  successDefaultMessage: () => tr('操作成功'),
   isShowErrorMessage: true,
-  errorDefaultMessage: DEFAULT_ERROR_MESSAGE,
+  errorDefaultMessage: () => tr('服务异常'),
   cacheFor: null,
   cacheLogger: true,
   requestAdapter: axiosRequestAdapter(),
 }
 
+/** 兼容不同 Method 元数据位置，优先读取请求配置内的选项。 */
 function getMethodMeta(method: unknown): RequestMeta {
   const methodRecord = method as { meta?: RequestMeta; config?: { meta?: RequestMeta } } | undefined
   return methodRecord?.config?.meta ?? methodRecord?.meta ?? {}
 }
 
+/** 读取请求级布尔开关，未显式指定时使用实例默认值。 */
 function getMetaFlag(meta: RequestMeta, key: keyof RequestMeta, fallback: boolean): boolean {
   const value = meta[key]
   return typeof value === 'boolean' ? value : fallback
 }
 
+/** 以单值、集合或自定义函数判断 HTTP 状态是否命中规则。 */
 function isMatchedStatus<RE>(
   status: number,
   matcher: StatusMatcher<RE> | undefined,
@@ -161,18 +163,21 @@ function isMatchedStatus<RE>(
   return Array.isArray(matcher) ? matcher.includes(status) : matcher === status
 }
 
+/** 将业务码转为字符串匹配；未配置匹配集合时视为命中。 */
 function isMatchedCode(code: unknown, matcher: CodeMatcher | undefined): boolean {
   if (!matcher?.length) return true
 
   return matcher.some((item) => String(item) === String(code))
 }
 
+/** 兼容 statusCode 和 status 字段，将响应状态转换为数字。 */
 function getResponseStatus(response: unknown): number {
   const responseRecord = response as { status?: unknown; statusCode?: unknown }
   const status = responseRecord.statusCode ?? responseRecord.status
   return typeof status === 'number' ? status : Number(status)
 }
 
+/** 按配置字段及常见消息字段读取提示，内容不可用时返回默认文案。 */
 function getResponseMessage(data: unknown, messageKey: string, defaultMessage: string): string {
   if (!isPlainObject(data)) return defaultMessage
 
@@ -183,10 +188,17 @@ function getResponseMessage(data: unknown, messageKey: string, defaultMessage: s
   return defaultMessage
 }
 
+/** 在请求实际完成时解析默认提示，使语言切换后无需重建请求实例。 */
+function resolveMessage(message: MessageResolver): string {
+  return typeof message === 'function' ? message() : message
+}
+
+/** 仅从普通对象读取指定响应字段，其他响应形态返回 undefined。 */
 function getResponseField(data: unknown, key: string): unknown {
   return isPlainObject(data) ? data[key] : undefined
 }
 
+/** 根据内容类型解析 Fetch 响应，204 返回空值并为 JSON 失败提供文本回退。 */
 async function parseFetchResponse(response: {
   status?: number
   body?: unknown
@@ -219,6 +231,7 @@ async function parseFetchResponse(response: {
   return undefined
 }
 
+/** 兼容 Headers 和普通对象读取响应头，缺失或非字符串值返回空串。 */
 function getHeaderValue(
   headers: Headers | Record<string, unknown> | undefined,
   key: string,
@@ -233,6 +246,7 @@ function getHeaderValue(
   return typeof value === 'string' ? value : ''
 }
 
+/** 统一提取 Axios 或 Fetch 响应内容，并尝试解析对象、数组形式的 JSON 文本。 */
 async function getResponseData(response: unknown): Promise<unknown> {
   const responseRecord = response as {
     body?: unknown
@@ -255,12 +269,14 @@ async function getResponseData(response: unknown): Promise<unknown> {
   return response
 }
 
+/** 求值静态或异步请求头配置，忽略空值并将有效结果转为字符串。 */
 async function resolveHeaderValue(value: HeaderValue): Promise<string | undefined> {
   const resolved = typeof value === 'function' ? await value() : value
   if (resolved === null || resolved === undefined) return undefined
   return String(resolved)
 }
 
+/** 兼容 Headers、键值对数组及普通对象写入请求头。 */
 function setHeader(target: unknown, key: string, value: string): void {
   if (typeof Headers !== 'undefined' && target instanceof Headers) {
     target.set(key, value)
@@ -275,12 +291,14 @@ function setHeader(target: unknown, key: string, value: string): void {
   ;(target as Record<string, string>)[key] = value
 }
 
+/** 将实例配置递归合并到请求默认项，保留未覆盖的默认设置。 */
 function resolveConfig<RC extends object, RE, RH, SE extends StatesExport<any>>(
   option: BaseRequestOption<RC, RE, RH, SE>,
 ): ResolvedRequestOption<RC, RE, RH, SE> {
   return deepMergeObject(defaultRequestOption, option) as ResolvedRequestOption<RC, RE, RH, SE>
 }
 
+/** 创建统一处理公共请求头、响应解析、业务错误与未授权回调的 alova 实例。 */
 export function createInstance<
   RC extends object = AlovaAxiosRequestConfig,
   RE = AxiosResponse,
@@ -289,10 +307,17 @@ export function createInstance<
 >(option: RequestOption<RC, RE, RH, SE> = {}) {
   const config = resolveConfig(option)
 
+  /** 从响应内容构造包含 HTTP 状态及业务码的可识别错误。 */
   function responseError(data: unknown, status: number) {
     const code = getResponseField(data, config.responseCodeKey)
     return Object.assign(
-      new Error(getResponseMessage(data, config.responseMessageKey, config.errorDefaultMessage)),
+      new Error(
+        getResponseMessage(
+          data,
+          config.responseMessageKey,
+          resolveMessage(config.errorDefaultMessage),
+        ),
+      ),
       { status, code: typeof code === 'string' || typeof code === 'number' ? code : undefined },
     )
   }
@@ -306,6 +331,7 @@ export function createInstance<
     requestAdapter: config.requestAdapter!,
     l1Cache: config.l1Cache,
     l2Cache: config.l2Cache ?? config.storageAdapter,
+    /** 逐项求值公共请求头，并写入本次请求配置。 */
     beforeRequest: async (method) => {
       const methodConfig = method.config as { headers?: unknown }
       const headers = methodConfig.headers ?? {}
@@ -318,6 +344,7 @@ export function createInstance<
     },
     responded: {
       // HTTP 成败由适配器判断；这里只解析成功响应并检查业务 code。
+      /** 按请求元数据解析成功响应，检查业务码并按配置提示或返回业务数据。 */
       onSuccess: async (response, method) => {
         const meta = getMethodMeta(method)
         const shouldTransform = getMetaFlag(meta, 'isTransformResponse', config.isTransformResponse)
@@ -331,7 +358,7 @@ export function createInstance<
         const data = await getResponseData(response)
 
         if (!isWrapped) {
-          if (showSuccess) config.successMessageFunc?.(config.successDefaultMessage)
+          if (showSuccess) config.successMessageFunc?.(resolveMessage(config.successDefaultMessage))
           return data
         }
 
@@ -340,7 +367,7 @@ export function createInstance<
         const responseMessage = getResponseMessage(
           data,
           config.responseMessageKey,
-          config.successDefaultMessage,
+          resolveMessage(config.successDefaultMessage),
         )
 
         if (!isMatchedCode(code, config.codeMap.success)) {
@@ -349,7 +376,11 @@ export function createInstance<
 
           if (showError) {
             config.errorMessageFunc?.(
-              getResponseMessage(data, config.responseMessageKey, config.errorDefaultMessage),
+              getResponseMessage(
+                data,
+                config.responseMessageKey,
+                resolveMessage(config.errorDefaultMessage),
+              ),
             )
           }
           throw responseError(data, status)
@@ -360,6 +391,7 @@ export function createInstance<
         return responseData
       },
       // 统一处理 HTTP 错误、网络故障和超时；onSuccess 抛出的业务错误直接传给调用方。
+      /** 统一处理 HTTP 和网络错误，触发未授权回调并抛出标准错误。 */
       onError: async (error, method) => {
         const meta = getMethodMeta(method)
         const showError = getMetaFlag(meta, 'isShowErrorMessage', config.isShowErrorMessage)
@@ -373,7 +405,7 @@ export function createInstance<
           }
           failure = responseError(await getResponseData(response), status)
         } else {
-          failure = new Error('无法连接服务，请检查网络后重试')
+          failure = new Error(tr('无法连接服务，请检查网络后重试'))
         }
 
         if (showError) {
@@ -402,6 +434,7 @@ export type DualCallInstance<
 > = RequestInstance<RC, RE, RH, SE> &
   ((option?: RequestOption<RC, RE, RH, SE>) => RequestInstance<RC, RE, RH, SE>)
 
+/** 提供默认请求实例的方法，同时支持通过函数调用创建覆盖配置的新实例。 */
 export function createDualCallInstance<
   RC extends object = AlovaAxiosRequestConfig,
   RE = AxiosResponse,
@@ -409,7 +442,9 @@ export function createDualCallInstance<
   SE extends StatesExport<any> = StatesExport<any>,
 >(baseConfig: BaseRequestOption<RC, RE, RH, SE>): DualCallInstance<RC, RE, RH, SE> {
   const defaultInstance = createInstance(baseConfig)
-  const dualInstance = ((option?: RequestOption<RC, RE, RH, SE>) => {
+  const dualInstance = /** 未传配置时复用默认请求实例，传入配置时合并基础设置创建独立实例。 */ ((
+    option?: RequestOption<RC, RE, RH, SE>,
+  ) => {
     if (!option) return defaultInstance
     return createInstance(deepMergeObject(baseConfig, option))
   }) as DualCallInstance<RC, RE, RH, SE>

package/template-vp-monorepo-react-nestjs/apps/web/src/utils/request/core/utils.ts

@@ -1,4 +1,6 @@
+/** 递归合并普通对象，数组等非普通对象由目标值整体替换。 */
 export function deepMergeObject<T = any>(source: T, target: Partial<T>): T {
+  /** 递归复制并合并目标对象属性，目标值未定义时沿用源值。 */
   const merge = (src: any, tgt: any): any => {
     if (!isPlainObject(src) || !isPlainObject(tgt)) return tgt === undefined ? src : tgt
 
@@ -14,15 +16,18 @@ export function deepMergeObject<T = any>(source: T, target: Partial<T>): T {
   return merge(source, target)
 }
 
+/** 通过对象标签判断值是否为普通对象形态。 */
 export function isPlainObject(data: unknown): data is Record<string, any> {
   return Object.prototype.toString.call(data) === '[object Object]'
 }
 
+/** 在运行环境支持 ReadableStream 时判断响应体是否为流。 */
 export function isReadableStream(data: unknown): boolean {
   if (typeof ReadableStream === 'undefined') return false
   return data instanceof ReadableStream
 }
 
+/** 仅尝试解析对象或数组形式的 JSON 字符串，解析失败时保留原值。 */
 export function tryParseJsonString(data: unknown): unknown {
   if (typeof data !== 'string') return data
 

package/template-vp-monorepo-react-nestjs/apps/web/src/utils/request/index.ts

@@ -2,6 +2,7 @@ import { axiosRequestAdapter, type AlovaAxiosRequestConfig } from '@alova/adapte
 import reactHook, { type ReactHookExportType } from 'alova/react'
 import { message } from 'antd'
 import type { AxiosResponse, AxiosResponseHeaders } from 'axios'
+import { tr } from '@/i18n'
 import { envVariables } from '@/utils/env'
 import { cookie } from '@/utils/storage/cookie'
 import { createDualCallInstance, type BaseRequestOption } from './core/index.ts'
@@ -13,6 +14,7 @@ type WebRequestOption = BaseRequestOption<
   ReactHookExportType<unknown>
 >
 
+/** 保留完整 URL 和绝对路径，为相对接口前缀补齐开头斜杠。 */
 function normalizeBaseUrl(apiAffix?: string) {
   if (!apiAffix) return '/'
   if (/^https?:\/\//.test(apiAffix) || apiAffix.startsWith('/')) {
@@ -22,6 +24,7 @@ function normalizeBaseUrl(apiAffix?: string) {
   return `/${apiAffix}`
 }
 
+/** 组装 Web 请求配置，绑定登录凭据、提示方式及未授权跳转。 */
 function getBaseConfig(): WebRequestOption {
   return {
     baseUrl: normalizeBaseUrl(envVariables.API_AFFIX),
@@ -35,7 +38,8 @@ function getBaseConfig(): WebRequestOption {
     },
     responseDataKey: 'data',
     responseMessageKey: 'message',
-    errorDefaultMessage: '请求失败，请稍后重试',
+    errorDefaultMessage: () => tr('请求失败，请稍后重试'),
+    /** 在发送请求时读取最新登录令牌，存在时附加 Bearer 鉴权头。 */
     commonHeaders: () => {
       const token = cookie.get('token')
       return token ? { Authorization: `Bearer ${token}` } : {}
@@ -46,9 +50,10 @@ function getBaseConfig(): WebRequestOption {
     errorMessageFunc: (msg) => {
       message.error(msg)
     },
+    /** 清除失效登录令牌，提示登录过期并跳转到登录页。 */
     unAuthorizedResponseFunc: () => {
       cookie.remove('token')
-      message.error('登录过期或未登录')
+      message.error(tr('登录过期或未登录'))
       window.location.assign('/login')
     },
     statesHook: reactHook,

package/template-vp-monorepo-react-nestjs/apps/web/src/utils/request/workspace.ts

@@ -0,0 +1,82 @@
+import request from './index'
+import { cookie } from '@/utils/storage/cookie'
+
+/** 权限和管理数据不进入 alova 缓存；每个工作空间代次都有独立的在途请求集合。 */
+export const workspaceRequest = request({
+  cacheFor: { GET: 0, POST: 0, PUT: 0, PATCH: 0, DELETE: 0, HEAD: 0, OPTIONS: 0 },
+  cacheLogger: false,
+  isShowErrorMessage: false,
+  /** 延后到请求代次校验后再处理 401，防止旧会话的迟到失败退出新会话。 */
+  unAuthorizedResponseFunc: () => {},
+})
+
+let currentKey = ''
+let generation = 0
+const pending = new Set<() => void>()
+
+/** 推进工作空间代次并中止所有在途请求，使迟到结果立即失效。 */
+export function clearWorkspaceRequests() {
+  generation += 1
+  for (const abort of pending) abort()
+  pending.clear()
+  currentKey = ''
+}
+
+/** 按会话令牌和工作空间键识别切换，切换时清理旧空间请求。 */
+export function enterWorkspace(key: string) {
+  const identityKey = `${cookie.get('token') ?? ''}:${key}`
+  if (identityKey !== currentKey) {
+    clearWorkspaceRequests()
+    currentKey = identityKey
+  }
+}
+
+/** 通知工作空间布局重新校验权限及导航数据。 */
+export function refreshAccess() {
+  window.dispatchEvent(new Event('workspace-access-refresh'))
+}
+
+export const freshRequest = { cacheFor: 0, shareRequest: false } as const
+
+/**
+ * 在指定工作空间代次内发送请求，丢弃跨账号、跨空间或已取消的结果。
+ * `workspaceKey` 必须由 API 创建时绑定，不能在实际发送时读取当前空间后补写。
+ */
+export async function runWorkspaceRequest<T>(options: {
+  method: { send: (force?: boolean) => Promise<T>; abort: () => void }
+  workspaceKey: string
+  signal?: AbortSignal
+  accessRequest?: boolean
+}): Promise<T> {
+  const { method, workspaceKey, signal, accessRequest } = options
+  const startedAt = generation
+  const token = cookie.get('token')
+  const identityKey = `${token ?? ''}:${workspaceKey}`
+  const abort = () => method.abort()
+  /** 检查取消信号、调用方空间、工作空间代次及登录令牌，判断请求是否已经过期。 */
+  const stale = () =>
+    signal?.aborted ||
+    currentKey !== identityKey ||
+    generation !== startedAt ||
+    token !== cookie.get('token')
+  if (stale()) throw new DOMException('请求已取消', 'AbortError')
+  pending.add(abort)
+  signal?.addEventListener('abort', abort, { once: true })
+  try {
+    const result = await method.send(true)
+    if (stale()) throw new DOMException('工作空间已切换', 'AbortError')
+    return result
+  } catch (error) {
+    if (stale()) throw new DOMException('工作空间已切换', 'AbortError')
+    if ((error as { status?: number }).status === 401) {
+      clearWorkspaceRequests()
+      cookie.remove('token')
+      window.location.assign('/login')
+    }
+    if (!accessRequest && (error as { status?: number }).status === 403) refreshAccess()
+    throw error
+  } finally {
+    pending.delete(abort)
+    signal?.removeEventListener('abort', abort)
+  }
+}