@windrun-huaiin/third-ui 7.1.2 → 7.2.0

package/src/clerk/fingerprint/fingerprint-shared.ts

@@ -0,0 +1,29 @@
+/**
+ * Fingerprint Shared Utilities
+ * 客户端和服务端共享的常量、类型和验证逻辑
+ */
+
+// Fingerprint ID的存储键和header名
+export const FINGERPRINT_STORAGE_KEY = 'diaomao_fingerprint_id';
+export const FINGERPRINT_HEADER_NAME = 'x-fingerprint-id';
+export const FINGERPRINT_COOKIE_NAME = 'fingerprint_id';
+
+/**
+ * 验证fingerprint ID格式
+ * 可以在客户端和服务端使用
+ */
+export function isValidFingerprintId(fingerprintId: string): boolean {
+  if (!fingerprintId) return false;
+  // 支持多种格式：
+  // - fp_ + FingerprintJS visitorId (变长字符串)
+  // - fp_fallback_ + 时间戳_随机字符串 (客户端降级方案)
+  // - fp_server_ + 时间戳_随机字符串 (服务端降级)
+  return /^fp(_fallback|_server)?_[a-zA-Z0-9_]+$/.test(fingerprintId);
+}
+
+// 常量导出
+export const FINGERPRINT_CONSTANTS = {
+  STORAGE_KEY: FINGERPRINT_STORAGE_KEY,
+  HEADER_NAME: FINGERPRINT_HEADER_NAME,
+  COOKIE_NAME: FINGERPRINT_COOKIE_NAME,
+} as const;

package/src/clerk/fingerprint/index.ts

@@ -0,0 +1,15 @@
+'use client';
+
+// Fingerprint system client-side exports
+// This follows the design specification for fingerprint module exports
+
+// Shared utilities (can be used in any environment)
+export * from './fingerprint-shared';
+export * from './types';
+
+// Client-side utilities (browser only)
+export * from './fingerprint-client';
+
+// Client-side hooks and context
+export * from './use-fingerprint';
+export * from './fingerprint-provider';

package/src/clerk/fingerprint/server.ts

@@ -0,0 +1,9 @@
+// Fingerprint system server-side exports
+// Server-only utilities for fingerprint ID extraction and validation
+
+// Shared utilities (can be used in any environment)
+export * from './fingerprint-shared';
+export * from './types';
+
+// Server-side utilities (server only)
+export * from './fingerprint-server';

package/src/clerk/fingerprint/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Fingerprint System Types
+ * 指纹识别系统的类型定义
+ */
+
+export interface AnonymousUser {
+  userId: string;
+  fingerprintId: string;
+  status: string;
+  createdAt: string;
+}
+
+export interface Credits {
+  balanceFree: number;
+  balancePaid: number;
+  totalBalance: number;
+}
+
+export interface FingerprintConfig {
+  /** API endpoint for anonymous user initialization */
+  apiEndpoint: string;
+  /** Whether to automatically initialize the user on load */
+  autoInitialize?: boolean;
+  /** Initial credits for new users */
+  initialCredits?: number;
+}
+
+export interface UseFingerprintResult {
+  fingerprintId: string | null;
+  anonymousUser: AnonymousUser | null;
+  credits: Credits | null;
+  isLoading: boolean;
+  isInitialized: boolean;
+  error: string | null;
+  initializeAnonymousUser: () => Promise<void>;
+  refreshUserData: () => Promise<void>;
+}
+
+export interface FingerprintContextType extends UseFingerprintResult {}
+
+export interface FingerprintProviderProps {
+  children: React.ReactNode;
+  config: FingerprintConfig;
+}
+// Fetch wrapper type
+export interface FingerprintFetch {
+  (url: string | URL | Request, init?: RequestInit): Promise<Response>;
+}

package/src/clerk/fingerprint/use-fingerprint.ts

