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

package/template/src/locale/hooks.ts

@@ -0,0 +1,35 @@
+import { useContext, useMemo } from 'react'
+import { LocaleContext } from './context'
+import type {
+  ILocaleMessageReader,
+  TLocaleMessageCatalog,
+  TSharedMessageKey,
+} from './types'
+
+/** 读取当前 Locale、时区、格式化和共享文案能力。 */
+export function useLocale() {
+  return useContext(LocaleContext)
+}
+
+/** 读取单条共享壳层或基础组件文案。 */
+export function useSharedMessage(strKey: TSharedMessageKey) {
+  return useLocale().fnTranslateShared(strKey)
+}
+
+/**
+ * 按当前应用语言读取 Feature 自己拥有的完整语言包。
+ *
+ * 语言包跟随 Feature 源码和路由分包，不注册到全局消息对象。
+ */
+export function useLocaleMessages<TKey extends string>(
+  objMessages: TLocaleMessageCatalog<TKey>
+): ILocaleMessageReader<TKey> {
+  const { strLocale } = useLocale()
+  return useMemo(
+    () => ({
+      strLocale,
+      fnTranslate: (objKey: TKey) => objMessages[strLocale][objKey],
+    }),
+    [objMessages, strLocale]
+  )
+}

package/template/src/locale/index.ts

@@ -0,0 +1,17 @@
+export { fnCreateLocaleFormatter } from './formatters'
+export { LocaleProvider } from './LocaleProvider'
+export { useLocale, useLocaleMessages, useSharedMessage } from './hooks'
+export { fnDefineLocaleMessages, objSharedLocaleMessages } from './messages'
+export type {
+  ILocaleContextValue,
+  ILocaleFormatter,
+  ILocaleFormatterConfig,
+  ILocaleMessageReader,
+  ILocaleProviderProps,
+  TAppLocale,
+  TCurrencyFormatOptions,
+  TLocaleDateValue,
+  TLocaleMessageCatalog,
+  TSharedMessageKey,
+  TSharedMessageOverrides,
+} from './types'

package/template/src/locale/messages.ts

