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

package/template/src/featureFlags/registry.ts

@@ -0,0 +1,149 @@
+import {
+  fnFreezeFeatureFlagJsonValue,
+  fnIsFeatureFlagJsonValue,
+} from './catalog'
+import { FeatureFlagError } from './errors'
+import type {
+  IFeatureFlagCatalog,
+  IFeatureFlagDefinition,
+  IFeatureFlagEvaluation,
+  TFeatureFlagKind,
+} from './types'
+
+function fnIsFeatureFlagKind(strKind: string): strKind is TFeatureFlagKind {
+  return (
+    strKind === 'experiment' ||
+    strKind === 'killSwitch' ||
+    strKind === 'release'
+  )
+}
+
+function fnNormalizeFeatureFlagDefinition(
+  objDefinition: IFeatureFlagDefinition
+): IFeatureFlagDefinition {
+  const bHasValidStalePolicy = objDefinition.bAllowStale
+    ? typeof objDefinition.nMaxStaleMs === 'number' &&
+      Number.isFinite(objDefinition.nMaxStaleMs) &&
+      objDefinition.nMaxStaleMs > 0
+    : objDefinition.nMaxStaleMs === undefined
+  const bHasValidKillSwitchPolicy =
+    objDefinition.strKind !== 'killSwitch' ||
+    (!objDefinition.bSafeDefault && !objDefinition.bAllowStale)
+
+  if (
+    !objDefinition.strKey.trim() ||
+    objDefinition.strKey.trim() !== objDefinition.strKey ||
+    !fnIsFeatureFlagKind(objDefinition.strKind) ||
+    typeof objDefinition.bSafeDefault !== 'boolean' ||
+    !bHasValidStalePolicy ||
+    !bHasValidKillSwitchPolicy ||
+    (objDefinition.objSafePayload !== undefined &&
+      !fnIsFeatureFlagJsonValue(objDefinition.objSafePayload)) ||
+    (objDefinition.strSafeVariant !== undefined &&
+      !objDefinition.strSafeVariant.trim())
+  ) {
+    throw new FeatureFlagError(
+      'INVALID_DEFINITION',
+      `Feature Flag ${objDefinition.strKey || '<empty>'} 的本地定义无效。Kill Switch 必须默认关闭且不能使用过期结果。`
+    )
+  }
+
+  return Object.freeze({
+    ...objDefinition,
+    objSafePayload:
+      objDefinition.objSafePayload === undefined
+        ? undefined
+        : fnFreezeFeatureFlagJsonValue(objDefinition.objSafePayload),
+  })
+}
+
+/** 校验本地定义、拒绝重复 Key，并创建稳定的只读定义表。 */
+export function fnCreateFeatureFlagRegistry(
+  arrDefinitions: readonly IFeatureFlagDefinition[]
+): ReadonlyMap<string, IFeatureFlagDefinition> {
+  const objRegistry = new Map<string, IFeatureFlagDefinition>()
+  arrDefinitions.forEach((objDefinition) => {
+    const objNormalizedDefinition =
+      fnNormalizeFeatureFlagDefinition(objDefinition)
+    if (objRegistry.has(objNormalizedDefinition.strKey)) {
+      throw new FeatureFlagError(
+        'INVALID_DEFINITION',
+        `Feature Flag ${objNormalizedDefinition.strKey} 被重复定义。`
+      )
+    }
+    objRegistry.set(objNormalizedDefinition.strKey, objNormalizedDefinition)
+  })
+  return objRegistry
+}
+
+function fnCreateSafeDefaultEvaluation(
+  objDefinition: IFeatureFlagDefinition,
+  strEvaluationReason: 'catalogExpired' | 'catalogUnavailable' | 'flagMissing'
+): IFeatureFlagEvaluation {
+  return Object.freeze({
+    bEnabled: objDefinition.bSafeDefault,
+    bIsFallback: true,
+    nEvaluatedAt: 0,
+    objPayload: objDefinition.objSafePayload,
+    strEvaluationReason,
+    strEvaluationSource: 'safeDefault',
+    strKey: objDefinition.strKey,
+    strKind: objDefinition.strKind,
+    strVariant: objDefinition.strSafeVariant,
+  })
+}
+
+/** 按本地安全策略评估远端结果，不在前端执行人群或百分比规则。 */
+export function fnEvaluateFeatureFlag(
+  objDefinition: IFeatureFlagDefinition,
+  objCatalog?: IFeatureFlagCatalog,
+  nNow = Date.now()
+): IFeatureFlagEvaluation {
+  if (!objCatalog) {
+    return fnCreateSafeDefaultEvaluation(objDefinition, 'catalogUnavailable')
+  }
+
+  const objFlag = objCatalog.objFlags.get(objDefinition.strKey)
+  if (!objFlag) {
+    return fnCreateSafeDefaultEvaluation(objDefinition, 'flagMissing')
+  }
+
+  const bIsFresh = nNow <= objCatalog.nExpiresAt
+  const bCanUseStale =
+    !bIsFresh &&
+    objDefinition.bAllowStale === true &&
+    objDefinition.nMaxStaleMs !== undefined &&
+    nNow <= objCatalog.nExpiresAt + objDefinition.nMaxStaleMs
+
+  if (!bIsFresh && !bCanUseStale) {
+    return fnCreateSafeDefaultEvaluation(objDefinition, 'catalogExpired')
+  }
+
+  return Object.freeze({
+    bEnabled: objFlag.bEnabled,
+    bIsFallback: false,
+    nEvaluatedAt: objFlag.nEvaluatedAt,
+    objPayload: objFlag.objPayload,
+    strEvaluationReason: bIsFresh ? 'remoteEvaluation' : 'catalogExpired',
+    strEvaluationSource: bIsFresh ? 'remote' : 'stale',
+    strKey: objDefinition.strKey,
+    strKind: objDefinition.strKind,
+    strRemoteReason: objFlag.strReason,
+    strVariant: objFlag.strVariant,
+  })
+}
+
+/** 从本地定义表读取开关；未知 Key 立即失败，避免拼写错误静默上线。 */
+export function fnGetFeatureFlagDefinition(
+  objRegistry: ReadonlyMap<string, IFeatureFlagDefinition>,
+  strKey: string
+): IFeatureFlagDefinition {
+  const objDefinition = objRegistry.get(strKey)
+  if (!objDefinition) {
+    throw new FeatureFlagError(
+      'INVALID_DEFINITION',
+      `Feature Flag ${strKey || '<empty>'} 尚未在本地定义。`
+    )
+  }
+  return objDefinition
+}

