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

package/template/src/authentication/types.ts

@@ -0,0 +1,300 @@
+import type { IAuthTokenResult } from '@/api/types'
+
+/** 认证编排所服务的业务目的。 */
+export type TAuthenticationPurpose = 'signIn' | 'stepUp'
+
+/** 认证控制器可观察的互斥状态。 */
+export type TAuthenticationStatus =
+  | 'awaitingChallenge'
+  | 'cancelled'
+  | 'completed'
+  | 'error'
+  | 'idle'
+  | 'redirecting'
+  | 'working'
+
+/** 登录认证的启动参数。 */
+export interface IAuthenticationSignInStartInput {
+  /** signIn 表示本次流程最终需要建立应用会话。 */
+  readonly strPurpose: 'signIn'
+  /** 后端配置的认证提供方稳定 key，例如 corporate-sso。 */
+  readonly strProviderKey: string
+  /** 登录成功后的站内路径；后端必须与 state 事务绑定并在回调时返回。 */
+  readonly strReturnPath?: string
+}
+
+/** 敏感操作二次认证的启动参数。 */
+export interface IAuthenticationStepUpStartInput {
+  /** stepUp 表示本次流程只提升当前会话保证级别。 */
+  readonly strPurpose: 'stepUp'
+  /** 后端定义的敏感操作稳定 key，不应包含参数或个人数据。 */
+  readonly strActionKey: string
+  /** 后端配置的二次认证提供方稳定 key。 */
+  readonly strProviderKey: string
+  /** 可选的资源类型或范围 key，不传递完整资源内容。 */
+  readonly strResourceKey?: string
+}
+
+/** 认证启动参数，以 purpose 阻止登录与 Step-up 字段混用。 */
+export type TAuthenticationStartInput =
+  | IAuthenticationSignInStartInput
+  | IAuthenticationStepUpStartInput
+
+/** 后端返回的可选认证方式。 */
+export interface IAuthenticationChallengeMethod {
+  /** Adapter 和后端共同约定的稳定方式 key，例如 totp、smsOtp。 */
+  readonly strMethod: string
+  /** 已完成本地化且不包含秘密的展示名称。 */
+  readonly strLabel: string
+}
+
+/** MFA 或 Step-up 等待用户完成的挑战。 */
+export interface IAuthenticationChallenge {
+  /** 后端签发的短期挑战标识，不得写入 URL、日志或持久化存储。 */
+  readonly strChallengeId: string
+  /** 当前选中的认证方式 key。 */
+  readonly strMethod: string
+  /** 挑战绝对过期时间，单位为毫秒时间戳。 */
+  readonly nExpiresAt: number
+  /** 剩余可提交次数；省略表示后端没有安全地公开该信息。 */
+  readonly nAttemptsRemaining?: number
+  /** 再次发送验证码前需要等待的毫秒数。 */
+  readonly nRetryAfterMs?: number
+  /** 后端已经脱敏的手机号、邮箱或设备提示。 */
+  readonly strMaskedDestination?: string
+  /** 当前允许切换的认证方式。 */
+  readonly arrMethods?: readonly IAuthenticationChallengeMethod[]
+}
+
+/** 浏览器回调路由交给生成客户端 Adapter 的协议参数。 */
+export interface IAuthenticationCallbackInput {
+  /** 回调所属目的必须由独立回调路由确定，不能相信查询参数自报。 */
+  readonly strPurpose: TAuthenticationPurpose
+  /** 路由运行时收窄后的回调参数；Adapter 再映射到后端生成 DTO。 */
+  readonly objParameters: Readonly<Record<string, string>>
+}
+
+/** 用户提交 MFA 或 Step-up 挑战时的结构化响应。 */
+export interface IAuthenticationChallengeResponseInput {
+  /** 当前控制器快照中的短期挑战标识。 */
+  readonly strChallengeId: string
+  /** 当前认证方式 key。 */
+  readonly strMethod: string
+  /** OTP、恢复码或 WebAuthn 字段的字符串映射，不得记录或持久化。 */
+  readonly objResponse: Readonly<Record<string, string>>
+}
+
+/** 由服务端会话承载、不需要浏览器传递凭据的 Step-up 授权。 */
+export interface IAuthenticationServerStepUpGrant {
+  /** serverSession 表示后续请求由后端会话识别提升结果。 */
+  readonly strMode: 'serverSession'
+  /** 用于审计关联的非秘密授权标识。 */
+  readonly strGrantId: string
+  /** 授权绝对过期时间，单位为毫秒时间戳。 */
+  readonly nExpiresAt: number
+}
+
+/** 必须由下一次敏感请求显式携带的短期 Step-up 授权。 */
+export interface IAuthenticationRequestTokenStepUpGrant {
+  /** requestToken 表示下一次敏感请求需要携带短期证明。 */
+  readonly strMode: 'requestToken'
+  /** 用于审计关联的非秘密授权标识。 */
+  readonly strGrantId: string
+  /** 只允许进入目标请求头或请求体的短期证明，不得持久化或记录。 */
+  readonly strProofToken: string
+  /** 授权绝对过期时间，单位为毫秒时间戳。 */
+  readonly nExpiresAt: number
+}
+
+/** Step-up 完成后服务端返回的两种授权承载方式。 */
+export type TAuthenticationStepUpGrant =
+  | IAuthenticationRequestTokenStepUpGrant
+  | IAuthenticationServerStepUpGrant
+
+/** 登录流程完成结果，由应用层建立唯一认证会话。 */
+export interface IAuthenticationSignInCompletion {
+  /** signIn 结果只能进入应用会话建立函数。 */
+  readonly strPurpose: 'signIn'
+  /** 生成客户端 Adapter 映射后的统一 Token 和身份结果。 */
+  readonly objTokenResult: IAuthTokenResult
+  /** 后端从认证事务恢复的站内回跳路径；应用仍须再次安全解析。 */
+  readonly strReturnPath?: string
+}
+
+/** Step-up 流程完成结果，不创建第二套登录会话。 */
+export interface IAuthenticationStepUpCompletion {
+  /** stepUp 结果只能用于恢复当前被挂起的敏感操作。 */
+  readonly strPurpose: 'stepUp'
+  /** 后端签发的短期提升授权。 */
+  readonly objGrant: TAuthenticationStepUpGrant
+}
+
+/** 认证流程完成结果。 */
+export type TAuthenticationCompletion =
+  | IAuthenticationSignInCompletion
+  | IAuthenticationStepUpCompletion
+
+/** Adapter 要求浏览器跳转到经过服务端创建的认证地址。 */
+export interface IAuthenticationRedirectResult {
+  /** redirect 表示当前页面需要离开或跳转。 */
+  readonly strResult: 'redirect'
+  /** 该结果所属认证目的。 */
+  readonly strPurpose: TAuthenticationPurpose
+  /** 服务端创建的授权地址，控制器仍会执行协议和 Origin 校验。 */
+  readonly strRedirectUrl: string
+  /** 后端认证事务的非秘密关联标识。 */
+  readonly strTransactionId: string
+}
+
+/** Adapter 要求页面收集 MFA 或 Step-up 响应。 */
+export interface IAuthenticationChallengeResult {
+  /** challenge 表示控制器进入等待用户输入状态。 */
+  readonly strResult: 'challenge'
+  /** 该结果所属认证目的。 */
+  readonly strPurpose: TAuthenticationPurpose
+  /** 后端认证事务的非秘密关联标识。 */
+  readonly strTransactionId: string
+  /** 当前需要展示的挑战。 */
+  readonly objChallenge: IAuthenticationChallenge
+}
+
+/** Adapter 已经完成登录或 Step-up。 */
+export interface IAuthenticationCompleteResult {
+  /** complete 表示结果可交给应用完成回调消费。 */
+  readonly strResult: 'complete'
+  /** 不在控制器快照中长期保存的完成结果。 */
+  readonly objCompletion: TAuthenticationCompletion
+}
+
+/** 认证 Adapter 每一步允许返回的互斥结果。 */
+export type TAuthenticationAdapterResult =
+  | IAuthenticationChallengeResult
+  | IAuthenticationCompleteResult
+  | IAuthenticationRedirectResult
+
+/** Adapter 调用时统一提供的取消上下文。 */
+export interface IAuthenticationAdapterContext {
+  /** 新操作、取消或控制器释放时终止生成客户端请求。 */
+  readonly objSignal: AbortSignal
+}
+
+/** 取消后端认证事务时提供的最小安全上下文。 */
+export interface IAuthenticationCancelInput {
+  /** 需要取消的认证目的。 */
+  readonly strPurpose: TAuthenticationPurpose
+  /** 后端认证事务的非秘密关联标识。 */
+  readonly strTransactionId: string
+}
+
+/** Feature 使用 swagger-typescript-api 生成客户端实现的认证 Adapter。 */
+export interface IAuthenticationAdapter {
+  /** 启动登录或 Step-up，返回 redirect、challenge 或 complete。 */
+  readonly fnStart: (
+    objInput: TAuthenticationStartInput,
+    objContext: IAuthenticationAdapterContext
+  ) => Promise<TAuthenticationAdapterResult>
+  /** 完成 OIDC/SAML 等回调；协议参数只在 Adapter 和后端之间流动。 */
+  readonly fnCompleteRedirect: (
+    objInput: IAuthenticationCallbackInput,
+    objContext: IAuthenticationAdapterContext
+  ) => Promise<TAuthenticationAdapterResult>
+  /** 验证当前 MFA 或 Step-up 挑战响应。 */
+  readonly fnVerifyChallenge: (
+    objInput: IAuthenticationChallengeResponseInput,
+    objContext: IAuthenticationAdapterContext
+  ) => Promise<TAuthenticationAdapterResult>
+  /** 尽力取消后端事务；本地状态不会因远端取消失败而继续保留。 */
+  readonly fnCancel?: (
+    objInput: IAuthenticationCancelInput,
+    objContext: IAuthenticationAdapterContext
+  ) => Promise<void>
+}
+
+/** 外部认证跳转的明确信任策略。 */
+export interface IAuthenticationRedirectPolicy {
+  /** 当前应用的完整 Origin，例如 `https://admin.example.com`。 */
+  readonly strApplicationOrigin: string
+  /** 允许跳转的身份提供方 Origin；当前应用 Origin 会自动加入。 */
+  readonly arrAllowedOrigins?: readonly string[]
+}
+
+type TAuthenticationErrorCode =
+  | 'adapter_failed'
+  | 'completion_failed'
+  | 'invalid_challenge'
+  | 'invalid_input'
+  | 'invalid_redirect'
+  | 'invalid_result'
+  | 'invalid_state'
+  | 'navigation_failed'
+
+/** 不包含 Token、挑战响应或协议参数的认证编排错误。 */
+export class AuthenticationError extends Error {
+  /** 页面反馈、监控分类和测试使用的稳定错误码。 */
+  readonly strCode: TAuthenticationErrorCode
+
+  constructor(
+    strCode: TAuthenticationErrorCode,
+    strMessage: string,
+    objOptions?: ErrorOptions
+  ) {
+    super(strMessage, objOptions)
+    this.name = 'AuthenticationError'
+    this.strCode = strCode
+  }
+}
+
+/** 页面可订阅的认证快照，不保存 Token、证明或挑战响应。 */
+export interface IAuthenticationSnapshot {
+  /** 当前控制器生命周期状态。 */
+  readonly strStatus: TAuthenticationStatus
+  /** 当前登录或 Step-up 目的。 */
+  readonly strPurpose?: TAuthenticationPurpose
+  /** 每次状态发布递增的修订号。 */
+  readonly nRevision: number
+  /** 等待用户完成的当前挑战。 */
+  readonly objChallenge?: IAuthenticationChallenge
+  /** 当前后端事务的非秘密关联标识。 */
+  readonly strTransactionId?: string
+  /** 不包含外部响应和凭据的安全错误。 */
+  readonly objError?: AuthenticationError
+}
+
+/** 创建认证控制器所需的外部边界。 */
+export interface ICreateAuthenticationControllerOptions {
+  /** 由 Feature 生成客户端实现的协议 Adapter。 */
+  readonly objAdapter: IAuthenticationAdapter
+  /** 外部跳转 Origin 白名单。 */
+  readonly objRedirectPolicy: IAuthenticationRedirectPolicy
+  /** 执行经过控制器校验的完整跳转地址。 */
+  readonly fnNavigateRedirect: (strRedirectUrl: string) => void | Promise<void>
+  /** 立即消费完成结果；控制器不会把 Token 或证明放入快照。 */
+  readonly fnOnComplete: (
+    objCompletion: TAuthenticationCompletion,
+    objContext: IAuthenticationAdapterContext
+  ) => void | Promise<void>
+}
+
+/** 登录、SSO 回调、MFA 和 Step-up 共用的认证控制器。 */
+export interface IAuthenticationController {
+  /** 读取当前不可变快照。 */
+  readonly fnGetSnapshot: () => IAuthenticationSnapshot
+  /** 订阅状态变化并返回取消订阅函数。 */
+  readonly fnSubscribe: (fnListener: () => void) => () => void
+  /** 启动新的登录或 Step-up，自动取消上一操作。 */
+  readonly fnStart: (
+    objInput: TAuthenticationStartInput
+  ) => Promise<IAuthenticationSnapshot>
+  /** 在回调路由中完成外部认证。 */
+  readonly fnCompleteRedirect: (
+    objInput: IAuthenticationCallbackInput
+  ) => Promise<IAuthenticationSnapshot>
+  /** 提交当前挑战响应。 */
+  readonly fnVerifyChallenge: (
+    objInput: IAuthenticationChallengeResponseInput
+  ) => Promise<IAuthenticationSnapshot>
+  /** 取消当前本地请求并尽力取消远端事务。 */
+  readonly fnCancel: () => Promise<IAuthenticationSnapshot>
+  /** 清除完成、取消或错误状态并回到 idle。 */
+  readonly fnReset: () => IAuthenticationSnapshot
+}

