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

package/src/seo/index.ts

@@ -0,0 +1,6 @@
+export { useSEO } from './useSEO';
+export { usePageTitle } from './usePageTitle';
+export { usePageMeta } from './usePageMeta';
+export { getArticleSchema } from './jsonld';
+export { upsertMeta, upsertCanonical, upsertLink, injectJSONLD } from './dom-utils';
+export type { SEOConfig, SiteSEOConfig, BlogPostSchema } from './types';

package/src/seo/jsonld.ts

@@ -0,0 +1,29 @@
+import type { BlogPostSchema } from './types';
+
+export function getArticleSchema(post: BlogPostSchema, baseBlogUrl: string) {
+	const article: Record<string, unknown> = {
+		'@context': 'https://schema.org',
+		'@type': 'BlogPosting',
+		headline: post.title,
+		description: post.excerpt,
+		datePublished: post.date,
+		url: `${baseBlogUrl}/${post.slug}`,
+	};
+
+	if (post.author) {
+		article.author = {
+			'@type': 'Person',
+			name: post.author,
+		};
+	}
+
+	if (post.image) {
+		article.image = post.image;
+	}
+
+	if (post.tags && post.tags.length > 0) {
+		article.keywords = post.tags.join(', ');
+	}
+
+	return article;
+}

package/src/seo/types.ts

@@ -0,0 +1,29 @@
+export interface SiteSEOConfig {
+	siteName?: string;
+	baseUrl?: string;
+	defaultOgImage?: string;
+	hreflang?: boolean;
+	hreflangLanguages?: string[];
+	hreflangXDefault?: string;
+}
+
+export interface SEOConfig {
+	title: string;
+	description: string;
+	ogImage?: string;
+	canonical?: string;
+	type?: 'website' | 'article';
+	publishedTime?: string;
+	author?: string;
+	jsonld?: object[];
+}
+
+export interface BlogPostSchema {
+	title: string;
+	excerpt: string;
+	date: string;
+	author?: string;
+	image?: string;
+	slug: string;
+	tags?: string[];
+}

package/src/seo/usePageMeta.ts

@@ -0,0 +1,17 @@
+import { useEffect } from 'react';
+
+export function usePageMeta(description: string) {
+	useEffect(() => {
+		let meta = document.querySelector('meta[name="description"]') as HTMLMetaElement | null;
+		const previous = meta?.content;
+		if (!meta) {
+			meta = document.createElement('meta');
+			meta.name = 'description';
+			document.head.appendChild(meta);
+		}
+		meta.content = description;
+		return () => {
+			if (meta && previous !== undefined) meta.content = previous;
+		};
+	}, [description]);
+}

package/src/seo/usePageTitle.ts

@@ -0,0 +1,14 @@
+import { useEffect } from 'react';
+
+const DEFAULT_SITE_NAME = 'Autional';
+
+export function usePageTitle(title: string, siteName?: string) {
+	const name = siteName || DEFAULT_SITE_NAME;
+	useEffect(() => {
+		const previous = document.title;
+		document.title = title ? `${title} — ${name}` : name;
+		return () => {
+			document.title = previous;
+		};
+	}, [title, name]);
+}

package/src/seo/useSEO.ts

