create-react-admin-template 0.0.0-stage → 0.1.0

package/template/src/optionalEditors/model.ts

@@ -0,0 +1,253 @@
+import { OptionalEditorError } from './errors'
+import type {
+  IMigrateOptionalEditorDocumentOptions,
+  IOptionalEditorDocument,
+  IOptionalEditorDocumentInput,
+  IOptionalEditorMountInput,
+  IOptionalEditorMountRequest,
+  TOptionalEditorKind,
+  TOptionalEditorMode,
+} from './types'
+
+const nMaxIdentifierLength = 200
+const nMaxMigrationSteps = 20
+
+function fnNormalizeRequiredText(
+  strValue: string,
+  strField: string,
+  strCode: 'INVALID_DOCUMENT' | 'INVALID_REQUEST' | 'MIGRATION_FAILED'
+) {
+  const strNormalizedValue = typeof strValue === 'string' ? strValue.trim() : ''
+  if (!strNormalizedValue || strNormalizedValue.length > nMaxIdentifierLength) {
+    throw new OptionalEditorError(
+      strCode,
+      `可选编辑器字段 ${strField} 必须是长度不超过 ${nMaxIdentifierLength} 的非空字符串。`
+    )
+  }
+  return strNormalizedValue
+}
+
+/** 校验地图、富文本或图形编辑器能力分类。 */
+export function fnNormalizeOptionalEditorKind(
+  strEditorKind: string
+): TOptionalEditorKind {
+  if (
+    strEditorKind !== 'diagram' &&
+    strEditorKind !== 'map' &&
+    strEditorKind !== 'richText'
+  ) {
+    throw new OptionalEditorError(
+      'INVALID_DOCUMENT',
+      '文档包含不受支持的编辑器能力分类。'
+    )
+  }
+  return strEditorKind
+}
+
+/** 校验编辑器查看或编辑模式。 */
+export function fnNormalizeOptionalEditorMode(
+  strMode: string
+): TOptionalEditorMode {
+  if (strMode !== 'edit' && strMode !== 'view') {
+    throw new OptionalEditorError(
+      'INVALID_REQUEST',
+      '可选编辑器模式必须是 edit 或 view。'
+    )
+  }
+  return strMode
+}
+
+/** 校验文档信封并保持项目拥有的结构化文档值。 */
+export function fnNormalizeOptionalEditorDocument<TDocument extends object>(
+  objInput: IOptionalEditorDocumentInput<TDocument>,
+  strExpectedKind?: TOptionalEditorKind
+): IOptionalEditorDocument<TDocument> {
+  if (
+    !objInput ||
+    typeof objInput !== 'object' ||
+    !objInput.objDocument ||
+    typeof objInput.objDocument !== 'object' ||
+    Array.isArray(objInput.objDocument)
+  ) {
+    throw new OptionalEditorError('INVALID_DOCUMENT', '编辑器文档无效。')
+  }
+  const strEditorKind = fnNormalizeOptionalEditorKind(objInput.strEditorKind)
+  if (strExpectedKind && strEditorKind !== strExpectedKind) {
+    throw new OptionalEditorError(
+      'INVALID_DOCUMENT',
+      '文档类型与当前编辑器 Adapter 不匹配。'
+    )
+  }
+  return Object.freeze({
+    objDocument: objInput.objDocument,
+    strContentRevision:
+      objInput.strContentRevision === undefined
+        ? undefined
+        : fnNormalizeRequiredText(
+            objInput.strContentRevision,
+            'strContentRevision',
+            'INVALID_DOCUMENT'
+          ),
+    strDocumentId: fnNormalizeRequiredText(
+      objInput.strDocumentId,
+      'strDocumentId',
+      'INVALID_DOCUMENT'
+    ),
+    strEditorKind,
+    strSchemaVersion: fnNormalizeRequiredText(
+      objInput.strSchemaVersion,
+      'strSchemaVersion',
+      'INVALID_DOCUMENT'
+    ),
+  })
+}
+
+/** 校验专用容器、身份作用域、文档和模式并创建完整挂载请求。 */
+export function fnNormalizeOptionalEditorMountRequest<TDocument extends object>(
+  objInput: IOptionalEditorMountInput<TDocument>,
+  strExpectedKind: TOptionalEditorKind,
+  fnValidateDocument: (objDocument: TDocument) => TDocument,
+  objSignal: AbortSignal
+): IOptionalEditorMountRequest<TDocument> {
+  if (
+    !objInput ||
+    typeof objInput !== 'object' ||
+    typeof HTMLElement === 'undefined' ||
+    !(objInput.objContainer instanceof HTMLElement)
+  ) {
+    throw new OptionalEditorError(
+      'INVALID_REQUEST',
+      '可选编辑器必须挂载到有效的专用 HTMLElement。'
+    )
+  }
+  const objDocument = fnNormalizeOptionalEditorDocument(
+    objInput.objDocument,
+    strExpectedKind
+  )
+  let objValidatedDocument: TDocument
+  try {
+    objValidatedDocument = fnValidateDocument(objDocument.objDocument)
+  } catch {
+    throw new OptionalEditorError(
+      'INVALID_DOCUMENT',
+      '项目 Adapter 拒绝了当前结构化文档。'
+    )
+  }
+  return Object.freeze({
+    objContainer: objInput.objContainer,
+    objDocument: Object.freeze({
+      ...objDocument,
+      objDocument: objValidatedDocument,
+    }),
+    objScope: objInput.objScope,
+    objSignal,
+    strMode: fnNormalizeOptionalEditorMode(objInput.strMode),
+  })
+}
+
+/** 清理供应商失败原因码，避免正文、URL 或堆栈进入快照。 */
+export function fnNormalizeOptionalEditorReasonCode(
+  strReasonCode: string | undefined
+) {
+  if (strReasonCode === undefined) return undefined
+  const strNormalizedValue = strReasonCode.trim()
+  return /^[A-Z0-9_.:-]{1,100}$/.test(strNormalizedValue)
+    ? strNormalizedValue
+    : undefined
+}
+
+/** 按唯一线性路径迁移项目结构版本，并在每一步重新校验。 */
+export function fnMigrateOptionalEditorDocument<TDocument extends object>({
+  arrMigrations,
+  objDocument: objDocumentInput,
+  fnValidateDocument,
+  strTargetVersion: strTargetVersionInput,
+}: IMigrateOptionalEditorDocumentOptions<TDocument>): IOptionalEditorDocument<TDocument> {
+  const objDocument = fnNormalizeOptionalEditorDocument(objDocumentInput)
+  const strTargetVersion = fnNormalizeRequiredText(
+    strTargetVersionInput,
+    'strTargetVersion',
+    'MIGRATION_FAILED'
+  )
+  if (arrMigrations.length > nMaxMigrationSteps) {
+    throw new OptionalEditorError(
+      'MIGRATION_FAILED',
+      `单次文档迁移最多允许 ${nMaxMigrationSteps} 步。`
+    )
+  }
+  const objMigrationByVersion = new Map(
+    arrMigrations.map((objMigration) => [
+      fnNormalizeRequiredText(
+        objMigration.strFromVersion,
+        'strFromVersion',
+        'MIGRATION_FAILED'
+      ),
+      objMigration,
+    ])
+  )
+  if (objMigrationByVersion.size !== arrMigrations.length) {
+    throw new OptionalEditorError(
+      'MIGRATION_FAILED',
+      '同一个文档版本只能声明一个前向迁移。'
+    )
+  }
+
+  let objCurrentValue: TDocument
+  try {
+    objCurrentValue = fnValidateDocument(objDocument.objDocument)
+  } catch {
+    throw new OptionalEditorError(
+      'INVALID_DOCUMENT',
+      '迁移前文档没有通过项目 Adapter 校验。'
+    )
+  }
+  let strCurrentVersion = objDocument.strSchemaVersion
+  const objVisitedVersions = new Set<string>()
+  for (let nStep = 0; strCurrentVersion !== strTargetVersion; nStep += 1) {
+    if (
+      nStep >= nMaxMigrationSteps ||
+      objVisitedVersions.has(strCurrentVersion)
+    ) {
+      throw new OptionalEditorError(
+        'MIGRATION_FAILED',
+        '文档迁移路径包含循环或超过最大步数。'
+      )
+    }
+    objVisitedVersions.add(strCurrentVersion)
+    const objMigration = objMigrationByVersion.get(strCurrentVersion)
+    if (!objMigration) {
+      throw new OptionalEditorError(
+        'MIGRATION_PATH_MISSING',
+        `缺少从文档版本 ${strCurrentVersion} 开始的迁移。`
+      )
+    }
+    const strNextVersion = fnNormalizeRequiredText(
+      objMigration.strToVersion,
+      'strToVersion',
+      'MIGRATION_FAILED'
+    )
+    if (strNextVersion === strCurrentVersion) {
+      throw new OptionalEditorError(
+        'MIGRATION_FAILED',
+        '文档迁移不能指向相同版本。'
+      )
+    }
+    try {
+      objCurrentValue = fnValidateDocument(
+        objMigration.fnMigrate(objCurrentValue)
+      )
+    } catch {
+      throw new OptionalEditorError(
+        'MIGRATION_FAILED',
+        `文档从版本 ${strCurrentVersion} 迁移失败。`
+      )
+    }
+    strCurrentVersion = strNextVersion
+  }
+
+  return Object.freeze({
+    ...objDocument,
+    objDocument: objCurrentValue,
+    strSchemaVersion: strCurrentVersion,
+  })
+}