@@ -0,0 +1,151 @@
+import type { TLocaleMessageCatalog, TSharedMessageKey } from './types'
+
+/** 脚手架共享壳层与基础组件的内建中英文语言包。 */
+export const objSharedLocaleMessages: TLocaleMessageCatalog<TSharedMessageKey> =
+  Object.freeze({
+    'en-US': Object.freeze({
+      'appDataTable.empty': 'No data',
+      'appDataTable.scrollable': 'horizontal scrolling available',
+      'appDialog.cancel': 'Cancel',
+      'appDialog.confirm': 'Confirm',
+      'appDialog.confirmTitle': 'Confirmation',
+      'common.retry': 'Retry',
+      'filePreview.error': 'File preview failed',
+      'filePreview.loading': 'Preparing preview',
+      'filePreview.titleSuffix': 'preview',
+      'fileUpload.cancel': 'Cancel upload',
+      'fileUpload.canceled': 'Upload canceled',
+      'fileUpload.progress': 'Upload progress',
+      'fileUpload.retry': 'Retry',
+      'fileUpload.select': 'Select file',
+      'fileUpload.selectedFiles': 'Selected files',
+      'fileUpload.success': 'Upload complete',
+      'fileUpload.uploading': 'Uploading',
+      'header.search.ariaLabel': 'Search menu',
+      'header.search.description':
+        'Search pages or switch the interface theme.',
+      'header.search.empty': 'No matching results.',
+      'header.search.inputAriaLabel': 'Search pages or commands',
+      'header.search.placeholder': 'Type a command or search…',
+      'header.search.shortLabel': 'Search',
+      'header.search.themeGroup': 'Theme',
+      'header.search.themeValuePrefix': 'Theme',
+      'header.search.title': 'Page search',
+      'header.signOut': 'Sign out',
+      'header.switchTheme': 'Switch theme',
+      'header.theme.dark': 'Dark',
+      'header.theme.light': 'Light',
+      'header.theme.system': 'System',
+      'header.user': 'User',
+      'header.userMenu': 'User menu',
+      'jsonEditor.ariaLabel': 'JSON editor',
+      'jsonEditor.format': 'Format',
+      'jsonEditor.formatError': 'Invalid JSON',
+      'jsonEditor.placeholder': 'Enter JSON',
+      'password.hide': 'Hide password',
+      'password.show': 'Show password',
+      'sensitiveData.copied': 'Copied',
+      'sensitiveData.copyFailed': 'Could not copy sensitive data',
+      'sensitiveData.copyMasked': 'Copy masked value',
+      'sensitiveData.copyRevealed': 'Copy revealed value',
+      'sensitiveData.hide': 'Hide sensitive data',
+      'sensitiveData.loading': 'Loading sensitive data',
+      'sensitiveData.reveal': 'Reveal sensitive data',
+      'sensitiveData.revealFailed': 'Could not reveal sensitive data',
+      'sidebar.builtAt': 'Built at',
+      'sidebar.commit': 'Commit',
+      'sidebar.environment': 'environment',
+      'sidebar.expand': 'Expand sidebar',
+      'sidebar.version': 'Application version',
+      'pageFeedback.emptyDescription':
+        'Adjust the filters or create the first item when available.',
+      'pageFeedback.emptyTitle': 'No results yet',
+      'pageFeedback.errorDescription':
+        'The page could not be loaded. Try again later.',
+      'pageFeedback.errorTitle': 'Page data unavailable',
+      'pageFeedback.loadingDescription':
+        'Please wait while the latest data is loaded.',
+      'pageFeedback.loadingTitle': 'Loading page data',
+      'pageFeedback.requestId': 'Request ID',
+      'pageFeedback.retrying': 'Retrying…',
+      'unsavedChanges.description':
+        'You have unsaved changes. Leaving this page will discard them.',
+      'unsavedChanges.leave': 'Leave page',
+      'unsavedChanges.stay': 'Stay on page',
+      'unsavedChanges.title': 'Unsaved changes',
+    }),
+    'zh-CN': Object.freeze({
+      'appDataTable.empty': '暂无数据',
+      'appDataTable.scrollable': '可横向滚动',
+      'appDialog.cancel': '取消',
+      'appDialog.confirm': '确定',
+      'appDialog.confirmTitle': '提示',
+      'common.retry': '重试',
+      'filePreview.error': '文件预览失败',
+      'filePreview.loading': '正在准备预览',
+      'filePreview.titleSuffix': '预览',
+      'fileUpload.cancel': '取消上传',
+      'fileUpload.canceled': '上传已取消',
+      'fileUpload.progress': '上传进度',
+      'fileUpload.retry': '重试',
+      'fileUpload.select': '选择文件',
+      'fileUpload.selectedFiles': '已选择文件',
+      'fileUpload.success': '上传完成',
+      'fileUpload.uploading': '正在上传',
+      'header.search.ariaLabel': '搜索菜单',
+      'header.search.description': '搜索页面或切换界面主题。',
+      'header.search.empty': '没有匹配的结果。',
+      'header.search.inputAriaLabel': '搜索页面或命令',
+      'header.search.placeholder': '输入命令或搜索…',
+      'header.search.shortLabel': '搜索',
+      'header.search.themeGroup': '主题',
+      'header.search.themeValuePrefix': '主题',
+      'header.search.title': '页面搜索',
+      'header.signOut': '退出登录',
+      'header.switchTheme': '切换主题',
+      'header.theme.dark': '深色',
+      'header.theme.light': '浅色',
+      'header.theme.system': '跟随系统',
+      'header.user': '用户',
+      'header.userMenu': '用户菜单',
+      'jsonEditor.ariaLabel': 'JSON 编辑器',
+      'jsonEditor.format': '格式化',
+      'jsonEditor.formatError': 'JSON 格式错误',
+      'jsonEditor.placeholder': '请输入 JSON',
+      'password.hide': '隐藏密码',
+      'password.show': '显示密码',
+      'sensitiveData.copied': '已复制',
+      'sensitiveData.copyFailed': '敏感数据复制失败',
+      'sensitiveData.copyMasked': '复制脱敏值',
+      'sensitiveData.copyRevealed': '复制当前明文',
+      'sensitiveData.hide': '隐藏敏感数据',
+      'sensitiveData.loading': '正在加载敏感数据',
+      'sensitiveData.reveal': '查看敏感数据',
+      'sensitiveData.revealFailed': '敏感数据查看失败',
+      'sidebar.builtAt': '构建于',
+      'sidebar.commit': 'Commit',
+      'sidebar.environment': '部署环境',
+      'sidebar.expand': '展开侧边栏',
+      'sidebar.version': '应用版本',
+      'pageFeedback.emptyDescription':
+        '可以调整筛选条件，或在具备权限时创建第一条数据。',
+      'pageFeedback.emptyTitle': '暂无结果',
+      'pageFeedback.errorDescription': '页面数据暂时无法加载，请稍后再试。',
+      'pageFeedback.errorTitle': '页面数据不可用',
+      'pageFeedback.loadingDescription': '正在获取最新数据，请稍候。',
+      'pageFeedback.loadingTitle': '正在加载页面数据',
+      'pageFeedback.requestId': '请求 ID',
+      'pageFeedback.retrying': '正在重试…',
+      'unsavedChanges.description': '当前页面有未保存的修改，离开后将丢失。',
+      'unsavedChanges.leave': '离开页面',
+      'unsavedChanges.stay': '留在当前页',
+      'unsavedChanges.title': '未保存的修改',
+    }),
+  })
+
+/** 保留 Feature 语言包的完整 Key 与双语言类型，不把它注册到全局目录。 */
+export function fnDefineLocaleMessages<TKey extends string>(
+  objMessages: TLocaleMessageCatalog<TKey>
+) {
+  return objMessages
+}

