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

package/template/src/router/router.ts

@@ -0,0 +1,66 @@
+import { QueryClient } from '@tanstack/react-query'
+import { createRouter } from '@tanstack/react-router'
+import {
+  fnCanCurrentUser,
+  fnValidateAuthSession,
+  useAuthStore,
+} from '@/stores/authStore'
+import { fnHandleAuthSessionTransition } from './authLifecycle'
+import { objRouteTree } from './config'
+
+export const objQueryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 10_000,
+    },
+  },
+})
+
+export const objRouter = createRouter({
+  routeTree: objRouteTree,
+  context: {
+    objQueryClient,
+    objAuth: {
+      fnHasPermission: fnCanCurrentUser,
+      fnIsAuthenticated: fnValidateAuthSession,
+    },
+  },
+  defaultPreload: 'intent',
+  defaultPreloadStaleTime: 0,
+})
+
+let fnStopAuthLifecycle: (() => void) | undefined
+
+/** 启动认证状态与 Router、Query 缓存之间的单向同步。 */
+export function fnStartAuthLifecycle() {
+  fnStopAuthLifecycle ??= useAuthStore.subscribe(
+    (objCurrentState, objPreviousState) => {
+      fnHandleAuthSessionTransition(objCurrentState, objPreviousState, {
+        fnClearQueryCache: () => objQueryClient.clear(),
+        fnInvalidateRouter: () => {
+          void objRouter.invalidate()
+        },
+        fnNavigateToSignIn: () => {
+          if (objRouter.state.location.pathname === '/sign-in') return
+          void objRouter.navigate({
+            to: '/sign-in',
+            search: {},
+            replace: true,
+            ignoreBlocker: true,
+          })
+        },
+      })
+    }
+  )
+
+  return () => {
+    fnStopAuthLifecycle?.()
+    fnStopAuthLifecycle = undefined
+  }
+}
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof objRouter
+  }
+}

package/template/src/router/searchSchemas.ts

@@ -0,0 +1,9 @@
+import { fnParseInternalRedirect } from '@/lib/navigationRedirect'
+
+export function fnValidateSignInSearch(objSearch: Record<string, unknown>): {
+  redirect?: string
+} {
+  const strRedirectPath = fnParseInternalRedirect(objSearch.redirect)
+
+  return strRedirectPath ? { redirect: strRedirectPath } : {}
+}

package/template/src/router/types.ts

@@ -0,0 +1,76 @@
+import type { ElementType } from 'react'
+import type { QueryClient } from '@tanstack/react-query'
+import type { RegisteredRouter } from '@tanstack/react-router'
+
+type TAppRoute =
+  RegisteredRouter['routesById'][keyof RegisteredRouter['routesById']]
+
+/** 经过权限、翻译和排序后可直接展示的导航条目。 */
+export interface INavigationCatalogEntry {
+  /** 当前条目经过相同规则筛选和排序的可见子条目。 */
+  readonly arrChildren: readonly INavigationCatalogEntry[]
+  /** 导航排序权重。 */
+  readonly nOrder: number
+  /** TanStack Router 的原始路由，用于类型安全跳转。 */
+  readonly objRoute: TAppRoute
+  /** 当前语言下的展示标题。 */
+  readonly strTitle: string
+}
+
+/** 一个稳定路由分组下的完整可见导航。 */
+export interface INavigationCatalogGroup {
+  /** 当前分组中的顶层导航条目。 */
+  readonly arrEntries: readonly INavigationCatalogEntry[]
+  /** 分组排序权重。 */
+  readonly nOrder: number
+  /** 不随语言变化的分组消息 Key。 */
+  readonly strKey: TRouteMessageKey
+  /** 当前语言下的分组标题。 */
+  readonly strTitle: string
+}
+
+/** 路由组合层拥有的标题与导航分组文案 Key。 */
+export type TRouteMessageKey =
+  | 'route.error.forbidden'
+  | 'route.error.general'
+  | 'route.error.maintenance'
+  | 'route.error.notFound'
+  | 'route.error.title'
+  | 'route.error.unauthorized'
+  | 'route.group.system'
+  | 'route.group.showcase'
+  | 'route.group.workspace'
+  | 'route.home.title'
+  | 'route.showcase.access'
+  | 'route.showcase.feedback'
+  | 'route.showcase.files'
+  | 'route.showcase.form'
+  | 'route.showcase.metadata'
+  | 'route.showcase.table'
+  | 'route.showcase.title'
+  | 'route.signIn.title'
+  | 'route.signUp.title'
+
+declare module '@tanstack/react-router' {
+  interface StaticDataRouteOption {
+    /** 页面标题的稳定语言包 Key，不直接保存某一种语言的展示文本。 */
+    strTitle?: TRouteMessageKey
+    Icon?: ElementType
+    /** 导航分组的稳定语言包 Key。 */
+    strNavigationGroup?: TRouteMessageKey
+    nNavigationGroupOrder?: number
+    nNavigationOrder?: number
+    bShowInSidebar?: boolean
+    strPermission?: string
+  }
+}
+
+export interface IAuthSession {
+  fnHasPermission: (strPermission?: string) => boolean
+  fnIsAuthenticated: () => boolean
+}
+
+export interface IRouterContext {
+  objQueryClient: QueryClient
+  objAuth: IAuthSession
+}

