@autional-cn/shared 0.1.0-rc

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@autional-cn/shared",
+  "version": "0.1.0-rc",
+  "description": "Autional shared layer — API client, auth, types, hooks, utils",
+  "license": "AGPL-3.0",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./branding": "./src/branding/index.ts",
+    "./slug-from-url": "./src/auth/slug-from-url.ts",
+    "./generated/api": "./src/generated/api.ts",
+    "./generated/types": "./src/generated/types.ts",
+    "./generated/queries": "./src/generated/queries.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@opentelemetry/api": "1.9.1",
+    "@tanstack/react-query": "5.100.9",
+    "axios": "1.16.0",
+    "lodash-es": "4.18.1",
+    "zustand": "5.0.13"
+  },
+  "devDependencies": {
+    "@types/lodash-es": "4.17.12",
+    "@types/node": "26.1.2",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "react": "19.2.5",
+    "react-dom": "19.2.5",
+    "typescript": "5.8.3",
+    "vitest": "3.2.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/api/__tests__/entry-plane.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from 'vitest';
+import { resolveEntryPlane } from '../entry-plane';
+
+describe('resolveEntryPlane', () => {
+	it('redirect 指向 admin 门户主机 → admin', () => {
+		expect(resolveEntryPlane('https://admin.iam.tianv.com/dashboard', 'auth.iam.tianv.com')).toBe(
+			'admin',
+		);
+	});
+
+	it('redirect 指向 platform 门户主机 → platform', () => {
+		expect(resolveEntryPlane('https://platform.iam.tianv.com/tenants', 'auth.iam.tianv.com')).toBe(
+			'platform',
+		);
+	});
+
+	it('redirect 指向非管理门户（user）→ 回落当前主机（auth）→ api', () => {
+		expect(resolveEntryPlane('https://user.iam.tianv.com/dashboard', 'auth.iam.tianv.com')).toBe(
+			'api',
+		);
+	});
+
+	it('redirect 指向安全仪表盘主机 → admin（SOC 门户为 admin 受众）', () => {
+		expect(
+			resolveEntryPlane('https://security.iam.tianv.com/risk-dashboard', 'auth.iam.tianv.com'),
+		).toBe('admin');
+	});
+
+	it('无 redirect、当前主机为安全仪表盘 → admin', () => {
+		expect(resolveEntryPlane(null, 'security.iam.tianv.com')).toBe('admin');
+	});
+
+	it('无 redirect、当前主机为 admin 门户 → admin', () => {
+		expect(resolveEntryPlane(null, 'admin.iam.tianv.com')).toBe('admin');
+	});
+
+	it('无 redirect、当前主机为 auth 门户 → api', () => {
+		expect(resolveEntryPlane(null, 'auth.iam.tianv.com')).toBe('api');
+	});
+
+	it('redirect 为相对路径时按当前主机判定', () => {
+		expect(resolveEntryPlane('/admin/dashboard', 'platform.iam.tianv.com')).toBe('platform');
+		expect(resolveEntryPlane('/dashboard', 'auth.iam.tianv.com')).toBe('api');
+	});
+
+	it('redirect 非法时回落当前主机判定', () => {
+		expect(resolveEntryPlane('http://[invalid', 'auth.iam.tianv.com')).toBe('api');
+	});
+
+	it('主机前缀大小写不敏感、带端口仍匹配', () => {
+		expect(resolveEntryPlane('https://ADMIN.iam.tianv.com/', 'auth.iam.tianv.com')).toBe('admin');
+		expect(resolveEntryPlane('https://admin.iam.tianv.com:8443/', 'auth.iam.tianv.com')).toBe(
+			'admin',
+		);
+	});
+});
+
+// 冷启动链：同意页无会话 → `<slug>/login?redirect=<authorize URL>`（oauth-cold-start TASK-07）。
+// authorize URL 宿主是 auth 门户 ⇒ 宿主判定为空，必须下钻内嵌目标（redirect_uri / state.redirect），
+// 否则回程门户拿到的 token 平面恒为 api，admin/platform 受众端点全部 403 40000503（F-W5）。
+describe('resolveEntryPlane（authorize URL 作为登录页 redirect）', () => {
+	/** 复刻 initiateOAuthLogin 的 authorize URL 组装（oauth-login.ts）。 */
+	function authorizeUrl(params: Record<string, string>): string {
+		const qs = new URLSearchParams({ response_type: 'code', client_id: 'cid-1', ...params });
+		return `https://auth.iam.tianv.com/oauth/api/v1/oauth/authorize?${qs}`;
+	}
+
+	it('redirect_uri 指向 admin 门户回调 → admin', () => {
+		const url = authorizeUrl({
+			redirect_uri: 'https://admin.iam.tianv.com/oauth/callback',
+			state: JSON.stringify({ csrf: 'x', redirect: 'https://admin.iam.tianv.com/demo/dashboard' }),
+		});
+		expect(resolveEntryPlane(url, 'auth.iam.tianv.com')).toBe('admin');
+	});
+
+	it('redirect_uri 缺失时以 state.redirect（发起页 URL）判定 → platform', () => {
+		const url = authorizeUrl({
+			state: JSON.stringify({ csrf: 'x', redirect: 'https://platform.iam.tianv.com/tenants' }),
+		});
+		expect(resolveEntryPlane(url, 'auth.iam.tianv.com')).toBe('platform');
+	});
+
+	it('内嵌目标为安全仪表盘 → admin（SOC 门户与 admin 同平面）', () => {
+		const url = authorizeUrl({ redirect_uri: 'https://security.iam.tianv.com/oauth/callback' });
+		expect(resolveEntryPlane(url, 'auth.iam.tianv.com')).toBe('admin');
+	});
+
+	it('内嵌目标为 user 门户 / 第三方应用 → 回落 api', () => {
+		expect(
+			resolveEntryPlane(
+				authorizeUrl({ redirect_uri: 'https://user.iam.tianv.com/oauth/callback' }),
+				'auth.iam.tianv.com',
+			),
+		).toBe('api');
+		expect(
+			resolveEntryPlane(
+				authorizeUrl({ redirect_uri: 'https://app.example.com/oauth/callback' }),
+				'auth.iam.tianv.com',
+			),
+		).toBe('api');
+	});
+
+	it('state 非 JSON（旧式纯串）不抛错，按 redirect_uri 判定', () => {
+		const url = authorizeUrl({
+			redirect_uri: 'https://admin.iam.tianv.com/oauth/callback',
+			state: 'plain-state',
+		});
+		expect(resolveEntryPlane(url, 'auth.iam.tianv.com')).toBe('admin');
+	});
+
+	it('非 authorize 路径的 redirect_uri 参数不参与判定（防普通深链伪造平面）', () => {
+		expect(
+			resolveEntryPlane(
+				'https://user.iam.tianv.com/demo/?redirect_uri=https://admin.iam.tianv.com/',
+				'auth.iam.tianv.com',
+			),
+		).toBe('api');
+	});
+});

package/src/api/bff-client.ts

@@ -0,0 +1,94 @@
+/**
+ * BFF (Backend-For-Frontend) Auth Client
+ * 使用 httpOnly session cookie 替代 localStorage token，消除 XSS 令牌窃取风险。
+ *
+ * BFF 统一路由后：所有 API 通过 /bff/identity/api/v1/auth/* 访问。
+ */
+
+const BFF_LOGIN = '/bff/identity/api/v1/auth/login';
+const BFF_REFRESH = '/bff/identity/api/v1/auth/refresh';
+const BFF_LOGOUT = '/bff/identity/api/v1/auth/logout';
+
+interface BFFLoginResult {
+	code: number;
+	message: string;
+	data?: {
+		user?: { id: string; username?: string; email?: string };
+		expires_in?: number;
+		requires_mfa?: boolean;
+		mfa_check_reason?: string;
+		challenge_token?: string;
+		must_change_password?: boolean;
+		password_warning?: string;
+		password_expires_in?: number;
+	};
+}
+
+export async function bffLogin(
+	identity: string,
+	password: string,
+	tenantId?: string,
+): Promise<BFFLoginResult> {
+	const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+	if (tenantId) {
+		headers['X-Tenant-ID'] = tenantId;
+	}
+	const resp = await fetch(BFF_LOGIN, {
+		method: 'POST',
+		headers,
+		body: JSON.stringify({ identity, password, ...(tenantId ? { tenant_id: tenantId } : {}) }),
+	});
+	if (!resp.ok) {
+		return { code: resp.status, message: `BFF unavailable (HTTP ${resp.status})` };
+	}
+	try {
+		return await resp.json();
+	} catch {
+		return { code: -1, message: 'BFF returned invalid response' };
+	}
+}
+
+export async function bffRefresh(): Promise<BFFLoginResult> {
+	const resp = await fetch(BFF_REFRESH, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+	});
+	if (!resp.ok) {
+		return { code: resp.status, message: `BFF unavailable (HTTP ${resp.status})` };
+	}
+	try {
+		return await resp.json();
+	} catch {
+		return { code: -1, message: 'BFF returned invalid response' };
+	}
+}
+
+export async function bffLogout(): Promise<void> {
+	// BFF cookie 模式未启用时此调用无凭据可依（identity logout 必 401），不发起无意义请求。
+	// 导航归调用方（useLogout / useAuthActions.logout 自身跳转），此处只做会话吊销。
+	if (!isBFFAvailable()) return;
+	await fetch(BFF_LOGOUT, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+	});
+}
+
+/**
+ * BFF 是否可用。
+ * 默认基于 __APP_CONFIG__ 中的 VITE_BFF_ENABLED 环境变量。
+ * 也可以在调用前通过 isBFFAvailable.override 设置（用于测试或动态切换）。
+ */
+export function isBFFAvailable(): boolean {
+	if (typeof window !== 'undefined') {
+		const cfg = (window as any).__APP_CONFIG__;
+		if (cfg?.VITE_BFF_ENABLED === 'true') return true;
+		if (cfg?.VITE_BFF_ENABLED === 'false') return false;
+	}
+	// Static override (for testing or dynamic switching)
+	if (isBFFAvailable._override !== undefined) return isBFFAvailable._override;
+	// Default: false (auth-pages opt-in via env var)
+	return false;
+}
+
+// Allow runtime override (e.g. for testing or feature-flag driven toggling)
+isBFFAvailable._override = undefined as boolean | undefined;

