@autional/shared 0.0.0-stage → 0.1.0-rc.32

package/src/auth/auth-machine.ts

@@ -0,0 +1,151 @@
+/**
+ * AuthMachine — 认证流程状态机（轻量版）
+ *
+ * 统一管理认证流程的各个阶段：
+ *   checking → authenticated → bootstrap → ready
+ *           → unauthenticated → redirecting
+ *
+ * 替代 RequireAuth 中的手动 useEffect 链式调用。
+ * 不依赖外部状态机库，使用 React hook + reducer 模式。
+ *
+ * @see docs/architecture/auth-next-issues-analysis.md
+ */
+
+'use client';
+
+import { useReducer, useEffect, useMemo } from 'react';
+import { AuthService } from './service';
+import { useBootstrap } from '../hooks/useBootstrap';
+
+// ============ Types ============
+
+export type AuthStatus =
+	| 'checking' // 初始态：正在检查 token
+	| 'authenticated' // token 有效
+	| 'bootstrap' // token 有效，正在加载权限/租户
+	| 'ready' // 全部就绪
+	| 'unauthenticated' // 无有效 token
+	| 'redirecting'; // 正在跳转到登录页
+
+export interface AuthMachineState {
+	status: AuthStatus;
+	hasToken: boolean;
+	bootstrapState: ReturnType<typeof useBootstrap>;
+}
+
+type AuthAction =
+	| { type: 'TOKEN_FOUND' }
+	| { type: 'NO_TOKEN' }
+	| { type: 'BOOTSTRAP_LOADING' }
+	| { type: 'BOOTSTRAP_READY' }
+	| { type: 'BOOTSTRAP_ERROR' }
+	| { type: 'SESSION_EXPIRED' }
+	| { type: 'REDIRECT' };
+
+// ============ Reducer ============
+
+function authReducer(state: AuthMachineState, action: AuthAction): AuthMachineState {
+	switch (action.type) {
+		case 'TOKEN_FOUND':
+			return { ...state, status: 'authenticated', hasToken: true };
+
+		case 'NO_TOKEN':
+			return { ...state, status: 'unauthenticated', hasToken: false };
+
+		case 'BOOTSTRAP_LOADING':
+			return state.status === 'authenticated' ? { ...state, status: 'bootstrap' } : state;
+
+		case 'BOOTSTRAP_READY':
+			return state.status === 'bootstrap'
+				? { ...state, status: 'ready' }
+				: state.status === 'authenticated'
+					? { ...state, status: 'ready' }
+					: state;
+
+		case 'BOOTSTRAP_ERROR':
+			// Bootstrap 失败仍应显示 UI（降级运行）
+			return state.status === 'bootstrap' ? { ...state, status: 'ready' } : state;
+
+		case 'SESSION_EXPIRED':
+			return { ...state, status: 'unauthenticated', hasToken: false };
+
+		case 'REDIRECT':
+			return { ...state, status: 'redirecting' };
+
+		default:
+			return state;
+	}
+}
+
+// ============ Initial State ============
+
+function createInitialState(): AuthMachineState {
+	const token = AuthService.getAccessToken();
+	return {
+		status: 'checking',
+		hasToken: !!token,
+		bootstrapState: 'idle' as const,
+	};
+}
+
+// ============ Hook ============
+
+/**
+ * 认证流程状态机 Hook。
+ *
+ * 整合 token 检查 + bootstrap 加载为统一状态机，
+ * 替代 RequireAuth + useBootstrap 的手动链式调用。
+ *
+ * 用法:
+ * ```tsx
+ * function App() {
+ *   const machine = useAuthMachine();
+ *   const { status, hasToken } = machine;
+ *
+ *   if (status === 'checking') return <Loading />;
+ *   if (status === 'unauthenticated' || status === 'redirecting') return <LoginPage />;
+ *   if (status === 'ready') return <Dashboard />;
+ *   return <Loading />; // authenticated / bootstrap
+ * }
+ * ```
+ */
+export function useAuthMachine(): AuthMachineState {
+	const [state, dispatch] = useReducer(authReducer, undefined, createInitialState);
+	const bootstrapState = useBootstrap();
+
+	// Phase 1: 检查 token
+	const hasToken = useMemo(() => {
+		const token = AuthService.getAccessToken();
+		return !!token && token !== 'undefined' && token !== 'null';
+	}, []);
+
+	// Phase 2: 根据 token 和 bootstrap 状态分发事件
+	useEffect(() => {
+		if (hasToken) {
+			dispatch({ type: 'TOKEN_FOUND' });
+		} else {
+			dispatch({ type: 'NO_TOKEN' });
+		}
+	}, [hasToken]);
+
+	// Phase 3: bootstrap 状态同步
+	useEffect(() => {
+		switch (bootstrapState) {
+			case 'loading':
+				dispatch({ type: 'BOOTSTRAP_LOADING' });
+				break;
+			case 'ready':
+				dispatch({ type: 'BOOTSTRAP_READY' });
+				break;
+			case 'error':
+				dispatch({ type: 'BOOTSTRAP_ERROR' });
+				break;
+		}
+	}, [bootstrapState]);
+
+	return {
+		...state,
+		hasToken,
+		bootstrapState,
+	};
+}

