@autional-cn/shared 0.1.0-rc.3 → 0.1.0-rc.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autional-cn/shared",
-  "version": "0.1.0-rc.3",
+  "version": "0.1.0-rc.4",
   "description": "Autional shared layer — API client, auth, types, hooks, utils",
   "license": "AGPL-3.0",
   "main": "./src/index.ts",
@@ -31,10 +31,15 @@
     "zustand": "5.0.13"
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/react": "16.3.2",
+    "jsdom": "29.1.1",
     "react": "19.2.5",
     "react-dom": "19.2.5",
     "typescript": "5.8.3",
-    "vitest": "3.2.0"
+    "vite": "6.4.2",
+    "vitest": "3.2.0",
+    "@autional-cn/tsconfig": "0.1.0-rc"
   },
   "peerDependencies": {
     "react": ">=18.0.0",

package/src/auth/__tests__/auth-trace.test.ts

@@ -0,0 +1,237 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// ============================================================
+// authTrace 三层回归锁（#48）
+//  ① interstitial：被动跳转 → 提示条（可停留），延迟后 replace
+//  ② debug=auth → 确认页（不自动跳，手动继续/留）
+//  ③ 结构化日志：环形缓冲 / 凭据剥离 / ?rt= 跨站面包屑 / dump()
+// ============================================================
+
+const replaceSpy = vi.fn();
+let assignCalls: string[] = [];
+let currentHref = '';
+const originalLocationDescriptor = Object.getOwnPropertyDescriptor(window, 'location');
+
+// 只替换 window.location（不动 window 本体 —— stubGlobal 会连 localStorage/sessionStorage
+// 一起遮蔽）。字段给纯值 + href getter/setter，绕开 jsdom Location brand check。
+function mockWindowLocation(pathname: string, search = ''): void {
+	currentHref = `https://user.autional.local${pathname}${search}`;
+	Object.defineProperty(window, 'location', {
+		configurable: true,
+		value: {
+			pathname,
+			search,
+			origin: 'https://user.autional.local',
+			hostname: 'user.autional.local',
+			protocol: 'https:',
+			replace: replaceSpy,
+			get href() {
+				return currentHref;
+			},
+			set href(v: string) {
+				assignCalls.push(v);
+			},
+		},
+	});
+}
+
+/** 每例取全新模块实例：清 initialized / pending / buffer 模块态。 */
+async function freshTrace() {
+	vi.resetModules();
+	return await import('../auth-trace');
+}
+
+function notice(): HTMLElement | null {
+	return document.getElementById('auth-trace-notice');
+}
+function confirm(): HTMLElement | null {
+	return document.getElementById('auth-trace-confirm');
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	assignCalls = [];
+	sessionStorage.clear();
+	document.body.innerHTML = '';
+	document.documentElement.lang = 'zh-CN';
+});
+
+afterEach(() => {
+	if (originalLocationDescriptor) {
+		Object.defineProperty(window, 'location', originalLocationDescriptor);
+	}
+	document.body.innerHTML = '';
+	vi.useRealTimers();
+});
+
+describe('层 ③ 结构化日志与缓冲', () => {
+	it('traceEvent 写入环形缓冲，50 条封顶（丢最旧）', async () => {
+		mockWindowLocation('/demo/');
+		const { traceEvent, traceDump } = await freshTrace();
+		for (let i = 0; i < 55; i++) traceEvent('evt', { reason: `r${i}` });
+		const entries = (window as any).__authTrace.entries() as any[];
+		expect(entries).toHaveLength(50);
+		expect(entries[0].reason).toBe('r5');
+		expect(entries[49].reason).toBe('r54');
+		expect(traceDump()).toContain('r54');
+	});
+
+	it('缓冲中的 URL 剥除凭据类 query（token/code/state 不入 trace）', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { traceRedirect } = await freshTrace();
+		traceRedirect(
+			'https://auth.autional.local/demo/login?redirect=x&access_token=SECRET&code=ABC123&state=st&ok=1',
+			{ reason: 'unauthenticated', kind: 'funnel' },
+		);
+		const entries = (window as any).__authTrace.entries() as any[];
+		const to = entries[entries.length - 1].to as string;
+		expect(to).not.toContain('SECRET');
+		expect(to).not.toContain('ABC123');
+		expect(to).not.toContain('state=');
+		expect(to).toContain('ok=1');
+	});
+
+	it('dump() 含环境摘要与条目', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { traceEvent, traceDump } = await freshTrace();
+		traceEvent('error-exit', { reason: 'session_expired' });
+		const dump = traceDump();
+		expect(dump).toContain('authTrace v1 @user');
+		expect(dump).toContain('error-exit');
+	});
+
+	it('?rt= 跨站面包屑：读取接续为 handoff 条目', async () => {
+		mockWindowLocation('/demo/login', '?rt=auth.unauthenticated.abc123&redirect=x');
+		const { traceDump } = await freshTrace();
+		const dump = traceDump();
+		expect(dump).toContain('handoff');
+		expect(dump).toContain('auth@');
+	});
+});
+
+describe('层 ① interstitial 提示与停留', () => {
+	it('被动跳转：先出提示条，延迟后 replace（URL 带 rt= 面包屑）', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { traceRedirect } = await freshTrace();
+		vi.useFakeTimers();
+
+		traceRedirect('https://auth.autional.local/demo/login?redirect=x', {
+			reason: 'session-expired',
+			kind: 'interstitial',
+		});
+
+		expect(replaceSpy).not.toHaveBeenCalled();
+		expect(notice()).not.toBeNull();
+		expect(notice()!.textContent).toContain('会话已过期');
+
+		vi.advanceTimersByTime(1600);
+		expect(notice()).toBeNull();
+		expect(replaceSpy).toHaveBeenCalledTimes(1);
+		expect(String(replaceSpy.mock.calls[0][0])).toContain('rt=user.session-expired.');
+	});
+
+	it('点「停留」：取消跳转 + pending 复位（后续 funnel 照常执行）', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { traceRedirect } = await freshTrace();
+		vi.useFakeTimers();
+
+		traceRedirect('https://auth.autional.local/demo/login?redirect=x', {
+			reason: 'session-expired',
+			kind: 'interstitial',
+		});
+		const stayBtn = Array.from(notice()!.querySelectorAll('button')).find((b) =>
+			b.textContent!.includes('停留'),
+		)!;
+		stayBtn.click();
+
+		expect(notice()).toBeNull();
+		vi.advanceTimersByTime(5000);
+		expect(replaceSpy).not.toHaveBeenCalled();
+
+		// pending 已复位：funnel 直跳不受阻
+		traceRedirect('https://brand.autional.local/?redirect=x', { reason: 'funnel-slug', kind: 'funnel' });
+		expect(replaceSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it('pending 抑制：提示条未决时再来一次 interstitial 被记为 suppressed', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { traceRedirect } = await freshTrace();
+		vi.useFakeTimers();
+
+		traceRedirect('https://auth.autional.local/demo/login', { reason: 'unauthenticated', kind: 'interstitial' });
+		traceRedirect('https://auth.autional.local/other/login', { reason: 'unauthenticated', kind: 'interstitial' });
+
+		const entries = (window as any).__authTrace.entries() as any[];
+		expect(entries.filter((e) => e.ev === 'suppressed')).toHaveLength(1);
+		vi.advanceTimersByTime(1600);
+		expect(replaceSpy).toHaveBeenCalledTimes(1);
+		expect(String(replaceSpy.mock.calls[0][0])).toContain('/demo/login');
+	});
+
+	it('funnel（缺省 kind）：静默直跳，不出现提示条', async () => {
+		mockWindowLocation('/');
+		const { traceRedirect } = await freshTrace();
+		traceRedirect('https://brand.autional.local/?redirect=x', { reason: 'funnel-brand' });
+		expect(notice()).toBeNull();
+		expect(replaceSpy).toHaveBeenCalledTimes(1);
+	});
+});
+
+describe('层 ② debug 确认页', () => {
+	it('?debug=auth：不自动跳，确认页出现；点「继续前往」才 replace', async () => {
+		mockWindowLocation('/demo/dashboard', '?debug=auth');
+		const { traceRedirect } = await freshTrace();
+		traceRedirect('https://auth.autional.local/demo/login?redirect=x', {
+			reason: 'session-expired',
+			kind: 'interstitial',
+		});
+
+		expect(replaceSpy).not.toHaveBeenCalled();
+		expect(confirm()).not.toBeNull();
+		expect(confirm()!.textContent).toContain('整页跳转确认');
+
+		const goBtn = Array.from(confirm()!.querySelectorAll('button')).find((b) =>
+			b.textContent!.includes('继续前往'),
+		)!;
+		goBtn.click();
+		expect(replaceSpy).toHaveBeenCalledTimes(1);
+		expect(String(replaceSpy.mock.calls[0][0])).toContain('debug=auth');
+	});
+
+	it('确认页点「留在本页」：不跳 + pending 复位', async () => {
+		mockWindowLocation('/demo/dashboard', '?debug=auth');
+		const { traceRedirect } = await freshTrace();
+		traceRedirect('https://auth.autional.local/demo/login', { reason: 'unauthenticated', kind: 'funnel' });
+
+		const stayBtn = Array.from(confirm()!.querySelectorAll('button')).find((b) =>
+			b.textContent!.includes('留在本页'),
+		)!;
+		stayBtn.click();
+		expect(confirm()).toBeNull();
+		expect(replaceSpy).not.toHaveBeenCalled();
+	});
+
+	it('debug 标志经 sessionStorage 保持并随跳转透传（无需每次带 ?debug=auth）', async () => {
+		mockWindowLocation('/demo/');
+		const { traceRedirect } = await freshTrace();
+		(window as any).__authTrace.on();
+
+		traceRedirect('https://auth.autional.local/demo/login', { reason: 'unauthenticated' });
+		expect(confirm()).not.toBeNull();
+		const goBtn = Array.from(confirm()!.querySelectorAll('button')).find((b) =>
+			b.textContent!.includes('继续前往'),
+		)!;
+		goBtn.click();
+		expect(String(replaceSpy.mock.calls[0][0])).toContain('debug=auth');
+	});
+
+	it('assign 语义：opts.assign=true 走 location.href（登录/登出链保持新增历史）', async () => {
+		mockWindowLocation('/demo/');
+		const { traceRedirect } = await freshTrace();
+		traceRedirect('https://auth.autional.local/?logout=1', { reason: 'logout', assign: true });
+		expect(replaceSpy).not.toHaveBeenCalled();
+		expect(assignCalls).toHaveLength(1);
+		expect(assignCalls[0]).toContain('logout=1');
+	});
+});

