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

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/generated/api.ts

@@ -1,6 +1,6 @@
 // Auto-generated from swagger.json annotations
 // DO NOT EDIT — run `python scripts/generate_api_ts.py` to regenerate
-// Generated: 2026-08-22 19:20:02
+// Generated: 2026-09-30 17:04:31
 
 // @ts-nocheck — auto-generated; validated by check-generated-api.py
 import type * as Types from './types';
@@ -6855,6 +6855,20 @@ export async function mfaWebauthnCredentialsByCredentialsPut(webauthnCredentialI
 // Notification Service
 // ============================================================
 
+/**
+ * 管理端列出公告
+ * 管理端分页查询本租户公告列表，支持按状态过滤和关键词搜索；与用户面 /announcements 同体（同租户范围），走 admin 受众供控制台读取 参考：CAN-SPAM Act (15 U.S.C. §7701) — Commercial Email Compliance。
+ */
+export async function adminAnnouncements(params?: {
+  page?: number;  // 页码
+  page_size?: number;  // 每页条数
+  status?: string;  // 状态过滤: draft/scheduled/published/expired
+  search?: string;  // 搜索关键词
+}) {
+  const res = await api.get(`/notification/api/v1/admin/announcements`, { params });
+  return res.data;
+}
+
 /**
  * 创建公告
  * 创建新的公告，支持草稿/定时发布，可指定目标租户和角色 参考：CAN-SPAM Act (15 U.S.C. §7701) — Commercial Email Compliance。
@@ -7224,15 +7238,25 @@ export async function notificationsStats() {
 
 /**
  * SSE实时通知流
- * 通过Server-Sent Events实时推送通知，客户端需传入user_id查询参数进行订阅 参考：CAN-SPAM Act (15 U.S.C. §7701) — Commercial Email Compliance。
+ * 通过Server-Sent Events实时推送通知。P5-4：经 POST /notifications/stream-ticket 换取一次性票据后以 ?ticket= 建流（浏览器 EventSource 主路径）；非浏览器客户端可走 Authorization 头 JWT（?token= 兼容回退已删除）。订阅身份以认证上下文（票据/JWT claims）为准。 参考：CAN-SPAM Act (15 U.S.C. §7701) — Commercial Email Compliance。
  */
 export async function notificationsStream(params?: {
-  user_id: string;  // 用户ID
+  ticket?: string;  // 一次性短期票据（P5-4 主路径，60s 内一次性消费）
+  user_id?: string;  // 用户ID（已弃用回退：仅在认证上下文无用户时使用）
 }) {
   const res = await api.get(`/notification/api/v1/notifications/stream`, { params });
   return res.data;
 }
 
+/**
+ * 签发 SSE 短期票据
+ * 为 /notifications/stream 签发一次性票据（P5-4）：浏览器 EventSource 不能携带 Authorization 头，故以 JWT 保护的本端点换取 60s 一次性票据，再以 ?ticket= 建流，避免 access token 进入 URL/接入日志。需 JWT 认证（正常 Authorization 头调用）。
+ */
+export async function notificationsStreamTicketPost() {
+  const res = await api.post(`/notification/api/v1/notifications/stream-ticket`);
+  return res.data;
+}
+
 /**
  * 列出通知模板
  * 获取所有通知模板列表，支持包含已停用模板的选项 参考：CAN-SPAM Act (15 U.S.C. §7701) — Commercial Email Compliance。
@@ -7377,7 +7401,7 @@ export async function pushSubscriptionsBySubscriptions(subscriptionId: string) {
 
 /**
  * 获取 VAPID 公钥
- * 返回 Web Push VAPID 公钥，供前端注册 Push 订阅时使用 参考：CAN-SPAM Act (15 U.S.C. §7701) — Commercial Email Compliance。
+ * 返回 Web Push VAPID 公钥，供前端注册 Push 订阅时使用（来源：communication-service） 参考：CAN-SPAM Act (15 U.S.C. §7701) — Commercial Email Compliance。
  */
 export async function pushVapidPublicKey() {
   const res = await api.get(`/notification/api/v1/push/vapid-public-key`);

package/src/generated/queries.ts

@@ -1,6 +1,6 @@
 // Auto-generated from swagger.json annotations
 // DO NOT EDIT — run `python scripts/generate_api_ts.py` to regenerate
-// Generated: 2026-08-22 19:20:02
+// Generated: 2026-09-30 17:04:31
 
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import * as api from './api';
@@ -2599,6 +2599,14 @@ export function useMfaWebauthnCredentialsByCredentials(webauthnCredentialId: str
 
 // --- notification-service ---
 
+/** 管理端列出公告 */
+export function useAdminAnnouncements(params?: any) {
+  return useQuery({
+    queryKey: ['notification-service', params] as const,
+    queryFn: () => api.adminAnnouncements(params),
+  });
+}
+
 /** 管理员查看指定用户通知列表 */
 export function useAdminNotifications(params?: any) {
   return useQuery({
@@ -9153,6 +9161,17 @@ export function usePostNotificationsSend_from_template() {
   });
 }
 
+/** 签发 SSE 短期票据 */
+export function usePostNotificationsStream_ticket() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: () => api.notificationsStreamTicketPost(),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ['notification-service'] });
+    },
+  });
+}
+
 /** 发送测试通知 */
 export function usePostNotificationsTest() {
   const qc = useQueryClient();

package/src/generated/types.ts

@@ -1,6 +1,6 @@
 // Auto-generated from swagger.json annotations
 // DO NOT EDIT — run `python scripts/generate_api_ts.py` to regenerate
-// Generated: 2026-08-22 06:50:43
+// Generated: 2026-09-30 17:04:31
 
 // ============================================================
 // Shared generic types
@@ -7516,6 +7516,71 @@ export type COSEAlgorithmIdentifier = "-7" | "-8" | "-9" | "-19" | "-35" | "-36"
 // notification-service
 // ============================================================
 
+export interface DataResponsegitee_com_autional_servicenotification_internal_handler_dto_EventMappingResponse {
+  code?: number;
+  data?: EventMappingResponse;
+  message?: string;
+  timestamp?: string;
+}
+
+export interface DataResponsegitee_com_autional_servicenotification_internal_handler_dto_ExportUserDataResponse {
+  code?: number;
+  data?: ExportUserDataResponse;
+  message?: string;
+  timestamp?: string;
+}
+
+export interface DataResponsegitee_com_autional_servicenotification_internal_handler_dto_NotificationPreferencesResponse {
+  code?: number;
+  data?: NotificationPreferencesResponse;
+  message?: string;
+  timestamp?: string;
+}
+
+export interface DataResponsegitee_com_autional_servicenotification_internal_handler_dto_NotificationResponse {
+  code?: number;
+  data?: NotificationResponse;
+  message?: string;
+  timestamp?: string;
+}
+
+export interface DataResponsegitee_com_autional_servicenotification_internal_handler_dto_StreamTicketResponse {
+  code?: number;
+  data?: StreamTicketResponse;
+  message?: string;
+  timestamp?: string;
+}
+
+export interface DataResponsegitee_com_autional_servicenotification_internal_handler_dto_TemplateResponse {
+  code?: number;
+  data?: TemplateResponse;
+  message?: string;
+  timestamp?: string;
+}
+
+export interface DataResponsehandler_HealthErrorResponse {
+  code?: number;
+  data?: HealthErrorResponse;
+  message?: string;
+  timestamp?: string;
+}
+
+export interface DataResponsemap_string_string {
+  code?: number;
+  data?: Map_string_string;
+  message?: string;
+  timestamp?: string;
+}
+
+export interface ListResponsegitee_com_autional_servicenotification_internal_handler_dto_NotificationResponse {
+  code?: number;
+  items?: NotificationResponse[];  // 统一使用 items
+  message?: string;
+  pagination?: PageInfo;  // 分页信息（嵌套对象）
+  timestamp?: string;
+  total?: number;  // 总条数（平铺，便于直接读取）
+}
+
 export interface AnnouncementDetailResponse {
   code?: number;
   data?: AnnouncementResponse;
@@ -7641,48 +7706,6 @@ export interface CreateGlobalVariableRequest {
   value: string;
 }
 
-export interface DataResponsedto_ExportUserDataResponse {
-  code?: number;
-  data?: ExportUserDataResponse;
-  message?: string;
-  timestamp?: string;
-}
-
-export interface DataResponsedto_NotificationPreferencesResponse {
-  code?: number;
-  data?: NotificationPreferencesResponse;
-  message?: string;
-  timestamp?: string;
-}
-
-export interface DataResponsedto_NotificationResponse {
-  code?: number;
-  data?: NotificationResponse;
-  message?: string;
-  timestamp?: string;
-}
-
-export interface DataResponsedto_TemplateResponse {
-  code?: number;
-  data?: TemplateResponse;
-  message?: string;
-  timestamp?: string;
-}
-
-export interface DataResponsehandler_HealthErrorResponse {
-  code?: number;
-  data?: HealthErrorResponse;
-  message?: string;
-  timestamp?: string;
-}
-
-export interface DataResponsemap_string_string {
-  code?: number;
-  data?: Map_string_string;
-  message?: string;
-  timestamp?: string;
-}
-
 export interface DeleteNotificationDetailResponse {
   code?: number;
   data?: DeleteNotificationResponse;
@@ -7776,13 +7799,20 @@ export interface InternalPushSendRequest {
   userId?: string;  // @example user-001
 }
 
-export interface ListResponsedto_NotificationResponse {
-  code?: number;
-  items?: NotificationResponse[];  // 统一使用 items
-  message?: string;
-  pagination?: PageInfo;  // 分页信息（嵌套对象）
-  timestamp?: string;
-  total?: number;  // 总条数（平铺，便于直接读取）
+export interface InternalSendExternalRequest {
+  channel: string;  // @example email
+  locale?: string;  // @example en-US
+  recipient: string;  // @example user@example.com
+  templateCode: string;  // @example status_subscription_confirm
+  variables?: Record<string, string>;
+}
+
+export interface InternalUpsertEventMappingRequest {
+  channel?: string;  // 空 → in_app | @example in_app
+  eventType: string;  // @example user.registered
+  isEnabled?: boolean;  // 空 → true
+  priority?: string;  // 空 → medium | @example medium
+  templateCode: string;  // @example welcome
 }
 
 export interface MarkReadDetailResponse {
@@ -8008,6 +8038,12 @@ export interface SendNotificationRequest {
   userId: string;  // 用户ID | @example usr_abc123
 }
 
+/** 一次性 SSE 票据：60s 内有效、消费一次即失效；以 ?ticket= 建立 EventSource 流 */
+export interface StreamTicketResponse {
+  expiresIn?: number;  // 有效期（秒） | @example 60
+  ticket?: string;  // 一次性票据 | @example 1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2
+}
+
 export interface TestNotificationDetailResponse {
   code?: number;
   data?: TestNotificationResponse;
@@ -8873,6 +8909,13 @@ export interface DataResponsedomain_PointIntegrityResult {
   timestamp?: string;
 }
 
+export interface DataResponsedto_ExportUserDataResponse {
+  code?: number;
+  data?: ExportUserDataResponse;
+  message?: string;
+  timestamp?: string;
+}
+
 export interface DeleteUserDataRequest {
   userId: string;
 }

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 {