@@ -0,0 +1,80 @@
+import { useEffect } from 'react';
+import type { SEOConfig, SiteSEOConfig } from './types';
+import { upsertMeta, upsertCanonical, upsertLink, injectJSONLD } from './dom-utils';
+import { SITE_BASE_URL, DEFAULT_OG_IMAGE } from '../config/constants';
+
+const DEFAULTS: Required<SiteSEOConfig> = {
+	siteName: 'Autional',
+	baseUrl: SITE_BASE_URL,
+	defaultOgImage: DEFAULT_OG_IMAGE,
+	hreflang: false,
+	hreflangLanguages: ['zh', 'en'],
+	hreflangXDefault: `${SITE_BASE_URL}/zh/`,
+};
+
+export function useSEO(config: SEOConfig, siteConfig?: SiteSEOConfig) {
+	const s = { ...DEFAULTS, ...siteConfig };
+	const { title, description, ogImage, canonical, type, publishedTime, author, jsonld } = {
+		ogImage: s.defaultOgImage,
+		type: 'website' as const,
+		...config,
+	};
+
+	useEffect(() => {
+		const pageTitle = title ? `${title} — ${s.siteName}` : s.siteName;
+		const prevTitle = document.title;
+		document.title = pageTitle;
+
+		const cleanups: (() => void)[] = [];
+
+		if (s.hreflang) {
+			try {
+				const currentPath = window.location.pathname;
+				const pathMatch = currentPath.match(/^\/(zh|en)(\/.*)?$/);
+				if (pathMatch) {
+					const pagePath = pathMatch[2] || '/';
+					for (const lang of s.hreflangLanguages) {
+						const url = `${s.baseUrl}/${lang}${pagePath === '/' ? '' : pagePath}`;
+						cleanups.push(upsertLink('alternate', url, { hreflang: lang }));
+					}
+					cleanups.push(upsertLink('alternate', s.hreflangXDefault, { hreflang: 'x-default' }));
+				}
+			} catch {
+				/* SSR-safe */
+			}
+		}
+
+		cleanups.push(upsertMeta('description', description));
+		cleanups.push(upsertMeta('og:title', pageTitle, 'property'));
+		cleanups.push(upsertMeta('og:description', description, 'property'));
+		cleanups.push(upsertMeta('og:image', ogImage, 'property'));
+		cleanups.push(upsertMeta('og:type', type, 'property'));
+		cleanups.push(upsertMeta('og:url', canonical || window.location.href, 'property'));
+		cleanups.push(upsertMeta('twitter:card', 'summary_large_image'));
+		cleanups.push(upsertMeta('twitter:title', pageTitle));
+		cleanups.push(upsertMeta('twitter:description', description));
+		cleanups.push(upsertMeta('twitter:image', ogImage));
+
+		if (type === 'article' && publishedTime) {
+			cleanups.push(upsertMeta('article:published_time', publishedTime, 'property'));
+		}
+		if (type === 'article' && author) {
+			cleanups.push(upsertMeta('article:author', author, 'property'));
+		}
+
+		if (canonical) {
+			cleanups.push(upsertCanonical(canonical));
+		}
+
+		let cleanupJSONLD: (() => void) | undefined;
+		if (jsonld && jsonld.length > 0) {
+			cleanupJSONLD = injectJSONLD(jsonld);
+		}
+
+		return () => {
+			document.title = prevTitle;
+			cleanups.forEach((fn) => fn());
+			cleanupJSONLD?.();
+		};
+	}, [title, description, ogImage, canonical, type, publishedTime, author, JSON.stringify(jsonld)]);
+}

package/src/types/index.ts

@@ -0,0 +1,190 @@
+/**
+ * Autional 共享 TypeScript 类型
+ * 所有前端应用共用
+ */
+
+// ============ 用户 ============
+
+export interface User {
+	id: string;
+	username: string;
+	email: string;
+	status: 'active' | 'inactive' | 'locked' | 'pending';
+	createdAt?: string;
+	updatedAt?: string;
+	lastLoginAt?: string;
+	avatarUrl?: string;
+	/**
+	 * 展示名（OIDC userinfo 的 nickname→name，登录时合入）。
+	 * 消费方展示优先级：displayName → username → email。
+	 */
+	displayName?: string;
+	phone?: string;
+	roles?: RoleSummary[];
+	department?: DepartmentSummary;
+	mfaEnabled?: boolean;
+	/** 后端 /auth/me 返回的扩展字段（可选，向后兼容） */
+	metadata?: Record<string, unknown>;
+	tenant_type?: string;
+	tenant_id?: string;
+}
+
+export interface RoleSummary {
+	id: string;
+	name: string;
+}
+
+export interface DepartmentSummary {
+	id: string;
+	name: string;
+}
+
+// ============ 认证 ============
+
+export interface LoginRequest {
+	identity: string;
+	password: string;
+}
+
+export interface LoginResponse {
+	accessToken: string;
+	refreshToken: string;
+	expiresIn?: number;
+	tokenType?: string;
+	user: User;
+}
+
+export interface RegisterRequest {
+	username: string;
+	email: string;
+	password: string;
+}
+
+// ============ 租户 ============
+
+export interface Tenant {
+	id: string;
+	name: string;
+	domain?: string;
+	status: 'active' | 'suspended' | 'pending';
+	createdAt?: string;
+}
+
+export interface TenantMember {
+	userId: string;
+	username: string;
+	email: string;
+	role: 'owner' | 'admin' | 'member';
+	status: string;
+	joinedAt?: string;
+}
+
+// ============ RBAC ============
+
+export interface Role {
+	id: string;
+	code: string;
+	name: string;
+	description: string;
+}
+
+export interface Permission {
+	id: string;
+	code: string;
+	name: string;
+	description: string;
+	category: string;
+}
+
+// ============ 应用 ============
+
+export interface Application {
+	id: string;
+	name: string;
+	type: 'oidc' | 'saml' | 'custom';
+	clientId: string;
+	status: string;
+	redirectUris: string[];
+	createdAt?: string;
+}
+
+// ============ 审计 ============
+
+export interface AuditLog {
+	id: string;
+	createdAt: string;
+	actorId: string;
+	actorName: string;
+	action: string;
+	resourceType: string;
+	resourceId: string;
+	description: string;
+	result: 'success' | 'failure';
+	ipAddress: string;
+}
+
+// ============ 会话 ============
+
+export interface Session {
+	id: string;
+	userId: string;
+	username: string;
+	ipAddress: string;
+	device: string;
+	browser: string;
+	location: string;
+	riskScore: number;
+	createdAt: string;
+	lastActiveAt: string;
+}
+
+// ============ 部门 ============
+
+export interface Department {
+	id: string;
+	name: string;
+	parentId?: string;
+	memberCount: number;
+}
+
+// ============ 列表响应 ============
+
+export interface ListResponse<T> {
+	items: T[];
+	total: number;
+	pagination?: {
+		page: number;
+		pageSize: number;
+		totalPages: number;
+	};
+}
+
+// ============ 分页请求 ============
+
+export interface PageRequest {
+	page?: number;
+	pageSize?: number;
+}
+
+// ============ API 错误 ============
+
+export interface ApiError {
+	code: string;
+	message: string;
+}
+
+// ============ 后端原始响应 ============
+
+export interface ApiResponse<T> {
+	code: number;
+	message: string;
+	data?: T;
+	items?: T[];
+	total?: number;
+	pagination?: {
+		page: number;
+		pageSize: number;
+		totalPages: number;
+	};
+	timestamp?: number;
+}