package/template/src/locale/types.ts

@@ -0,0 +1,167 @@
+import type { ReactNode } from 'react'
+
+/** 脚手架当前内建语言；项目扩展时必须同时补齐共享和 Feature 语言包。 */
+export type TAppLocale = 'en-US' | 'zh-CN'
+
+/** 日期格式化接受的无歧义输入；字符串必须由业务先解析为 Date 或时间戳。 */
+export type TLocaleDateValue = Date | number
+
+/** 货币格式化选项；货币代码由单独参数明确提供。 */
+export type TCurrencyFormatOptions = Omit<
+  Intl.NumberFormatOptions,
+  'currency' | 'style'
+>
+
+/** 共享壳层和基础组件使用的稳定文案 Key。 */
+export type TSharedMessageKey =
+  | 'appDataTable.empty'
+  | 'appDataTable.scrollable'
+  | 'appDialog.cancel'
+  | 'appDialog.confirm'
+  | 'appDialog.confirmTitle'
+  | 'common.retry'
+  | 'filePreview.error'
+  | 'filePreview.loading'
+  | 'filePreview.titleSuffix'
+  | 'fileUpload.cancel'
+  | 'fileUpload.canceled'
+  | 'fileUpload.progress'
+  | 'fileUpload.retry'
+  | 'fileUpload.select'
+  | 'fileUpload.selectedFiles'
+  | 'fileUpload.success'
+  | 'fileUpload.uploading'
+  | 'header.search.ariaLabel'
+  | 'header.search.description'
+  | 'header.search.empty'
+  | 'header.search.inputAriaLabel'
+  | 'header.search.placeholder'
+  | 'header.search.shortLabel'
+  | 'header.search.themeGroup'
+  | 'header.search.themeValuePrefix'
+  | 'header.search.title'
+  | 'header.signOut'
+  | 'header.switchTheme'
+  | 'header.theme.dark'
+  | 'header.theme.light'
+  | 'header.theme.system'
+  | 'header.user'
+  | 'header.userMenu'
+  | 'jsonEditor.ariaLabel'
+  | 'jsonEditor.format'
+  | 'jsonEditor.formatError'
+  | 'jsonEditor.placeholder'
+  | 'password.hide'
+  | 'password.show'
+  | 'sensitiveData.copied'
+  | 'sensitiveData.copyFailed'
+  | 'sensitiveData.copyMasked'
+  | 'sensitiveData.copyRevealed'
+  | 'sensitiveData.hide'
+  | 'sensitiveData.loading'
+  | 'sensitiveData.reveal'
+  | 'sensitiveData.revealFailed'
+  | 'sidebar.builtAt'
+  | 'sidebar.commit'
+  | 'sidebar.environment'
+  | 'sidebar.expand'
+  | 'sidebar.version'
+  | 'pageFeedback.emptyDescription'
+  | 'pageFeedback.emptyTitle'
+  | 'pageFeedback.errorDescription'
+  | 'pageFeedback.errorTitle'
+  | 'pageFeedback.loadingDescription'
+  | 'pageFeedback.loadingTitle'
+  | 'pageFeedback.requestId'
+  | 'pageFeedback.retrying'
+  | 'unsavedChanges.description'
+  | 'unsavedChanges.leave'
+  | 'unsavedChanges.stay'
+  | 'unsavedChanges.title'
+
+/** 某组稳定 Key 在全部内建语言下的完整语言包。 */
+export type TLocaleMessageCatalog<TKey extends string> = Readonly<
+  Record<TAppLocale, Readonly<Record<TKey, string>>>
+>
+
+/** 项目对共享文案的按语言覆盖；未提供的 Key 回退到脚手架内建文案。 */
+export type TSharedMessageOverrides = Readonly<
+  Partial<
+    Record<TAppLocale, Readonly<Partial<Record<TSharedMessageKey, string>>>>
+  >
+>
+
+/** Locale Provider 的公共参数。 */
+export interface ILocaleProviderProps {
+  /** 应用子树。 */
+  children: ReactNode
+  /** 当前应用语言，同时驱动共享文案、Intl 和后端元数据语言。 */
+  strLocale: TAppLocale
+  /** 当前 IANA 时区，例如 `Asia/Shanghai`。 */
+  strTimeZone: string
+  /** 项目级共享文案覆盖，不用于注册 Feature 业务语言包。 */
+  objSharedMessages?: TSharedMessageOverrides
+}
+
+/** Locale 格式化器的公共配置。 */
+export interface ILocaleFormatterConfig {
+  /** BCP 47 语言标签。 */
+  strLocale: TAppLocale
+  /** 所有日期和时间格式化统一使用的 IANA 时区。 */
+  strTimeZone: string
+}
+
+/** Locale 格式化能力；由 Provider 和 React 外代码共同消费。 */
+export interface ILocaleFormatter {
+  /** 当前 BCP 47 语言标签。 */
+  strLocale: TAppLocale
+  /** 当前统一 IANA 时区。 */
+  strTimeZone: string
+  /** 按当前语言和时区格式化日期。 */
+  fnFormatDate: (
+    objValue: TLocaleDateValue,
+    objOptions?: Intl.DateTimeFormatOptions
+  ) => string
+  /** 按当前语言和时区格式化日期时间。 */
+  fnFormatDateTime: (
+    objValue: TLocaleDateValue,
+    objOptions?: Intl.DateTimeFormatOptions
+  ) => string
+  /** 按当前语言和时区格式化时间。 */
+  fnFormatTime: (
+    objValue: TLocaleDateValue,
+    objOptions?: Intl.DateTimeFormatOptions
+  ) => string
+  /** 按当前语言格式化有限数字。 */
+  fnFormatNumber: (
+    nValue: number,
+    objOptions?: Intl.NumberFormatOptions
+  ) => string
+  /** 按 Intl 的 0 到 1 比例语义格式化百分比。 */
+  fnFormatPercent: (
+    nValue: number,
+    objOptions?: Intl.NumberFormatOptions
+  ) => string
+  /** 按 ISO 4217 货币代码格式化金额。 */
+  fnFormatCurrency: (
+    nValue: number,
+    strCurrency: string,
+    objOptions?: TCurrencyFormatOptions
+  ) => string
+  /** 使用当前语言的排序规则比较两个展示字符串。 */
+  fnCompare: (strLeft: string, strRight: string) => number
+}
+
+/** React 消费者读取的 Locale 上下文。 */
+export interface ILocaleContextValue extends ILocaleFormatter {
+  /** 读取共享壳层或基础组件文案。 */
+  fnTranslateShared: (strKey: TSharedMessageKey) => string
+}
+
+/** Feature 自有语言包的读取结果。 */
+export interface ILocaleMessageReader<TKey extends string> {
+  /** 当前应用语言。 */
+  strLocale: TAppLocale
+  /** 从当前 Feature 语言包读取文案。 */
+  fnTranslate: (objKey: TKey) => string
+}