package/template/src/featureFlags/scope.ts

@@ -0,0 +1,27 @@
+import type { IFeatureFlagScope, IFeatureFlagScopeContext } from './types'
+
+function fnNormalizeScopeValue(strValue: string | undefined) {
+  const strNormalizedValue = strValue?.trim()
+  return strNormalizedValue || undefined
+}
+
+/** 创建不含凭据、可安全用于 Query Key 的 Feature Flag 作用域。 */
+export function fnCreateFeatureFlagScope(
+  objContext: IFeatureFlagScopeContext = {}
+): IFeatureFlagScope {
+  if (
+    objContext.nSessionGeneration !== undefined &&
+    (!Number.isInteger(objContext.nSessionGeneration) ||
+      objContext.nSessionGeneration < 0)
+  ) {
+    throw new TypeError('Feature Flag 作用域的会话版本必须是非负整数。')
+  }
+
+  return Object.freeze({
+    nSessionGeneration: objContext.nSessionGeneration,
+    strEnvironment: fnNormalizeScopeValue(objContext.strEnvironment),
+    strTenantId: fnNormalizeScopeValue(objContext.strTenantId),
+    strUserId: fnNormalizeScopeValue(objContext.strUserId),
+    strWorkspaceId: fnNormalizeScopeValue(objContext.strWorkspaceId),
+  })
+}

package/template/src/featureFlags/types.ts

