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

package/template/src/api/authClient.ts

@@ -0,0 +1,134 @@
+import { z } from 'zod'
+import { objAppConfig } from '@/config/appConfig'
+import axios from 'axios'
+import { fnIsSuccessfulHttpStatus } from '@/api/clients/httpStatus'
+import {
+  fnCreateErrorHook,
+  fnCreateRequestHook,
+  fnCreateResponseHook,
+} from '@/api/hooks'
+import type { IAuthApiClient, IAuthTokenResult } from '@/api/types'
+
+const objIdentitySchema = z.object({
+  id: z.string().optional(),
+  maskedPhone: z.string().optional(),
+  nickname: z.string().optional(),
+  organizationName: z.string().optional(),
+  permissions: z.array(z.string()).optional(),
+  role: z.string().optional(),
+  roles: z.array(z.string()).optional(),
+  tenantId: z.string().optional(),
+  avatarURL: z.string().optional(),
+})
+
+const objTokenSchema = z.object({
+  accessToken: z.string().min(1),
+  refreshToken: z.string().min(1),
+  expiresIn: z.number().optional(),
+  refreshIdleExpiresIn: z.number().optional(),
+  refreshExpiresIn: z.number().optional(),
+  user: objIdentitySchema.optional(),
+})
+
+const objTokenEnvelopeSchema = z.object({
+  data: objTokenSchema.optional(),
+  message: z.string().optional(),
+})
+
+const fnAuthHttp = axios.create({
+  baseURL: objAppConfig.api.strBaseUrl || undefined,
+  validateStatus: fnIsSuccessfulHttpStatus,
+})
+
+const arrAuthPaths = [
+  objAppConfig.auth.strSignInPath,
+  objAppConfig.auth.strRefreshPath,
+  objAppConfig.auth.strSignOutPath,
+]
+fnAuthHttp.interceptors.request.use(
+  fnCreateRequestHook({ arrAnonymousPaths: arrAuthPaths })
+)
+fnAuthHttp.interceptors.response.use(
+  fnCreateResponseHook(),
+  fnCreateErrorHook()
+)
+
+function fnNormalizeTokenResponse(
+  objResponseData: unknown,
+  strFallbackMessage: string
+): IAuthTokenResult {
+  const objEnvelopeResult = objTokenEnvelopeSchema.safeParse(objResponseData)
+  if (!objEnvelopeResult.success) throw new Error(strFallbackMessage)
+
+  const objPayload = objEnvelopeResult.data.data
+  if (!objPayload) {
+    throw new Error(objEnvelopeResult.data.message || strFallbackMessage)
+  }
+
+  return {
+    strAccessToken: objPayload.accessToken,
+    strRefreshToken: objPayload.refreshToken,
+    nExpiresIn: objPayload.expiresIn,
+    nRefreshIdleExpiresIn: objPayload.refreshIdleExpiresIn,
+    nRefreshExpiresIn: objPayload.refreshExpiresIn,
+    ...(objPayload.user
+      ? {
+          objUser: {
+            arrPermissions: objPayload.user.permissions,
+            arrRoleCodes: objPayload.user.roles,
+            strId: objPayload.user.id,
+            strMaskedPhone: objPayload.user.maskedPhone,
+            strNickname: objPayload.user.nickname,
+            strOrganizationName: objPayload.user.organizationName,
+            strRole: objPayload.user.role,
+            strTenantId: objPayload.user.tenantId,
+            strAvatarUrl: objPayload.user.avatarURL,
+          },
+        }
+      : {}),
+  }
+}
+
+async function fnPostForToken(
+  strPath: string,
+  objBody: Record<string, string>,
+  strFallbackMessage: string,
+  objSignal?: AbortSignal
+) {
+  const objResponse = await fnAuthHttp.post<unknown>(strPath, objBody, {
+    signal: objSignal,
+  })
+
+  return fnNormalizeTokenResponse(objResponse.data, strFallbackMessage)
+}
+
+/** 认证只依赖三个端点，避免把完整业务 OpenAPI 客户端打进应用入口。 */
+export const objAuthApiClient: IAuthApiClient = {
+  fnFirstPartyLogin: (objInput) =>
+    fnPostForToken(
+      objAppConfig.auth.strSignInPath,
+      {
+        audience: objInput.strAudience,
+        clientId: objInput.strClientId,
+        password: objInput.strPassword,
+        phone: objInput.strPhone,
+        scope: objInput.strScope,
+      },
+      '登录接口未返回有效响应。'
+    ),
+  fnRefreshToken: (objInput, objSignal) =>
+    fnPostForToken(
+      objAppConfig.auth.strRefreshPath,
+      {
+        clientId: objInput.strClientId,
+        refreshToken: objInput.strRefreshToken,
+      },
+      '刷新接口未返回有效响应。',
+      objSignal
+    ),
+  fnSignOut: async (objInput) => {
+    await fnAuthHttp.post(objAppConfig.auth.strSignOutPath, {
+      refreshToken: objInput.strRefreshToken,
+    })
+  },
+}