package/src/auth/__tests__/build-login-url.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { buildLoginUrl, buildLogoutUrl } from '../roles';
+import { buildLoginUrl, buildLogoutUrl, isAuthLoginSurface } from '../roles';
 
 const MOCK_CONFIG = {
 	VITE_PORTAL_CONFIG: {
@@ -217,3 +217,43 @@ describe('buildLoginUrl', () => {
 		});
 	});
 });
+
+// ============================================================
+// F-W8b 修复②：登录承接面判定（onUnauthorized 抑制整页弹走的判据）
+//  承接面（只清理不导航）：`/`、`/login`、`/<slug>/login`、`/error`
+//  非承接面（照常弹登录页）：应用页、PKCE 发起页、其它静态路由
+// ============================================================
+function mockPathname(pathname: string): void {
+	vi.stubGlobal('window', {
+		location: { pathname, hostname: 'auth.autional.local', protocol: 'https:' },
+		__APP_CONFIG__: MOCK_CONFIG,
+	});
+}
+
+describe('isAuthLoginSurface', () => {
+	beforeEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it.each([
+		['裸根入口', '/', true],
+		['/login 入口', '/login', true],
+		['错误页', '/error', true],
+		['租户登录页', '/demo/login', true],
+		['带尾斜杠的租户登录页', '/demo/login/', true],
+		['应用页 dashboard', '/demo/dashboard', false],
+		['租户 index（守卫跳转页）', '/demo', false],
+		['裸 dashboard', '/dashboard', false],
+		['PKCE 发起页', '/oauth/api/v1/oauth/authorize', false],
+		['重置密码页', '/reset-password', false],
+		['注册页', '/demo/register', false],
+	])('%s（%s）→ %s', (_name, pathname, expected) => {
+		mockPathname(pathname as string);
+		expect(isAuthLoginSurface()).toBe(expected);
+	});
+
+	it('服务端渲染（无 window）→ false，不抑制', () => {
+		vi.stubGlobal('window', undefined);
+		expect(isAuthLoginSurface()).toBe(false);
+	});
+});

package/src/auth/__tests__/session-terminal-redirect.test.ts