package/template/src/optionalEditors/react.ts

@@ -0,0 +1,89 @@
+import {
+  useCallback,
+  useEffect,
+  useEffectEvent,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+} from 'react'
+import { useAppQueryScope } from '@/api/query'
+import { fnCreateOptionalEditorController } from './controller'
+import type {
+  IOptionalEditorMountInput,
+  IUseOptionalEditorOptions,
+  TUseOptionalEditorResult,
+} from './types'
+
+/** 在当前路由拥有一个可销毁、可导出且带 dirty 状态的可选编辑器会话。 */
+export function useOptionalEditor<TDocument extends object, TBinding>({
+  bIsEnabled = true,
+  objAdapter,
+  objDocument,
+  strMode,
+  strWorkspaceId,
+}: IUseOptionalEditorOptions<TDocument, TBinding>): TUseOptionalEditorResult<
+  TDocument,
+  TBinding
+> {
+  const objScope = useAppQueryScope({ strWorkspaceId })
+  const [objContainer, fnSetContainer] = useState<HTMLElement | null>(null)
+  const objController = useMemo(
+    () => fnCreateOptionalEditorController(objAdapter),
+    [objAdapter]
+  )
+  const fnCreateMountInput = useEffectEvent(
+    (objNextContainer: HTMLElement): IOptionalEditorMountInput<TDocument> => ({
+      objContainer: objNextContainer,
+      objDocument,
+      objScope,
+      strMode,
+    })
+  )
+  const objSnapshot = useSyncExternalStore(
+    objController.fnSubscribe,
+    objController.fnGetSnapshot,
+    objController.fnGetSnapshot
+  )
+
+  useEffect(() => {
+    if (!bIsEnabled || !objContainer) {
+      objController.fnClose()
+      return
+    }
+    void objController.fnMount(fnCreateMountInput(objContainer))
+    return () => {
+      objController.fnClose()
+    }
+  }, [
+    bIsEnabled,
+    objContainer,
+    objController,
+    objDocument.strContentRevision,
+    objDocument.strDocumentId,
+    objDocument.strEditorKind,
+    objDocument.strSchemaVersion,
+    objScope,
+    strMode,
+  ])
+
+  const fnClose = useCallback(() => {
+    objController.fnClose()
+  }, [objController])
+  const fnExportDocument = useCallback(() => {
+    return objController.fnExportDocument()
+  }, [objController])
+  const fnMarkSaved = useCallback(() => {
+    objController.fnMarkSaved()
+  }, [objController])
+
+  return useMemo(
+    () => ({
+      ...objSnapshot,
+      fnClose,
+      fnExportDocument,
+      fnMarkSaved,
+      fnSetContainer,
+    }),
+    [fnClose, fnExportDocument, fnMarkSaved, objSnapshot]
+  )
+}