@@ -0,0 +1,208 @@
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+import { 
+  getOrGenerateFingerprintId, 
+  getFingerprintId, 
+  setFingerprintId,
+  createFingerprintHeaders
+} from './fingerprint-client';
+import type { 
+  AnonymousUser, 
+  Credits, 
+  UseFingerprintResult, 
+  FingerprintConfig 
+} from './types';
+
+/**
+ * Hook for managing fingerprint ID and anonymous user data
+ * Accepts configuration to customize API endpoint and behavior
+ */
+export function useFingerprint(config: FingerprintConfig): UseFingerprintResult {
+  const [fingerprintId, setFingerprintIdState] = useState<string | null>(null);
+  const [anonymousUser, setAnonymousUser] = useState<AnonymousUser | null>(null);
+  const [credits, setCredits] = useState<Credits | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [isInitialized, setIsInitialized] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  /**
+   * 第一阶段：初始化fingerprint ID
+   */
+  const initializeFingerprintId = useCallback(async () => {
+    if (typeof window === 'undefined') return null;
+
+    try {
+      // 优先检查现有ID
+      const existingId = getFingerprintId();
+      if (existingId) {
+        setFingerprintIdState(existingId);
+        return existingId;
+      }
+
+      // 生成新的fingerprint ID
+      const currentFingerprintId = await getOrGenerateFingerprintId();
+      setFingerprintIdState(currentFingerprintId);
+      return currentFingerprintId;
+    } catch (error) {
+      console.error('Failed to initialize fingerprint ID:', error);
+      setError('Failed to generate fingerprint ID');
+      return null;
+    }
+  }, []);
+
+  /**
+   * 第二阶段：初始化匿名用户
+   */
+  const initializeAnonymousUser = useCallback(async () => {
+    if (!fingerprintId) {
+      console.warn('Cannot initialize user without fingerprint ID');
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      const fingerprintHeaders = await createFingerprintHeaders();
+      const response = await fetch(config.apiEndpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...fingerprintHeaders,
+        },
+        body: JSON.stringify({
+          fingerprintId: fingerprintId,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new Error(errorData.error || 'Failed to initialize anonymous user');
+      }
+
+      const data = await response.json();
+      
+      if (data.success) {
+        setAnonymousUser(data.user);
+        setCredits(data.credits);
+        setIsInitialized(true);
+        
+        // 确保fingerprint ID同步
+        if (data.user.fingerprintId !== fingerprintId) {
+          setFingerprintId(data.user.fingerprintId);
+          setFingerprintIdState(data.user.fingerprintId);
+        }
+      } else {
+        throw new Error(data.error || 'Unknown error occurred');
+      }
+    } catch (err) {
+      console.error('Failed to initialize anonymous user:', err);
+      setError(err instanceof Error ? err.message : 'Unknown error');
+    } finally {
+      setIsLoading(false);
+    }
+  }, [fingerprintId]);
+
+  /**
+   * 刷新用户数据
+   */
+  const refreshUserData = useCallback(async () => {
+    if (!fingerprintId) return;
+
+    try {
+      setError(null);
+
+      const fingerprintHeaders = await createFingerprintHeaders();
+      const response = await fetch(`${config.apiEndpoint}?fingerprintId=${fingerprintId}`, {
+        method: 'GET',
+        headers: fingerprintHeaders,
+      });
+
+      if (!response.ok) {
+        if (response.status === 404) {
+          // 用户不存在，需要重新初始化
+          await initializeAnonymousUser();
+          return;
+        }
+        throw new Error('Failed to fetch user data');
+      }
+
+      const data = await response.json();
+      
+      if (data.success) {
+        setAnonymousUser(data.user);
+        setCredits(data.credits);
+      }
+    } catch (err) {
+      console.error('Failed to refresh user data:', err);
+      setError(err instanceof Error ? err.message : 'Unknown error');
+    }
+  }, [fingerprintId, initializeAnonymousUser, config.apiEndpoint]);
+
+  /**
+   * 检查现有用户数据（仅在有fingerprint ID时执行）
+   */
+  const checkExistingUser = useCallback(async () => {
+    if (!fingerprintId) return;
+
+    try {
+      const fingerprintHeaders = await createFingerprintHeaders();
+      const response = await fetch(`${config.apiEndpoint}?fingerprintId=${fingerprintId}`, {
+        method: 'GET',
+        headers: fingerprintHeaders,
+      });
+
+      if (response.ok) {
+        const data = await response.json();
+        if (data.success) {
+          setAnonymousUser(data.user);
+          setCredits(data.credits);
+          setIsInitialized(true);
+        }
+      }
+    } catch (err) {
+      console.error('Failed to check existing user:', err);
+    }
+  }, [fingerprintId, config.apiEndpoint]);
+
+  // 第一阶段：页面加载完成后生成指纹ID
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const initFingerprint = async () => {
+      await initializeFingerprintId();
+      setIsLoading(false); // 第一阶段完成，结束加载状态
+    };
+
+    initFingerprint();
+  }, [initializeFingerprintId]);
+
+  // 第二阶段：有指纹ID后检查现有用户
+  useEffect(() => {
+    if (!fingerprintId || isInitialized) return;
+
+    checkExistingUser();
+  }, [fingerprintId, isInitialized, checkExistingUser]);
+
+  // 第三阶段：如果没有现有用户且自动初始化开启，则创建新用户
+  useEffect(() => {
+    if (!fingerprintId || isInitialized || isLoading || error) return;
+    if (config.autoInitialize === false) return;
+
+    initializeAnonymousUser();
+  }, [fingerprintId, isInitialized, isLoading, error, initializeAnonymousUser, config.autoInitialize]);
+
+  return {
+    fingerprintId,
+    anonymousUser,
+    credits,
+    isLoading,
+    isInitialized,
+    error,
+    initializeAnonymousUser,
+    refreshUserData,
+  };
+}
+
+// createFingerprintFetch moved to fingerprint.ts

package/src/clerk/index.ts

@@ -1,3 +1,10 @@
 'use client';
