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

package/template/src/dataMasking/types.ts

@@ -0,0 +1,144 @@
+import type {
+  TPermissionMatchMode,
+  TPermissionRequirement,
+} from '@/permissions'
+
+/** 脚手架内建的常见敏感数据脱敏预设。 */
+export type TDataMaskingPreset =
+  | 'bankCard'
+  | 'email'
+  | 'identity'
+  | 'name'
+  | 'phone'
+  | 'segment'
+
+/** 数据脱敏函数的可配置策略。 */
+export interface IDataMaskingPolicy {
+  /** 使用的内建策略；segment 表示仅按首尾可见位数处理。 */
+  readonly strPreset: TDataMaskingPreset
+  /** 遮罩字符，必须是单个可见 Unicode 字符，默认 `*`。 */
+  readonly strMaskCharacter?: string
+  /** 明文起始侧保留的 Unicode 字符数。 */
+  readonly nVisibleStart?: number
+  /** 明文结束侧保留的 Unicode 字符数。 */
+  readonly nVisibleEnd?: number
+  /** 固定遮罩字符数；省略时按实际隐藏长度生成。 */
+  readonly nMaskLength?: number
+  /** 原值为空时的展示占位文案，默认 `—`。 */
+  readonly strEmptyText?: string
+}
+
+/** 后端只返回了允许当前用户查看的脱敏结果。 */
+export interface ISensitiveDataMaskedValue {
+  /** masked 明确表示浏览器中不存在可直接展示的原始值。 */
+  readonly strState: 'masked'
+  /** 后端按数据权限生成的脱敏文本。 */
+  readonly strMaskedValue: string
+}
+
+/** 后端已经授权并返回原始值，前端仍默认以脱敏形态展示。 */
+export interface ISensitiveDataAvailableValue {
+  /** available 表示浏览器内存中已经存在原始值。 */
+  readonly strState: 'available'
+  /** 已经过后端数据权限校验的原始文本。 */
+  readonly strValue: string
+  /** 可选的后端脱敏文本；存在时优先于前端策略计算结果。 */
+  readonly strMaskedValue?: string
+}
+
+/** 敏感数据在前端可接收的互斥数据形态。 */
+export type TSensitiveDataValue =
+  | ISensitiveDataAvailableValue
+  | ISensitiveDataMaskedValue
+
+/** 禁止在当前展示位置查看原始值。 */
+export interface ISensitiveDataRevealDisabledPolicy {
+  /** disabled 表示不渲染查看入口。 */
+  readonly strMode: 'disabled'
+}
+
+/** 允许具备指定操作权限的用户临时查看原始值。 */
+export interface ISensitiveDataRevealAuthorizedPolicy {
+  /** authorized 表示前端展示权限通过后才允许发起查看。 */
+  readonly strMode: 'authorized'
+  /** 查看原始值所需的独立操作权限码。 */
+  readonly objRequirement: TPermissionRequirement
+  /** 多个查看权限码的匹配方式，默认全部满足。 */
+  readonly strMatchMode?: TPermissionMatchMode
+  /** 查看后自动回掩的毫秒数，默认 30 秒，最小 1 秒。 */
+  readonly nDurationMs?: number
+}
+
+/** 敏感数据原始值的临时查看策略。 */
+export type TSensitiveDataRevealPolicy =
+  | ISensitiveDataRevealAuthorizedPolicy
+  | ISensitiveDataRevealDisabledPolicy
+
+/** 禁止在当前展示位置复制敏感数据。 */
+export interface ISensitiveDataCopyDisabledPolicy {
+  /** disabled 表示不渲染复制入口。 */
+  readonly strMode: 'disabled'
+}
+
+/** 只允许复制当前脱敏文本。 */
+export interface ISensitiveDataCopyMaskedPolicy {
+  /** masked 表示即使当前正在查看原始值，也只复制脱敏文本。 */
+  readonly strMode: 'masked'
+  /** 复制脱敏文本所需的可选操作权限码。 */
+  readonly objRequirement?: TPermissionRequirement
+  /** 多个复制权限码的匹配方式，默认全部满足。 */
+  readonly strMatchMode?: TPermissionMatchMode
+}
+
+/** 允许具备独立权限的用户复制当前已临时展示的原始值。 */
+export interface ISensitiveDataCopyRevealedPolicy {
+  /** revealed 表示复制入口只在原始值正在展示时出现。 */
+  readonly strMode: 'revealed'
+  /** 复制原始值所需的独立操作权限码，不能省略。 */
+  readonly objRequirement: TPermissionRequirement
+  /** 多个复制权限码的匹配方式，默认全部满足。 */
+  readonly strMatchMode?: TPermissionMatchMode
+}
+
+/** 敏感数据的显式复制策略，默认禁止复制。 */
+export type TSensitiveDataCopyPolicy =
+  | ISensitiveDataCopyDisabledPolicy
+  | ISensitiveDataCopyMaskedPolicy
+  | ISensitiveDataCopyRevealedPolicy
+
+/** 按需向后端请求原始值时提供的取消上下文。 */
+export interface ISensitiveDataRevealRequest {
+  /** 组件回掩、卸载或开始新请求时用于取消生成客户端请求。 */
+  readonly objSignal: AbortSignal
+}
+
+/** Feature 使用生成客户端实现的原始值按需加载 Adapter。 */
+export type TSensitiveDataRevealAdapter = (
+  objRequest: ISensitiveDataRevealRequest
+) => Promise<string>
+
+/** 可替换的剪贴板写入 Adapter，便于浏览器兼容处理和测试。 */
+export type TSensitiveDataClipboardAdapter = (strText: string) => Promise<void>
+
+/** 敏感数据交互产生的稳定错误码。 */
+type TSensitiveDataErrorCode =
+  | 'clipboard_unavailable'
+  | 'copy_failed'
+  | 'empty_reveal_value'
+  | 'reveal_failed'
+
+/** 敏感数据组件向页面反馈的安全错误，不携带原始值。 */
+export class SensitiveDataError extends Error {
+  /** 页面反馈、监控分类和测试使用的稳定错误码。 */
+  readonly strCode: TSensitiveDataErrorCode
+
+  constructor(
+    strCode: TSensitiveDataErrorCode,
+    strMessage: string,
+    objOptions?: ErrorOptions
+  ) {
+    super(strMessage, objOptions)
+    this.name = 'SensitiveDataError'
+    this.strCode = strCode
+  }
+}