package/src/utils/__tests__/case.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'vitest';
+import { snakeCaseKeys, camelCaseKeys } from '../case';
+
+// U385 回归锁（AC-AUTH-39/U385）：snakeCaseKeys 必须 acronym-aware。
+// 此前朴素正则（每个大写字母前插 `_`）把 WebAuthn 请求体的 camel 键 mangling：
+//   clientDataJSON → client_data_j_s_o_n（服务端期望 client_data_json，go-webauthn 校验恒败）
+// 真实受害链：passkey begin/complete 请求经 apiClient 拦截器后键名错位 → 400/校验失败。
+describe('snakeCaseKeys acronym-aware（U385）', () => {
+	it('WebAuthn camel 键族 → 正确 snake（旧实现 mangling 的键）', () => {
+		expect(
+			snakeCaseKeys({
+				clientDataJSON: 'cdj',
+				attestationObject: 'ao',
+				rawId: 'rid',
+				userHandle: 'uh',
+				transports: ['usb'],
+			}),
+		).toEqual({
+			client_data_json: 'cdj',
+			attestation_object: 'ao',
+			raw_id: 'rid',
+			user_handle: 'uh',
+			transports: ['usb'],
+		});
+	});
+
+	it('尾部缩写：userID → user_id、testID → test_id（旧实现 user_i_d/test_i_d）', () => {
+		expect(snakeCaseKeys({ userID: 'u', testID: 't' })).toEqual({ user_id: 'u', test_id: 't' });
+	});
+
+	it('前导缩写：URLValue → url_value、APIVersion → api_version、HTMLParser → html_parser', () => {
+		expect(
+			snakeCaseKeys({ URLValue: 'v', APIVersion: 'v1', HTMLParser: true }),
+		).toEqual({ url_value: 'v', api_version: 'v1', html_parser: true });
+	});
+
+	it('数字边界：sha256Value → sha256_value、base64URL → base64_url', () => {
+		expect(snakeCaseKeys({ sha256Value: 'v', base64URL: 'b' })).toEqual({
+			sha256_value: 'v',
+			base64_url: 'b',
+		});
+	});
+
+	it('常规 camel 不回归：pageSize/currentPage（contract G1 同口径）', () => {
+		expect(snakeCaseKeys({ pageSize: 20, currentPage: 2 })).toEqual({
+			page_size: 20,
+			current_page: 2,
+		});
+	});
+
+	it('已是 snake 的字面量键原样保留（含下划线/全小写）', () => {
+		expect(snakeCaseKeys({ client_data_json: 'v', plain: 1 })).toEqual({
+			client_data_json: 'v',
+			plain: 1,
+		});
+	});
+
+	it('深递归：嵌套对象/数组同样走 acronym-aware 转换', () => {
+		expect(snakeCaseKeys({ webAuthn: { clientDataJSON: 'x', list: [{ rawID: 'r' }] } })).toEqual({
+			web_authn: { client_data_json: 'x', list: [{ raw_id: 'r' }] },
+		});
+	});
+});
+
+// U407 wire 约定锁定：数字贴词尾（`_<数字>` 形态对 lodash camel 折叠不可逆，wire 禁止使用）。
+// 原 wire 键 live_stream_blocked_under_16 与 under16 在响应方向折叠为同名 liveStreamBlockedUnder16
+// ⇒ 请求方向无法还原下划线位置（line1/under_16 同形歧义）。平台侧已把该字段归一为
+// live_stream_blocked_under16（service-tenant U407），本锁固定双向往返无损 + 反例（下划线-数字形态不可逆）。
+describe('snakeCaseKeys ↔ camelCaseKeys 往返（U407 wire 键约定：数字贴词）', () => {
+	it('live_stream_blocked_under16 双向无损（平台 minors 字段现行 wire 形态）', () => {
+		expect(snakeCaseKeys({ liveStreamBlockedUnder16: true })).toEqual({
+			live_stream_blocked_under16: true,
+		});
+		expect(camelCaseKeys({ live_stream_blocked_under16: true })).toEqual({
+			liveStreamBlockedUnder16: true,
+		});
+	});
+
+	it('反例说明：下划线-数字形态（under_16）不可由 camel 还原——故 wire 禁用该形态', () => {
+		// camelCaseKeys 折叠后与 under16 同名；snakeCaseKeys 只能还原出 under16，不可能知道下划线位置。
+		expect(camelCaseKeys({ under_16: true })).toEqual({ under16: true });
+		expect(snakeCaseKeys({ under16: true })).toEqual({ under16: true });
+	});
+});
+
+// camelCaseKeys 回归边界：lodash camelCase 对缩写的行为（响应方向契约，保持现状即可）
+describe('camelCaseKeys 响应方向（现状锁定）', () => {
+	it('snake → camel；缩写键由 lodash 归一为小写驼峰（client_data_json → clientDataJson）', () => {
+		expect(camelCaseKeys({ client_data_json: 'v', page_size: 10 })).toEqual({
+			clientDataJson: 'v',
+			pageSize: 10,
+		});
+	});
+});