package/template/src/optionalEditors/types.ts

@@ -0,0 +1,254 @@
+import type { IAppQueryScope } from '@/api/query'
+import type { OptionalEditorError } from './errors'
+
+/** 脚手架可选编辑器的稳定能力分类。 */
+export type TOptionalEditorKind = 'diagram' | 'map' | 'richText'
+
+/** 可选编辑器当前查看或编辑模式。 */
+export type TOptionalEditorMode = 'edit' | 'view'
+
+/** 可选编辑器边界的稳定错误码。 */
+export type TOptionalEditorErrorCode =
+  | 'ADAPTER_FAILED'
+  | 'EXPORT_FAILED'
+  | 'INVALID_DOCUMENT'
+  | 'INVALID_EVENT'
+  | 'INVALID_REQUEST'
+  | 'MIGRATION_FAILED'
+  | 'MIGRATION_PATH_MISSING'
+  | 'SESSION_INACTIVE'
+
+/** 从接口或本地迁移边界进入编辑器的文档信封。 */
+export interface IOptionalEditorDocumentInput<TDocument extends object> {
+  /** 项目定义且经过 Adapter 校验的结构化文档值。 */
+  objDocument: TDocument
+  /** 同一文档 ID 的服务端内容版本；变化时 Hook 会重建编辑器会话。 */
+  strContentRevision?: string
+  /** 后端授权返回的稳定业务文档 ID。 */
+  strDocumentId: string
+  /** 文档所属编辑器能力；不接受任意供应商名称。 */
+  strEditorKind: string
+  /** 项目拥有的不可变文档结构版本，不等同于 SDK 版本。 */
+  strSchemaVersion: string
+}
+
+/** 经过校验、可交给具体编辑器 Adapter 的文档信封。 */
+export interface IOptionalEditorDocument<TDocument extends object> {
+  /** 项目定义且经过 Adapter 校验的结构化文档值。 */
+  readonly objDocument: TDocument
+  /** 同一文档 ID 的服务端内容版本。 */
+  readonly strContentRevision?: string
+  /** 后端授权返回的稳定业务文档 ID。 */
+  readonly strDocumentId: string
+  /** 当前地图、富文本或图形编辑器能力分类。 */
+  readonly strEditorKind: TOptionalEditorKind
+  /** 项目拥有的不可变文档结构版本。 */
+  readonly strSchemaVersion: string
+}
+
+/** 打开一个可选编辑器会话所需的输入。 */
+export interface IOptionalEditorMountInput<TDocument extends object> {
+  /** 仅供 SDK 挂载的空白专用容器，不得传入应用根节点。 */
+  readonly objContainer: HTMLElement
+  /** 当前需要编辑或查看的结构化文档。 */
+  readonly objDocument: IOptionalEditorDocumentInput<TDocument>
+  /** 当前用户、会话、租户、工作空间和语言组成的身份作用域。 */
+  readonly objScope: IAppQueryScope
+  /** 当前查看或编辑模式。 */
+  readonly strMode: TOptionalEditorMode
+}
+
+/** 交给项目编辑器 Adapter 的完整挂载请求。 */
+export interface IOptionalEditorMountRequest<
+  TDocument extends object,
+> extends Omit<IOptionalEditorMountInput<TDocument>, 'objDocument'> {
+  /** 经过基础字段和项目文档校验的结构化文档。 */
+  readonly objDocument: IOptionalEditorDocument<TDocument>
+  /** 文档切换、容器卸载或路由离开时触发的取消信号。 */
+  readonly objSignal: AbortSignal
+}
+
+/** 编辑器产生的 dirty 状态变化事件。 */
+export interface IOptionalEditorDirtyChangedEvent {
+  /** 当前文档是否包含尚未由业务后端确认保存的变化。 */
+  readonly bIsDirty: boolean
+  /** 可判别事件类型。 */
+  readonly strType: 'dirtyChanged'
+}
+
+/** 编辑器 SDK 无法继续工作时产生的安全失败事件。 */
+export interface IOptionalEditorSessionFailedEvent {
+  /** 稳定、非敏感原因码，不得包含正文、Token、URL 或堆栈。 */
+  readonly strReasonCode?: string
+  /** 可判别事件类型。 */
+  readonly strType: 'sessionFailed'
+}
+
+/** 可选编辑器允许发送给控制器的全部事件。 */
+export type TOptionalEditorSessionEvent =
+  | IOptionalEditorDirtyChangedEvent
+  | IOptionalEditorSessionFailedEvent
+
+/** 一个已经挂载到专用容器的供应商编辑器会话。 */
+export interface IOptionalEditorSession<TDocument extends object, TBinding> {
+  /** 交给具体 Feature 使用的项目强类型编辑器 Binding。 */
+  readonly objBinding: TBinding
+  /**
+   * 销毁编辑器实例、事件监听、Worker、Observer、对象 URL 和专用 DOM；必须可重复调用。
+   */
+  readonly fnDestroy: () => Promise<void> | void
+  /** 从 SDK 导出当前结构化文档，不得返回 HTML DOM、Canvas 或供应商实例。 */
+  readonly fnReadDocument: () => Promise<TDocument> | TDocument
+  /** 订阅 dirty 和致命失败事件；返回函数必须解除全部监听。 */
+  readonly fnSubscribe: (
+    fnOnEvent: (objEvent: TOptionalEditorSessionEvent) => void
+  ) => () => void
+}
+
+/** 项目接入具体地图、富文本或图形 SDK 的唯一边界。 */
+export interface IOptionalEditorAdapter<TDocument extends object, TBinding> {
+  /** 当前 Adapter 支持的唯一编辑器能力。 */
+  readonly strEditorKind: TOptionalEditorKind
+  /** 懒加载 SDK 并挂载到专用容器。 */
+  readonly fnMount: (
+    objRequest: IOptionalEditorMountRequest<TDocument>
+  ) => Promise<IOptionalEditorSession<TDocument, TBinding>>
+  /** 在挂载、迁移和导出后校验项目拥有的结构化文档契约。 */
+  readonly fnValidateDocument: (objDocument: TDocument) => TDocument
+}
+
+/** 尚未挂载可选编辑器。 */
+export interface IOptionalEditorIdleSnapshot {
+  /** 每次可观察状态变化后递增。 */
+  readonly nRevision: number
+  /** 可判别空闲状态。 */
+  readonly strStatus: 'idle'
+}
+
+/** 正在校验文档、加载 SDK 或挂载编辑器。 */
+export interface IOptionalEditorLoadingSnapshot {
+  /** 每次可观察状态变化后递增。 */
+  readonly nRevision: number
+  /** 同一文档 ID 的服务端内容版本。 */
+  readonly strContentRevision?: string
+  /** 当前准备挂载的业务文档 ID。 */
+  readonly strDocumentId: string
+  /** 当前编辑器能力分类。 */
+  readonly strEditorKind: TOptionalEditorKind
+  /** 当前查看或编辑模式。 */
+  readonly strMode: TOptionalEditorMode
+  /** 当前项目文档结构版本。 */
+  readonly strSchemaVersion: string
+  /** 可判别加载状态。 */
+  readonly strStatus: 'loading'
+}
+
+/** SDK 已经挂载且可以由 Feature 消费。 */
+export interface IOptionalEditorActiveSnapshot<TBinding> {
+  /** 是否包含尚未由业务后端确认保存的变化。 */
+  readonly bIsDirty: boolean
+  /** 每次可观察状态变化后递增。 */
+  readonly nRevision: number
+  /** 交给具体 Feature 的项目强类型编辑器 Binding。 */
+  readonly objBinding: TBinding
+  /** 同一文档 ID 的服务端内容版本。 */
+  readonly strContentRevision?: string
+  /** 当前业务文档 ID。 */
+  readonly strDocumentId: string
+  /** 当前编辑器能力分类。 */
+  readonly strEditorKind: TOptionalEditorKind
+  /** 当前查看或编辑模式。 */
+  readonly strMode: TOptionalEditorMode
+  /** 当前项目文档结构版本。 */
+  readonly strSchemaVersion: string
+  /** 可判别活动状态。 */
+  readonly strStatus: 'active'
+}
+
+/** 文档、Adapter、SDK 或迁移无法继续工作。 */
+export interface IOptionalEditorErrorSnapshot {
+  /** 每次可观察状态变化后递增。 */
+  readonly nRevision: number
+  /** 已清理供应商细节的稳定错误。 */
+  readonly objError: OptionalEditorError
+  /** 可判别失败状态。 */
+  readonly strStatus: 'error'
+}
+
+/** React 与非 React 消费者读取的统一可选编辑器状态。 */
+export type TOptionalEditorSnapshot<TBinding> =
+  | IOptionalEditorActiveSnapshot<TBinding>
+  | IOptionalEditorErrorSnapshot
+  | IOptionalEditorIdleSnapshot
+  | IOptionalEditorLoadingSnapshot
+
+/** 非 React 可选编辑器生命周期控制器。 */
+export interface IOptionalEditorController<TDocument extends object, TBinding> {
+  /** 取消挂载、解除订阅并销毁当前 SDK 会话。 */
+  readonly fnClose: () => TOptionalEditorSnapshot<TBinding>
+  /** 导出并重新校验当前结构化文档。 */
+  readonly fnExportDocument: () => Promise<IOptionalEditorDocument<TDocument>>
+  /** 同步读取当前稳定快照。 */
+  readonly fnGetSnapshot: () => TOptionalEditorSnapshot<TBinding>
+  /** 业务保存成功后清除 dirty 状态。 */
+  readonly fnMarkSaved: () => TOptionalEditorSnapshot<TBinding>
+  /** 在专用容器挂载或替换编辑器；只有最后一次请求可以生效。 */
+  readonly fnMount: (
+    objInput: IOptionalEditorMountInput<TDocument>
+  ) => Promise<TOptionalEditorSnapshot<TBinding>>
+  /** 订阅控制器快照变化。 */
+  readonly fnSubscribe: (fnListener: () => void) => () => void
+}
+
+/** 一步项目文档结构迁移。 */
+export interface IOptionalEditorMigration<TDocument extends object> {
+  /** 迁移前的项目结构版本。 */
+  readonly strFromVersion: string
+  /** 迁移后的项目结构版本。 */
+  readonly strToVersion: string
+  /** 无副作用地返回新结构；不得读取网络、DOM 或供应商全局状态。 */
+  readonly fnMigrate: (objDocument: TDocument) => TDocument
+}
+
+/** 执行可选编辑器文档迁移的完整参数。 */
+export interface IMigrateOptionalEditorDocumentOptions<
+  TDocument extends object,
+> {
+  /** 唯一、线性的前向迁移列表。 */
+  readonly arrMigrations: readonly IOptionalEditorMigration<TDocument>[]
+  /** 需要迁移的结构化文档信封。 */
+  readonly objDocument: IOptionalEditorDocumentInput<TDocument>
+  /** 每一步之后执行的项目文档运行时校验。 */
+  readonly fnValidateDocument: (objDocument: TDocument) => TDocument
+  /** 目标项目结构版本。 */
+  readonly strTargetVersion: string
+}
+
+/** 路由级可选编辑器 Hook 的公共参数。 */
+export interface IUseOptionalEditorOptions<TDocument extends object, TBinding> {
+  /** 是否允许挂载编辑器，默认启用。 */
+  readonly bIsEnabled?: boolean
+  /** 项目编辑器 SDK Adapter。 */
+  readonly objAdapter: IOptionalEditorAdapter<TDocument, TBinding>
+  /** 当前结构化业务文档。 */
+  readonly objDocument: IOptionalEditorDocumentInput<TDocument>
+  /** 当前查看或编辑模式。 */
+  readonly strMode: TOptionalEditorMode
+  /** 跨工作空间 Feature 显式指定的工作空间 ID。 */
+  readonly strWorkspaceId?: string
+}
+
+/** 路由级可选编辑器 Hook 返回的快照与命令。 */
+export type TUseOptionalEditorResult<
+  TDocument extends object,
+  TBinding,
+> = TOptionalEditorSnapshot<TBinding> & {
+  /** 关闭并销毁当前编辑器会话。 */
+  readonly fnClose: () => void
+  /** 导出并重新校验当前结构化文档。 */
+  readonly fnExportDocument: () => Promise<IOptionalEditorDocument<TDocument>>
+  /** 业务保存成功后清除 dirty 状态。 */
+  readonly fnMarkSaved: () => void
+  /** 传给专用编辑器宿主元素的 React ref 回调。 */
+  readonly fnSetContainer: (objContainer: HTMLElement | null) => void
+}

