@autional-cn/shared 0.1.0-rc

package/src/auth/tenant-route-middleware.ts

@@ -0,0 +1,113 @@
+/**
+ * useTenantRoute — 路由层中间件
+ *
+ * 从 URL slug 解析租户配置，与认证逻辑解耦。
+ * 代替 RequireAuth 直接使用 useOAuthClientIdFromUrl。
+ *
+ * 职责:
+ *  - 从 URL 提取 tenant slug
+ *  - 请求 OAuth 客户端配置 (slug → clientId)
+ *  - 自动将 tenantId 写入 AuthService
+ *  - 暴露 loading/notFound 状态给路由层
+ *
+ * @see docs/architecture/auth-next-issues-analysis.md
+ */
+
+'use client';
+
+import { useEffect } from 'react';
+import { useOAuthClientIdFromUrl } from './oauth-client-from-slug';
+import { AuthService } from './service';
+import { getPortalUrl } from '../config';
+
+export interface TenantRouteResult {
+	/** 租户 slug（从 URL 提取） */
+	slug: string | null;
+	/** 租户 ID（从 OAuth 配置获取） */
+	tenantId: string | null;
+	/** OAuth 客户端 ID */
+	oauthClientId: string | null;
+	/** 是否正在加载（API 请求中） */
+	loading: boolean;
+	/** 未找到（无 slug / 无 OAuth 配置 / slug 不存在） */
+	notFound: boolean;
+	/**
+	 * URL slug 确定性不存在（by-slug HTTP 404）。
+	 * 门户口径（F-W6）：本地渲染 404、不发弹跳 —— 否则与 auth 侧
+	 * 「有会话 → 回跳 redirect」构成无限整页往返。
+	 * 网络错误/5xx 不置本标记（fail-open，仍走原登录漏斗）。
+	 */
+	unknownSlug: boolean;
+}
+
+/**
+ * 路由层中间件：从 URL slug 解析租户配置。
+ *
+ * 用法:
+ * ```tsx
+ * function AppLayout() {
+ *   const tenantRoute = useTenantRoute();
+ *   if (tenantRoute.loading) return <Spin />;
+ *   return <App tenantSlug={tenantRoute.slug} />;
+ * }
+ * ```
+ */
+export function useTenantRoute(): TenantRouteResult {
+	const slugResolution = useOAuthClientIdFromUrl();
+
+	// Auto-store tenantId in AuthService when resolved
+	useEffect(() => {
+		if (slugResolution.status === 'resolved' && slugResolution.config.tenantId) {
+			AuthService.updateCurrentTenant(slugResolution.config.tenantId);
+		}
+	}, [slugResolution.status]);
+
+	// slug 在 useOAuthClientIdFromUrl 中通过 extractSlugFromPath 从 URL 提取，
+	// 通过 SlugResolution.resolved.slug 传递，无需从 API 响应中读取。
+	const slug = slugResolution.status === 'resolved' ? slugResolution.slug : null;
+
+	const unknownSlug = slugResolution.status === 'unknown-slug';
+
+	return {
+		slug,
+		tenantId: slugResolution.status === 'resolved' ? slugResolution.config.tenantId || null : null,
+		oauthClientId: slugResolution.status === 'resolved' ? slugResolution.clientId : null,
+		loading: slugResolution.status === 'loading',
+		notFound: slugResolution.status === 'not-found' || unknownSlug,
+		unknownSlug,
+	};
+}
+
+/**
+ * 获取有效的 OAuth clientId：配置 > 环境变量 > slug 解析。
+ * 这是 redirect 决策的核心逻辑，提取为纯函数便于测试。
+ */
+export function resolveEffectiveClientId(
+	tenantRoute: TenantRouteResult,
+	envClientId?: string,
+): string | null {
+	// slug 解析出的 clientId 优先（多租户场景）
+	if (tenantRoute.oauthClientId) return tenantRoute.oauthClientId;
+	// 环境变量其次（单租户/开发场景）
+	if (envClientId) return envClientId;
+	return null;
+}
+
+/**
+ * 判断 OAuth 是否在同域（slug-resolved 或同域 auth-pages）。
+ * SSR 安全：在服务端环境下始终返回 false。
+ */
+export function isSameDomainOAuth(tenantRoute: TenantRouteResult): boolean {
+	if (typeof window === 'undefined') return false; // SSR guard
+	if (tenantRoute.notFound) return false;
+	// slug 解析到的 client 一定是同域的（API 在同一 gateway 后）
+	if (tenantRoute.oauthClientId) return true;
+	// 检查 auth-pages URL 是否同域
+	try {
+		const authPagesUrl = getPortalUrl('auth');
+		if (!authPagesUrl) return false;
+		return new URL(authPagesUrl).origin === window.location.origin;
+	} catch {
+		return false;
+	}
+}