package/src/auth/auth-queries.ts

@@ -0,0 +1,118 @@
+/**
+ * auth-queries — React Query 认证数据查询
+ *
+ * 为 permissions / tenants / me 等服务端数据提供缓存语义。
+ * 替代 useBootstrap 手动管理请求/loading/error 状态的方式。
+ *
+ * 用法:
+ *   const { data: permissions, isLoading } = usePermissionsQuery();
+ *   const { data: tenants, isError } = useTenantsQuery();
+ *
+ * @see docs/architecture/auth-next-issues-analysis.md
+ */
+
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import { apiClient } from '../api/client';
+import { extractItem } from '../utils/response';
+
+// ============ Constants ============
+
+/** 权限/租户缓存时间：5 分钟内不重复请求 */
+export const AUTH_DATA_STALE_TIME = 5 * 60 * 1000;
+
+// ============ Query Keys ============
+
+export const authQueryKeys = {
+	all: ['auth'] as const,
+	permissions: (tenantId?: string | null) =>
+		tenantId
+			? ([...authQueryKeys.all, 'permissions', tenantId] as const)
+			: ([...authQueryKeys.all, 'permissions'] as const),
+	tenants: (tenantId?: string | null) =>
+		tenantId
+			? ([...authQueryKeys.all, 'tenants', tenantId] as const)
+			: ([...authQueryKeys.all, 'tenants'] as const),
+	me: () => [...authQueryKeys.all, 'me'] as const,
+};
+
+// ============ Queries ============
+
+/**
+ * 当前用户权限列表查询。
+ * 结果自动写入 AuthService（通过 onSuccess 回调），
+ * 供 usePermission hook 和权限检查使用。
+ *
+ * @param tenantId — 可选，切换租户时自动重新请求
+ */
+export function usePermissionsQuery(tenantId?: string | null, enabled = true) {
+	return useQuery({
+		queryKey: authQueryKeys.permissions(tenantId),
+		queryFn: async () => {
+			const headers: Record<string, string> = {};
+			if (tenantId) headers['X-Tenant-ID'] = tenantId;
+			const res = await apiClient.get('/identity/api/v1/auth/me/permissions', { headers });
+			const d = extractItem(res.data);
+			return ((Array.isArray(d) ? d : (d as { permissions?: string[] } | null)?.permissions) ||
+				[]) as string[];
+		},
+		staleTime: AUTH_DATA_STALE_TIME,
+		retry: 1,
+		retryDelay: 1000,
+		// 无 token 时禁止发起请求：未登录时该查询必然 401 → apiClient 401 拦截
+		// → refreshToken() 无 refresh token → onUnauthorized() 抢跑 buildLoginUrl，
+		// 与 RequireAuth 的 OAuth PKCE 触发形成时序竞争（跨域 admin 场景偶发 302 回登录页）。
+		// 未登录的跳转决策统一交给 RequireAuth（OAuth PKCE 或 buildLoginUrl）。
+		enabled,
+	});
+}
+
+/**
+ * 当前用户租户列表查询。
+ * 结果自动写入 AuthService。
+ *
+ * @param tenantId — 可选，切换租户时自动重新请求
+ */
+export function useTenantsQuery(tenantId?: string | null, enabled = true) {
+	return useQuery({
+		queryKey: authQueryKeys.tenants(tenantId),
+		queryFn: async () => {
+			const headers: Record<string, string> = {};
+			if (tenantId) headers['X-Tenant-ID'] = tenantId;
+			const res = await apiClient.get('/identity/api/v1/auth/me/tenants', { headers });
+			const d = extractItem(res.data);
+			return ((Array.isArray(d)
+				? d
+				: (d as { tenants?: Array<{ id: string; name: string; role: string }> } | null)?.tenants) ||
+				[]) as Array<{
+				id: string;
+				name: string;
+				role: string;
+			}>;
+		},
+		staleTime: AUTH_DATA_STALE_TIME,
+		retry: 1,
+		retryDelay: 1000,
+		// 与 usePermissionsQuery 一致：无 token 时禁止发起请求，
+		// 避免 401 → onUnauthorized 抢跑 RequireAuth 的 OAuth PKCE 流程。
+		enabled,
+	});
+}
+
+/**
+ * 当前用户信息查询。
+ * 用于 OAuth 回调后获取完整用户信息。
+ */
+export function useMeQuery() {
+	return useQuery({
+		queryKey: authQueryKeys.me(),
+		queryFn: async () => {
+			const res = await apiClient.get('/identity/api/v1/auth/me');
+			return extractItem(res.data) ?? res.data;
+		},
+		staleTime: AUTH_DATA_STALE_TIME,
+		retry: 1,
+		retryDelay: 1000,
+	});
+}