package/src/api/client.ts

@@ -0,0 +1,174 @@
+/**
+ * Autional 统一 API Client
+ * - 所有前端应用共用同一个 axios 实例
+ * - 自动注入 Bearer token + X-Tenant-ID
+ * - 自动 unwrap 后端响应 + PascalCase→camelCase 转换
+ * - 自动 token refresh + 401 处理
+ */
+
+import axios, { AxiosError } from 'axios';
+import type { AxiosInstance, InternalAxiosRequestConfig } from 'axios';
+import { camelCaseKeys, snakeCaseKeys } from '../utils/case';
+import { getApiBaseUrl } from '../config';
+import { getTraceParentHeader } from './trace';
+import { ENTRY_PLANE_HEADER, resolveEntryPlane } from './entry-plane';
+import { AuthService } from '../auth/service';
+
+function setupInterceptors(instance: AxiosInstance) {
+	// ============ Request Interceptor ============
+	instance.interceptors.request.use(async (config: InternalAxiosRequestConfig) => {
+		// 预判式 Token 刷新：如果 Token 已过期或即将过期（60s 缓冲），先刷新再发请求
+		const token = AuthService.getAccessToken();
+		if (token && AuthService.isTokenExpired(token)) {
+			try {
+				const newToken = await AuthService.refreshToken();
+				if (newToken) {
+					config.headers.Authorization = `Bearer ${newToken}`;
+					return config;
+				}
+			} catch (e) {
+				console.warn('[API] token pre-refresh failed', (e as Error)?.message || '');
+			}
+		}
+		if (token) {
+			config.headers.Authorization = `Bearer ${token}`;
+		}
+
+		const tenantId = AuthService.getCurrentTenantId();
+		if (tenantId) {
+			config.headers['X-Tenant-ID'] = tenantId;
+		}
+
+		// 请求体 camelCase → snake_case 转换（后端 Go 期望 snake_case）
+		if (config.data && typeof config.data === 'object' && !(config.data instanceof FormData)) {
+			config.data = snakeCaseKeys(config.data);
+		}
+
+		// 查询参数 camelCase → snake_case 转换（后端 Go 期望 snake_case form tag）
+		if (config.params && typeof config.params === 'object') {
+			config.params = snakeCaseKeys(config.params);
+		}
+
+		// 按入口登录（P5）：登录端点声明入口平面，identity 据此签发 entry_plane claim
+		// （admin./platform. 门户的 redirect 目标决定平面；缺省 api）
+		if (config.url?.includes('/api/v1/auth/login') && typeof window !== 'undefined') {
+			const redirect = new URLSearchParams(window.location.search).get('redirect');
+			config.headers[ENTRY_PLANE_HEADER] = resolveEntryPlane(redirect, window.location.hostname);
+		}
+
+		const traceparent = getTraceParentHeader();
+		if (traceparent) {
+			config.headers['traceparent'] = traceparent;
+		}
+
+		return config;
+	});
+
+	// ============ Response Interceptor ============
+	instance.interceptors.response.use(
+		(res) => {
+			const data = res.data;
+
+			// 只处理后端标准响应格式 { code, message, ... }
+			if (data && typeof data === 'object' && 'code' in data) {
+				let payload: unknown;
+
+				// 嵌套 data 格式: { code, message, data: {...}, timestamp }
+				if ('data' in data && data.data !== undefined) {
+					payload = data.data;
+				}
+				// 扁平列表格式: { code, message, items, total, pagination, timestamp }
+				else if ('items' in data) {
+					payload = {
+						items: data.items,
+						total: data.total,
+						pagination: data.pagination,
+					};
+				}
+				// 无 data/items 的简单响应 (如删除成功)
+				else {
+					payload = data;
+				}
+
+				// PascalCase → camelCase 转换
+				res.data = camelCaseKeys(payload);
+			}
+
+			return res;
+		},
+		async (err: AxiosError) => {
+			const originalRequest = err.config as InternalAxiosRequestConfig & {
+				_retry?: boolean;
+				_tenantRetry?: boolean;
+			};
+			if (!originalRequest) return Promise.reject(err);
+
+			// 401 → token refresh (skip for login & refresh endpoints — no token to refresh / avoid loops)
+			// Also skip OAuth token-exchange: a 401 there is a business error (invalid_grant / invalid_client),
+			// NOT session expiry. Treating it as one routes through refreshToken() → onUnauthorized → login
+			// page bounce while the auth code is already consumed → infinite redirect loop.
+			if (
+				err.response?.status === 401 &&
+				!originalRequest._retry &&
+				!originalRequest.url?.includes('/api/v1/auth/login') &&
+				!originalRequest.url?.includes('/api/v1/auth/refresh') &&
+				!originalRequest.url?.includes('/oauth/api/v1/oauth/token') &&
+				// oauth refresh 端点自身的 401（无效/过期 refresh token）是业务性失败，
+				// 不走 refresh 重试（避免 oauth refresh → 401 → 再 refresh 的循环）
+				!originalRequest.url?.includes('/oauth/api/v1/oauth/refresh') &&
+				// P1-4: export-data 的业务性 401（step-up 拒绝）不是会话过期，
+				// 不走 refresh 重试/登出，由页面 catch 展示错误。
+				!originalRequest.url?.includes('/auth/me/export-data')
+			) {
+				originalRequest._retry = true;
+
+				// 尝试刷新 token（refreshToken 内部处理无 refresh token / 刷新失败 / onUnauthorized）
+				const newToken = await AuthService.refreshToken();
+				if (newToken) {
+					originalRequest.headers.Authorization = `Bearer ${newToken}`;
+					return instance(originalRequest);
+				}
+
+				// 刷新失败 → 已由 refreshToken 内部调用 onUnauthorized
+				return Promise.reject(err);
+			}
+
+			// 404 + tenant not found (ErrCodeDomainTenantNotFound=40000102)
+			// → clear tenant from store → retry without X-Tenant-ID
+			const data = err.response?.data as any;
+			if (
+				err.response?.status === 404 &&
+				data?.code === '40000102' &&
+				!originalRequest._tenantRetry
+			) {
+				originalRequest._tenantRetry = true;
+				AuthService.updateCurrentTenant('');
+				// Remove X-Tenant-ID header and retry
+				const headers = originalRequest.headers as Record<string, unknown>;
+				delete headers['X-Tenant-ID'];
+				return instance(originalRequest);
+			}
+
+			return Promise.reject(err);
+		},
+	);
+}
+
+/**
+ * 创建自定义 baseURL 的 API client 实例
+ * 适用于需要访问多个不同服务前缀的场景（如 admin-console）
+ */
+export function createApiClient(baseUrl: string): AxiosInstance {
+	const instance = axios.create({
+		baseURL: baseUrl,
+		timeout: 30000,
+		headers: { 'Content-Type': 'application/json' },
+	});
+	setupInterceptors(instance);
+	return instance;
+}
+
+/**
+ * 默认 API client 实例，baseURL 从 API_BASE_URL 配置读取，fallback '/api/v1'
+ */
+export const apiClient: AxiosInstance = createApiClient(getApiBaseUrl());