package/template/src/api/authSession.ts

@@ -0,0 +1,307 @@
+import { objAppConfig } from '@/config/appConfig'
+import axios from 'axios'
+import { objAuthApiClient } from '@/api/authClient'
+import { objDemoAuthApiClient } from '@/api/demoAuthClient'
+import type {
+  IAuthApiClient,
+  IAuthErrorMessages,
+  IAuthIdentityResult,
+  IAuthTokenResult,
+} from '@/api/types'
+import {
+  type IAuthSession,
+  type IAuthTokens,
+  useAuthStore,
+} from '@/stores/authStore'
+import type { IAuthUser } from '@/stores/types'
+
+const nDefaultAccessTokenLifetime = 10 * 60
+const nDefaultRefreshTokenLifetime = 7 * 24 * 60 * 60
+const objDefaultAuthApiClient =
+  objAppConfig.runtime.strMode === 'demo'
+    ? objDemoAuthApiClient
+    : objAuthApiClient
+
+interface IAuthCredentials {
+  /** 当前第一方登录表单采集的手机号。 */
+  strPhone: string
+  /** 只在本次登录请求中使用的密码，不得持久化或记录。 */
+  strPassword: string
+}
+
+/** 认证成功响应缺少可建立应用会话的用户身份。 */
+export class AuthIdentityError extends Error {
+  constructor() {
+    super('认证服务没有返回有效的用户身份。')
+    this.name = 'AuthIdentityError'
+  }
+}
+
+function fnCreateTokenState(objPayload: IAuthTokenResult): IAuthTokens {
+  const nNow = Date.now()
+  const nAccessTokenLifetime =
+    objPayload.nExpiresIn ?? nDefaultAccessTokenLifetime
+  const nRefreshTokenLifetime =
+    objPayload.nRefreshIdleExpiresIn ??
+    objPayload.nRefreshExpiresIn ??
+    nDefaultRefreshTokenLifetime
+
+  return {
+    strAccessToken: objPayload.strAccessToken,
+    strRefreshToken: objPayload.strRefreshToken,
+    nAccessTokenExpiresAt: nNow + nAccessTokenLifetime * 1_000,
+    nRefreshTokenExpiresAt: nNow + nRefreshTokenLifetime * 1_000,
+  }
+}
+
+function fnNormalizeStringList(arrValues: readonly string[] = []) {
+  return [
+    ...new Set(arrValues.map((strValue) => strValue.trim()).filter(Boolean)),
+  ]
+}
+
+/** 将后端身份契约合并为应用唯一的用户与权限模型。 */
+function fnCreateAuthUser(
+  objIdentity: IAuthIdentityResult,
+  strFallbackAccount: string,
+  objCurrentUser?: IAuthUser
+): IAuthUser {
+  const strOrganizationName =
+    objIdentity.strOrganizationName ?? objCurrentUser?.strOrganizationName
+  const strTenantId = objIdentity.strTenantId ?? objCurrentUser?.strTenantId
+  const strAvatarUrl = objIdentity.strAvatarUrl ?? objCurrentUser?.strAvatarUrl
+  const strAccount =
+    objIdentity.strMaskedPhone ??
+    objCurrentUser?.strAccount ??
+    strFallbackAccount
+
+  return {
+    arrPermissions:
+      objIdentity.arrPermissions === undefined
+        ? [...(objCurrentUser?.arrPermissions ?? [])]
+        : fnNormalizeStringList(objIdentity.arrPermissions),
+    arrRoleCodes:
+      objIdentity.arrRoleCodes === undefined
+        ? [...(objCurrentUser?.arrRoleCodes ?? [])]
+        : fnNormalizeStringList(objIdentity.arrRoleCodes),
+    strId: objIdentity.strId ?? objCurrentUser?.strId ?? '',
+    strAccount,
+    strDisplayName:
+      objIdentity.strNickname?.trim() ||
+      objCurrentUser?.strDisplayName ||
+      strAccount ||
+      objIdentity.strId ||
+      '—',
+    ...(strOrganizationName ? { strOrganizationName } : {}),
+    strRole:
+      objIdentity.strRole?.trim().toLowerCase() ??
+      objCurrentUser?.strRole ??
+      '',
+    ...(strTenantId ? { strTenantId } : {}),
+    ...(strAvatarUrl ? { strAvatarUrl } : {}),
+  }
+}
+
+async function fnRevokeRefreshToken(
+  strRefreshToken: string,
+  objApiClient: IAuthApiClient
+) {
+  try {
+    await objApiClient.fnSignOut({
+      strRefreshToken,
+    })
+  } catch {
+    // The local session is still rejected even if server-side revocation fails.
+  }
+}
+
+/** 使用第一方凭据完成登录并建立唯一应用会话。 */
+export async function fnSignInWithCredentials(
+  { strPhone, strPassword }: IAuthCredentials,
+  objApiClient: IAuthApiClient = objDefaultAuthApiClient
+) {
+  const objLoginPayload = await objApiClient.fnFirstPartyLogin({
+    strAudience: objAppConfig.auth.strAudience,
+    strClientId: objAppConfig.auth.strClientId,
+    strPassword,
+    strPhone,
+    strScope: objAppConfig.auth.strScope,
+  })
+  return fnEstablishAuthSessionFromToken(
+    objLoginPayload,
+    strPhone,
+    objApiClient
+  )
+}
+
+/**
+ * 将第一方、SSO 或 MFA 完成后的统一 Token 结果接入唯一应用会话。
+ *
+ * 调用前的协议交换、挑战和应用准入由认证 Adapter 与后端负责。前端只要求结果包含
+ * 可建立会话的身份，不把角色字符串当作授权边界。
+ */
+export async function fnEstablishAuthSessionFromToken(
+  objLoginPayload: IAuthTokenResult,
+  strFallbackAccount: string,
+  objApiClient: IAuthApiClient = objDefaultAuthApiClient
+) {
+  const objIdentity = objLoginPayload.objUser
+
+  if (!objIdentity) {
+    await fnRevokeRefreshToken(objLoginPayload.strRefreshToken, objApiClient)
+    throw new AuthIdentityError()
+  }
+
+  const objSession: IAuthSession = {
+    ...fnCreateTokenState(objLoginPayload),
+    objUser: fnCreateAuthUser(objIdentity, strFallbackAccount),
+  }
+  fnCancelAdminSessionRefresh()
+  useAuthStore.getState().fnEstablishSession(objSession)
+
+  return objSession.objUser
+}
+
+let objRefreshPromise: Promise<string | null> | null = null
+let objRefreshController: AbortController | null = null
+
+function fnIsCurrentRefreshSession(
+  nSessionGeneration: number,
+  strRefreshToken: string
+) {
+  const objState = useAuthStore.getState()
+  return (
+    objState.bIsAuthenticated &&
+    objState.nSessionGeneration === nSessionGeneration &&
+    objState.strRefreshToken === strRefreshToken
+  )
+}
+
+function fnCancelAdminSessionRefresh() {
+  objRefreshController?.abort()
+  objRefreshController = null
+  objRefreshPromise = null
+}
+
+async function fnRefreshAdminSessionRequest(
+  objApiClient: IAuthApiClient,
+  objSignal: AbortSignal
+) {
+  const objState = useAuthStore.getState()
+  if (
+    !objState.objUser ||
+    !objState.strRefreshToken ||
+    !objState.nRefreshTokenExpiresAt ||
+    objState.nRefreshTokenExpiresAt <= Date.now()
+  ) {
+    objState.fnClearSession()
+    return null
+  }
+
+  const { nSessionGeneration, strRefreshToken } = objState
+
+  try {
+    const objTokenResult = await objApiClient.fnRefreshToken(
+      {
+        strClientId: objAppConfig.auth.strClientId,
+        strRefreshToken,
+      },
+      objSignal
+    )
+    const objTokens = fnCreateTokenState(objTokenResult)
+
+    if (!fnIsCurrentRefreshSession(nSessionGeneration, strRefreshToken)) {
+      throw new axios.CanceledError('认证会话已切换，忽略旧令牌刷新结果。')
+    }
+
+    const objCurrentState = useAuthStore.getState()
+    const objNextUser = objTokenResult.objUser
+      ? fnCreateAuthUser(
+          objTokenResult.objUser,
+          objCurrentState.objUser?.strAccount ?? '',
+          objCurrentState.objUser ?? undefined
+        )
+      : undefined
+
+    objCurrentState.fnUpdateTokens(objTokens)
+    if (objNextUser) objCurrentState.fnUpdateUser(objNextUser)
+    return objTokens.strAccessToken
+  } catch (objError) {
+    if (
+      axios.isCancel(objError) ||
+      !fnIsCurrentRefreshSession(nSessionGeneration, strRefreshToken)
+    ) {
+      throw objError
+    }
+    useAuthStore.getState().fnClearSession()
+    throw objError
+  }
+}
+
+/** 合并并发刷新请求，并只把结果写回发起刷新时的同一会话。 */
+export function fnRefreshAuthSession(
+  objApiClient: IAuthApiClient = objDefaultAuthApiClient
+) {
+  if (!objRefreshPromise) {
+    const objController = new AbortController()
+    objRefreshController = objController
+    const objCurrentPromise = fnRefreshAdminSessionRequest(
+      objApiClient,
+      objController.signal
+    ).finally(() => {
+      if (objRefreshPromise !== objCurrentPromise) return
+      objRefreshPromise = null
+      objRefreshController = null
+    })
+    objRefreshPromise = objCurrentPromise
+  }
+
+  return objRefreshPromise
+}
+
+/** 先清除本地会话，再尽力撤销服务端刷新令牌。 */
+export async function fnSignOutAuthSession(
+  objApiClient: IAuthApiClient = objDefaultAuthApiClient
+) {
+  const strRefreshToken: string = useAuthStore.getState().strRefreshToken ?? ''
+  fnCancelAdminSessionRefresh()
+  useAuthStore.getState().fnClearSession()
+
+  if (strRefreshToken) {
+    await fnRevokeRefreshToken(strRefreshToken, objApiClient)
+  }
+}
+
+function fnReadErrorPayloadValue(objPayload: unknown, strKey: string) {
+  if (!objPayload || typeof objPayload !== 'object') return undefined
+  return Reflect.get(objPayload, strKey) as unknown
+}
+
+const objDefaultAuthErrorMessages: IAuthErrorMessages = {
+  strFallbackMessage: '登录失败，请检查手机号和密码。',
+  strNetworkMessage: '无法连接认证服务，请稍后重试。',
+}
+
+/** 从认证错误中读取安全文案，并使用调用方提供的本地化回退。 */
+export function fnReadAuthError(
+  objError: unknown,
+  objMessages: IAuthErrorMessages = objDefaultAuthErrorMessages
+) {
+  if (objError instanceof AuthIdentityError) {
+    return objMessages.strFallbackMessage
+  }
+  if (axios.isAxiosError(objError)) {
+    const objPayload = objError.response?.data
+    const objMessage = fnReadErrorPayloadValue(objPayload, 'message')
+    const objLegacyMessage = fnReadErrorPayloadValue(objPayload, 'msg')
+    if (typeof objMessage === 'string' && objMessage) return objMessage
+    if (typeof objLegacyMessage === 'string' && objLegacyMessage) {
+      return objLegacyMessage
+    }
+    if (!objError.response) return objMessages.strNetworkMessage
+  }
+
+  return objError instanceof Error && objError.message
+    ? objError.message
+    : objMessages.strFallbackMessage
+}