package/src/auth/tenant-slug-context.tsx

@@ -0,0 +1,9 @@
+import { createContext, useContext } from 'react';
+
+const TenantSlugContext = createContext<string | undefined>(undefined);
+
+export const TenantSlugProvider = TenantSlugContext.Provider;
+
+export function useTenantSlug(): string | undefined {
+	return useContext(TenantSlugContext);
+}

package/src/branding/BrandingInitializer.tsx

@@ -0,0 +1,60 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { useTenantSlugFromUrl } from '../auth/slug-from-url';
+import { tenantPublicTenantsByTenants } from '../generated/api';
+import { extractBranding } from './extract-branding';
+import { readCachedBranding, writeCachedBranding } from './branding-cache';
+import { useTenantBrandingStore } from './tenant-store';
+import type { Branding } from './types';
+
+const TTL = 6 * 60 * 60 * 1000; // 6h，与公开租户接口的缓存口径一致
+
+export interface BrandingInitializerProps {
+	/**
+	 * 覆盖 slug 来源。缺省按 URL 首段取（共享层口径）；
+	 * auth 站传入自己的判定——它要求至少两段，裸 /{slug} 视为无租户上下文。
+	 */
+	slug?: string | null;
+	/** 接口尚未返回时的兜底品牌（auth 站用 auth-config 里的 branding 段）。 */
+	fallback?: Branding | null;
+}
+
+/** 按 slug 拉公开品牌并写入 store；渲染 `null`，只做接线。 */
+export function BrandingInitializer({ slug: slugProp, fallback }: BrandingInitializerProps) {
+	const urlSlug = useTenantSlugFromUrl();
+	const slug = slugProp !== undefined ? slugProp : urlSlug;
+	const setBranding = useTenantBrandingStore((s) => s.setBranding);
+
+	// 缓存先到：首屏立即有品牌（未命中则由 useBranding 回落 tokens 缺省）
+	useEffect(() => {
+		if (!slug) {
+			setBranding(null);
+			return;
+		}
+		const cached = readCachedBranding(slug);
+		if (cached) setBranding(cached);
+	}, [slug, setBranding]);
+
+	const { data } = useQuery<Branding | null>({
+		queryKey: ['tenant-branding', slug],
+		queryFn: async () => {
+			if (!slug) return null;
+			const res = await tenantPublicTenantsByTenants(slug);
+			const branding = extractBranding(res);
+			if (branding) writeCachedBranding(slug, branding);
+			return branding;
+		},
+		enabled: Boolean(slug),
+		staleTime: TTL,
+		gcTime: TTL * 2,
+	});
+
+	useEffect(() => {
+		const resolved = data ?? fallback ?? null;
+		if (resolved) setBranding(resolved);
+	}, [data, fallback, setBranding]);
+
+	return null;
+}

package/src/branding/brand-color.ts