package/template/src/main.tsx

@@ -0,0 +1,5 @@
+import '@fontsource-variable/inter'
+import { fnBootstrapApplication } from './bootstrap'
+import './styles/index.css'
+
+void fnBootstrapApplication()

package/template/src/observability/browser.ts

@@ -0,0 +1,37 @@
+import { fnCaptureError } from './observer'
+
+/** 监听浏览器未捕获异常和未处理 Promise，并返回明确的清理函数。 */
+export function fnStartGlobalErrorObservation(objWindow: Window = window) {
+  function fnHandleWindowError(objEvent: ErrorEvent) {
+    const objError =
+      objEvent.error instanceof Error ? objEvent.error : objEvent.message
+    fnCaptureError(objError, {
+      strName: 'browser.unhandled_error',
+      strSource: 'global',
+      objAttributes: { strPhase: 'window' },
+    })
+  }
+
+  function fnHandleUnhandledRejection(objEvent: PromiseRejectionEvent) {
+    const objReason =
+      objEvent.reason instanceof Error
+        ? objEvent.reason
+        : 'Unhandled Promise rejection'
+    fnCaptureError(objReason, {
+      strName: 'browser.unhandled_rejection',
+      strSource: 'global',
+      objAttributes: { strPhase: 'promise' },
+    })
+  }
+
+  objWindow.addEventListener('error', fnHandleWindowError)
+  objWindow.addEventListener('unhandledrejection', fnHandleUnhandledRejection)
+
+  return () => {
+    objWindow.removeEventListener('error', fnHandleWindowError)
+    objWindow.removeEventListener(
+      'unhandledrejection',
+      fnHandleUnhandledRejection
+    )
+  }
+}