package/template/src/bootstrap.tsx

@@ -0,0 +1,96 @@
+import { StrictMode } from 'react'
+import ReactDOM from 'react-dom/client'
+import { RuntimeConfigErrorPage } from './config/RuntimeConfigErrorPage'
+import { objBuildInfo } from './config/buildInfo'
+import { objProjectObservabilityAdapter } from './config/observabilityAdapter'
+import { fnLoadRuntimeConfig, RuntimeConfigError } from './config/runtimeConfig'
+import {
+  fnCaptureError,
+  fnCaptureObservabilityEvent,
+  fnConfigureObservability,
+  fnStartGlobalErrorObservation,
+} from './observability'
+
+/**
+ * 完成运行时配置、可观测性、认证生命周期与 React 根节点的有序启动。
+ * 调用方不需要了解 runtime config 必须早于 appConfig 求值的约束。
+ */
+export async function fnBootstrapApplication() {
+  const objRootElement = document.getElementById('root')
+  if (!objRootElement) return
+  const objRoot = ReactDOM.createRoot(objRootElement)
+  let fnStopGlobalErrorObservation: (() => void) | undefined
+
+  fnConfigureObservability({
+    bEnabled: Boolean(objProjectObservabilityAdapter),
+    objAdapter: objProjectObservabilityAdapter,
+    objRelease: {
+      ...objBuildInfo,
+      strEnvironment: 'bootstrap',
+    },
+  })
+
+  try {
+    await fnLoadRuntimeConfig()
+    const { fnApplyAppDocumentMetadata, objAppConfig } =
+      await import('./config/appConfig')
+    fnConfigureObservability({
+      bEnabled: objAppConfig.observability.bEnabled,
+      objAdapter: objProjectObservabilityAdapter,
+      objRelease: objAppConfig.release,
+    })
+    fnStopGlobalErrorObservation = fnStartGlobalErrorObservation()
+    const [{ Application }, { fnStartAuthLifecycle }] = await Promise.all([
+      import('./Application'),
+      import('./router/router'),
+    ])
+    const fnStopAuthLifecycle = fnStartAuthLifecycle()
+    import.meta.hot?.dispose(() => {
+      fnStopAuthLifecycle()
+      fnStopGlobalErrorObservation?.()
+    })
+    fnApplyAppDocumentMetadata()
+
+    objRoot.render(
+      <StrictMode>
+        <Application
+          objLocale={{
+            strLocale: objAppConfig.locale.strLocale,
+            strTimeZone: objAppConfig.locale.strTimeZone,
+          }}
+        />
+      </StrictMode>
+    )
+    fnCaptureObservabilityEvent({
+      strName: 'application.ready',
+      strSource: 'bootstrap',
+      objAttributes: { strPhase: 'rendered' },
+    })
+  } catch (objError) {
+    const strCode =
+      objError instanceof RuntimeConfigError
+        ? objError.strCode
+        : 'bootstrap_failed'
+    const strMessage =
+      objError instanceof Error ? objError.message : '应用启动时发生未知错误。'
+
+    const objBootstrapError =
+      objError instanceof Error ||
+      typeof objError === 'string' ||
+      typeof objError === 'number' ||
+      typeof objError === 'boolean'
+        ? objError
+        : null
+    fnCaptureError(objBootstrapError, {
+      strName: 'application.bootstrap_failed',
+      strSource: 'bootstrap',
+      objAttributes: { strCode, strPhase: 'bootstrap' },
+    })
+
+    objRoot.render(
+      <StrictMode>
+        <RuntimeConfigErrorPage strCode={strCode} strMessage={strMessage} />
+      </StrictMode>
+    )
+  }
+}