package/template/src/stores/authSessionStorage.ts

@@ -0,0 +1,27 @@
+import type { StateStorage } from 'zustand/middleware'
+
+type TAuthSessionStorageMode = 'memory' | 'session'
+
+/**
+ * 创建认证会话存储端口。
+ *
+ * `memory` 不跨页面刷新保留 Token，适合作为 connected 模式的安全默认值；
+ * `session` 便于本地演示，但 Token 会进入当前标签页的 sessionStorage。
+ */
+export function fnCreateAuthSessionStorage(
+  strMode: TAuthSessionStorageMode
+): StateStorage {
+  if (strMode === 'session') return globalThis.sessionStorage
+
+  const objItems = new Map<string, string>()
+
+  return {
+    getItem: (strName) => objItems.get(strName) ?? null,
+    setItem: (strName, strValue) => {
+      objItems.set(strName, strValue)
+    },
+    removeItem: (strName) => {
+      objItems.delete(strName)
+    },
+  }
+}

package/template/src/stores/authStore.ts

@@ -0,0 +1,165 @@
+import { objAppConfig } from '@/config/appConfig'
+import { create } from 'zustand'
+import { createJSONStorage, persist } from 'zustand/middleware'
+import { fnHasPermission } from '@/lib/accessControl'
+import { fnCreateAuthSessionStorage } from './authSessionStorage'
+import type { IAuthSession, IAuthTokens, IAuthUser } from './types'
+
+export type { IAuthSession, IAuthTokens } from './types'
+
+interface IAuthState {
+  bIsAuthenticated: boolean
+  nSessionGeneration: number
+  objUser: IAuthUser | null
+  strAccessToken: string | null
+  strRefreshToken: string | null
+  nAccessTokenExpiresAt: number | null
+  nRefreshTokenExpiresAt: number | null
+  fnEstablishSession: (objSession: IAuthSession) => void
+  fnUpdateTokens: (objTokens: IAuthTokens) => void
+  fnUpdateUser: (objUser: IAuthUser) => void
+  fnClearSession: () => void
+}
+
+function fnHaveEqualStringSets(
+  arrLeft: readonly string[],
+  arrRight: readonly string[]
+) {
+  const objLeft = new Set(arrLeft)
+  const objRight = new Set(arrRight)
+  if (objLeft.size !== objRight.size) return false
+  return [...objLeft].every((strValue) => objRight.has(strValue))
+}
+
+/** 授权上下文变化时提升会话版本，以驱动路由和服务端缓存重新校验。 */
+function fnHasAuthorizationContextChanged(
+  objCurrentUser: IAuthUser | null,
+  objNextUser: IAuthUser
+) {
+  if (!objCurrentUser) return true
+
+  return (
+    objCurrentUser.strId !== objNextUser.strId ||
+    objCurrentUser.strRole !== objNextUser.strRole ||
+    objCurrentUser.strTenantId !== objNextUser.strTenantId ||
+    !fnHaveEqualStringSets(
+      objCurrentUser.arrPermissions,
+      objNextUser.arrPermissions
+    ) ||
+    !fnHaveEqualStringSets(
+      objCurrentUser.arrRoleCodes,
+      objNextUser.arrRoleCodes
+    )
+  )
+}
+
+const objInitialAuthState = {
+  bIsAuthenticated: false,
+  objUser: null,
+  strAccessToken: null,
+  strRefreshToken: null,
+  nAccessTokenExpiresAt: null,
+  nRefreshTokenExpiresAt: null,
+}
+
+export const useAuthStore = create<IAuthState>()(
+  persist(
+    (fnSet) => ({
+      ...objInitialAuthState,
+      nSessionGeneration: 0,
+      fnEstablishSession: (objSession) =>
+        fnSet((objState) => ({
+          bIsAuthenticated: true,
+          nSessionGeneration: objState.nSessionGeneration + 1,
+          objUser: objSession.objUser,
+          strAccessToken: objSession.strAccessToken,
+          strRefreshToken: objSession.strRefreshToken,
+          nAccessTokenExpiresAt: objSession.nAccessTokenExpiresAt,
+          nRefreshTokenExpiresAt: objSession.nRefreshTokenExpiresAt,
+        })),
+      fnUpdateTokens: (objTokens) => fnSet(objTokens),
+      fnUpdateUser: (objUser) =>
+        fnSet((objState) => ({
+          objUser,
+          nSessionGeneration: fnHasAuthorizationContextChanged(
+            objState.objUser,
+            objUser
+          )
+            ? objState.nSessionGeneration + 1
+            : objState.nSessionGeneration,
+        })),
+      fnClearSession: () =>
+        fnSet((objState) => ({
+          ...objInitialAuthState,
+          nSessionGeneration: objState.nSessionGeneration + 1,
+        })),
+    }),
+    {
+      name: objAppConfig.storage.strAuthSessionKey,
+      storage: createJSONStorage(() =>
+        fnCreateAuthSessionStorage(objAppConfig.auth.strSessionStorage)
+      ),
+      partialize: ({
+        bIsAuthenticated,
+        objUser,
+        strAccessToken,
+        strRefreshToken,
+        nAccessTokenExpiresAt,
+        nRefreshTokenExpiresAt,
+      }) => ({
+        bIsAuthenticated,
+        objUser,
+        strAccessToken,
+        strRefreshToken,
+        nAccessTokenExpiresAt,
+        nRefreshTokenExpiresAt,
+      }),
+    }
+  )
+)
+
+export function fnIsAccessTokenExpired() {
+  const { strAccessToken, nAccessTokenExpiresAt } = useAuthStore.getState()
+
+  return (
+    !strAccessToken ||
+    !nAccessTokenExpiresAt ||
+    nAccessTokenExpiresAt <= Date.now() + 30_000
+  )
+}
+
+/** 只校验会话完整性与刷新有效期，不把角色字符串当作认证条件。 */
+export function fnIsAuthenticated() {
+  const { bIsAuthenticated, objUser, strRefreshToken, nRefreshTokenExpiresAt } =
+    useAuthStore.getState()
+
+  return Boolean(
+    bIsAuthenticated &&
+    objUser &&
+    strRefreshToken &&
+    nRefreshTokenExpiresAt &&
+    nRefreshTokenExpiresAt > Date.now()
+  )
+}
+
+export function fnCanCurrentUser(strPermission?: string) {
+  return fnHasPermission(useAuthStore.getState().objUser, strPermission)
+}
+
+/** 校验持久化会话，并在失效时同步清除残留凭据。 */
+export function fnValidateAuthSession() {
+  if (fnIsAuthenticated()) return true
+
+  const objState = useAuthStore.getState()
+  const bHasSessionMaterial = Boolean(
+    objState.bIsAuthenticated ||
+    objState.objUser ||
+    objState.strAccessToken ||
+    objState.strRefreshToken ||
+    objState.nAccessTokenExpiresAt ||
+    objState.nRefreshTokenExpiresAt
+  )
+
+  if (bHasSessionMaterial) objState.fnClearSession()
+  return false
+}