-// Clerk related components
-export * from './clerk-provider-client';
+// Client-side exports
+export * from './clerk-provider-client';
+
+// Fingerprint-enhanced Clerk components (client-side)
+export * from './signup-with-fingerprint-client';
+export * from './signin-with-fingerprint-client';
+
+// Client-side page generators
+export * from './clerk-page-generator-client';

package/src/clerk/server.ts

@@ -1,3 +1,4 @@
+// Server-side exports - safe for SSR
 export * from './clerk-page-generator';
 export * from './clerk-user';
 export * from './clerk-organization'; 

package/src/clerk/signin-with-fingerprint-client.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import { SignIn } from '@clerk/nextjs';
+import { useEffect } from 'react';
+import { useFingerprintContextSafe } from './fingerprint/fingerprint-provider';
+
+/**
+ * SignIn component with fingerprint awareness
+ * 如果没有FingerprintProvider，会优雅降级为普通SignIn组件
+ * 如果有FingerprintProvider，会处理fingerprint相关逻辑
+ */
+export function SignInWithFingerprint() {
+  const fingerprintContext = useFingerprintContextSafe();
+  
+  // 如果没有fingerprint context，使用默认值
+  const { 
+    fingerprintId = null, 
+    anonymousUser = null, 
+    isInitialized = false,
+    initializeAnonymousUser = async () => {}
+  } = fingerprintContext || {};
+
+  // 准备传递给Clerk的metadata，包含匿名用户信息
+  const unsafeMetadata = {
+    user_id: anonymousUser?.userId || null,        // 数据库中的user_id
+    fingerprint_id: fingerprintId || null,        // 浏览器指纹ID
+  };
+
+  // 确保匿名用户已初始化
+  useEffect(() => {
+    if (!isInitialized && fingerprintId) {
+      initializeAnonymousUser();
+    }
+  }, [fingerprintId, isInitialized, initializeAnonymousUser]);
+
+  // 调试日志和处理登录逻辑
+  useEffect(() => {
+    console.log('SignInWithFingerprint Debug:', {
+      fingerprintProvider: fingerprintContext ? 'Available' : 'Not found',
+      fingerprintId: fingerprintId || 'Not generated',
+      anonymousUser: anonymousUser ? 'Initialized' : 'Not initialized',
+      clerkMetadata: unsafeMetadata
+    });
+
+    if (anonymousUser && fingerprintId) {
+      console.log('User signed in with existing anonymous data:', {
+        anonymousUserId: anonymousUser.userId,
+        fingerprintId,
+      });
+      // TODO: 实现数据合并逻辑
+    }
+  }, [anonymousUser, fingerprintId, fingerprintContext, unsafeMetadata]);
+
+  return <SignIn unsafeMetadata={unsafeMetadata} />;
+}
+
+export default SignInWithFingerprint;

package/src/clerk/signup-with-fingerprint-client.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import { SignUp } from '@clerk/nextjs';
+import { useEffect } from 'react';
+import { useFingerprintContextSafe } from './fingerprint/fingerprint-provider';
+
+/**
+ * SignUp component with fingerprint awareness
+ * 如果没有FingerprintProvider，会优雅降级为普通SignUp组件
+ * 如果有FingerprintProvider，会处理fingerprint相关逻辑
+ */
+export function SignUpWithFingerprint() {
+  const fingerprintContext = useFingerprintContextSafe();
+  
+  // 如果没有fingerprint context，使用默认值
+  const { 
+    fingerprintId = null, 
+    anonymousUser = null, 
+    isInitialized = false,
+    initializeAnonymousUser = async () => {}
+  } = fingerprintContext || {};
+
+  // 准备传递给Clerk的metadata，包含匿名用户信息
+  const unsafeMetadata = {
+    user_id: anonymousUser?.userId || null,        // 数据库中的user_id
+    fingerprint_id: fingerprintId || null,        // 浏览器指纹ID
+  };
+
+  // 确保匿名用户已初始化
+  useEffect(() => {
+    if (!isInitialized && fingerprintId) {
+      initializeAnonymousUser();
+    }
+  }, [fingerprintId, isInitialized, initializeAnonymousUser]);
+
+  // 调试日志和处理注册逻辑
+  useEffect(() => {
+    console.log('SignUpWithFingerprint Debug:', {
+      fingerprintProvider: fingerprintContext ? 'Available' : 'Not found',
+      fingerprintId: fingerprintId || 'Not generated',
+      anonymousUser: anonymousUser ? 'Initialized' : 'Not initialized',
+      clerkMetadata: unsafeMetadata
+    });
+
+    if (anonymousUser && fingerprintId) {
+      console.log('User signed up with existing anonymous data:', {
+        anonymousUserId: anonymousUser.userId,
+        fingerprintId,
+      });
+      // TODO: 实现数据迁移逻辑
+    }
+  }, [anonymousUser, fingerprintId, fingerprintContext, unsafeMetadata]);
+
+  return <SignUp unsafeMetadata={unsafeMetadata} />;
+}
+
+export default SignUpWithFingerprint;