package/template/src/api/clients/configureApiClient.ts

@@ -0,0 +1,62 @@
+import { toast } from 'sonner'
+import { ApiError } from '@/api/ApiError'
+import { fnRefreshAuthSession } from '@/api/authSession'
+import {
+  fnCreateErrorHook,
+  fnCreateRequestHook,
+  fnCreateResponseHook,
+  type IApiHookOptions,
+} from '@/api/hooks'
+import type { IGeneratedApiClient } from '@/api/types'
+import { fnIsAccessTokenExpired, useAuthStore } from '@/stores/authStore'
+
+const objNotifiedErrors = new WeakSet<object>()
+
+type TApiErrorInput = Error | object | string | number | boolean | null
+
+/** 将请求错误统一交给全局 Sonner，并避免同一错误被多层重复提示。 */
+export function fnShowApiError(objError: TApiErrorInput) {
+  const bCanTrack = typeof objError === 'object' && objError !== null
+  if (bCanTrack && objNotifiedErrors.has(objError)) return
+  if (bCanTrack) objNotifiedErrors.add(objError)
+
+  const strMessage =
+    objError instanceof Error ? objError.message : String(objError || '')
+  const strFallbackMessage = strMessage || '请求失败，请稍后重试'
+
+  if (objError instanceof ApiError && objError.strRequestId) {
+    toast.error(strFallbackMessage, {
+      description: `请求 ID：${objError.strRequestId}`,
+    })
+    return
+  }
+  toast.error(strFallbackMessage)
+}
+
+const objDefaultHookOptions: IApiHookOptions = {
+  fnGetAccessToken: () => useAuthStore.getState().strAccessToken,
+  fnIsAccessTokenExpired,
+  fnRefreshAccessToken: fnRefreshAuthSession,
+  fnOnUnauthorized: () => {
+    useAuthStore.getState().fnClearSession()
+  },
+  fnOnError: fnShowApiError,
+}
+
+/** 为生成的 Swagger 客户端挂载应用级通用行为。 */
+export function fnConfigureApiClient<TClient extends IGeneratedApiClient>(
+  objClient: TClient,
+  objOptions: IApiHookOptions = {}
+) {
+  const objHookOptions = { ...objDefaultHookOptions, ...objOptions }
+
+  objClient.instance.interceptors.request.use(
+    fnCreateRequestHook(objHookOptions)
+  )
+  objClient.instance.interceptors.response.use(
+    fnCreateResponseHook(objHookOptions),
+    fnCreateErrorHook(objHookOptions)
+  )
+
+  return objClient
+}