package/template/src/stores/types.ts

@@ -0,0 +1,36 @@
+export interface IAuthUser {
+  /** 后端授予的稳定权限码；`*` 表示拥有全部权限。 */
+  arrPermissions: string[]
+  /** 后端授予的角色编码，可用于授权上下文刷新，不用于替代权限码。 */
+  arrRoleCodes: string[]
+  /** 当前用户的稳定唯一标识。 */
+  strId: string
+  /** 用于界面展示的登录账号，通常已经脱敏。 */
+  strAccount: string
+  /** 当前用户的展示名称。 */
+  strDisplayName: string
+  /** 当前用户所属组织的展示名称。 */
+  strOrganizationName?: string
+  /** 后端返回的可选身份类型；前端授权仍以权限码为准。 */
+  strRole: string
+  /** 当前租户标识；变化时必须隔离服务端缓存。 */
+  strTenantId?: string
+  /** 当前用户头像地址。 */
+  strAvatarUrl?: string
+}
+
+export interface IAuthTokens {
+  /** 短期访问令牌，只允许进入请求头，不得写入日志。 */
+  strAccessToken: string
+  /** 会话续期令牌，只允许进入认证存储和刷新请求。 */
+  strRefreshToken: string
+  /** 访问令牌的绝对过期时间，单位为毫秒时间戳。 */
+  nAccessTokenExpiresAt: number
+  /** 刷新令牌的绝对过期时间，单位为毫秒时间戳。 */
+  nRefreshTokenExpiresAt: number
+}
+
+export interface IAuthSession extends IAuthTokens {
+  /** 与令牌绑定的当前用户身份和授权上下文。 */
+  objUser: IAuthUser
+}

package/template/src/stores/uiPreferenceStore.ts