package/template/src/featureFlags/FeatureFlagProvider.tsx

@@ -0,0 +1,143 @@
+import { createContext, useContext, useMemo } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import { fnFeatureFlagQueryOptions } from './query'
+import {
+  fnCreateFeatureFlagRegistry,
+  fnEvaluateFeatureFlag,
+  fnGetFeatureFlagDefinition,
+} from './registry'
+import { fnCreateFeatureFlagScope } from './scope'
+import type {
+  IFeatureFlagProviderProps,
+  IFeatureFlagScope,
+  IFeatureFlagSource,
+  IUseFeatureFlagCatalogResult,
+  IUseFeatureFlagResult,
+} from './types'
+
+interface IFeatureFlagContextValue {
+  readonly arrKeys: readonly string[]
+  readonly bIsEnabled: boolean
+  readonly objRegistry: ReturnType<typeof fnCreateFeatureFlagRegistry>
+  readonly objScope: IFeatureFlagScope
+  readonly objSource?: IFeatureFlagSource
+}
+
+const objUnavailableSource: IFeatureFlagSource = {
+  fnLoadCatalog: () =>
+    Promise.reject(new Error('尚未配置 Feature Flag 后端数据源。')),
+}
+const fnFeatureFlagContext = createContext<IFeatureFlagContextValue | null>(
+  null
+)
+
+/** 装配本地安全定义与远端已评估目录，远端失败不会阻塞应用子树。 */
+export function FeatureFlagProvider({
+  arrDefinitions,
+  bIsEnabled = true,
+  children: objChildren,
+  objScope: objScopeInput,
+  objSource,
+}: IFeatureFlagProviderProps) {
+  const objRegistry = useMemo(
+    () => fnCreateFeatureFlagRegistry(arrDefinitions),
+    [arrDefinitions]
+  )
+  const arrKeys = useMemo(
+    () => Object.freeze([...objRegistry.keys()].sort()),
+    [objRegistry]
+  )
+  const objScope = useMemo(
+    () => fnCreateFeatureFlagScope(objScopeInput),
+    [objScopeInput]
+  )
+  const objContextValue = useMemo(
+    () => ({ arrKeys, bIsEnabled, objRegistry, objScope, objSource }),
+    [arrKeys, bIsEnabled, objRegistry, objScope, objSource]
+  )
+
+  return (
+    <fnFeatureFlagContext.Provider value={objContextValue}>
+      <FeatureFlagPreload />
+      {objChildren}
+    </fnFeatureFlagContext.Provider>
+  )
+}
+
+function useFeatureFlagContext() {
+  const objContext = useContext(fnFeatureFlagContext)
+  if (!objContext) {
+    throw new Error('useFeatureFlag 必须在 FeatureFlagProvider 内使用。')
+  }
+  return objContext
+}
+
+/** 读取完整目录、刷新状态及按本地策略评估开关的统一入口。 */
+// eslint-disable-next-line react-refresh/only-export-components
+export function useFeatureFlagCatalog(): IUseFeatureFlagCatalogResult {
+  const { arrKeys, bIsEnabled, objRegistry, objScope, objSource } =
+    useFeatureFlagContext()
+  const bIsConfigured = objSource !== undefined
+  const bCanLoad = bIsConfigured && bIsEnabled && arrKeys.length > 0
+  const objQuery = useQuery({
+    ...fnFeatureFlagQueryOptions(
+      objSource ?? objUnavailableSource,
+      objScope,
+      arrKeys
+    ),
+    enabled: bCanLoad,
+  })
+  const objCatalog = bCanLoad ? objQuery.data : undefined
+
+  function fnEvaluate(strKey: string) {
+    return fnEvaluateFeatureFlag(
+      fnGetFeatureFlagDefinition(objRegistry, strKey),
+      objCatalog
+    )
+  }
+
+  async function fnRefetch() {
+    if (!bCanLoad) return
+    await objQuery.refetch()
+  }
+
+  return {
+    arrKeys,
+    bIsConfigured,
+    bIsEnabled,
+    bIsError: objQuery.isError,
+    bIsFetching: objQuery.isFetching,
+    bIsLoading: bCanLoad && objQuery.isPending,
+    nUpdatedAt: objQuery.dataUpdatedAt,
+    objCatalog,
+    objError: objQuery.error,
+    objScope,
+    strVersion: objCatalog?.version ?? null,
+    fnEvaluate,
+    fnRefetch,
+  }
+}
+
+function FeatureFlagPreload() {
+  useFeatureFlagCatalog()
+  return null
+}
+
+/** 读取一个已声明开关；加载和失败期间也始终返回可用的安全状态。 */
+// eslint-disable-next-line react-refresh/only-export-components
+export function useFeatureFlag(strKey: string): IUseFeatureFlagResult {
+  const objCatalogResult = useFeatureFlagCatalog()
+  const objEvaluation = objCatalogResult.fnEvaluate(strKey)
+
+  return {
+    ...objEvaluation,
+    bIsConfigured: objCatalogResult.bIsConfigured,
+    bIsEnabled: objCatalogResult.bIsEnabled,
+    bIsError: objCatalogResult.bIsError,
+    bIsFetching: objCatalogResult.bIsFetching,
+    bIsLoading: objCatalogResult.bIsLoading,
+    objError: objCatalogResult.objError,
+    strVersion: objCatalogResult.strVersion,
+    fnRefetch: objCatalogResult.fnRefetch,
+  }
+}