@@ -0,0 +1,241 @@
+import type { ReactNode } from 'react'
+
+/** Feature Flag 可携带的递归只读 JSON 值。 */
+export type TFeatureFlagJsonValue =
+  | boolean
+  | number
+  | string
+  | null
+  | readonly TFeatureFlagJsonValue[]
+  | { readonly [strKey: string]: TFeatureFlagJsonValue }
+
+/** 开关的稳定用途分类。 */
+export type TFeatureFlagKind = 'experiment' | 'killSwitch' | 'release'
+
+/** 一次开关评估实际采用的数据来源。 */
+export type TFeatureFlagEvaluationSource = 'remote' | 'safeDefault' | 'stale'
+
+/** 开关使用当前结果的稳定原因，便于诊断而不暴露人群规则。 */
+export type TFeatureFlagEvaluationReason =
+  | 'catalogExpired'
+  | 'catalogUnavailable'
+  | 'flagMissing'
+  | 'remoteEvaluation'
+
+/** Feature Flag 边界的稳定错误分类。 */
+export type TFeatureFlagErrorCode =
+  | 'INVALID_CATALOG'
+  | 'INVALID_DEFINITION'
+  | 'INVALID_FLAG'
+  | 'INVALID_SCOPE'
+
+/** 后端已经完成灰度评估后的单个原始开关。 */
+export interface IFeatureFlagPayload {
+  /** 当前作用域是否启用该能力。 */
+  bEnabled?: boolean
+  /** 实验分组或配置版本；普通布尔开关可以省略。 */
+  strVariant?: string
+  /** 与当前变体绑定的只读 JSON 配置，不得包含凭据或敏感信息。 */
+  objPayload?: TFeatureFlagJsonValue
+  /** 后端用于诊断的非敏感原因码，不应包含完整灰度规则。 */
+  strReason?: string
+}
+
+/** 后端统一 Feature Flag 接口返回的原始目录。 */
+export interface IFeatureFlagCatalogPayload {
+  /** 服务端完成本次评估的毫秒时间戳。 */
+  nEvaluatedAt?: number
+  /** 本次评估结果允许使用到的毫秒时间戳。 */
+  nExpiresAt?: number
+  /** 以稳定开关 Key 为索引的已评估结果。 */
+  objFlags?: Readonly<Record<string, IFeatureFlagPayload | undefined>>
+  /** 后端目录或规则版本，用于诊断与刷新确认。 */
+  version?: string
+}
+
+/** 前端本地声明的开关及其安全回退策略。 */
+export interface IFeatureFlagDefinition {
+  /** 远端不可用、目录过期或 Key 缺失时采用的安全状态。 */
+  readonly bSafeDefault: boolean
+  /** 是否允许在远端目录过期后短暂使用最近一次结果。 */
+  readonly bAllowStale?: boolean
+  /** 允许使用过期结果的最长毫秒数；仅在 `bAllowStale` 时有效。 */
+  readonly nMaxStaleMs?: number
+  /** 安全默认状态配套的只读 JSON 配置。 */
+  readonly objSafePayload?: TFeatureFlagJsonValue
+  /** 跨环境稳定且由前后端共同约定的开关 Key。 */
+  readonly strKey: string
+  /** 开关用途；Kill Switch 会强制安全默认关闭且禁止过期结果。 */
+  readonly strKind: TFeatureFlagKind
+  /** 安全默认状态配套的实验分组或配置版本。 */
+  readonly strSafeVariant?: string
+}
+
+/** 除请求信号外，用于后端评估和隔离前端缓存的稳定作用域。 */
+export interface IFeatureFlagScopeContext {
+  /** 登录、退出或授权上下文变化时递增的会话版本。 */
+  readonly nSessionGeneration?: number
+  /** 运行环境标识，例如 production 或 staging。 */
+  readonly strEnvironment?: string
+  /** 当前租户稳定标识。 */
+  readonly strTenantId?: string
+  /** 当前认证用户稳定标识；匿名场景可以省略。 */
+  readonly strUserId?: string
+  /** 当前组织、项目或工作空间稳定标识。 */
+  readonly strWorkspaceId?: string
+}
+
+/** 一个 Feature Flag 请求与缓存的完整身份。 */
+export interface IFeatureFlagScope extends IFeatureFlagScopeContext {
+  /** 登录、退出或授权上下文变化时递增的会话版本。 */
+  readonly nSessionGeneration?: number
+}
+
+/** 后端 Feature Flag 请求所需的完整运行时上下文。 */
+export interface IFeatureFlagRequestContext {
+  /** 按字典序排列、仅请求当前应用声明的开关 Key。 */
+  readonly arrFlagKeys: readonly string[]
+  /** 本次请求与缓存使用的稳定业务作用域。 */
+  readonly objScope: IFeatureFlagScope
+  /** QueryClient 取消或替换请求时触发的取消信号。 */
+  readonly objSignal: AbortSignal
+}
+
+/** 由 Swagger 生成客户端实现的后端 Feature Flag 请求函数。 */
+export type TFeatureFlagRequest = (
+  objContext: IFeatureFlagRequestContext
+) => Promise<IFeatureFlagCatalogPayload | undefined>
+
+/** 项目对接后端或供应商 SDK 时实现的数据源契约。 */
+export interface IFeatureFlagSource {
+  /** 加载当前作用域下已经由后端完成评估的开关目录。 */
+  readonly fnLoadCatalog: (
+    objContext: IFeatureFlagRequestContext
+  ) => Promise<IFeatureFlagCatalog>
+}
+
+/** 经过运行时校验、可安全交给 Feature 使用的远端开关结果。 */
+export interface IFeatureFlag {
+  /** 当前作用域是否启用该能力。 */
+  readonly bEnabled: boolean
+  /** 服务端完成本次评估的毫秒时间戳。 */
+  readonly nEvaluatedAt: number
+  /** 与当前变体绑定的深度冻结 JSON 配置。 */
+  readonly objPayload?: TFeatureFlagJsonValue
+  /** 跨环境稳定的开关 Key。 */
+  readonly strKey: string
+  /** 后端用于诊断的非敏感原因码。 */
+  readonly strReason?: string
+  /** 实验分组或配置版本。 */
+  readonly strVariant?: string
+}
+
+/** 单个作用域下已标准化的完整远端开关目录。 */
+export interface IFeatureFlagCatalog {
+  /** 服务端完成本次目录评估的毫秒时间戳。 */
+  readonly nEvaluatedAt: number
+  /** 本次目录结果允许使用到的毫秒时间戳。 */
+  readonly nExpiresAt: number
+  /** 以稳定 Key 为索引的已评估开关。 */
+  readonly objFlags: ReadonlyMap<string, IFeatureFlag>
+  /** 后端目录或规则版本。 */
+  readonly version: string
+}
+
+/** Feature 最终消费的开关评估结果。 */
+export interface IFeatureFlagEvaluation {
+  /** 当前最终是否启用能力。 */
+  readonly bEnabled: boolean
+  /** 是否正在使用本地安全默认值。 */
+  readonly bIsFallback: boolean
+  /** 当前结果对应的服务端评估时间；本地默认值为 `0`。 */
+  readonly nEvaluatedAt: number
+  /** 当前变体携带的只读 JSON 配置。 */
+  readonly objPayload?: TFeatureFlagJsonValue
+  /** 当前结果使用本地默认或远端结果的稳定原因。 */
+  readonly strEvaluationReason: TFeatureFlagEvaluationReason
+  /** 当前结果的数据来源。 */
+  readonly strEvaluationSource: TFeatureFlagEvaluationSource
+  /** 开关稳定 Key。 */
+  readonly strKey: string
+  /** 本地定义的用途分类。 */
+  readonly strKind: TFeatureFlagKind
+  /** 后端返回的非敏感诊断原因码。 */
+  readonly strRemoteReason?: string
+  /** 当前采用的实验分组或配置版本。 */
+  readonly strVariant?: string
+}
+
+/** Feature Flag Provider 的公共参数。 */
+export interface IFeatureFlagProviderProps {
+  /** 本应用声明的开关和安全默认策略。 */
+  readonly arrDefinitions: readonly IFeatureFlagDefinition[]
+  /** 是否允许请求远端目录；关闭后所有开关立即使用安全默认值。 */
+  readonly bIsEnabled?: boolean
+  /** 始终渲染的应用子树；远端开关失败不会阻塞它。 */
+  readonly children: ReactNode
+  /** 当前用户、租户、工作空间和环境组成的评估作用域。 */
+  readonly objScope?: IFeatureFlagScopeContext
+  /** 由 Swagger 生成客户端或厂商 SDK 适配的数据源。 */
+  readonly objSource?: IFeatureFlagSource
+}
+
+/** 完整 Feature Flag 目录及诊断状态。 */
+export interface IUseFeatureFlagCatalogResult {
+  /** 本地按字典序声明的所有开关 Key。 */
+  readonly arrKeys: readonly string[]
+  /** 是否已经配置远端数据源。 */
+  readonly bIsConfigured: boolean
+  /** 当前是否允许请求远端目录。 */
+  readonly bIsEnabled: boolean
+  /** 最近一次远端请求是否失败。 */
+  readonly bIsError: boolean
+  /** 是否正在进行首次请求或后台刷新。 */
+  readonly bIsFetching: boolean
+  /** 是否仍在进行首次远端请求。 */
+  readonly bIsLoading: boolean
+  /** 最近一次成功更新 Query 缓存的时间戳。 */
+  readonly nUpdatedAt: number
+  /** 当前已校验的远端目录；尚未成功时为空。 */
+  readonly objCatalog: IFeatureFlagCatalog | undefined
+  /** 最近一次请求失败时的标准 Error。 */
+  readonly objError: Error | null
+  /** 当前请求与缓存使用的稳定作用域。 */
+  readonly objScope: IFeatureFlagScope
+  /** 后端目录版本；尚未加载时为空。 */
+  readonly strVersion: string | null
+  /** 根据本地定义评估指定开关，未知 Key 会立即失败。 */
+  readonly fnEvaluate: (strKey: string) => IFeatureFlagEvaluation
+  /** 重新请求当前作用域的远端目录。 */
+  readonly fnRefetch: () => Promise<void>
+}
+
+/** 单个 Feature Flag Hook 返回的评估结果和加载诊断。 */
+export interface IUseFeatureFlagResult extends IFeatureFlagEvaluation {
+  /** 是否已经配置远端数据源。 */
+  readonly bIsConfigured: boolean
+  /** 当前是否允许请求远端目录。 */
+  readonly bIsEnabled: boolean
+  /** 最近一次远端请求是否失败。 */
+  readonly bIsError: boolean
+  /** 是否正在进行首次请求或后台刷新。 */
+  readonly bIsFetching: boolean
+  /** 是否仍在进行首次远端请求；此时安全默认值仍可立即使用。 */
+  readonly bIsLoading: boolean
+  /** 最近一次请求失败时的标准 Error。 */
+  readonly objError: Error | null
+  /** 后端目录版本；尚未加载时为空。 */
+  readonly strVersion: string | null
+  /** 重新请求当前作用域的远端目录。 */
+  readonly fnRefetch: () => Promise<void>
+}
+
+/** 声明式开关渲染边界的公共参数。 */
+export interface IFeatureGateProps {
+  /** 开关启用时渲染的内容。 */
+  readonly children: ReactNode
+  /** 开关关闭或回退为关闭时渲染的内容，默认不渲染。 */
+  readonly objFallback?: ReactNode
+  /** 本地定义表中已经声明的稳定开关 Key。 */
+  readonly strFlagKey: string
+}