package/template/src/permissions/index.ts

@@ -0,0 +1,3 @@
+export { fnHasPermission, fnHasPermissions } from '@/lib/accessControl'
+export { usePermission } from './usePermission'
+export type { TPermissionMatchMode, TPermissionRequirement } from './types'

package/template/src/permissions/types.ts

@@ -0,0 +1,5 @@
+/** 多权限要求的匹配方式。 */
+export type TPermissionMatchMode = 'all' | 'any'
+
+/** 单个权限码或一组需要匹配的权限码。 */
+export type TPermissionRequirement = string | readonly string[]

package/template/src/permissions/usePermission.ts

@@ -0,0 +1,16 @@
+import { useAuthStore } from '@/stores/authStore'
+import { fnHasPermissions } from '@/lib/accessControl'
+import type { TPermissionMatchMode, TPermissionRequirement } from './types'
+
+/**
+ * 响应式判断当前用户是否具备操作权限。
+ *
+ * 权限数据直接来自认证会话；身份刷新后组件会自动重新渲染。
+ */
+export function usePermission(
+  objRequirement?: TPermissionRequirement,
+  strMatchMode: TPermissionMatchMode = 'all'
+) {
+  const objUser = useAuthStore((objState) => objState.objUser)
+  return fnHasPermissions(objUser, objRequirement, strMatchMode)
+}