package/template/src/featureFlags/FeatureGate.tsx

@@ -0,0 +1,12 @@
+import { useFeatureFlag } from './FeatureFlagProvider'
+import type { IFeatureGateProps } from './types'
+
+/** 按开关结果选择渲染内容；它只控制前端呈现，不能替代后端授权。 */
+export function FeatureGate({
+  children: objChildren,
+  objFallback = null,
+  strFlagKey,
+}: IFeatureGateProps) {
+  const { bEnabled } = useFeatureFlag(strFlagKey)
+  return bEnabled ? objChildren : objFallback
+}

package/template/src/featureFlags/catalog.ts

@@ -0,0 +1,140 @@
+import { FeatureFlagError } from './errors'
+import type {
+  IFeatureFlag,
+  IFeatureFlagCatalog,
+  IFeatureFlagCatalogPayload,
+  IFeatureFlagPayload,
+  IFeatureFlagRequestContext,
+  IFeatureFlagSource,
+  TFeatureFlagJsonValue,
+  TFeatureFlagRequest,
+} from './types'
+
+export function fnIsFeatureFlagJsonValue(
+  objValue: TFeatureFlagJsonValue
+): boolean {
+  if (objValue === null) return true
+  if (typeof objValue === 'number') return Number.isFinite(objValue)
+  if (typeof objValue === 'boolean' || typeof objValue === 'string') return true
+  if (Array.isArray(objValue)) {
+    return objValue.every(fnIsFeatureFlagJsonValue)
+  }
+  if (typeof objValue !== 'object') return false
+  return Object.values(objValue).every(fnIsFeatureFlagJsonValue)
+}
+
+export function fnFreezeFeatureFlagJsonValue(
+  objValue: TFeatureFlagJsonValue
+): TFeatureFlagJsonValue {
+  if (Array.isArray(objValue)) {
+    return Object.freeze(objValue.map(fnFreezeFeatureFlagJsonValue))
+  }
+  if (objValue && typeof objValue === 'object') {
+    return Object.freeze(
+      Object.fromEntries(
+        Object.entries(objValue).map(([strKey, objItem]) => [
+          strKey,
+          fnFreezeFeatureFlagJsonValue(objItem),
+        ])
+      )
+    )
+  }
+  return objValue
+}
+
+function fnNormalizeFeatureFlag(
+  strKey: string,
+  objPayload: IFeatureFlagPayload,
+  nEvaluatedAt: number
+): IFeatureFlag {
+  if (
+    !strKey.trim() ||
+    strKey.trim() !== strKey ||
+    !objPayload ||
+    typeof objPayload !== 'object' ||
+    typeof objPayload.bEnabled !== 'boolean' ||
+    (objPayload.strVariant !== undefined &&
+      (typeof objPayload.strVariant !== 'string' ||
+        !objPayload.strVariant.trim())) ||
+    (objPayload.strReason !== undefined &&
+      typeof objPayload.strReason !== 'string') ||
+    (objPayload.objPayload !== undefined &&
+      !fnIsFeatureFlagJsonValue(objPayload.objPayload))
+  ) {
+    throw new FeatureFlagError(
+      'INVALID_FLAG',
+      `Feature Flag ${strKey || '<empty>'} 的远端结果无效。`
+    )
+  }
+
+  return Object.freeze({
+    bEnabled: objPayload.bEnabled,
+    nEvaluatedAt,
+    objPayload:
+      objPayload.objPayload === undefined
+        ? undefined
+        : fnFreezeFeatureFlagJsonValue(objPayload.objPayload),
+    strKey,
+    strReason: objPayload.strReason,
+    strVariant: objPayload.strVariant,
+  })
+}
+
+function fnNormalizeFeatureFlagCatalog(
+  objPayload: IFeatureFlagCatalogPayload | undefined,
+  arrRequestedKeys: readonly string[]
+): IFeatureFlagCatalog {
+  const nEvaluatedAt = objPayload?.nEvaluatedAt
+  const nExpiresAt = objPayload?.nExpiresAt
+  if (
+    !objPayload ||
+    !objPayload.objFlags ||
+    typeof objPayload.objFlags !== 'object' ||
+    Array.isArray(objPayload.objFlags) ||
+    typeof nEvaluatedAt !== 'number' ||
+    !Number.isFinite(nEvaluatedAt) ||
+    typeof nExpiresAt !== 'number' ||
+    !Number.isFinite(nExpiresAt) ||
+    nExpiresAt <= nEvaluatedAt ||
+    typeof objPayload.version !== 'string' ||
+    !objPayload.version.trim()
+  ) {
+    throw new FeatureFlagError(
+      'INVALID_CATALOG',
+      'Feature Flag 接口未返回有效目录。'
+    )
+  }
+
+  const objFlags = new Map<string, IFeatureFlag>()
+  const objRequestedKeys = new Set(arrRequestedKeys)
+  Object.entries(objPayload.objFlags).forEach(([strKey, objFlag]) => {
+    if (!objRequestedKeys.has(strKey)) return
+    if (!objFlag) {
+      throw new FeatureFlagError(
+        'INVALID_FLAG',
+        `Feature Flag ${strKey || '<empty>'} 缺少评估结果。`
+      )
+    }
+    objFlags.set(strKey, fnNormalizeFeatureFlag(strKey, objFlag, nEvaluatedAt))
+  })
+
+  return Object.freeze({
+    nEvaluatedAt,
+    nExpiresAt,
+    objFlags,
+    version: objPayload.version,
+  })
+}
+
+/** 将 Swagger 生成客户端请求适配为已校验的 Feature Flag 数据源。 */
+export function fnCreateFeatureFlagSource(
+  fnRequest: TFeatureFlagRequest
+): IFeatureFlagSource {
+  return Object.freeze({
+    fnLoadCatalog: async (objContext: IFeatureFlagRequestContext) =>
+      fnNormalizeFeatureFlagCatalog(
+        await fnRequest(objContext),
+        objContext.arrFlagKeys
+      ),
+  })
+}