package/src/utils/__tests__/error.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { extractApiError, extractApiErrorMessage } from '../error';
+
+// UP-17-B 回归锁（AC-401）：extractApiError message 键链。
+// 后端 Problem 契约（service-core/base/dto/problem.go）为 title 必填 / detail / code / i18n_key，无 message；
+// 只认 message 会把 Problem 类错误整类退化为 defaultMsg。
+describe('extractApiError message 键链（UP-17-B / AC-401）', () => {
+	it('title 优先：Problem 契约（title/detail/code）→ 取 title', () => {
+		const err = {
+			response: { data: { code: 403, title: '平台级访问受限', detail: '需要平台角色' } },
+		};
+		const out = extractApiError(err, 'fallback');
+		expect(out.message).toBe('平台级访问受限');
+		expect(out.code).toBe(403);
+	});
+
+	it('detail 兜底：无 message/title 时取 detail', () => {
+		const err = { response: { data: { detail: '令牌已过期' } } };
+		expect(extractApiError(err, 'fallback').message).toBe('令牌已过期');
+	});
+
+	it('皆无回落 err.message，再皆无回落 defaultMsg', () => {
+		expect(extractApiError(new Error('network boom'), 'fallback').message).toBe('network boom');
+		expect(extractApiError({}, 'fallback').message).toBe('fallback');
+		expect(extractApiError(undefined, 'fallback')).toEqual({ code: 'UNKNOWN', message: 'fallback' });
+	});
+
+	it('业务信封（code+message）不回归：message 仍优先于 title', () => {
+		const err = {
+			response: { data: { code: 61040010, message: 'TOTP already enabled', title: 'Conflict' } },
+		};
+		expect(extractApiError(err, 'fallback')).toEqual({
+			code: 61040010,
+			message: 'TOTP already enabled',
+		});
+		expect(extractApiErrorMessage(err, 'fallback')).toBe('TOTP already enabled');
+	});
+});
+
+// AUTH-46 回归锁：i18n_key 透出（消费方按 key 映射本地化文案，不再暴露英文裸句）。
+describe('extractApiError i18n_key 透出（AUTH-46）', () => {
+	it('Problem 体带 i18n_key → i18nKey 字段透出（snake 形）', () => {
+		const err = {
+			response: {
+				data: {
+					code: 400,
+					title: 'Invalid Parameter',
+					detail: 'state not found',
+					i18n_key: 'error.oauth_state_missing',
+				},
+			},
+		};
+		const out = extractApiError(err, 'fallback');
+		expect(out.i18nKey).toBe('error.oauth_state_missing');
+		// message 键链不回归（title 优先于 detail）
+		expect(out.message).toBe('Invalid Parameter');
+	});
+
+	it('响应拦截器深 camel 后（i18nKey）同样识别', () => {
+		const err = { response: { data: { code: 400, i18nKey: 'error.sso_provider_not_configured' } } };
+		expect(extractApiError(err, 'fallback').i18nKey).toBe('error.sso_provider_not_configured');
+	});
+
+	it('无 i18n_key → undefined（向后兼容，不改变既有形状）', () => {
+		expect(extractApiError(new Error('boom'), 'fallback').i18nKey).toBeUndefined();
+		expect(extractApiError({}, 'fallback')).toEqual({
+			code: 'UNKNOWN',
+			message: 'fallback',
+			i18nKey: undefined,
+		});
+	});
+});