package/template/src/components/AppDataTable/AppDataTable.tsx

@@ -0,0 +1,74 @@
+import { useLocale } from '@/locale'
+import { cn } from '@/lib/utils'
+import type { IAppDataTableProps } from './types'
+
+/** 普通企业 CRUD 列表，保持语义化表格和轻量运行时。 */
+export function AppDataTable<TRow>({
+  arrColumns,
+  arrRows,
+  fnGetRowKey,
+  strAriaLabel,
+  strEmptyMessage: strEmptyMessageOverride,
+}: IAppDataTableProps<TRow>) {
+  const { fnTranslateShared } = useLocale()
+  const strEmptyMessage =
+    strEmptyMessageOverride ?? fnTranslateShared('appDataTable.empty')
+  return (
+    <div
+      role='region'
+      tabIndex={0}
+      aria-label={`${strAriaLabel} (${fnTranslateShared('appDataTable.scrollable')})`}
+      className='overflow-x-auto rounded-lg border focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none'
+    >
+      <table aria-label={strAriaLabel} className='w-full min-w-[52rem] text-sm'>
+        <thead className='bg-muted/50 text-start text-muted-foreground'>
+          <tr className='border-b'>
+            {arrColumns.map((objColumn) => (
+              <th
+                key={objColumn.strKey}
+                scope='col'
+                className={cn(
+                  'h-11 px-4 text-start align-middle font-medium',
+                  objColumn.strHeaderClassName
+                )}
+              >
+                {objColumn.strHeader}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {arrRows.length > 0 ? (
+            arrRows.map((objRow) => (
+              <tr
+                key={fnGetRowKey(objRow)}
+                className='border-b transition-colors last:border-b-0 hover:bg-muted/30'
+              >
+                {arrColumns.map((objColumn) => (
+                  <td
+                    key={objColumn.strKey}
+                    className={cn(
+                      'px-4 py-3 align-middle',
+                      objColumn.strCellClassName
+                    )}
+                  >
+                    {objColumn.fnRender(objRow)}
+                  </td>
+                ))}
+              </tr>
+            ))
+          ) : (
+            <tr>
+              <td
+                colSpan={arrColumns.length}
+                className='h-28 px-4 text-center text-muted-foreground'
+              >
+                {strEmptyMessage}
+              </td>
+            </tr>
+          )}
+        </tbody>
+      </table>
+    </div>
+  )
+}

package/template/src/components/AppDataTable/index.ts

@@ -0,0 +1,2 @@
+export { AppDataTable } from './AppDataTable'
+export type { IAppDataTableColumn } from './types'

package/template/src/components/AppDataTable/types.ts

@@ -0,0 +1,27 @@
+import type { ReactNode } from 'react'
+
+export interface IAppDataTableColumn<TRow> {
+  /** 稳定列标识，用于 React Key。 */
+  strKey: string
+  /** 列标题；业务文案由 Feature 语言包提供。 */
+  strHeader: string
+  /** 数据单元格样式类名。 */
+  strCellClassName?: string
+  /** 表头单元格样式类名。 */
+  strHeaderClassName?: string
+  /** 渲染当前行对应单元格内容。 */
+  fnRender: (objRow: TRow) => ReactNode
+}
+
+export interface IAppDataTableProps<TRow> {
+  /** 表格列定义。 */
+  arrColumns: IAppDataTableColumn<TRow>[]
+  /** 当前需要展示的行数据。 */
+  arrRows: TRow[]
+  /** 获取每一行稳定唯一 Key。 */
+  fnGetRowKey: (objRow: TRow) => string | number
+  /** 描述表格业务用途的无障碍名称。 */
+  strAriaLabel: string
+  /** 空数据文案；省略时使用当前 Locale 的共享文案。 */
+  strEmptyMessage?: string
+}

package/template/src/components/AppDialog/AppConfirmDialog.tsx

@@ -0,0 +1,44 @@
+import { useLocale, useSharedMessage } from '@/locale'
+import { AppDialog } from './AppDialog'
+import { objAppConfirmMessages } from './messages'
+import type { IAppConfirmRequest } from './types'
+
+export function AppConfirmDialog({
+  objRequest,
+  fnOnRequestChange,
+}: {
+  objRequest?: IAppConfirmRequest
+  fnOnRequestChange: (objRequest?: IAppConfirmRequest) => void
+}) {
+  const { strLocale } = useLocale()
+  const strDefaultTitle = useSharedMessage('appDialog.confirmTitle')
+  if (!objRequest) return null
+
+  const strAction = objRequest.strTitle.replace(/[?？]\s*$/, '')
+  const objMessages = objAppConfirmMessages[strLocale]
+
+  return (
+    <AppDialog
+      bOpen
+      fnOnOpenChange={(bOpen) => {
+        if (!bOpen) fnOnRequestChange(undefined)
+      }}
+      strTitle={strDefaultTitle}
+      strSize='sm'
+      strHeaderClassName='border-b-0'
+      strBodyClassName='py-3 text-sm leading-6 text-foreground'
+      strFooterClassName='border-t-0'
+      strConfirmText={objRequest.strConfirmText}
+      strConfirmVariant={objRequest.strConfirmVariant}
+      fnOnConfirm={() => {
+        fnOnRequestChange(undefined)
+        objRequest.fnOnConfirm()
+      }}
+    >
+      <p className='break-words'>
+        {objMessages.fnRenderPrompt(strAction, objRequest.objContent)}
+        {objRequest.strDescription}
+      </p>
+    </AppDialog>
+  )
+}

package/template/src/components/AppDialog/AppDialog.tsx

@@ -0,0 +1,113 @@
+import { useSharedMessage } from '@/locale'
+import { Loader2 } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { Button } from '@/components/ui/button'
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog'
+import type { TAppDialogProps, TAppDialogSize } from './types'
+
+const objDialogSizeClasses = {
+  sm: 'sm:max-w-md',
+  md: 'sm:max-w-lg',
+  lg: 'sm:max-w-2xl',
+  xl: 'sm:max-w-3xl',
+  '2xl': 'sm:max-w-4xl',
+  '3xl': 'sm:max-w-5xl',
+  '4xl': 'sm:max-w-6xl',
+} as const satisfies Record<TAppDialogSize, string>
+
+export function AppDialog({
+  bOpen,
+  fnOnOpenChange,
+  strTitle,
+  strDescription,
+  strSize = 'md',
+  strContentClassName,
+  strHeaderClassName,
+  strBodyClassName,
+  strFooterClassName,
+  strCancelText,
+  strConfirmText,
+  strConfirmVariant = 'default',
+  bShowCloseButton = true,
+  bWrapBody = true,
+  bCancelDisabled = false,
+  bConfirmDisabled = false,
+  bConfirmPending = false,
+  fnOnCancel,
+  fnOnConfirm,
+  children: objChildren,
+  objConfirmIcon,
+  objFooter,
+}: TAppDialogProps) {
+  const strDefaultCancelText = useSharedMessage('appDialog.cancel')
+  const strDefaultConfirmText = useSharedMessage('appDialog.confirm')
+  const bHasCustomFooter = objFooter !== undefined
+  const bHasDefaultFooter = Boolean(fnOnConfirm)
+  const fnHandleCancel = () => {
+    if (fnOnCancel) {
+      fnOnCancel()
+      return
+    }
+    fnOnOpenChange(false)
+  }
+
+  return (
+    <Dialog open={bOpen} onOpenChange={fnOnOpenChange}>
+      <DialogContent
+        showCloseButton={bShowCloseButton}
+        className={cn(objDialogSizeClasses[strSize], strContentClassName)}
+      >
+        <DialogHeader className={strHeaderClassName}>
+          <DialogTitle>{strTitle}</DialogTitle>
+          {strDescription ? (
+            <DialogDescription>{strDescription}</DialogDescription>
+          ) : null}
+        </DialogHeader>
+        {bWrapBody ? (
+          <DialogBody className={strBodyClassName}>{objChildren}</DialogBody>
+        ) : (
+          objChildren
+        )}
+        {bHasCustomFooter || bHasDefaultFooter ? (
+          <DialogFooter className={strFooterClassName}>
+            {bHasCustomFooter ? (
+              objFooter
+            ) : (
+              <>
+                <Button
+                  type='button'
+                  variant='outline'
+                  disabled={bCancelDisabled}
+                  onClick={fnHandleCancel}
+                >
+                  {strCancelText ?? strDefaultCancelText}
+                </Button>
+                <Button
+                  type='button'
+                  variant={strConfirmVariant}
+                  disabled={bConfirmDisabled || bConfirmPending}
+                  onClick={() => void fnOnConfirm?.()}
+                >
+                  {bConfirmPending ? (
+                    <Loader2 className='animate-spin' />
+                  ) : (
+                    objConfirmIcon
+                  )}
+                  {strConfirmText ?? strDefaultConfirmText}
+                </Button>
+              </>
+            )}
+          </DialogFooter>
+        ) : null}
+      </DialogContent>
+    </Dialog>
+  )
+}

package/template/src/components/AppDialog/index.ts

@@ -0,0 +1,3 @@
+export { AppDialog } from './AppDialog'
+export { AppConfirmDialog } from './AppConfirmDialog'
+export type { IAppConfirmRequest, TAppDialogProps } from './types'

package/template/src/components/AppDialog/messages.tsx

@@ -0,0 +1,22 @@
+import type { TAppLocale } from '@/locale'
+import type { IAppConfirmMessages } from './types'
+
+/** AppConfirmDialog 自有的中英文句式；动态内容保持 ReactNode 类型。 */
+export const objAppConfirmMessages: Readonly<
+  Record<TAppLocale, IAppConfirmMessages>
+> = Object.freeze({
+  'en-US': Object.freeze({
+    fnRenderPrompt: (strAction, objContent) => (
+      <>
+        Are you sure you want to {strAction} “{objContent}”?
+      </>
+    ),
+  } satisfies IAppConfirmMessages),
+  'zh-CN': Object.freeze({
+    fnRenderPrompt: (strAction, objContent) => (
+      <>
+        确定{strAction}“{objContent}”吗？
+      </>
+    ),
+  } satisfies IAppConfirmMessages),
+})