package/template/src/observability/consoleAdapter.ts

@@ -0,0 +1,18 @@
+import type { IObservabilityAdapter } from './types'
+
+/** 仅用于本地开发的安全 Console Adapter；生产项目应替换为正式监控供应商。 */
+export function fnCreateConsoleObservabilityAdapter(): IObservabilityAdapter {
+  return {
+    fnCaptureEvent(objEvent) {
+      if (objEvent.strLevel === 'error') {
+        console.error('[observability]', objEvent)
+        return
+      }
+      if (objEvent.strLevel === 'warning') {
+        console.warn('[observability]', objEvent)
+        return
+      }
+      console.info('[observability]', objEvent)
+    },
+  }
+}

package/template/src/observability/index.ts

@@ -0,0 +1,26 @@
+export { fnStartGlobalErrorObservation } from './browser'
+export { fnCreateConsoleObservabilityAdapter } from './consoleAdapter'
+export {
+  fnCaptureError,
+  fnCaptureObservabilityEvent,
+  fnConfigureObservability,
+} from './observer'
+export {
+  fnRedactObservabilityString,
+  fnSanitizeObservabilityAttributes,
+} from './redaction'
+export type {
+  ICaptureErrorOptions,
+  ICaptureEventOptions,
+  IBuildInfo,
+  IObservabilityAdapter,
+  IObservabilityConfig,
+  IObservabilityEvent,
+  IObservabilityException,
+  IReleaseInfo,
+  TObservabilityAttributeInput,
+  TObservabilityAttributeValue,
+  TObservabilityErrorInput,
+  TObservabilityLevel,
+  TObservabilitySource,
+} from './types'