package/src/api/entry-plane.ts

@@ -0,0 +1,61 @@
+/**
+ * 按入口登录：登录请求的入口平面声明（GATEWAY-ENTRY-ISOLATION-DESIGN §4.4）。
+ * 值域 api|admin|platform（identity entry_plane.go 契约）；仅登录端点消费，
+ * refresh/challenge 由服务端从 claim 继承，无需前端声明。
+ */
+
+export type EntryPlane = 'api' | 'admin' | 'platform';
+
+export const ENTRY_PLANE_HEADER = 'X-Entry-Plane';
+
+function planeFromHostname(hostname: string): EntryPlane | null {
+	const h = hostname.toLowerCase();
+	if (h === 'admin' || h.startsWith('admin.')) return 'admin';
+	// security.<root>（安全仪表盘/SOC 门户）API 面为 admin 受众（风险看板等 admin 路由），
+	// 与 admin 门户同平面（GATEWAY-ENTRY-ISOLATION-DESIGN §3.2/§4.4）。
+	if (h === 'security' || h.startsWith('security.')) return 'admin';
+	if (h === 'platform' || h.startsWith('platform.')) return 'platform';
+	return null;
+}
+
+/**
+ * 授权流下钻：同意页冷启动时（无会话），登录页的 redirect 参数是 authorize URL 本身
+ * （`<slug>/login?redirect=<authorize URL>`，oauth-cold-start/TASK-07），其宿主是 auth
+ * 门户 ⇒ 宿主判定为空。发起门户嵌在其查询参数里：`redirect_uri`（发起方回调，宿主即
+ * 门户）或 `state.redirect`（发起页 URL，见 oauth-login state 载荷）。不下钻则回程
+ * 门户拿到的 token 平面恒为 api，admin/platform 受众端点全部 403 40000503（F-W5）。
+ */
+function planeFromAuthorizeRequest(url: URL): EntryPlane | null {
+	if (!url.pathname.includes('/oauth/authorize')) return null;
+	const candidates: Array<string | null> = [url.searchParams.get('redirect_uri')];
+	try {
+		const state = JSON.parse(url.searchParams.get('state') || '');
+		if (state && typeof state.redirect === 'string') candidates.push(state.redirect);
+	} catch {
+		// state 非 JSON（旧式纯串）→ 唯一候选 redirect_uri
+	}
+	for (const candidate of candidates) {
+		if (!candidate) continue;
+		try {
+			const plane = planeFromHostname(new URL(candidate, url.origin).hostname);
+			if (plane) return plane;
+		} catch {
+			// 单个候选非法不阻断后续候选
+		}
+	}
+	return null;
+}
+
+/** 由登录页 redirect 参数目标（或当前主机）推导入口平面，无法判定时缺省 api。 */
+export function resolveEntryPlane(redirect: string | null, currentHostname: string): EntryPlane {
+	if (redirect) {
+		try {
+			const url = new URL(redirect, `https://${currentHostname || 'localhost'}`);
+			const fromTarget = planeFromHostname(url.hostname) ?? planeFromAuthorizeRequest(url);
+			if (fromTarget) return fromTarget;
+		} catch {
+			// redirect 非法时回落当前主机判定
+		}
+	}
+	return planeFromHostname(currentHostname) ?? 'api';
+}