package/template/src/api/clients/httpStatus.ts

@@ -0,0 +1,4 @@
+/** OpenAPI 响应遵循 HTTP 语义：仅 2xx 状态表示请求成功。 */
+export function fnIsSuccessfulHttpStatus(nStatus: number) {
+  return nStatus >= 200 && nStatus < 300
+}

package/template/src/api/config/services.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": "backend",
+    "baseUrlEnv": "VITE_API_BASE_URL",
+    "openapiPath": "/swagger/openapi.json"
+  }
+]

package/template/src/api/demoAuthClient.ts

@@ -0,0 +1,46 @@
+import type { IAuthApiClient } from '@/api/types'
+
+export const objDemoCredentials = {
+  strPhone: '13800000000',
+  strPassword: 'admin123',
+} as const
+
+function fnCreateDemoToken(strPrefix: string) {
+  return `${strPrefix}-${crypto.randomUUID()}`
+}
+
+/** 零后端演示适配器，仅在显式 demo 模式下使用。 */
+export const objDemoAuthApiClient: IAuthApiClient = {
+  fnFirstPartyLogin: async (objInput) => {
+    if (
+      objInput.strPhone !== objDemoCredentials.strPhone ||
+      objInput.strPassword !== objDemoCredentials.strPassword
+    ) {
+      throw new Error('演示账号或密码不正确。')
+    }
+
+    return {
+      strAccessToken: fnCreateDemoToken('demo-access'),
+      strRefreshToken: fnCreateDemoToken('demo-refresh'),
+      nExpiresIn: 10 * 60,
+      nRefreshIdleExpiresIn: 7 * 24 * 60 * 60,
+      objUser: {
+        arrPermissions: ['*'],
+        arrRoleCodes: ['platform-admin'],
+        strId: 'demo-platform-admin',
+        strMaskedPhone: '138****0000',
+        strNickname: '演示管理员',
+        strOrganizationName: '示例企业',
+        strRole: 'admin',
+        strTenantId: 'demo-tenant',
+      },
+    }
+  },
+  fnRefreshToken: async () => ({
+    strAccessToken: fnCreateDemoToken('demo-access'),
+    strRefreshToken: fnCreateDemoToken('demo-refresh'),
+    nExpiresIn: 10 * 60,
+    nRefreshIdleExpiresIn: 7 * 24 * 60 * 60,
+  }),
+  fnSignOut: async () => undefined,
+}