package/template/src/observability/observer.ts

@@ -0,0 +1,118 @@
+import { objBuildInfo } from '@/config/buildInfo'
+import {
+  fnRedactObservabilityStack,
+  fnRedactObservabilityString,
+  fnSanitizeObservabilityAttributes,
+} from './redaction'
+import type {
+  ICaptureErrorOptions,
+  ICaptureEventOptions,
+  IObservabilityConfig,
+  IObservabilityEvent,
+  IReleaseInfo,
+  TObservabilityErrorInput,
+} from './types'
+
+const objSeenErrors = new WeakSet<object>()
+const objDefaultRelease: Readonly<IReleaseInfo> = Object.freeze({
+  ...objBuildInfo,
+  strEnvironment: 'unknown',
+})
+let objObservabilityConfig: IObservabilityConfig = {
+  bEnabled: false,
+  objRelease: objDefaultRelease,
+}
+
+function fnCreateEventId() {
+  if (typeof globalThis.crypto?.randomUUID === 'function') {
+    return globalThis.crypto.randomUUID()
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 14)}`
+}
+
+function fnDispatchObservabilityEvent(objEvent: IObservabilityEvent) {
+  const fnCaptureEvent = objObservabilityConfig.objAdapter?.fnCaptureEvent
+  if (!fnCaptureEvent) return
+
+  try {
+    void Promise.resolve(fnCaptureEvent(objEvent)).catch(() => undefined)
+  } catch {
+    // 监控供应商故障不能阻断应用，也不能递归产生新的监控错误。
+  }
+}
+
+function fnCreateBaseEvent({
+  strName,
+  strSource,
+  strLevel = 'info',
+  objAttributes,
+}: ICaptureEventOptions): IObservabilityEvent {
+  return Object.freeze({
+    strEventId: fnCreateEventId(),
+    strName: fnRedactObservabilityString(strName),
+    strLevel,
+    strSource,
+    strTimestamp: new Date().toISOString(),
+    objRelease: objObservabilityConfig.objRelease,
+    objAttributes: fnSanitizeObservabilityAttributes(objAttributes),
+  })
+}
+
+/** 替换当前可观测性配置；通常在运行时配置加载完成后调用一次。 */
+export function fnConfigureObservability(objConfig: IObservabilityConfig) {
+  objObservabilityConfig = {
+    bEnabled: objConfig.bEnabled,
+    objAdapter: objConfig.objAdapter,
+    objRelease: Object.freeze({ ...objConfig.objRelease }),
+  }
+}
+
+/** 发送不包含原始业务数据的结构化生命周期事件。 */
+export function fnCaptureObservabilityEvent(objOptions: ICaptureEventOptions) {
+  if (!objObservabilityConfig.bEnabled) return undefined
+
+  const objEvent = fnCreateBaseEvent(objOptions)
+  fnDispatchObservabilityEvent(objEvent)
+  return objEvent
+}
+
+/**
+ * 捕获全局、路由或 API 异常。只发送脱敏摘要，同一个 Error 对象只采集一次。
+ */
+export function fnCaptureError(
+  objError: TObservabilityErrorInput,
+  objOptions: ICaptureErrorOptions
+) {
+  if (!objObservabilityConfig.bEnabled) return undefined
+  if (typeof objError === 'object' && objError !== null) {
+    if (objSeenErrors.has(objError)) return undefined
+    objSeenErrors.add(objError)
+  }
+
+  const strErrorName =
+    objError instanceof Error ? objError.name : 'UnknownError'
+  const strErrorMessage =
+    objError instanceof Error
+      ? objError.message
+      : ['boolean', 'number', 'string'].includes(typeof objError)
+        ? String(objError)
+        : '应用发生未知错误'
+  const objEvent: IObservabilityEvent = Object.freeze({
+    ...fnCreateBaseEvent({
+      ...objOptions,
+      strLevel: 'error',
+    }),
+    objException: Object.freeze({
+      strName: fnRedactObservabilityString(strErrorName) || 'Error',
+      strMessage:
+        fnRedactObservabilityString(strErrorMessage) || '应用发生未知错误',
+      strStack:
+        objError instanceof Error && objError.stack
+          ? fnRedactObservabilityStack(objError.stack)
+          : undefined,
+    }),
+  })
+
+  fnDispatchObservabilityEvent(objEvent)
+  return objEvent
+}

package/template/src/observability/redaction.ts

@@ -0,0 +1,85 @@
+import type {
+  TObservabilityAttributeInput,
+  TObservabilityAttributeValue,
+} from './types'
+
+const nMaxObservabilityStringLength = 500
+const nMaxObservabilityStackLength = 4_000
+const objAllowedAttributeKeys = new Set([
+  'bRetriable',
+  'nMetricDelta',
+  'nMetricValue',
+  'nNavigationId',
+  'nStatus',
+  'strCode',
+  'strKind',
+  'strMetricId',
+  'strMetricName',
+  'strMetricRating',
+  'strNavigationType',
+  'strPhase',
+  'strReason',
+  'strRequestId',
+  'strRouteId',
+])
+const objSensitiveAttributeKeyPattern =
+  /authorization|cookie|credential|email|password|phone|secret|token|body|payload/i
+
+/** 清理日志字符串中的控制字符、凭据和常见个人信息。 */
+export function fnRedactObservabilityString(strValue: string) {
+  return Array.from(strValue)
+    .map((strCharacter) => {
+      const nCodePoint = strCharacter.codePointAt(0) ?? 0
+      return nCodePoint <= 31 || nCodePoint === 127 ? ' ' : strCharacter
+    })
+    .join('')
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi, 'Bearer [REDACTED]')
+    .replace(
+      /\b(authorization|cookie|password|passwd|secret|token|access[_-]?token|refresh[_-]?token)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s,;]+)/gi,
+      '$1=[REDACTED]'
+    )
+    .replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, '[REDACTED_EMAIL]')
+    .replace(/(?<!\d)1[3-9]\d{9}(?!\d)/g, '[REDACTED_PHONE]')
+    .replace(/\b(https?:\/\/[^\s?#]+)[?#][^\s]*/gi, '$1')
+    .trim()
+    .slice(0, nMaxObservabilityStringLength)
+}
+
+/** 保留诊断所需的前 20 行调用栈，同时复用字符串脱敏策略。 */
+export function fnRedactObservabilityStack(strStack: string) {
+  return strStack
+    .split('\n')
+    .slice(0, 20)
+    .map(fnRedactObservabilityString)
+    .join('\n')
+    .slice(0, nMaxObservabilityStackLength)
+}
+
+/**
+ * 默认拒绝上下文：只有脚手架声明的标量 Key 能进入 Adapter，嵌套请求体和未知字段全部丢弃。
+ */
+export function fnSanitizeObservabilityAttributes(
+  objInput: Readonly<Record<string, TObservabilityAttributeInput>> = {}
+) {
+  const objSafeAttributes: Record<string, TObservabilityAttributeValue> = {}
+
+  Object.entries(objInput).forEach(([strKey, objValue]) => {
+    if (
+      !objAllowedAttributeKeys.has(strKey) ||
+      objSensitiveAttributeKeyPattern.test(strKey) ||
+      (typeof objValue !== 'string' &&
+        typeof objValue !== 'number' &&
+        typeof objValue !== 'boolean' &&
+        objValue !== null)
+    ) {
+      return
+    }
+
+    objSafeAttributes[strKey] =
+      typeof objValue === 'string'
+        ? fnRedactObservabilityString(objValue)
+        : objValue
+  })
+
+  return Object.freeze(objSafeAttributes)
+}