package/src/utils/__tests__/mock-test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect, vi } from 'vitest';
+
+// Mock from test's relative path
+vi.mock('../../generated/api', () => ({
+	PublicKeyExchange: vi.fn(() => Promise.resolve({ server_pub_key: 'x', key_exchange_id: 'y' })),
+}));
+
+import { PublicKeyExchange as pk } from '../../generated/api';
+
+describe('mock test', () => {
+	it('should return mock value', async () => {
+		const result = await pk();
+		expect(result).toEqual({ server_pub_key: 'x', key_exchange_id: 'y' });
+	});
+});

package/src/utils/__tests__/page.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import { toPageParams, fromPageResult } from '../page';
+
+describe('toPageParams（AC-AB1-29 请求侧）', () => {
+	it('camel 入参 → 输出键集恰为 page/page_size（无 camel 残留）', () => {
+		const out = toPageParams({ page: 2, pageSize: 20 });
+		expect(Object.keys(out).sort()).toEqual(['page', 'page_size']);
+		expect(out).toEqual({ page: 2, page_size: 20 });
+		expect('pageSize' in out).toBe(false);
+	});
+
+	it('pageSize 缺省不输出键', () => {
+		expect(toPageParams({ page: 1 })).toEqual({ page: 1 });
+		expect(Object.keys(toPageParams())).toEqual([]);
+		expect(Object.keys(toPageParams({ pageSize: 5 }))).toEqual(['page_size']);
+	});
+});
+
+describe('fromPageResult（AC-AB1-29 响应侧三形态归一）', () => {
+	it('扁平 {items,total} → items/total/page/page_size', () => {
+		const out = fromPageResult<{ id: string }>({
+			items: [{ id: 'a' }, { id: 'b' }],
+			total: 42,
+			page: 2,
+			page_size: 20,
+		});
+		expect(out.items).toHaveLength(2);
+		expect(out.total).toBe(42);
+		expect(out.page).toBe(2);
+		expect(out.page_size).toBe(20);
+	});
+
+	it('信封 {data:{items,total}} → 归一成功（total 取 data.total）', () => {
+		const out = fromPageResult<{ id: string }>({
+			data: { items: [{ id: 'x' }], total: 7, page: 3, page_size: 10 },
+		});
+		expect(out.items).toEqual([{ id: 'x' }]);
+		expect(out.total).toBe(7);
+		expect(out.page).toBe(3);
+		expect(out.page_size).toBe(10);
+	});
+
+	it('裸数组 → items 为数组本体，total 取长度', () => {
+		const out = fromPageResult<string>(['a', 'b', 'c']);
+		expect(out.items).toEqual(['a', 'b', 'c']);
+		expect(out.total).toBe(3);
+	});
+
+	it('空输入 → 空列表零值，不抛错', () => {
+		const out = fromPageResult(null);
+		expect(out.items).toEqual([]);
+		expect(out.total).toBe(0);
+	});
+});