@@ -0,0 +1,155 @@
+// brand-color.ts — OKLab (Ottosson) 颜色转换 + WCAG 2.x 对比度 + 暗色品牌推导
+// 纯函数，零外部依赖。移植自 butler/requirements/design/brand-contrast.mjs（保留全部常数）
+// 防御 (N3): 非法 hex 输入（非 #rgb/#rrggbb、空串、null/undefined）返回原值/安全默认，不抛错，
+//            避免租户数据异常产生 invalid CSS 变量值。
+
+type Rgb = [number, number, number];
+
+const HEX_RE = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+/** 归一化为小写 #rrggbb（支持 #rgb 展开 + 大写 hex）；非法输入返回 null */
+function normalizeHex(hex: unknown): string | null {
+	if (typeof hex !== 'string') return null;
+	const h = hex.trim();
+	if (!HEX_RE.test(h)) return null;
+	let digits = h.slice(1).toLowerCase();
+	if (digits.length === 3)
+		digits = digits
+			.split('')
+			.map((c) => c + c)
+			.join('');
+	return `#${digits}`;
+}
+
+// ── WCAG 2.x 相对亮度 / 对比度（脚本 L4-20）──
+function hexToRgb(hex: string): Rgb {
+	const norm = normalizeHex(hex);
+	if (!norm) return [0, 0, 0];
+	const d = norm.slice(1);
+	return [0, 2, 4].map((i) => parseInt(d.slice(i, i + 2), 16) / 255) as Rgb;
+}
+function lin(c: number): number {
+	return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+function lum(rgb: Rgb): number {
+	const [r, g, b] = rgb.map(lin) as [number, number, number];
+	return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function contrast(a: Rgb, b: Rgb): number {
+	const l1 = lum(a);
+	const l2 = lum(b);
+	const [hi, lo] = l1 > l2 ? [l1, l2] : [l2, l1];
+	return (hi + 0.05) / (lo + 0.05);
+}
+
+// ── sRGB ↔ OKLab (Ottosson，脚本 L22-46，含 Math.cbrt 与输出钳位) ──
+function srgbToOklab(rgb: Rgb): [number, number, number] {
+	const [r, g, b] = rgb.map(lin) as [number, number, number];
+	let l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
+	let m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
+	let s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
+	l = Math.cbrt(l);
+	m = Math.cbrt(m);
+	s = Math.cbrt(s);
+	return [
+		0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+		1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+		0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+	];
+}
+function oklabToSrgb([L, a, b]: [number, number, number]): Rgb {
+	const l = Math.pow(L + 0.3963377774 * a + 0.2158037573 * b, 3);
+	const m = Math.pow(L - 0.1055613458 * a - 0.0638541728 * b, 3);
+	const s = Math.pow(L - 0.0894841775 * a - 1.291485548 * b, 3);
+	const r = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+	const g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+	const b2 = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
+	const conv = (c: number): number => {
+		c = Math.min(1, Math.max(0, c)); // 钳位（脚本 L42）
+		return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+	};
+	return [conv(r), conv(g), conv(b2)];
+}
+function rgbToHex(rgb: Rgb): string {
+	return (
+		'#' +
+		rgb
+			.map((c) =>
+				Math.round(c * 255)
+					.toString(16)
+					.padStart(2, '0'),
+			)
+			.join('')
+	);
+}
+
+/** hex → OKLCH [L, C, H]（防御: 非法输入返回 [0, 0, 0]，不抛错） */
+export function hexToOklch(hex: string): [number, number, number] {
+	if (normalizeHex(hex) === null) return [0, 0, 0];
+	const [L, a, b] = srgbToOklab(hexToRgb(hex));
+	return [L, Math.hypot(a, b), Math.atan2(b, a)];
+}
+
+/** OKLCH [L, C, H] → hex（防御: 非法输入返回 '#000000'，不抛错） */
+export function oklchToHex(oklch: [number, number, number]): string {
+	if (
+		!Array.isArray(oklch) ||
+		oklch.length < 3 ||
+		oklch.slice(0, 3).some((v) => typeof v !== 'number' || Number.isNaN(v))
+	) {
+		return '#000000';
+	}
+	const [L, C, H] = oklch;
+	return rgbToHex(oklabToSrgb([L, C * Math.cos(H), C * Math.sin(H)]));
+}
+
+/** 向白色混入比例 t: OKLCH[L+(1-L)·t, C·(1-t), H]（保持色相，抬升 L、压降 C，脚本 L58-63） */
+function mixWhite(hex: string, t: number): string {
+	const [L, C, H] = hexToOklch(hex);
+	return oklchToHex([L + (1 - L) * t, C * (1 - t), H]);
+}
+
+/** 内部函数（不导出）: 二分 24 迭代求最小 t∈[0,cap]，使 mixWhite(hex,t) 对 refBg 对比度 ≥ target。
+ *  供 deriveDarkColor / deriveDarkHover 复用，避免二次二分（ADR-003）。 */
+function deriveT(hex: string, refBg: string, target: number, cap: number): number {
+	let lo = 0;
+	let hi = cap;
+	const bgRgb = hexToRgb(refBg);
+	for (let i = 0; i < 24; i++) {
+		const mid = (lo + hi) / 2;
+		if (contrast(hexToRgb(mixWhite(hex, mid)), bgRgb) >= target) hi = mid;
+		else lo = mid;
+	}
+	return (lo + hi) / 2;
+}
+
+/** 推导暗色品牌变体 = mixWhite(hex, deriveT(...))。
+ *  D3 锁定默认参数: refBg='#0a2940', target=4.55, cap=0.85。
+ *  防御 (N3): 非法 hex → 返回原值不抛错（不产生 invalid CSS 变量值）。 */
+export function deriveDarkColor(hex: string, refBg = '#0a2940', target = 4.55, cap = 0.85): string {
+	if (normalizeHex(hex) === null) return hex;
+	const bg = normalizeHex(refBg) ?? '#0a2940';
+	const tgt = typeof target === 'number' && !Number.isNaN(target) ? target : 4.55;
+	const c = typeof cap === 'number' && !Number.isNaN(cap) ? Math.max(0, Math.min(cap, 1)) : 0.85;
+	return mixWhite(hex, deriveT(hex, bg, tgt, c));
+}
+
+/** on-brand 文本色: 选 '#ffffff' 与 '#0a0f1a' 中对比度更高者（保证 ≥4.5）。
+ *  防御: 非法 fill → '#0a0f1a'（安全默认，不抛错）。 */
+export function pickOnColor(fill: string): '#ffffff' | '#0a0f1a' {
+	if (normalizeHex(fill) === null) return '#0a0f1a';
+	const white: Rgb = [1, 1, 1];
+	const dark = hexToRgb('#0a0f1a');
+	return contrast(white, hexToRgb(fill)) >= contrast(dark, hexToRgb(fill)) ? '#ffffff' : '#0a0f1a';
+}
+
+/** hover 暗色变体 = mixWhite(color, min(t+0.08, 0.92))，t 复用 deriveT（ADR-003/D4）。
+ *  防御 (N3): 非法 hex → 返回原值不抛错。 */
+export function deriveDarkHover(hex: string, refBg = '#0a2940', target = 4.55, cap = 0.85): string {
+	if (normalizeHex(hex) === null) return hex;
+	const bg = normalizeHex(refBg) ?? '#0a2940';
+	const tgt = typeof target === 'number' && !Number.isNaN(target) ? target : 4.55;
+	const c = typeof cap === 'number' && !Number.isNaN(cap) ? Math.max(0, Math.min(cap, 1)) : 0.85;
+	const t = deriveT(hex, bg, tgt, c);
+	return mixWhite(hex, Math.min(t + 0.08, 0.92));
+}

package/src/branding/branding-cache.ts

@@ -0,0 +1,71 @@
+import type { Branding } from './types';
+import { extractBranding } from './extract-branding';
+
+/**
+ * 缓存键。三套前缀都要认——顺序不能改，越靠前越早、越权威。
+ *
+ *   page-init:tenant-branding:  页面内联脚本在 React 之前写入 → 首帧就有缓存色可上
+ *   tenant-branding:            运行时写入（writeCachedBranding）
+ *   page-init:auth-config: / auth-config:   auth-config 里也带 branding 段，作为兜底
+ *
+ * 只认第二套的代价是实测过的：首帧读不到缓存，先闪一次品牌默认色再跳到租户色。
+ * auth 站的同类实现一直读的是 page-init 键，这里把能力并到共享版，避免两套各读各的。
+ */
+export const BRANDING_CACHE_PREFIX = 'tenant-branding:';
+export const PAGE_INIT_BRANDING_PREFIX = 'page-init:tenant-branding:';
+export const AUTH_CONFIG_PREFIX = 'auth-config:';
+export const PAGE_INIT_AUTH_CONFIG_PREFIX = 'page-init:auth-config:';
+
+function get(key: string): string | null {
+	try {
+		return localStorage.getItem(key);
+	} catch {
+		return null;
+	}
+}
+
+/** 兼容 `{data, _ts}` 包装与裸对象两种历史写入形态。 */
+function unwrap(raw: string | null): Branding | null {
+	if (!raw) return null;
+	try {
+		const parsed = JSON.parse(raw) as { data?: Branding } | Branding;
+		return ((parsed as { data?: Branding })?.data ?? parsed) as Branding;
+	} catch {
+		return null;
+	}
+}
+
+/** auth-config 缓存里也带 branding 段——作为最后兜底。 */
+function fromAuthConfig(slug: string): Branding | null {
+	for (const prefix of [PAGE_INIT_AUTH_CONFIG_PREFIX, AUTH_CONFIG_PREFIX]) {
+		const raw = get(prefix + slug);
+		if (!raw) continue;
+		try {
+			const cfg = JSON.parse(raw) as { data?: { branding?: unknown } };
+			const branding = extractBranding(cfg?.data?.branding);
+			if (branding) return branding;
+		} catch {
+			/* 坏数据视为没有 */
+		}
+	}
+	return null;
+}
+
+export function readCachedBranding(slug: string): Branding | null {
+	return (
+		unwrap(get(PAGE_INIT_BRANDING_PREFIX + slug)) ??
+		unwrap(get(BRANDING_CACHE_PREFIX + slug)) ??
+		fromAuthConfig(slug)
+	);
+}
+
+export function writeCachedBranding(slug: string, branding: Branding): void {
+	try {
+		localStorage.setItem(
+			BRANDING_CACHE_PREFIX + slug,
+			JSON.stringify({ data: branding, _ts: Date.now() }),
+		);
+	} catch {
+		/* storage full or unavailable */
+	}
+}

package/src/branding/extract-branding.ts

@@ -0,0 +1,27 @@
+import type { Branding } from './types';
+
+/** 从 public tenant 接口响应里取 branding 段（兼容 snake_case / camelCase，且兼容已解包的对象）。 */
+export function extractBranding(raw: unknown): Branding | null {
+	if (!raw || typeof raw !== 'object') return null;
+	const record = raw as Record<string, unknown>;
+	const source = (record.branding ?? record) as Record<string, string | undefined>;
+	if (!source || typeof source !== 'object') return null;
+
+	const logoUrl = source.logo_url || source.logoUrl || '';
+	const primaryColor = source.primary_color || source.primaryColor || '';
+	if (!logoUrl && !primaryColor) return null;
+
+	return {
+		primaryColor,
+		primaryColorDark: source.primary_color_dark || source.primaryColorDark || undefined,
+		logoUrl,
+		faviconUrl: source.favicon_url || source.faviconUrl || '',
+		customCss: source.custom_css || source.customCss || '',
+		secondaryColor: source.secondary_color || source.secondaryColor || undefined,
+		companyName: source.company_name || source.companyName || undefined,
+		loginPageTitle: source.login_page_title || source.loginPageTitle || undefined,
+		loginPageDescription: source.login_page_description || source.loginPageDescription || undefined,
+		privacyPolicyUrl: source.privacy_policy_url || source.privacyPolicyUrl || undefined,
+		termsOfServiceUrl: source.terms_of_service_url || source.termsOfServiceUrl || undefined,
+	};
+}

package/src/branding/index.ts

@@ -0,0 +1,15 @@
+export { useBranding, applyBrandColors } from './useBranding';
+export { BrandingInitializer } from './BrandingInitializer';
+export type { BrandingInitializerProps } from './BrandingInitializer';
+export { useTenantBrandingStore } from './tenant-store';
+export { extractBranding } from './extract-branding';
+export {
+	readCachedBranding,
+	writeCachedBranding,
+	BRANDING_CACHE_PREFIX,
+	PAGE_INIT_BRANDING_PREFIX,
+	AUTH_CONFIG_PREFIX,
+	PAGE_INIT_AUTH_CONFIG_PREFIX,
+} from './branding-cache';
+export { deriveDarkColor, deriveDarkHover, pickOnColor, hexToOklch, oklchToHex } from './brand-color';
+export type { Branding } from './types';

package/src/branding/tenant-store.ts

@@ -0,0 +1,13 @@
+import { create } from 'zustand';
+import type { Branding } from './types';
+
+interface TenantBrandingState {
+	branding: Branding | null;
+	setBranding: (branding: Branding | null) => void;
+}
+
+/** 品牌 store —— `BrandingInitializer` 写入，`useBranding` 消费并落到 CSS 变量。 */
+export const useTenantBrandingStore = create<TenantBrandingState>((set) => ({
+	branding: null,
+	setBranding: (branding) => set({ branding }),
+}));

package/src/branding/types.ts

@@ -0,0 +1,14 @@
+/** 租户公开品牌契约（与 tenant-service `GET /tenant/public/tenants/{slug}` 的 branding 段一致）。 */
+export interface Branding {
+	primaryColor: string;
+	primaryColorDark?: string;
+	logoUrl: string;
+	faviconUrl: string;
+	customCss: string;
+	secondaryColor?: string;
+	companyName?: string;
+	loginPageTitle?: string;
+	loginPageDescription?: string;
+	privacyPolicyUrl?: string;
+	termsOfServiceUrl?: string;
+}

package/src/branding/useBranding.ts

@@ -0,0 +1,85 @@
+'use client';
+
+import { useLayoutEffect, useRef } from 'react';
+import { useTenantSlugFromUrl } from '../auth/slug-from-url';
+import { deriveDarkColor, deriveDarkHover, pickOnColor } from './brand-color';
+import { readCachedBranding } from './branding-cache';
+import { useTenantBrandingStore } from './tenant-store';
+
+/** 品牌注入的 7 个 CSS 变量（与 auth 站同口径，tokens.css 提供缺省值）。 */
+const BRAND_VARS = [
+	'--color-brand-base',
+	'--color-brand-hover-base',
+	'--color-brand-dark',
+	'--color-brand-dark-hover',
+	'--color-on-brand-base',
+	'--color-on-brand',
+	'--color-on-brand-dark',
+];
+
+export function applyBrandColors(color: string, darkOverride?: string): void {
+	const root = document.documentElement;
+	if (!color) {
+		BRAND_VARS.forEach((v) => root.style.removeProperty(v));
+		return;
+	}
+	const dark = darkOverride || deriveDarkColor(color);
+	root.style.setProperty('--color-brand-base', color);
+	root.style.setProperty('--color-brand-hover-base', color);
+	root.style.setProperty('--color-brand-dark', dark);
+	root.style.setProperty('--color-brand-dark-hover', deriveDarkHover(color));
+	root.style.setProperty('--color-on-brand-base', pickOnColor(color));
+	root.style.setProperty('--color-on-brand-dark', pickOnColor(dark));
+}
+
+/**
+ * 把当前租户品牌落到 DOM（CSS 变量 / favicon / customCss）。
+ * 需与 `<BrandingInitializer/>` 同时挂载：前者负责写 store，这里负责呈现。
+ */
+export function useBranding(): void {
+	const branding = useTenantBrandingStore((s) => s.branding);
+	const slug = useTenantSlugFromUrl();
+	const styleRef = useRef<HTMLStyleElement | null>(null);
+	const primedSlugRef = useRef<string | null>(null);
+
+	// 首帧前用缓存上色，避免默认品牌色闪一下
+	useLayoutEffect(() => {
+		if (!slug || primedSlugRef.current === slug) return;
+		primedSlugRef.current = slug;
+		const cached = readCachedBranding(slug);
+		applyBrandColors(cached?.primaryColor ?? '', cached?.primaryColorDark);
+	}, [slug]);
+
+	useLayoutEffect(() => {
+		if (!branding) {
+			applyBrandColors('');
+			return;
+		}
+
+		applyBrandColors(branding.primaryColor, branding.primaryColorDark);
+
+		if (branding.faviconUrl) {
+			let favicon = document.querySelector<HTMLLinkElement>('link[rel="icon"]');
+			if (!favicon) {
+				favicon = document.createElement('link');
+				favicon.rel = 'icon';
+				document.head.appendChild(favicon);
+			}
+			favicon.href = branding.faviconUrl;
+		}
+
+		if (branding.customCss) {
+			if (!styleRef.current) {
+				styleRef.current = document.createElement('style');
+				styleRef.current.setAttribute('data-tenant-css', '');
+				document.head.appendChild(styleRef.current);
+			}
+			styleRef.current.textContent = branding.customCss;
+		}
+
+		return () => {
+			applyBrandColors('');
+			if (styleRef.current) styleRef.current.textContent = '';
+		};
+	}, [branding]);
+}

package/src/components/AuditStatsOnly.tsx

@@ -0,0 +1,65 @@
+/**
+ * AuditStatsOnly — 审计统计摘要组件
+ *
+ * 在 strict sod_mode 下，admin 角色仅能看到聚合统计卡片，
+ * 不能看到审计日志明细行、全文检索、导出等功能。
+ *
+ * 不使用 antd 依赖（shared 包不直接依赖 antd），
+ * 使用纯 Tailwind CSS + HTML 实现轻量提示卡片。
+ *
+ * @see document/architecture/decisions/007-security-dashboard-audit.md §2.2
+ */
+
+'use client';
+
+import React from 'react';
+
+interface AuditStatsOnlyProps {
+	title?: string;
+	description?: string;
+	children?: React.ReactNode;
+}
+
+/**
+ * 审计受限提示组件。
+ * 在 strict 模式下替换完整审计页面内容。
+ *
+ * 可选的 children 用于放置自定义的统计卡片内容。
+ */
+export function AuditStatsOnly({ title, description, children }: AuditStatsOnlyProps) {
+	return (
+		<div className="flex flex-col items-center justify-center min-h-[40vh] p-8">
+			<div className="w-full max-w-2xl bg-white dark:bg-slate-800 rounded-lg shadow-sm border border-gray-200 dark:border-slate-700 p-8">
+				<div className="flex flex-col items-center text-center space-y-4">
+					{/* Lock icon via inline SVG (no external dependency) */}
+					<svg
+						className="w-12 h-12 text-gray-400 dark:text-gray-500"
+						fill="none"
+						stroke="currentColor"
+						viewBox="0 0 24 24"
+						xmlns="http://www.w3.org/2000/svg"
+					>
+						<path
+							strokeLinecap="round"
+							strokeLinejoin="round"
+							strokeWidth={1.5}
+							d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"
+						/>
+					</svg>
+					<h4 className="text-lg font-semibold text-gray-900 dark:text-gray-100 !mb-1">
+						{title || '统计摘要'}
+					</h4>
+					<p className="text-sm text-gray-500 dark:text-gray-400 max-w-md">
+						{description ||
+							'在当前模式下，您只能查看审计统计摘要。如需查看完整审计日志，请联系您的安全管理员或使用 security-dashboard 的审计员账号登录。'}
+					</p>
+					{children && (
+						<div className="w-full mt-4 pt-4 border-t border-gray-200 dark:border-slate-700">
+							{children}
+						</div>
+					)}
+				</div>
+			</div>
+		</div>
+	);
+}