@@ -0,0 +1,138 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// ============================================================
+// F-W8b 修复②：会话终结（onUnauthorized）与刷新失败处置的整链回归锁
+//  - 已在 auth 登录承接面（`/<slug>/login`、`/error`、裸根入口）→ 只清会话，
+//    不整页弹走（否则 buildLoginUrl 防嵌套截断会丢掉 URL 中的 redirect 回程目标，
+//    且构成一次整页闪烁 —— 存量过期 token 在登录页「静默弹走」）
+//  - 非承接面 → 照常清理 + 整页弹登录页（带 slug 与回程 redirect）
+//  - refreshToken onFailure：'clear' 只清理不导航；'none' 零副作用；缺省 'redirect'
+// ============================================================
+
+const { mockPost } = vi.hoisted(() => ({ mockPost: vi.fn() }));
+
+vi.mock('axios', () => ({ default: { post: mockPost } }));
+vi.mock('../../api/bff-client', () => ({ bffLogout: vi.fn(() => Promise.resolve()) }));
+
+const replaceSpy = vi.fn();
+const originalLocationDescriptor = Object.getOwnPropertyDescriptor(window, 'location');
+
+// 只替换 window.location（不动 window 本体 —— stubGlobal 会连 localStorage 一起遮蔽，
+// zustand persist 在 setState 时崩）。字段给纯值，绕开 jsdom Location 的 brand check。
+function mockWindowLocation(pathname: string): void {
+	Object.defineProperty(window, 'location', {
+		configurable: true,
+		value: {
+			pathname,
+			href: `https://auth.autional.local${pathname}`,
+			origin: 'https://auth.autional.local',
+			hostname: 'auth.autional.local',
+			protocol: 'https:',
+			replace: replaceSpy,
+		},
+	});
+	(window as any).__APP_CONFIG__ = { VITE_PORTAL_CONFIG: { auth: { host: 'auth', base: '' } } };
+}
+
+/** 剥除 authTrace 面包屑（rt=）后比较；rt 装饰本身由 toMatch 锁定。 */
+function withoutRt(url: string): string {
+	const u = new URL(url);
+	u.searchParams.delete('rt');
+	return u.toString();
+}
+
+/** 每例取全新模块实例：清零 service.ts 的模块级重入锁（redirectingToLogin）。 */
+async function freshService() {
+	vi.resetModules();
+	const svc = await import('../service');
+	const store = await import('../store');
+	return { AuthService: svc.AuthService, useAuthStore: store.useAuthStore };
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	localStorage.clear();
+});
+
+afterEach(() => {
+	if (originalLocationDescriptor) {
+		Object.defineProperty(window, 'location', originalLocationDescriptor);
+	}
+	delete (window as any).__APP_CONFIG__;
+	vi.useRealTimers();
+});
+
+describe('onUnauthorized 承接面抑制（F-W8b 修复②）', () => {
+	it('已在 /<slug>/login：清理会话但不整页弹走（回程 redirect 不丢）', async () => {
+		mockWindowLocation('/demo/login');
+		const { AuthService, useAuthStore } = await freshService();
+		useAuthStore.setState({ accessToken: 'at-old', refreshToken: 'rt-old', isAuthenticated: true });
+
+		AuthService.onUnauthorized();
+
+		expect(useAuthStore.getState().accessToken).toBeNull();
+		expect(useAuthStore.getState().isAuthenticated).toBe(false);
+		expect(replaceSpy).not.toHaveBeenCalled();
+	});
+
+	it('已在 /error：同样只清理不弹走（错误页有自身倒计时出口）', async () => {
+		mockWindowLocation('/error');
+		const { AuthService, useAuthStore } = await freshService();
+		useAuthStore.setState({ accessToken: 'at-old', refreshToken: 'rt-old', isAuthenticated: true });
+
+		AuthService.onUnauthorized();
+
+		expect(useAuthStore.getState().accessToken).toBeNull();
+		expect(replaceSpy).not.toHaveBeenCalled();
+	});
+
+	it('非承接面 /demo/dashboard：清理 + 整页弹登录页（带 slug 与回程 redirect）', async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { AuthService, useAuthStore } = await freshService();
+		useAuthStore.setState({ accessToken: 'at-old', refreshToken: 'rt-old', isAuthenticated: true });
+
+		vi.useFakeTimers();
+		AuthService.onUnauthorized();
+		vi.runAllTimers();
+
+		expect(useAuthStore.getState().accessToken).toBeNull();
+		expect(replaceSpy).toHaveBeenCalledTimes(1);
+		const url = String(replaceSpy.mock.calls[0][0]);
+		expect(url).toMatch(/[?&]rt=auth\.session-expired\.[0-9a-z]+$/);
+		expect(withoutRt(url)).toBe(
+			'https://auth.autional.local/demo/login?redirect=' +
+				encodeURIComponent('https://auth.autional.local/demo/dashboard') +
+				'&from_requireauth=1',
+		);
+	});
+});
+
+describe('refreshToken onFailure 处置', () => {
+	it("'clear'：刷新失败只清理会话，不做任何导航（导航权交调用方）", async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { AuthService, useAuthStore } = await freshService();
+		useAuthStore.setState({ accessToken: 'at-old', refreshToken: 'rt-opaque-1', isAuthenticated: true });
+		mockPost.mockRejectedValue(new Error('refresh rejected'));
+
+		const at = await AuthService.refreshToken({ onFailure: 'clear' });
+
+		expect(at).toBeNull();
+		expect(useAuthStore.getState().accessToken).toBeNull();
+		expect(replaceSpy).not.toHaveBeenCalled();
+	});
+
+	it("'none'：刷新失败零副作用（会话保留、不导航）", async () => {
+		mockWindowLocation('/demo/dashboard');
+		const { AuthService, useAuthStore } = await freshService();
+		useAuthStore.setState({ accessToken: 'at-old', refreshToken: 'rt-opaque-1', isAuthenticated: true });
+		mockPost.mockRejectedValue(new Error('refresh rejected'));
+
+		const at = await AuthService.refreshToken({ onFailure: 'none' });
+
+		expect(at).toBeNull();
+		expect(useAuthStore.getState().accessToken).toBe('at-old');
+		expect(useAuthStore.getState().isAuthenticated).toBe(true);
+		expect(replaceSpy).not.toHaveBeenCalled();
+	});
+});

package/src/auth/auth-trace.ts