@@ -0,0 +1,34 @@
+import { objAppConfig } from '@/config/appConfig'
+import { create } from 'zustand'
+import { createJSONStorage, persist } from 'zustand/middleware'
+
+interface IUiPreferenceState {
+  bIsSidebarOpen: boolean
+  nSidebarWidth: number
+  fnSetSidebarOpen: (bIsOpen: boolean) => void
+  fnSetSidebarWidth: (nWidth: number) => void
+}
+
+const objInitialUiPreferenceState = {
+  bIsSidebarOpen: true,
+  nSidebarWidth: 256,
+}
+
+export const useUiPreferenceStore = create<IUiPreferenceState>()(
+  persist(
+    (fnSet) => ({
+      ...objInitialUiPreferenceState,
+      fnSetSidebarOpen: (bIsOpen) => fnSet({ bIsSidebarOpen: bIsOpen }),
+      fnSetSidebarWidth: (nWidth) => fnSet({ nSidebarWidth: nWidth }),
+    }),
+    {
+      name: objAppConfig.storage.strUiPreferenceKey,
+      version: 1,
+      storage: createJSONStorage(() => localStorage),
+      partialize: ({ bIsSidebarOpen, nSidebarWidth }) => ({
+        bIsSidebarOpen,
+        nSidebarWidth,
+      }),
+    }
+  )
+)

package/template/src/styles/index.css

@@ -0,0 +1,141 @@
+@import 'tailwindcss';
+@import 'tw-animate-css';
+@import './theme.css';
+
+@custom-variant dark (&:is(.dark *));
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+
+    scrollbar-color: var(--border) transparent;
+    scrollbar-width: thin;
+  }
+
+  html {
+    @apply overflow-x-hidden;
+  }
+
+  body {
+    @apply min-h-svh w-full bg-background font-sans text-foreground has-[div[data-variant='inset']]:bg-sidebar;
+  }
+
+  /* Override Radix scroll locking for sticky headers */
+  body[data-scroll-locked] {
+    overflow: unset !important;
+  }
+
+  /* Cursor pointer for buttons */
+  button:not(:disabled),
+  [role='button']:not(:disabled) {
+    cursor: pointer;
+  }
+
+  /* Prevent focus zoom on mobile devices */
+  @media screen and (width <= 767px) {
+    input,
+    select,
+    textarea {
+      font-size: 16px !important;
+    }
+  }
+}
+
+@utility container {
+  padding-inline: 2rem;
+  margin-inline: auto;
+}
+
+@utility no-scrollbar {
+  /* Hide scrollbar for Chrome, Safari and Opera */
+  &::-webkit-scrollbar {
+    display: none;
+  }
+
+  /* Hide scrollbar for IE, Edge and Firefox */
+  -ms-overflow-style: none; /* IE and Edge */
+  scrollbar-width: none; /* Firefox */
+}
+
+@utility faded-bottom {
+  @apply after:pointer-events-none after:absolute after:inset-s-0 after:bottom-0 after:hidden after:h-32 after:w-full after:rounded-b-2xl after:bg-[linear-gradient(180deg,transparent_10%,var(--background)_70%)] md:after:block;
+}
+
+/* Remove after the internal advanced table makes select command height content-based. */
+.table-cell-layer__select > [data-slot='command'] {
+  height: auto;
+}
+
+/* Keep a lone table filter readable instead of stretching across the row. */
+.table-search-bar__field:only-child {
+  max-width: 32rem;
+}
+
+/* Keep the compact search action stable while its spinner is mounted. */
+.table-search-bar__actions > button[type='submit'] {
+  position: relative;
+  width: 4rem;
+}
+
+.table-search-bar__actions > button[type='submit']:disabled {
+  color: transparent;
+}
+
+.table-search-bar__actions > button[type='submit']:disabled > svg {
+  position: absolute;
+  inset: 0;
+  margin: auto;
+  color: var(--primary-foreground);
+}
+
+/* Keep the table's native link renderer visually consistent with app links. */
+.table-component__link {
+  padding: 0;
+  font: inherit;
+  color: var(--primary);
+  text-underline-offset: 4px;
+  background: transparent;
+  border: 0;
+}
+
+.table-component__link:hover:not(:disabled) {
+  text-decoration: underline;
+}
+
+.table-component__link:disabled {
+  color: var(--muted-foreground);
+  cursor: default;
+}
+
+/* styles.css */
+.CollapsibleContent {
+  overflow: hidden;
+}
+
+.CollapsibleContent[data-state='open'] {
+  animation: slide-down 300ms ease-out;
+}
+
+.CollapsibleContent[data-state='closed'] {
+  animation: slide-up 300ms ease-out;
+}
+
+@keyframes slide-down {
+  from {
+    height: 0;
+  }
+
+  to {
+    height: var(--radix-collapsible-content-height);
+  }
+}
+
+@keyframes slide-up {
+  from {
+    height: var(--radix-collapsible-content-height);
+  }
+
+  to {
+    height: 0;
+  }
+}