package/src/api/trace.ts

@@ -0,0 +1,21 @@
+const traceparentProviders: Array<() => string | undefined> = [];
+
+export function setTraceParentProvider(provider: () => string | undefined): void {
+	traceparentProviders.push(provider);
+}
+
+export function getTraceParentHeader(): string | undefined {
+	for (const provider of traceparentProviders) {
+		const tp = provider();
+		if (tp) return tp;
+	}
+	return undefined;
+}
+
+export function resetSessionTraceId(): void {
+	// trace ID is managed by the OTel bridge
+}
+
+export function enableOtelBridge(): void {
+	// No-op stub — requires @opentelemetry/api dependency
+}

package/src/auth/__tests__/ac007-role-source.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { useAuthStore, getCurrentRole } from '../store';
+
+// 注：node 测试环境下 zustand persist 中间件会打印一条无害的 storage 降级警告
+// （"Unable to update item 'authms-auth-v1'"），这是 store.ts 既有 persist 的
+// 标准降级行为，不影响被测的 getCurrentRole 派生逻辑。
+
+const TENANTS = [
+	{ id: 'tenant-a', name: 'Tenant A', role: 'admin' },
+	{ id: 'tenant-b', name: 'Tenant B', role: 'member' },
+];
+
+/**
+ * 构造最小 JWT（base64url header.payload.signature）。
+ * 仅用于测试「前端不再读取 token 载荷」——getCurrentRole 只读 store，
+ * 因此 signature 内容无关紧要。
+ */
+function buildJwt(payload: Record<string, unknown>): string {
+	const enc = (obj: unknown) =>
+		btoa(JSON.stringify(obj)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+	return `${enc({ alg: 'none', typ: 'JWT' })}.${enc(payload)}.test-signature`;
+}
+
+/** 重置 store 到初始状态，避免跨用例污染 */
+function resetAuthStore(): void {
+	useAuthStore.setState({
+		user: null,
+		accessToken: null,
+		refreshToken: null,
+		tenants: [],
+		currentTenantId: null,
+		permissions: [],
+		isAuthenticated: false,
+	});
+}
+
+describe('AC-007 密码/OAuth 双路径行为一致（userinfo-first，角色来自 store）', () => {
+	beforeEach(() => {
+		resetAuthStore();
+	});
+
+	it('密码场景：token 带 custom.role 但前端不读 → 返回 store 角色', () => {
+		// 密码登录 token 载荷带 custom.role（旧解析来源），但前端已不再读取
+		const passwordToken = buildJwt({
+			sub: 'user-1',
+			custom: { role: 'super_admin', username: 'pw-user' },
+		});
+
+		// 角色真正来源：loadAuthExtras 写入的 store
+		useAuthStore.setState({
+			accessToken: passwordToken,
+			tenants: TENANTS,
+			currentTenantId: 'tenant-a',
+		});
+
+		// 若前端仍解析 token 会得到 super_admin；正确行为是返回 store 角色 admin
+		expect(getCurrentRole()).toBe('admin');
+	});
+
+	it('OAuth 场景：token 无 role + 相同 store → 结果与密码场景一致', () => {
+		// OAuth/挂载路径 token 载荷无 role（旧解析无角色来源）
+		const oauthToken = buildJwt({ sub: 'user-1' });
+
+		useAuthStore.setState({
+			accessToken: oauthToken,
+			tenants: TENANTS,
+			currentTenantId: 'tenant-a',
+		});
+
+		expect(getCurrentRole()).toBe('admin');
+	});
+
+	it('双路径矩阵：两场景结果相等（store 预填充为唯一角色来源）', () => {
+		const passwordToken = buildJwt({
+			sub: 'user-1',
+			custom: { role: 'super_admin', username: 'pw-user' },
+		});
+		const oauthToken = buildJwt({ sub: 'user-1' });
+
+		// 相同 store 预填充
+		useAuthStore.setState({
+			accessToken: passwordToken,
+			tenants: TENANTS,
+			currentTenantId: 'tenant-a',
+		});
+		const roleFromPassword = getCurrentRole();
+
+		useAuthStore.setState({
+			accessToken: oauthToken,
+			tenants: TENANTS,
+			currentTenantId: 'tenant-a',
+		});
+		const roleFromOAuth = getCurrentRole();
+
+		expect(roleFromPassword).toBe(roleFromOAuth);
+		expect(roleFromPassword).toBe('admin');
+		expect(roleFromOAuth).toBe('admin');
+	});
+
+	it('token 携带不同 custom.role 时 store 角色仍胜出（证明零 token 载荷读取）', () => {
+		const adminToken = buildJwt({
+			sub: 'user-1',
+			custom: { role: 'super_admin' },
+		});
+		const memberToken = buildJwt({
+			sub: 'user-1',
+			custom: { role: 'member' },
+		});
+
+		useAuthStore.setState({
+			accessToken: adminToken,
+			tenants: TENANTS,
+			currentTenantId: 'tenant-a',
+		});
+		expect(getCurrentRole()).toBe('admin'); // store 角色，非 token 的 super_admin
+
+		useAuthStore.setState({
+			accessToken: memberToken,
+			tenants: TENANTS,
+			currentTenantId: 'tenant-a',
+		});
+		expect(getCurrentRole()).toBe('admin'); // token role 变化不影响 store 派生
+	});
+});