@@ -0,0 +1,473 @@
+/**
+ * authTrace —— auth 整页跳转的统一出口与三层可观测（#48）。
+ *
+ * 三层：
+ *  ① interstitial 提示：**被动**整页跳转（会话终结 / 未认证深链）执行前显示提示条
+ *     （原因 + 目标 host + 停留 / 立即前往），短延迟后自动前往。「停留」取消本次跳转；
+ *     页面数据面虽已失效，但用户知情（消除「静默弹走」）。
+ *  ② confirm 确认页：`?debug=auth`（或 __authTrace.on()）时所有整页跳转不自动执行，
+ *     停在遮罩确认页（跳转详情 + 最近 trace 列表 + 继续 / 留）。debug 标志随跳转
+ *     跨站透传，排障可全程跟随。
+ *  ③ 结构化日志：`[auth-trace]` console 行 + sessionStorage 环形缓冲（跨 SPA 路由、
+ *     同 tab 存活）+ `?rt=` 跨站面包屑（目标 URL 追加，下游站读取接续）+
+ *     `__authTrace.dump()` 一键导出（排障取证）。
+ *
+ * kind 语义（提示层的适用面）：
+ *  - 'interstitial'：被动跳转（会话终结 / buildLoginUrl 弹登录）→ 提示 + 延迟（可停留）。
+ *  - 'funnel'（缺省）：预期漏斗（裸根 → brand / 登出 / OAuth 发起与回跳）→ 静默直跳，
+ *    仅记 trace（用户主动或流程本身的必经步骤，加延迟只拖慢）。
+ *  - debug 模式不分 kind，一律确认页。
+ *
+ * 隐私红线：缓冲与面包屑中的 URL 一律剥除凭据类 query（token/code/state 等），
+ * 不落任何 PII。模块零依赖（不 import React / 各站设施），显式调用即用。
+ */
+
+const BUFFER_KEY = 'auth-trace-v1';
+const DEBUG_KEY = 'auth-trace-debug';
+const RT_PARAM = 'rt';
+const DEBUG_PARAM = 'debug';
+const DEBUG_VALUE = 'auth';
+const BUFFER_LIMIT = 50;
+const INTERSTITIAL_DELAY_MS = 1500;
+const Z_INDEX = '2147483000';
+
+/** URL query 中不得进入 trace 缓冲的凭据类键（前缀匹配）。 */
+const SENSITIVE_KEYS = ['token', 'access_token', 'refresh_token', 'id_token', 'code', 'state', 'secret', 'password'];
+
+export interface AuthTraceEntry {
+	/** epoch ms */
+	t: number;
+	/** 事件类型：redirect / handoff / stay / suppressed / error-exit / … */
+	ev: string;
+	reason?: string;
+	from?: string;
+	to?: string;
+}
+
+export interface AuthTraceRedirectOptions {
+	reason: string;
+	kind?: 'interstitial' | 'funnel';
+	/** true 用 location.href（新增历史），缺省 false 用 location.replace */
+	assign?: boolean;
+	/** 覆盖缺省延迟（ms），仅 interstitial 生效 */
+	delayMs?: number;
+}
+
+function isBrowser(): boolean {
+	return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+
+function station(): string {
+	if (!isBrowser()) return 'ssr';
+	return window.location.hostname.split('.')[0] || 'unknown';
+}
+
+function isZh(): boolean {
+	if (!isBrowser()) return false;
+	return (document.documentElement.lang || '').toLowerCase().startsWith('zh');
+}
+
+/** 剥除 URL 中的凭据类 query 参数（前缀命中 SENSITIVE_KEYS 即剥），保留其余。 */
+function sanitizeUrl(raw: string): string {
+	try {
+		const u = new URL(raw, isBrowser() ? window.location.origin : 'https://x.invalid');
+		for (const key of Array.from(u.searchParams.keys())) {
+			if (SENSITIVE_KEYS.some((s) => key.toLowerCase() === s || key.toLowerCase().startsWith(`${s}_`))) {
+				u.searchParams.delete(key);
+			}
+		}
+		return u.toString();
+	} catch {
+		return raw.split(/[?#]/)[0];
+	}
+}
+
+// ---------------------------------------------------------------- 缓冲（环形）
+
+let bufferLoaded = false;
+let buffer: AuthTraceEntry[] = [];
+
+function readBuffer(): AuthTraceEntry[] {
+	if (!isBrowser()) return [];
+	if (!bufferLoaded) {
+		bufferLoaded = true;
+		try {
+			const raw = sessionStorage.getItem(BUFFER_KEY);
+			const parsed = raw ? JSON.parse(raw) : [];
+			buffer = Array.isArray(parsed) ? parsed.slice(-BUFFER_LIMIT) : [];
+		} catch {
+			buffer = [];
+		}
+	}
+	return buffer;
+}
+
+function writeBuffer(): void {
+	if (!isBrowser()) return;
+	try {
+		sessionStorage.setItem(BUFFER_KEY, JSON.stringify(buffer.slice(-BUFFER_LIMIT)));
+	} catch {
+		// 存储受限（隐私模式 / 配额）时静默降级为仅 console
+	}
+}
+
+function push(ev: string, extra?: Partial<AuthTraceEntry>): AuthTraceEntry {
+	const entry: AuthTraceEntry = { t: Date.now(), ev, ...extra };
+	readBuffer().push(entry);
+	if (buffer.length > BUFFER_LIMIT) buffer = buffer.slice(-BUFFER_LIMIT);
+	writeBuffer();
+	if (isBrowser()) {
+		// eslint-disable-next-line no-console
+		console.info('[auth-trace]', entry.ev, entry.reason ?? '', entry.to ?? '');
+	}
+	return entry;
+}
+
+// ---------------------------------------------------------------- debug 与水印
+
+function readRTP(): string | null {
+	if (!isBrowser()) return null;
+	try {
+		return new URLSearchParams(window.location.search).get(RT_PARAM);
+	} catch {
+		return null;
+	}
+}
+
+function inDebug(): boolean {
+	if (!isBrowser()) return false;
+	try {
+		if (new URLSearchParams(window.location.search).get(DEBUG_PARAM) === DEBUG_VALUE) return true;
+		return sessionStorage.getItem(DEBUG_KEY) === '1';
+	} catch {
+		return false;
+	}
+}
+
+let initialized = false;
+
+/** 懒初始化：吸收跨站面包屑（?rt=）与 debug 标志；同 URL 重复调用无副作用。 */
+function ensureInit(): void {
+	if (!isBrowser() || initialized) return;
+	initialized = true;
+
+	let urlDebug = false;
+	try {
+		urlDebug = new URLSearchParams(window.location.search).get(DEBUG_PARAM) === DEBUG_VALUE;
+		if (urlDebug) sessionStorage.setItem(DEBUG_KEY, '1');
+	} catch {
+		/* noop */
+	}
+
+	const rt = readRTP();
+	if (rt) {
+		const [prevStation, prevReason, prevTs] = rt.split('.');
+		if (prevStation && prevReason) {
+			push('handoff', {
+				from: `${prevStation}@${prevTs ? parseInt(prevTs, 36) : ''}`,
+				reason: prevReason,
+			});
+		}
+	}
+
+	(window as any).__authTrace = {
+		version: 1,
+		dump: traceDump,
+		entries: () => readBuffer().slice(),
+		on: () => {
+			try {
+				sessionStorage.setItem(DEBUG_KEY, '1');
+			} catch {
+				/* noop */
+			}
+			return 'auth-trace debug ON（整页跳转将停在确认页；随跳转跨站透传）';
+		},
+		off: () => {
+			try {
+				sessionStorage.removeItem(DEBUG_KEY);
+			} catch {
+				/* noop */
+			}
+			return 'auth-trace debug OFF';
+		},
+	};
+
+	if (urlDebug || rt) {
+		// eslint-disable-next-line no-console
+		console.info('[auth-trace] station', station(), urlDebug ? '(debug=on)' : '', rt ? `(handoff from ${rt.split('.')[0]})` : '');
+	}
+}
+
+// ---------------------------------------------------------------- 目标 URL 装饰
+
+/** 目标 URL 追加 rt=（本站 + 原因 + 时间）与 debug 透传（debug 开启时）。 */
+function decorateTarget(target: string, reason: string): string {
+	if (!isBrowser()) return target;
+	try {
+		const u = new URL(target, window.location.origin);
+		if (!u.searchParams.has(RT_PARAM)) {
+			u.searchParams.set(RT_PARAM, `${station()}.${reason}.${Date.now().toString(36)}`);
+		}
+		if (inDebug() && !u.searchParams.has(DEBUG_PARAM)) {
+			u.searchParams.set(DEBUG_PARAM, DEBUG_VALUE);
+		}
+		return u.toString();
+	} catch {
+		return target;
+	}
+}
+
+// ---------------------------------------------------------------- 跳转执行
+
+let pending = false;
+
+function go(target: string, assign: boolean): void {
+	pending = true;
+	if (assign) window.location.href = target;
+	else window.location.replace(target);
+}
+
+function removeNode(id: string): void {
+	if (!isBrowser()) return;
+	const el = document.getElementById(id);
+	if (el && el.parentNode) el.parentNode.removeChild(el);
+}
+
+// ---------------------------------------------------------------- 层 ① 提示条
+
+const NOTICE_ID = 'auth-trace-notice';
+
+function reasonText(reason: string): { zh: string; en: string } {
+	const map: Record<string, { zh: string; en: string }> = {
+		'session-expired': { zh: '会话已过期', en: 'Session expired' },
+		unauthenticated: { zh: '需要登录', en: 'Sign-in required' },
+	};
+	return map[reason] ?? { zh: '即将离开本页', en: 'Leaving this page' };
+}
+
+function showInterstitial(target: string, opts: AuthTraceRedirectOptions, onStay: () => void): void {
+	const zh = isZh();
+	const text = reasonText(opts.reason);
+	const delay = opts.delayMs ?? INTERSTITIAL_DELAY_MS;
+
+	removeNode(NOTICE_ID);
+	const box = document.createElement('div');
+	box.id = NOTICE_ID;
+	box.setAttribute('role', 'status');
+	box.style.cssText = [
+		'position:fixed',
+		'left:50%',
+		'bottom:24px',
+		'transform:translateX(-50%)',
+		`z-index:${Z_INDEX}`,
+		'display:flex',
+		'align-items:center',
+		'gap:12px',
+		'max-width:calc(100vw - 32px)',
+		'padding:10px 14px',
+		'border-radius:8px',
+		'background:rgba(17,24,39,.94)',
+		'color:#f9fafb',
+		'font-size:13px',
+		'line-height:1.4',
+		'font-family:system-ui,-apple-system,sans-serif',
+		'box-shadow:0 8px 24px rgba(0,0,0,.28)',
+	].join(';');
+
+	const label = document.createElement('span');
+	label.textContent = zh
+		? `${text.zh}，即将前往登录（${delay / 1000} 秒后自动跳转）`
+		: `${text.en} — redirecting to sign-in in ${delay / 1000}s`;
+	box.appendChild(label);
+
+	const mkButton = (txt: string, primary: boolean, onClick: () => void) => {
+		const b = document.createElement('button');
+		b.type = 'button';
+		b.textContent = txt;
+		b.style.cssText = [
+			'border:0',
+			'border-radius:6px',
+			'padding:5px 10px',
+			'font-size:13px',
+			'cursor:pointer',
+			primary ? 'background:#2563eb;color:#fff' : 'background:rgba(255,255,255,.14);color:#f9fafb',
+		].join(';');
+		b.addEventListener('click', onClick);
+		return b;
+	};
+
+	const timer = setTimeout(() => {
+		removeNode(NOTICE_ID);
+		go(target, !!opts.assign);
+	}, delay);
+
+	box.appendChild(mkButton(zh ? '停留' : 'Stay', false, () => {
+		clearTimeout(timer);
+		removeNode(NOTICE_ID);
+		onStay();
+	}));
+	box.appendChild(mkButton(zh ? '立即前往' : 'Go now', true, () => {
+		clearTimeout(timer);
+		removeNode(NOTICE_ID);
+		go(target, !!opts.assign);
+	}));
+
+	document.body.appendChild(box);
+}
+
+// ---------------------------------------------------------------- 层 ② 确认页
+
+const CONFIRM_ID = 'auth-trace-confirm';
+
+function showConfirm(target: string, opts: AuthTraceRedirectOptions, onStay: () => void): void {
+	const zh = isZh();
+	removeNode(CONFIRM_ID);
+
+	const overlay = document.createElement('div');
+	overlay.id = CONFIRM_ID;
+	overlay.style.cssText = [
+		'position:fixed',
+		'inset:0',
+		`z-index:${Z_INDEX}`,
+		'display:flex',
+		'align-items:center',
+		'justify-content:center',
+		'background:rgba(15,23,42,.55)',
+		'font-family:system-ui,-apple-system,sans-serif',
+	].join(';');
+
+	const card = document.createElement('div');
+	card.style.cssText = [
+		'width:min(560px,calc(100vw - 40px))',
+		'max-height:80vh',
+		'overflow:auto',
+		'background:#fff',
+		'color:#111827',
+		'border-radius:10px',
+		'padding:18px 20px',
+		'box-shadow:0 20px 48px rgba(0,0,0,.32)',
+		'font-size:13px',
+	].join(';');
+
+	const title = document.createElement('h2');
+	title.textContent = zh ? '整页跳转确认（authTrace debug）' : 'Full-page redirect (authTrace debug)';
+	title.style.cssText = 'margin:0 0 10px;font-size:15px;font-weight:600';
+	card.appendChild(title);
+
+	const detail = document.createElement('pre');
+	detail.textContent = [
+		`reason: ${opts.reason}`,
+		`kind:   ${opts.kind ?? 'funnel'}`,
+		`from:   ${sanitizeUrl(window.location.href)}`,
+		`to:     ${target}`,
+		'',
+		...(readBuffer().slice(-10).map((e) => `${new Date(e.t).toISOString()}  ${e.ev}  ${e.reason ?? ''}  ${e.to ?? e.from ?? ''}`)),
+	].join('\n');
+	detail.style.cssText = [
+		'margin:0 0 14px',
+		'padding:10px',
+		'border-radius:6px',
+		'background:#f3f4f6',
+		'white-space:pre-wrap',
+		'word-break:break-all',
+		'font-size:12px',
+		'line-height:1.5',
+		'max-height:46vh',
+		'overflow:auto',
+	].join(';');
+	card.appendChild(detail);
+
+	const mkButton = (txt: string, primary: boolean, onClick: () => void) => {
+		const b = document.createElement('button');
+		b.type = 'button';
+		b.textContent = txt;
+		b.style.cssText = [
+			primary ? 'background:#2563eb;color:#fff' : 'background:#e5e7eb;color:#111827',
+			'border:0',
+			'border-radius:6px',
+			'padding:7px 14px',
+			'font-size:13px',
+			'cursor:pointer',
+			'margin-right:8px',
+		].join(';');
+		b.addEventListener('click', onClick);
+		return b;
+	};
+
+	card.appendChild(mkButton(zh ? '继续前往' : 'Continue', true, () => {
+		removeNode(CONFIRM_ID);
+		go(target, !!opts.assign);
+	}));
+	card.appendChild(mkButton(zh ? '留在本页' : 'Stay', false, () => {
+		removeNode(CONFIRM_ID);
+		onStay();
+	}));
+
+	overlay.appendChild(card);
+	document.body.appendChild(overlay);
+}
+
+// ---------------------------------------------------------------- 公开 API
+
+/**
+ * 统一整页跳转出口：记 trace →（debug 时）确认页 →（interstitial 时）提示条 →
+ * 执行 location.replace/href。
+ *
+ * 重入语义：pending 期间新的 interstitial 请求被抑制（记 suppressed，防双提示/双跳）；
+ * funnel 请求不被抑制（用户主动 / 流程必经，优先且覆盖 pending）。
+ */
+export function traceRedirect(target: string, opts: AuthTraceRedirectOptions): void {
+	if (!isBrowser()) return;
+	ensureInit();
+	const kind = opts.kind ?? 'funnel';
+	const decorated = decorateTarget(target, opts.reason);
+	const from = sanitizeUrl(window.location.href);
+
+	if (pending && kind === 'interstitial') {
+		push('suppressed', { reason: opts.reason, from, to: sanitizeUrl(decorated) });
+		return;
+	}
+
+	push('redirect', { reason: opts.reason, from, to: sanitizeUrl(decorated) });
+
+	const onStay = () => {
+		pending = false;
+		push('stay', { reason: opts.reason, from, to: sanitizeUrl(decorated) });
+	};
+
+	if (inDebug()) {
+		pending = true;
+		showConfirm(decorated, opts, onStay);
+		return;
+	}
+
+	if (kind === 'interstitial') {
+		pending = true;
+		showInterstitial(decorated, opts, onStay);
+		return;
+	}
+
+	go(decorated, !!opts.assign);
+}
+
+/** 记一条非跳转 trace 事件（如 error 页出口、OAuth 链路里程碑）。 */
+export function traceEvent(ev: string, extra?: { reason?: string; from?: string; to?: string }): void {
+	if (!isBrowser()) return;
+	ensureInit();
+	push(ev, extra);
+}
+
+/** 导出全部缓冲 + 环境摘要（`copy(__authTrace.dump())` 取证用）。 */
+export function traceDump(): string {
+	if (!isBrowser()) return '';
+	ensureInit();
+	const header = [
+		`authTrace v1 @${station()}`,
+		`url: ${sanitizeUrl(window.location.href)}`,
+		`debug: ${inDebug() ? 'on' : 'off'}`,
+		`ua: ${navigator.userAgent}`,
+		`entries: ${readBuffer().length}`,
+	];
+	const lines = readBuffer().map((e) => `${new Date(e.t).toISOString()}  ${e.ev}  ${e.reason ?? ''}  ${e.to ?? e.from ?? ''}`);
+	return [...header, '', ...lines].join('\n');
+}

package/src/auth/oauth-login.ts

@@ -14,6 +14,7 @@ import { AuthService } from './service';
 import { generatePKCE } from './pkce';
 import { getPortalUrl } from '../config';
 import { persistOAuthClientId } from './oauth-client-id-store';
+import { traceRedirect } from './auth-trace';
 import type { User } from '../types';
 
 function getAppConfig(): Record<string, string> | undefined {
@@ -157,7 +158,13 @@ export async function initiateOAuthLogin(
 			code_challenge_method: 'S256',
 			state,
 		});
-		window.location.href = `${cfg.authorizeUrl}?${params}`;
+		// interstitial：未认证深链被动弹去登录 → authTrace 提示（可停留）；
+		// 「停留」取消后 10s 防重入窗口过期即失效，用户刷新/再次交互可重新发起。
+		traceRedirect(`${cfg.authorizeUrl}?${params}`, {
+			reason: 'oauth-initiate',
+			kind: 'interstitial',
+			assign: true,
+		});
 	} catch {
 		const params = new URLSearchParams({
 			response_type: 'code',
@@ -166,7 +173,11 @@ export async function initiateOAuthLogin(
 			scope: cfg.scope,
 			state,
 		});
-		window.location.href = `${cfg.authorizeUrl}?${params}`;
+		traceRedirect(`${cfg.authorizeUrl}?${params}`, {
+			reason: 'oauth-initiate',
+			kind: 'interstitial',
+			assign: true,
+		});
 	}
 }
 
@@ -287,5 +298,6 @@ export async function handleOAuthCallback(): Promise<void> {
 	}
 
 	// Full page navigation to the target (auth gateway will route to dashboard)
-	window.location.href = target;
+	// funnel：登录成功回跳（预期行为，静默直跳，assign 保持原语义）；仅记 trace。
+	traceRedirect(target, { reason: 'oauth-callback', assign: true });
 }

package/src/auth/roles.ts

@@ -51,6 +51,22 @@ export function buildLogoutUrl(returnUrl?: string): string {
 	return `${base}/?${redirect}logout=1`;
 }
 
+/**
+ * 当前页是否已是 auth 的「登录承接面」——裸根入口（`/`、`/login`，由入口路由承接）、
+ * `/<slug>/login` 登录页、`/error` 错误页。
+ *
+ * 会话终结（onUnauthorized）时若已停在承接面，整页 replace 不但无益（目标就是本页），
+ * 还会因 buildLoginUrl 的防嵌套截断返回不带 redirect 的本页 —— 把 URL 中的回程目标
+ * 一并丢掉，且构成一次整页闪烁（F-W8b 修复②：存量过期 token 在登录页「静默弹走」）。
+ */
+export function isAuthLoginSurface(): boolean {
+	if (typeof window === 'undefined') return false;
+	const segs = window.location.pathname.split('/').filter(Boolean);
+	if (segs.length === 0) return true; // 裸根 `/`
+	if (segs[0] === 'login' || segs[0] === 'error') return true; // `/login`、`/error`
+	return segs.length === 2 && segs[1] === 'login'; // `/<slug>/login`
+}
+
 export function buildLoginUrl(returnUrl?: string, fromRequireAuth?: boolean): string {
 	const base = getPortalUrl('auth');
 	if (!base) return '/';

package/src/auth/service.ts

@@ -23,13 +23,13 @@ import {
 	isTokenExpired as checkExpired,
 } from './store';
 import { loginWithTokens } from './store';
-import { buildLoginUrl } from './roles';
+import { buildLoginUrl, isAuthLoginSurface } from './roles';
+import { traceRedirect } from './auth-trace';
 import { resolveClientIdForSession } from './oauth-client-id-store';
 import type { User } from '../types';
 
 // ============ Internal State ============
 
-let redirectingToLogin = false;
 let refreshPromise: Promise<string | null> | null = null;
 
 // ============ OAuth PKCE Bootstrap Lock ============
@@ -259,19 +259,30 @@ export const AuthService = {
 	/**
 	 * 刷新 access token。
 	 * 防重入：同一时间只会有一个刷新请求进行中。
-	 * 刷新失败时自动调用 onUnauthorized。
+	 *
+	 * 失败处置（onFailure，缺省 'redirect'）：
+	 * - 'redirect'：onUnauthorized —— 清理 + 引导登录（常规路径）；
+	 * - 'clear'   ：clearSession —— 只清理不导航（调用方自控唯一导航出口，
+	 *               如会话过期横幅 → error 页，避免与整页跳转双跳竞争）；
+	 * - 'none'    ：零副作用静默（尽力续期场景：如过期前 5 分钟的自动续期尝试，
+	 *               失败不清理不打断——会话此刻仍有效，等真正过期再统一处置）。
 	 */
-	refreshToken: async (): Promise<string | null> => {
+	refreshToken: async (opts?: {
+		onFailure?: 'redirect' | 'clear' | 'none';
+	}): Promise<string | null> => {
 		if (refreshPromise) return refreshPromise;
+		const onFailure = opts?.onFailure ?? 'redirect';
+		const handleFailure = () => {
+			if (onFailure === 'redirect') AuthService.onUnauthorized();
+			else if (onFailure === 'clear') AuthService.clearSession();
+		};
 
 		refreshPromise = (async () => {
 			const rt = AuthService.getRefreshToken();
 			if (!rt) {
 				// During OAuth PKCE bootstrap (no token yet), suppress redirect.
 				// RequireAuth will handle OAuth PKCE vs BFF fallback once tenantRoute resolves.
-				if (!_bootstrapLocked) {
-					AuthService.onUnauthorized();
-				}
+				if (!_bootstrapLocked) handleFailure();
 				return null;
 			}
 
@@ -315,7 +326,7 @@ export const AuthService = {
 				return newAT || null;
 			} catch (err) {
 				console.warn('[AuthService] Token refresh failed', (err as Error)?.message || '');
-				AuthService.onUnauthorized();
+				handleFailure();
 				return null;
 			} finally {
 				refreshPromise = null;
@@ -328,14 +339,10 @@ export const AuthService = {
 	// ==================== 401/未授权处理 ====================
 
 	/**
-	 * 处理 401 未授权响应：
-	 * 1. 登出（清除所有状态）
-	 * 2. 重定向到登录页（防重入锁）
+	 * 仅清除会话状态（store + localStorage），不做任何导航。
+	 * 供 silent 刷新失败、以及需要自控导航出口的调用方使用。
 	 */
-	onUnauthorized: (): void => {
-		// Suppress redirect during OAuth PKCE bootstrap — RequireAuth handles it
-		if (_bootstrapLocked) return;
-		// 先清除状态，不等待 logout 的异步吊销
+	clearSession: (): void => {
 		useAuthStore.getState().clearAuth();
 		if (typeof window !== 'undefined') {
 			// 清除 localStorage（同步，立即生效）
@@ -343,12 +350,32 @@ export const AuthService = {
 			localStorage.removeItem('access_token');
 			localStorage.removeItem('refresh_token');
 		}
+	},
+
+	/**
+	 * 处理 401 未授权响应：
+	 * 1. 清除所有状态（clearSession）
+	 * 2. 经 authTrace 提示（会话已过期 → 即将前往登录，可停留）后整页弹登录页
+	 *
+	 * 例外：已在 auth 登录承接面（裸根入口 / `/<slug>/login` / `/error`）时只清理不导航 ——
+	 * 目标就是当前页，整页 replace 反而会丢掉 URL 里的 redirect 回程目标并造成闪烁
+	 * （F-W8b 修复②）；承接面页面对 401 有自己的收口（登录页落表单、error 页走倒计时）。
+	 *
+	 * 重入抑制在 authTrace 内（pending 单例；并发 401 只提示一次、只跳一次）。
+	 */
+	onUnauthorized: (): void => {
+		// Suppress redirect during OAuth PKCE bootstrap — RequireAuth handles it
+		if (_bootstrapLocked) return;
+		// 先清除状态，不等待 logout 的异步吊销
+		AuthService.clearSession();
 
-		if (!redirectingToLogin && typeof window !== 'undefined') {
-			redirectingToLogin = true;
-			setTimeout(() => {
-				window.location.replace(buildLoginUrl(window.location.href, true));
-			}, 0);
+		if (isAuthLoginSurface()) return;
+
+		if (typeof window !== 'undefined') {
+			traceRedirect(buildLoginUrl(window.location.href, true), {
+				reason: 'session-expired',
+				kind: 'interstitial',
+			});
 		}
 	},
 

package/src/components/RequireAuth.tsx

@@ -1,6 +1,7 @@
 import { useEffect } from 'react';
 import { AuthService, setBootstrapLock } from '../auth/service';
 import { buildLoginUrl } from '../auth/roles';
+import { traceRedirect } from '../auth/auth-trace';
 import { initiateOAuthLogin } from '../auth/oauth-login';
 import {
 	useTenantRoute,
@@ -103,8 +104,12 @@ export function RequireAuth({
 		// Cross-domain or no client: redirect to auth-pages login
 		// from_requireauth=1 与 service.ts 的 onUnauthorized 同口径：auth 侧据此先做会话复检
 		// （有会话直接回跳，避免「已登录还被要求再登一次」）
+		// interstitial：未认证深链被动弹登录 → authTrace 提示（可停留）；重入抑制在其内。
 		setTimeout(() => {
-			window.location.replace(buildLoginUrl(window.location.href, true));
+			traceRedirect(buildLoginUrl(window.location.href, true), {
+				reason: 'unauthenticated',
+				kind: 'interstitial',
+			});
 		}, 0);
 	}, [machine.status, tenantRoute]);
 

package/src/components/TenantRootRedirect.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useMemo } from 'react';
 import { useCurrentTenantId } from '../hooks/useAuth';
 import { getPortalUrl } from '../config';
+import { traceRedirect } from '../auth/auth-trace';
 import { usePublicTenantSlugs } from './TenantIndexGuard';
 
 /**
@@ -29,7 +30,7 @@ export function TenantRootRedirect() {
 		if (typeof window === 'undefined') return;
 		if (slug) {
 			const base = window.location.pathname.replace(/\/+$/, '');
-			window.location.replace(`${base}/${slug}/`);
+			traceRedirect(`${base}/${slug}/`, { reason: 'funnel-slug' });
 			return;
 		}
 		// 有会话但公开名单尚未返回：等待（名单是 slug 唯一权威，不得抢跑漏斗 brand）。
@@ -38,7 +39,7 @@ export function TenantRootRedirect() {
 		const target = `${getPortalUrl('brand')}/?redirect=${encodeURIComponent(
 			window.location.origin + window.location.pathname,
 		)}`;
-		window.location.replace(target);
+		traceRedirect(target, { reason: 'funnel-brand' });
 	}, [slug, currentTenantId, tenantsLoaded]);
 
 	return null;

package/src/components/__tests__/RequireAuth.test.tsx

@@ -55,8 +55,33 @@ import { getPortalUrl } from '../../config';
 
 const originalWindowLocation = window.location;
 
+/**
+ * 每例取全新模块实例：auth-trace 的模块级重入抑制（pending）与「停留」复位
+ * 是同页语义，跨用例泄漏会让后续 interstitial 被静默抑制（假红/假绿）。
+ */
+async function freshRequireAuth() {
+	vi.resetModules();
+	const mod = await import('../RequireAuth');
+	return mod.RequireAuth;
+}
+
+/** authTrace 的提示条/确认页挂在 document.body（非 React 树），手动清理防跨用例残留。 */
+function cleanupAuthTraceNodes() {
+	document.getElementById('auth-trace-notice')?.remove();
+	document.getElementById('auth-trace-confirm')?.remove();
+}
+
+function clickGoNow(): void {
+	const btn = Array.from(document.querySelectorAll<HTMLButtonElement>('#auth-trace-notice button')).find(
+		(b) => b.textContent === '立即前往',
+	);
+	expect(btn).toBeTruthy();
+	btn!.click();
+}
+
 beforeEach(() => {
 	vi.clearAllMocks();
+	document.documentElement.lang = 'zh-CN';
 	mockState.machineStatus = 'unauthenticated';
 	mockState.tenantRoute = {
 		slug: null,
@@ -85,22 +110,30 @@ afterEach(() => {
 	}
 	// vitest globals 未开启 ⇒ RTL 不会自动 cleanup，手动清理防跨用例 DOM 污染
 	cleanup();
+	cleanupAuthTraceNodes();
 });
 
 describe('RequireAuth 未登录出口', () => {
-	it('无可用 client_id → 跳 auth 登录页并带 from_requireauth=1', async () => {
+	it('无可用 client_id → 提示条（可停留）后跳 auth 登录页并带 from_requireauth=1', async () => {
+		const RequireAuthFresh = await freshRequireAuth();
+
 		render(
-			<RequireAuth>
+			<RequireAuthFresh>
 				<div>protected</div>
-			</RequireAuth>,
+			</RequireAuthFresh>,
 		);
 
+		// 层①：被动弹登录先出提示条（不再静默整页弹走）
+		await waitFor(() => expect(document.getElementById('auth-trace-notice')).toBeTruthy());
+		clickGoNow();
+
 		await waitFor(() => {
 			expect(mockState.replace).toHaveBeenCalled();
 		});
 		const url = String(mockState.replace.mock.calls[0][0]);
 		expect(url).toContain('from_requireauth=1');
 		expect(url).toContain('redirect=');
+		expect(url).toContain('rt=localhost.unauthenticated.');
 		expect(url.startsWith(getPortalUrl('auth'))).toBe(true);
 		expect(mockState.initiate).not.toHaveBeenCalled();
 	});
@@ -230,12 +263,16 @@ describe('RequireAuth F-W6 确定性 404 闸门', () => {
 
 	it('非 unknownSlug（网络错误 fail-open）→ 维持原漏斗（回归锁）', async () => {
 		// 默认 tenantRoute: notFound=true, unknownSlug=false —— 即 by-slug 网络错误场景
+		const RequireAuthFresh = await freshRequireAuth();
+
 		render(
-			<RequireAuth notFound={<div data-testid="tenant-404">no such tenant</div>}>
+			<RequireAuthFresh notFound={<div data-testid="tenant-404">no such tenant</div>}>
 				<div>protected</div>
-			</RequireAuth>,
+			</RequireAuthFresh>,
 		);
 
+		await waitFor(() => expect(document.getElementById('auth-trace-notice')).toBeTruthy());
+		clickGoNow();
 		await waitFor(() => expect(mockState.replace).toHaveBeenCalled());
 		const url = String(mockState.replace.mock.calls[0][0]);
 		expect(url).toContain('from_requireauth=1');

package/src/components/__tests__/TenantRootRedirect.test.tsx

@@ -58,6 +58,13 @@ function expectedBrandFunnel() {
 	)}`;
 }
 
+/** 剥除 authTrace 面包屑（rt=）后比较；rt 装饰本身由专门断言锁定。 */
+function withoutRt(url: string): string {
+	const u = new URL(url, 'http://trace.invalid');
+	u.searchParams.delete('rt');
+	return u.pathname + u.search;
+}
+
 const originalWindowLocation = window.location;
 
 beforeEach(() => {
@@ -102,7 +109,8 @@ describe('TenantRootRedirect 裸根漏斗', () => {
 
 		await waitFor(() => expect(mockState.replace).toHaveBeenCalled());
 		const url = String(mockState.replace.mock.calls[0][0]);
-		expect(url).toBe('/demo/');
+		expect(url).toContain('rt=localhost.funnel-slug.');
+		expect(withoutRt(url)).toBe('/demo/');
 		expect(url).not.toContain('Demo%20Tenant');
 		expect(url).not.toContain('Demo');
 	});
@@ -114,7 +122,7 @@ describe('TenantRootRedirect 裸根漏斗', () => {
 		render(wrapper(<TenantRootRedirect />));
 
 		await waitFor(() => expect(mockState.replace).toHaveBeenCalled());
-		expect(String(mockState.replace.mock.calls[0][0])).toBe('/demo-fallback/');
+		expect(withoutRt(String(mockState.replace.mock.calls[0][0]))).toBe('/demo-fallback/');
 	});
 
 	it('有会话但名单未返回（加载中）→ 等待，不抢跑 brand 漏斗', async () => {
@@ -133,7 +141,7 @@ describe('TenantRootRedirect 裸根漏斗', () => {
 		render(wrapper(<TenantRootRedirect />));
 
 		await waitFor(() => expect(mockState.replace).toHaveBeenCalled());
-		expect(String(mockState.replace.mock.calls[0][0])).toBe(expectedBrandFunnel());
+		expect(withoutRt(String(mockState.replace.mock.calls[0][0]))).toBe(withoutRt(expectedBrandFunnel()));
 	});
 
 	it('有会话但名单无匹配（陈旧会话）→ 漏斗 brand', async () => {
@@ -143,7 +151,7 @@ describe('TenantRootRedirect 裸根漏斗', () => {
 		render(wrapper(<TenantRootRedirect />));
 
 		await waitFor(() => expect(mockState.replace).toHaveBeenCalled());
-		expect(String(mockState.replace.mock.calls[0][0])).toBe(expectedBrandFunnel());
+		expect(withoutRt(String(mockState.replace.mock.calls[0][0]))).toBe(withoutRt(expectedBrandFunnel()));
 	});
 
 	it('名单接口失败（返回空数组）→ 有会话按无匹配处理，漏斗 brand（不卡死）', async () => {
@@ -153,6 +161,6 @@ describe('TenantRootRedirect 裸根漏斗', () => {
 		render(wrapper(<TenantRootRedirect />));
 
 		await waitFor(() => expect(mockState.replace).toHaveBeenCalled());
-		expect(String(mockState.replace.mock.calls[0][0])).toBe(expectedBrandFunnel());
+		expect(withoutRt(String(mockState.replace.mock.calls[0][0]))).toBe(withoutRt(expectedBrandFunnel()));
 	});
 });

package/src/hooks/useLogout.ts

@@ -6,6 +6,7 @@
 
 import { useCallback } from 'react';
 import { buildLogoutUrl } from '../auth/roles';
+import { traceRedirect } from '../auth/auth-trace';
 
 /**
  * 统一的登出 Hook
@@ -26,7 +27,8 @@ export function useLogout() {
 
 			// buildLogoutUrl = auth 域裸根 + `logout=1` 登出意图标记：入口路由据此先
 			// 终结会话再落 brand，而不是把带会话的回程当普通深链直送登录页（会静默重登）。
-			window.location.href = buildLogoutUrl(currentUrl);
+			// funnel：用户主动行为，静默直跳（assign 保持原 href 历史语义）；仅记 trace。
+			traceRedirect(buildLogoutUrl(currentUrl), { reason: 'logout', assign: true });
 		};
 		performLogout();
 	}, []);

package/src/index.ts

@@ -25,6 +25,8 @@ export { generatePKCE, generateCodeChallenge } from './auth/pkce';
 export type { PKCEPair } from './auth/pkce';
 export { initiateOAuthLogin, handleOAuthCallback, isOAuthEnabled } from './auth/oauth-login';
 export { buildLoginUrl } from './auth/roles';
+export { traceRedirect, traceEvent, traceDump } from './auth/auth-trace';
+export type { AuthTraceEntry, AuthTraceRedirectOptions } from './auth/auth-trace';
 
 // Types
 export type {