package/template/src/featureFlags/errors.ts

@@ -0,0 +1,17 @@
+import type { TFeatureFlagErrorCode } from './types'
+
+/** 可由接入层和诊断界面稳定分类的 Feature Flag 错误。 */
+export class FeatureFlagError extends Error {
+  /** 供日志、UI 和测试分类的稳定错误码。 */
+  readonly strCode: TFeatureFlagErrorCode
+
+  constructor(
+    strCode: TFeatureFlagErrorCode,
+    strMessage: string,
+    objOptions?: ErrorOptions
+  ) {
+    super(strMessage, objOptions)
+    this.name = 'FeatureFlagError'
+    this.strCode = strCode
+  }
+}

package/template/src/featureFlags/index.ts

@@ -0,0 +1,43 @@
+export { fnCreateFeatureFlagSource } from './catalog'
+export { FeatureFlagError } from './errors'
+export { FeatureGate } from './FeatureGate'
+export {
+  FeatureFlagProvider,
+  useFeatureFlag,
+  useFeatureFlagCatalog,
+} from './FeatureFlagProvider'
+export {
+  fnEnsureFeatureFlags,
+  fnFeatureFlagQueryKey,
+  fnFeatureFlagQueryOptions,
+  fnGetCachedFeatureFlags,
+  fnInvalidateFeatureFlags,
+} from './query'
+export {
+  fnCreateFeatureFlagRegistry,
+  fnEvaluateFeatureFlag,
+  fnGetFeatureFlagDefinition,
+} from './registry'
+export { fnCreateFeatureFlagScope } from './scope'
+export type {
+  IFeatureFlag,
+  IFeatureFlagCatalog,
+  IFeatureFlagCatalogPayload,
+  IFeatureFlagDefinition,
+  IFeatureFlagEvaluation,
+  IFeatureFlagPayload,
+  IFeatureFlagProviderProps,
+  IFeatureFlagRequestContext,
+  IFeatureFlagScope,
+  IFeatureFlagScopeContext,
+  IFeatureFlagSource,
+  IFeatureGateProps,
+  IUseFeatureFlagCatalogResult,
+  IUseFeatureFlagResult,
+  TFeatureFlagErrorCode,
+  TFeatureFlagEvaluationReason,
+  TFeatureFlagEvaluationSource,
+  TFeatureFlagJsonValue,
+  TFeatureFlagKind,
+  TFeatureFlagRequest,
+} from './types'