package/template/src/features/auth/AuthLayout.tsx

@@ -0,0 +1,17 @@
+import { Outlet } from '@tanstack/react-router'
+import { objAppConfig } from '@/config/appConfig'
+import { BrandLogo } from '@/components/BrandLogo'
+
+export function AuthLayout() {
+  return (
+    <div className='flex min-h-svh w-full items-center justify-center px-4 py-8'>
+      <div className='flex w-full max-w-sm flex-col gap-6'>
+        <header className='flex items-center justify-center'>
+          <BrandLogo strClassName='me-2 size-8 rounded-lg object-contain' />
+          <h1 className='text-xl font-medium'>{objAppConfig.brand.strName}</h1>
+        </header>
+        <Outlet />
+      </div>
+    </div>
+  )
+}

package/template/src/features/auth/index.ts

@@ -0,0 +1,2 @@
+export { AuthLayout } from './AuthLayout'
+export { SignIn } from './signIn'

package/template/src/features/auth/signIn/components/UserAuthForm.tsx

@@ -0,0 +1,121 @@
+import { useMemo, useState } from 'react'
+import { z } from 'zod'
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { useLocaleMessages } from '@/locale'
+import { Loader2, LogIn } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { Button } from '@/components/ui/button'
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from '@/components/ui/form'
+import { Input } from '@/components/ui/input'
+import { PasswordInput } from '@/components/PasswordInput'
+import { objSignInMessages } from '../messages'
+import type { TSignInValues } from '../types'
+
+interface IUserAuthFormProps extends Omit<
+  React.HTMLAttributes<HTMLFormElement>,
+  'onSubmit'
+> {
+  strError?: string | null
+  fnOnSubmit: (objValues: TSignInValues) => void | Promise<void>
+}
+
+export function UserAuthForm({
+  className: strClassName,
+  strError,
+  fnOnSubmit,
+  ...objProps
+}: IUserAuthFormProps) {
+  const [bIsLoading, fnSetIsLoading] = useState(false)
+  const { fnTranslate } = useLocaleMessages(objSignInMessages)
+  const objFormSchema = useMemo(
+    () =>
+      z.object({
+        phone: z.string().trim().min(1, fnTranslate('accountRequired')),
+        password: z
+          .string()
+          .min(1, fnTranslate('passwordRequired'))
+          .min(7, fnTranslate('passwordMinimum')),
+      }),
+    [fnTranslate]
+  )
+
+  const objForm = useForm<TSignInValues>({
+    resolver: zodResolver(objFormSchema),
+    defaultValues: {
+      phone: '',
+      password: '',
+    },
+  })
+
+  async function fnHandleSubmit(objData: TSignInValues) {
+    fnSetIsLoading(true)
+    try {
+      await fnOnSubmit(objData)
+    } finally {
+      fnSetIsLoading(false)
+    }
+  }
+
+  return (
+    <Form {...objForm}>
+      <form
+        onSubmit={objForm.handleSubmit(fnHandleSubmit)}
+        className={cn('grid gap-3', strClassName)}
+        {...objProps}
+      >
+        <FormField
+          control={objForm.control}
+          name='phone'
+          render={({ field: objField }) => (
+            <FormItem>
+              <FormLabel>{fnTranslate('accountLabel')}</FormLabel>
+              <FormControl>
+                <Input
+                  inputMode='tel'
+                  autoComplete='username'
+                  placeholder={fnTranslate('accountPlaceholder')}
+                  {...objField}
+                />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <FormField
+          control={objForm.control}
+          name='password'
+          render={({ field: objField }) => (
+            <FormItem>
+              <FormLabel>{fnTranslate('passwordLabel')}</FormLabel>
+              <FormControl>
+                <PasswordInput
+                  autoComplete='current-password'
+                  placeholder='********'
+                  {...objField}
+                />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        {strError ? (
+          <p role='alert' className='text-sm text-destructive'>
+            {strError}
+          </p>
+        ) : null}
+        <Button className='mt-2' disabled={bIsLoading}>
+          {bIsLoading ? <Loader2 className='animate-spin' /> : <LogIn />}
+          {fnTranslate('submit')}
+        </Button>
+      </form>
+    </Form>
+  )
+}

package/template/src/features/auth/signIn/index.tsx

@@ -0,0 +1,71 @@
+import { useState } from 'react'
+import { useNavigate, useSearch } from '@tanstack/react-router'
+import { objAppConfig } from '@/config/appConfig'
+import { useLocaleMessages } from '@/locale'
+import { fnReadAuthError, fnSignInWithCredentials } from '@/api/authSession'
+import { objDemoCredentials } from '@/api/demoAuthClient'
+import { fnGetPostSignInPath } from '@/lib/navigationRedirect'
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card'
+import { UserAuthForm } from './components/UserAuthForm'
+import { objSignInMessages } from './messages'
+import type { TSignInValues } from './types'
+
+export function SignIn() {
+  const fnNavigate = useNavigate()
+  const { fnTranslate } = useLocaleMessages(objSignInMessages)
+  const { redirect: strRedirect } = useSearch({ from: '/_guest/sign-in' })
+  const [strAuthError, fnSetAuthError] = useState<string | null>(null)
+
+  async function fnHandleSignIn(objValues: TSignInValues) {
+    fnSetAuthError(null)
+
+    try {
+      await fnSignInWithCredentials({
+        strPhone: objValues.phone,
+        strPassword: objValues.password,
+      })
+    } catch (objError) {
+      fnSetAuthError(
+        fnReadAuthError(objError, {
+          strFallbackMessage: fnTranslate('fallbackError'),
+          strNetworkMessage: fnTranslate('networkError'),
+        })
+      )
+      return
+    }
+
+    await fnNavigate({
+      href: fnGetPostSignInPath(strRedirect),
+      replace: true,
+    })
+  }
+
+  return (
+    <Card className='w-full gap-4'>
+      <CardHeader>
+        <CardTitle className='text-lg tracking-tight'>
+          {fnTranslate('cardTitle')}
+        </CardTitle>
+        <CardDescription>{fnTranslate('cardDescription')}</CardDescription>
+      </CardHeader>
+      <CardContent>
+        {objAppConfig.runtime.strMode === 'demo' ? (
+          <div className='mb-4 rounded-lg border border-primary/20 bg-primary/5 p-3 text-sm'>
+            <p className='font-medium'>{fnTranslate('demoTitle')}</p>
+            <p className='mt-1 text-muted-foreground'>
+              {fnTranslate('demoAccount')} {objDemoCredentials.strPhone},{' '}
+              {fnTranslate('demoPassword')} {objDemoCredentials.strPassword}
+            </p>
+          </div>
+        ) : null}
+        <UserAuthForm strError={strAuthError} fnOnSubmit={fnHandleSignIn} />
+      </CardContent>
+    </Card>
+  )
+}

package/template/src/features/auth/signIn/messages.ts

@@ -0,0 +1,37 @@
+import { fnDefineLocaleMessages } from '@/locale'
+
+/** 登录 Feature 自有的完整中英文语言包。 */
+export const objSignInMessages = fnDefineLocaleMessages({
+  'en-US': {
+    accountLabel: 'Phone number',
+    accountPlaceholder: 'Enter your phone number',
+    accountRequired: 'Enter your phone number.',
+    cardDescription: 'Use an authorized organization account to continue.',
+    cardTitle: 'Sign in',
+    demoAccount: 'Account',
+    demoPassword: 'password',
+    demoTitle: 'Demo mode',
+    fallbackError: 'Sign-in failed. Check your account and password.',
+    networkError: 'Could not reach the authentication service. Try again.',
+    passwordLabel: 'Password',
+    passwordMinimum: 'Password must contain at least 7 characters.',
+    passwordRequired: 'Enter your password.',
+    submit: 'Sign in',
+  },
+  'zh-CN': {
+    accountLabel: '手机号',
+    accountPlaceholder: '请输入手机号',
+    accountRequired: '请输入手机号。',
+    cardDescription: '请使用已获授权的组织账号继续访问。',
+    cardTitle: '登录',
+    demoAccount: '账号',
+    demoPassword: '密码',
+    demoTitle: '演示模式',
+    fallbackError: '登录失败，请检查手机号和密码。',
+    networkError: '无法连接认证服务，请稍后重试。',
+    passwordLabel: '密码',
+    passwordMinimum: '密码至少需要 7 个字符。',
+    passwordRequired: '请输入密码。',
+    submit: '登录',
+  },
+})

package/template/src/features/auth/signIn/types.ts

@@ -0,0 +1,4 @@
+export type TSignInValues = {
+  password: string
+  phone: string
+}