package/template/src/featureFlags/query.ts

@@ -0,0 +1,103 @@
+import { queryOptions, type QueryClient } from '@tanstack/react-query'
+import { fnCreateFeatureFlagScope } from './scope'
+import type {
+  IFeatureFlagCatalog,
+  IFeatureFlagScope,
+  IFeatureFlagScopeContext,
+  IFeatureFlagSource,
+} from './types'
+
+const arrFeatureFlagQueryRoot: readonly ['featureFlags'] = ['featureFlags']
+const nFeatureFlagGcTimeMs = 30 * 60_000
+const nFeatureFlagMinimumRefreshIntervalMs = 5_000
+const nFeatureFlagFailedRefreshIntervalMs = 60_000
+
+function fnNormalizeFeatureFlagKeys(arrFlagKeys: readonly string[]) {
+  return Object.freeze([...new Set(arrFlagKeys)].sort())
+}
+
+/** 返回一个作用域和声明集合对应的稳定 Query Key。 */
+export function fnFeatureFlagQueryKey(
+  objScopeInput: IFeatureFlagScopeContext,
+  arrFlagKeys: readonly string[]
+): readonly ['featureFlags', IFeatureFlagScope, readonly string[]] {
+  return [
+    arrFeatureFlagQueryRoot[0],
+    fnCreateFeatureFlagScope(objScopeInput),
+    fnNormalizeFeatureFlagKeys(arrFlagKeys),
+  ]
+}
+
+/** 创建完整 Feature Flag 目录的 QueryClient 查询配置。 */
+export function fnFeatureFlagQueryOptions(
+  objSource: IFeatureFlagSource,
+  objScopeInput: IFeatureFlagScopeContext,
+  arrFlagKeys: readonly string[]
+) {
+  const objScope = fnCreateFeatureFlagScope(objScopeInput)
+  const arrNormalizedFlagKeys = fnNormalizeFeatureFlagKeys(arrFlagKeys)
+  return queryOptions({
+    gcTime: nFeatureFlagGcTimeMs,
+    queryFn: ({ signal: objSignal }) =>
+      objSource.fnLoadCatalog({
+        arrFlagKeys: arrNormalizedFlagKeys,
+        objScope,
+        objSignal,
+      }),
+    queryKey: fnFeatureFlagQueryKey(objScope, arrNormalizedFlagKeys),
+    refetchInterval: (objQuery) => {
+      if (objQuery.state.error) return nFeatureFlagFailedRefreshIntervalMs
+      const nExpiresAt = objQuery.state.data?.nExpiresAt
+      if (!nExpiresAt) return false
+      return Math.max(
+        nFeatureFlagMinimumRefreshIntervalMs,
+        nExpiresAt - Date.now()
+      )
+    },
+    staleTime: 0,
+  })
+}
+
+/** 在路由 Loader 或应用启动阶段确保指定作用域开关已加载。 */
+export function fnEnsureFeatureFlags(
+  objQueryClient: QueryClient,
+  objSource: IFeatureFlagSource,
+  objScope: IFeatureFlagScopeContext,
+  arrFlagKeys: readonly string[]
+) {
+  return objQueryClient.ensureQueryData(
+    fnFeatureFlagQueryOptions(objSource, objScope, arrFlagKeys)
+  )
+}
+
+/** 从 QueryClient 同步读取指定作用域和定义集合的远端目录。 */
+export function fnGetCachedFeatureFlags(
+  objQueryClient: QueryClient,
+  objScope: IFeatureFlagScopeContext,
+  arrFlagKeys: readonly string[]
+): IFeatureFlagCatalog | undefined {
+  return objQueryClient.getQueryData<IFeatureFlagCatalog>(
+    fnFeatureFlagQueryKey(objScope, arrFlagKeys)
+  )
+}
+
+/** 失效一个精确作用域或全部 Feature Flag 内存缓存。 */
+export function fnInvalidateFeatureFlags(
+  objQueryClient: QueryClient,
+  objScope?: IFeatureFlagScopeContext,
+  arrFlagKeys: readonly string[] = []
+) {
+  const objNormalizedScope = objScope
+    ? fnCreateFeatureFlagScope(objScope)
+    : undefined
+  const bHasExactKey =
+    objNormalizedScope !== undefined && arrFlagKeys.length > 0
+  return objQueryClient.invalidateQueries({
+    exact: bHasExactKey,
+    queryKey: objNormalizedScope
+      ? bHasExactKey
+        ? fnFeatureFlagQueryKey(objNormalizedScope, arrFlagKeys)
+        : [arrFeatureFlagQueryRoot[0], objNormalizedScope]
+      : arrFeatureFlagQueryRoot,
+  })
+}