@windrun-huaiin/backend-core 10.0.1

package/prisma/schema.prisma

@@ -0,0 +1,191 @@
+// NOTE:
+// - generator/datasource 配置仅为示例，合并到宿主时请以宿主的 schema 为准，必要时删除/覆盖本段。
+// - models 定义可直接复用，数据库连接信息应由宿主自行配置。
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+  schemas  = ["nextai", "public"]
+}
+
+model User {
+  id            BigInt         @id @default(autoincrement())
+  userId        String         @unique @default(dbgenerated("gen_random_uuid()")) @map("user_id") @db.Uuid
+  status        String         @default("anonymous") @db.VarChar(50)
+  fingerprintId String?        @map("fingerprint_id") @db.VarChar(255)
+  clerkUserId   String?        @unique @map("clerk_user_id") @db.VarChar(255)
+  stripeCusId   String?        @unique @map("stripe_cus_id") @db.VarChar(255)
+  email         String?        @db.VarChar(255)
+  userName String?        @map("user_name") @db.VarChar(255)
+  createdAt     DateTime?      @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt     DateTime?      @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(6)
+  sourceRef     Json?          @map("source_ref")
+  creditAuditLogs   CreditAuditLog[]
+  credit       Credit?
+  subscription  Subscription?
+  transactions  Transaction[]
+
+  @@index([fingerprintId], map: "idx_users_fingerprint_id")
+  @@map("users")
+
+  @@schema("nextai")
+}
+
+model Subscription {
+  id                BigInt    @id @default(autoincrement())
+  userId            String    @unique @map("user_id") @db.Uuid
+  status            String    @default("incomplete") @db.VarChar(50)
+  paySubscriptionId String?   @map("pay_subscription_id") @db.VarChar(255)
+  orderId           String?    @map("order_id") @db.VarChar(255)
+  priceId           String?   @map("price_id") @db.VarChar(255)
+  priceName         String?   @map("price_name") @db.VarChar(255)
+  creditsAllocated  Int       @default(0) @map("credits_allocated")
+  subPeriodStart    DateTime? @map("sub_period_start") @db.Timestamptz(6)
+  subPeriodEnd      DateTime? @map("sub_period_end") @db.Timestamptz(6)
+  createdAt         DateTime? @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt         DateTime? @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(6)
+  deleted           Int       @default(0)
+  user              User      @relation(fields: [userId], references: [userId], onDelete: NoAction, onUpdate: NoAction)
+
+  @@index([paySubscriptionId], map: "idx_subscriptions_pay_subscription_id")
+  @@index([orderId], map: "idx_subscriptions_order_id")
+  @@map("subscriptions")
+
+  @@schema("nextai")
+}
+
+model Credit {
+  id             BigInt    @id @default(autoincrement())
+  userId         String    @unique @map("user_id") @db.Uuid
+
+  // ===== 免费积分 =====
+  balanceFree    Int       @default(0) @map("balance_free")
+  totalFreeLimit Int       @default(0) @map("total_free_limit")
+  freeStart      DateTime? @map("free_start") @db.Timestamptz(6)
+  freeEnd        DateTime? @map("free_end") @db.Timestamptz(6)
+
+  // ===== 订阅付费积分 =====
+  balancePaid    Int       @default(0) @map("balance_paid")
+  totalPaidLimit Int       @default(0) @map("total_paid_limit")
+  paidStart      DateTime? @map("paid_start") @db.Timestamptz(6)
+  paidEnd        DateTime? @map("paid_end") @db.Timestamptz(6)
+
+  // ===== 一次性支付积分 =====
+  balanceOneTimePaid    Int       @default(0) @map("balance_onetime_paid")
+  totalOneTimePaidLimit Int       @default(0) @map("total_onetime_paid_limit")
+  oneTimePaidStart      DateTime? @map("onetime_paid_start") @db.Timestamptz(6)
+  oneTimePaidEnd        DateTime? @map("onetime_paid_end") @db.Timestamptz(6)
+
+  createdAt      DateTime? @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt      DateTime? @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(6)
+  user           User      @relation(fields: [userId], references: [userId], onDelete: NoAction, onUpdate: NoAction)
+
+  @@index([userId], map: "idx_credits_user_id")
+  @@map("credits")
+
+  @@schema("nextai")
+}
+
+model Transaction {
+  id                BigInt    @id @default(autoincrement())
+  userId            String    @map("user_id") @db.Uuid
+  orderId           String    @unique @map("order_id") @db.VarChar(255)
+  orderStatus       String    @default("created") @map("order_status") @db.VarChar(50)
+  orderCreatedAt    DateTime? @default(now()) @map("order_created_at") @db.Timestamptz(6)
+  orderExpiredAt    DateTime? @map("order_expired_at") @db.Timestamptz(6)
+  orderUpdatedAt    DateTime? @default(now()) @updatedAt @map("order_updated_at") @db.Timestamptz(6)
+  type              String?   @db.VarChar(50)
+  paySupplier       String?   @map("pay_supplier") @db.VarChar(255)
+  paySessionId      String?   @map("pay_session_id") @db.VarChar(255)
+  payTransactionId  String?   @unique @map("pay_transaction_id") @db.VarChar(255)
+  paySubscriptionId String?   @map("pay_subscription_id") @db.VarChar(255)
+  subPeriodStart    DateTime? @map("sub_period_start") @db.Timestamptz(6)
+  subPeriodEnd      DateTime? @map("sub_period_end") @db.Timestamptz(6)
+  subLastTryCancelAt  DateTime? @map("sub_last_try_cancel_at") @db.Timestamptz(6)
+  subPeriodCanceledAt      DateTime? @map("sub_period_canceled_at") @db.Timestamptz(6)
+  subCancellationDetail  String?   @map("sub_cancellation_detail") @db.Text
+  priceId           String?   @map("price_id") @db.VarChar(255)
+  priceName         String?   @map("price_name") @db.VarChar(255)
+  amount            Decimal?  @db.Decimal(10, 2)
+  currency          String?   @db.VarChar(50)
+  creditsGranted    Int?      @default(0) @map("credits_granted")
+  payInvoiceId      String?   @map("pay_invoice_id") @db.VarChar(255)
+  paymentStatus String    @default("un_paid") @map("payment_status") @db.VarChar(50)
+  billingReason     String?   @map("billing_reason") @db.VarChar(100)
+  hostedInvoiceUrl  String?   @map("hosted_invoice_url") @db.Text
+  invoicePdf        String?   @map("invoice_pdf") @db.Text
+  orderDetail       String?   @map("order_detail")
+  paidEmail         String?   @map("paid_email") @db.VarChar(255)
+  paidAt            DateTime? @map("paid_at") @db.Timestamptz(6)
+  paidDetail        String?   @map("paid_detail")
+  payUpdatedAt      DateTime? @map("pay_updated_at") @db.Timestamptz(6)
+  deleted           Int       @default(0)
+  user              User      @relation(fields: [userId], references: [userId], onDelete: NoAction, onUpdate: NoAction)
+
+  @@index([orderId], map: "idx_transactions_order_id")
+  @@index([paySubscriptionId], map: "idx_transactions_pay_subscription_id")
+  @@index([userId], map: "idx_transactions_user_id")
+  @@map("transactions")
+
+  @@schema("nextai")
+}
+
+model CreditAuditLog {
+  id            BigInt    @id @default(autoincrement())
+  userId        String    @map("user_id") @db.Uuid
+  creditsChange   Int       @map("credits_change")
+  feature       String?   @db.VarChar(255)
+  creditType    String    @map("credit_type") @db.VarChar(50)
+  operationType String    @map("operation_type") @db.VarChar(100)
+  operationReferId       String?   @map("operation_refer_id") @db.VarChar(255)
+  createdAt     DateTime? @default(now()) @map("created_at") @db.Timestamptz(6)
+  deleted       Int       @default(0)
+  user          User      @relation(fields: [userId], references: [userId], onDelete: NoAction, onUpdate: NoAction)
+
+  @@index([creditType], map: "idx_credit_audit_log_credit_type")
+  @@index([operationType], map: "idx_credit_audit_log_operation_type")
+  @@index([userId], map: "idx_credit_audit_log_user_id")
+  @@map("credit_audit_log")
+
+  @@schema("nextai")
+}
+
+model UserBackup {
+  id             BigInt    @id @default(autoincrement())
+  originalUserId String    @map("original_user_id") @db.Uuid
+  status         String?   @db.VarChar(50)
+  fingerprintId  String?   @map("fingerprint_id") @db.VarChar(255)
+  clerkUserId    String?   @map("clerk_user_id") @db.VarChar(255)
+  stripeCusId   String?    @map("stripe_cus_id") @db.VarChar(255)
+  email          String?   @db.VarChar(255)
+  userName String?        @map("user_name") @db.VarChar(255)
+  backupData     Json?     @map("backup_data")
+  deletedAt      DateTime? @default(now()) @map("deleted_at") @db.Timestamptz(6)
+  createdAt      DateTime? @default(now()) @map("created_at") @db.Timestamptz(6)
+  deleted        Int       @default(0)
+
+  @@index([clerkUserId], map: "idx_user_backup_clerk_user_id")
+  @@index([email], map: "idx_user_backup_email")
+  @@index([fingerprintId], map: "idx_user_backup_fingerprint_id")
+  @@index([originalUserId], map: "idx_user_backup_original_user_id")
+  @@map("user_backup")
+
+   @@schema("nextai")
+}
+
+model Apilog {
+  id         BigInt    @id @default(autoincrement())
+  apiType    String    @map("api_type") @db.VarChar(100)
+  methodName String    @map("method_name") @db.VarChar(255)
+  summary    String?
+  request    String?
+  response   String?
+  createdAt  DateTime? @default(now()) @map("created_at") @db.Timestamptz(6)
+
+  @@map("apilog")
+
+  @@schema("nextai")
+}

package/src/app/api/stripe/checkout/route.ts

@@ -0,0 +1,145 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+import {
+  createCheckoutSession,
+  createOrGetCustomer,
+  ActiveSubscriptionExistsError,
+} from '../../../../lib/stripe-config';
+import {
+  transactionService,
+  TransactionType,
+  OrderStatus,
+  PaySupplier,
+  PaymentStatus
+} from '../../../../services/database/index';
+import { ApiAuthUtils } from '../../../../lib/auth-utils';
+import { getPriceConfig } from '../../../../lib/money-price-config';
+
+// Request validation schema
+const createCheckoutSchema = z.object({
+  priceId: z.string().min(1, 'PriceID is required'),
+  plan: z.string().min(1, 'Plan is required'),
+  billingType: z.string().min(1, 'BillingType is required'),
+  provider: z.string().min(1, 'Provider is required'),
+});
+
+export async function POST(request: NextRequest) {
+  try {
+    // Parse request body
+    const body = await request.json();
+    const { priceId, plan, billingType, provider } = createCheckoutSchema.parse(body);
+
+    console.log(`Create Checkout: ${priceId} | ${plan} | ${billingType} | ${provider}`);
+
+    // Use unified authentication to get user info
+    const authUtils = new ApiAuthUtils(request);
+    const { user } = await authUtils.requireAuthWithUser();
+
+    // Validate price configuration
+    const priceConfig = getPriceConfig(priceId, plan, billingType, provider);
+    if (!priceConfig) {
+      return NextResponse.json(
+        { error: 'Invalid price configuration' },
+        { status: 400 }
+      );
+    }
+
+    // Create or get Stripe customer
+    const customerId = await createOrGetCustomer({
+      userId: user.userId,
+    });
+
+    // Generate order ID
+    const orderId = `order_${Date.now()}_${Math.random().toString(36).substring(2)}`;
+
+    // Default URLs if not provided
+    const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || 'http://localhost:3000';
+    const defaultSuccessUrl = `${baseUrl}`;
+    const defaultCancelUrl = `${baseUrl}`;
+
+    // Create Stripe checkout session with interval for dynamic mode
+
+    const basciParams = {
+      priceId,
+      customerId,
+      clientReferenceId: user.userId,
+      successUrl: defaultSuccessUrl,
+      cancelUrl: defaultCancelUrl,
+      interval: priceConfig.interval, // ✅ Pass interval to auto-determine mode
+      metadata: {
+        order_id: orderId,
+        user_id: user.userId,
+        price_name: priceConfig.priceName,
+        credits_granted: priceConfig.credits?.toString() || '',
+      }
+    }
+
+    const subscriptionData = {
+      metadata: {
+        order_id: orderId,
+        user_id: user.userId,
+      },
+    };
+    const session = await createCheckoutSession(basciParams,subscriptionData);
+
+    // Create transaction record with session info
+    const orderType = priceConfig.interval && priceConfig.interval !== 'onetime' ? TransactionType.SUBSCRIPTION : TransactionType.ONE_TIME;
+    await transactionService.createTransaction({
+      userId: user.userId,
+      orderId,
+      orderStatus: OrderStatus.CREATED,
+      paymentStatus: PaymentStatus.UN_PAID,
+      paySupplier: PaySupplier.STRIPE,
+      paySessionId: session.id,
+      priceId,
+      priceName: priceConfig.priceName,
+      amount: priceConfig.amount,
+      currency: priceConfig.currency,
+      type: orderType,
+      creditsGranted: priceConfig.credits,
+      orderDetail: priceConfig.description,
+      paidEmail: null
+    });
+
+    return NextResponse.json({
+      success: true,
+      data: {
+        sessionId: session.id,
+        sessionUrl: session.url,
+        orderId,
+        priceConfig: {
+          priceName: priceConfig.priceName,
+          amount: priceConfig.amount,
+          currency: priceConfig.currency,
+          credits: priceConfig.credits,
+          description: priceConfig.description,
+        },
+      },
+    });
+
+  } catch (error) {
+    console.error('Create checkout error:', error);
+
+    if (error instanceof ActiveSubscriptionExistsError) {
+      return NextResponse.json(
+        {
+          error: 'Active subscription exists',
+          detail: 'Please use the customer portal to manage your existing subscription.',
+        },
+        { status: 409 }
+      );
+    }
+
+    if (error instanceof z.ZodError) {
+      return NextResponse.json(
+        { error: 'Validation error', details: error.issues },
+        { status: 400 }
+      );
+    }
+
+    return NextResponse.json(
+      { error: 'Failed to create checkout session' },
+      { status: 500 }
+    );
+  }
+}

package/src/app/api/stripe/customer-portal/route.ts

@@ -0,0 +1,83 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+import {
+  createCustomerPortalSession,
+  createOrGetCustomer,
+} from '../../../../lib/stripe-config';
+import { ApiAuthUtils } from '../../../../lib/auth-utils';
+import { subscriptionService } from '../../../../services/database/index';
+
+const createCustomerPortalSchema = z
+  .object({
+    returnUrl: z.string().min(1).optional(),
+  })
+  .optional();
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json().catch(() => ({}));
+    const parsed = createCustomerPortalSchema.parse(body);
+    const returnUrlInput = parsed?.returnUrl;
+
+    const authUtils = new ApiAuthUtils(request);
+    const { user } = await authUtils.requireAuthWithUser();
+
+    const activeSubscription = await subscriptionService.getActiveSubscription(user.userId);
+    if (!activeSubscription) {
+      return NextResponse.json(
+        { error: 'No active subscription' },
+        { status: 403 }
+      );
+    }
+
+    const customerId = await createOrGetCustomer({
+      userId: user.userId,
+    });
+
+    const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || 'http://localhost:3000';
+    const resolvedReturnUrl = resolveReturnUrl(returnUrlInput, baseUrl);
+
+    const session = await createCustomerPortalSession({
+      customerId,
+      returnUrl: resolvedReturnUrl,
+    });
+
+    return NextResponse.json({
+      success: true,
+      data: {
+        sessionId: session.id,
+        sessionUrl: session.url,
+      },
+    });
+  } catch (error) {
+    console.error('Create customer portal error:', error);
+
+    if (error instanceof z.ZodError) {
+      return NextResponse.json(
+        { error: 'Validation error', details: error.issues },
+        { status: 400 }
+      );
+    }
+
+    return NextResponse.json(
+      { error: 'Failed to create customer portal session' },
+      { status: 500 }
+    );
+  }
+}
+
+function resolveReturnUrl(returnUrl: string | undefined, baseUrl: string): string {
+  if (!returnUrl) {
+    return baseUrl;
+  }
+
+  try {
+    return new URL(returnUrl).toString();
+  } catch {
+    try {
+      return new URL(returnUrl, baseUrl).toString();
+    } catch {
+      return baseUrl;
+    }
+  }
+}

package/src/app/api/user/anonymous/init/route.ts

@@ -0,0 +1,284 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+// Fix BigInt serialization issue
+(BigInt.prototype as any).toJSON = function () {
+  return this.toString();
+};
+
+import { userAggregateService } from '../../../../../services/aggregate/index';
+import { XCredit, XSubscription, XUser } from '@windrun-huaiin/third-ui/fingerprint';
+import { extractFingerprintFromNextRequest } from '@windrun-huaiin/third-ui/fingerprint/server';
+import { auth } from '@clerk/nextjs/server';
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  applyUserMockContext,
+  fetchLatestUserContextByFingerprintId,
+  fetchUserContextByClerkUserId,
+  mapCreditToXCredit,
+  mapSubscriptionToXSubscription,
+  mapUserToXUser,
+  type UserContextEntities,
+} from '../../../../../services/context/user-context-service';
+import type { Prisma } from '../../../../../services/database/prisma-model-type';
+
+
+// ==================== 类型定义 ====================
+
+/** 成功响应数据 */
+interface XUserResponse {
+  success: true;
+  xUser: XUser;
+  xCredit: XCredit | null;
+  xSubscription: XSubscription | null;
+  isNewUser: boolean;
+  totalUsersOnDevice?: number;
+  hasAnonymousUser?: boolean;
+}
+
+/** 错误响应数据 */
+interface ErrorResponse {
+  error: string;
+}
+
+// ==================== 工具函数 ====================
+
+/** 创建成功响应对象 */
+function createSuccessResponse(params: {
+  entities: UserContextEntities;
+  isNewUser: boolean;
+  options?: {
+    totalUsersOnDevice?: number;
+    hasAnonymousUser?: boolean;
+  };
+}): XUserResponse {
+  const response: XUserResponse = {
+    success: true,
+    xUser: mapUserToXUser(params.entities.user),
+    xCredit: params.entities.credit ? mapCreditToXCredit(params.entities.credit) : null,
+    xSubscription: mapSubscriptionToXSubscription(params.entities.subscription),
+    isNewUser: params.isNewUser,
+    ...params.options,
+  };
+
+  return applyUserMockContext(response);
+}
+
+/** 创建错误响应 */
+function createErrorResponse(message: string, status = 400): NextResponse {
+  const errorResponse: ErrorResponse = { error: message };
+  return NextResponse.json(errorResponse, { status });
+}
+
+type SourceRefData = Prisma.InputJsonObject & {
+  httpRefer?: string;
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+  ref?: string;
+};
+
+type SourceRefKey = 'utmSource' | 'utmMedium' | 'utmCampaign' | 'utmTerm' | 'utmContent' | 'ref';
+
+const SOURCE_REF_MAX_LENGTH = 2048;
+const QUERY_PARAM_MAX_LENGTH = 512;
+
+function normalizeSourceRef(ref: string | null): string | null {
+  if (!ref) {
+    return null;
+  }
+
+  const trimmed = ref.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  return trimmed.length > SOURCE_REF_MAX_LENGTH
+    ? trimmed.slice(0, SOURCE_REF_MAX_LENGTH)
+    : trimmed;
+}
+
+function normalizeQueryParam(value: string | null): string | null {
+  if (!value) {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  return trimmed.length > QUERY_PARAM_MAX_LENGTH
+    ? trimmed.slice(0, QUERY_PARAM_MAX_LENGTH)
+    : trimmed;
+}
+
+function applySearchParams(sourceRef: SourceRefData, params: URLSearchParams) {
+  const setIfEmpty = (key: SourceRefKey, value: string | null) => {
+    if (sourceRef[key] !== undefined) {
+      return;
+    }
+    const normalized = normalizeQueryParam(value);
+    if (normalized) {
+      sourceRef[key] = normalized;
+    }
+  };
+
+  setIfEmpty('utmSource', params.get('utm_source'));
+  setIfEmpty('utmMedium', params.get('utm_medium'));
+  setIfEmpty('utmCampaign', params.get('utm_campaign'));
+  setIfEmpty('utmTerm', params.get('utm_term'));
+  setIfEmpty('utmContent', params.get('utm_content'));
+  setIfEmpty('ref', params.get('ref'));
+}
+
+// 提取用户首次访问来源
+function extractSourceRef(request: NextRequest): SourceRefData | null {
+  const headerRef = request.headers.get('referer') || request.headers.get('referrer');
+  const customRef = request.headers.get('x-source-ref');
+  const queryRef = request.nextUrl.searchParams.get('ref');
+  console.log({
+    headerRef,
+    customRef,
+    queryRef
+  })
+
+  const sourceRef: SourceRefData = {};
+
+  let normalizedHttpRef: string | null = null;
+  const candidates = [headerRef, customRef, queryRef];
+  for (const candidate of candidates) {
+    const normalized = normalizeSourceRef(candidate);
+    if (normalized) {
+      normalizedHttpRef = normalized;
+      sourceRef.httpRefer = normalized;
+      break;
+    }
+  }
+
+  const searchParams = request.nextUrl.searchParams;
+  applySearchParams(sourceRef, searchParams);
+
+  if (normalizedHttpRef) {
+    try {
+      const refererUrl = new URL(normalizedHttpRef);
+      applySearchParams(sourceRef, refererUrl.searchParams);
+    } catch (error) {
+      console.warn('Failed to parse referer url for utm/ref:', error);
+    }
+  }
+
+  return Object.keys(sourceRef).length > 0 ? sourceRef : null;
+}
+
+
+/**
+ * 根据fingerprint_id查询用户并返回响应数据
+ */
+async function getUserByClerkId(clerkUserId: string): Promise<XUserResponse | null> {
+  const entities = await fetchUserContextByClerkUserId(clerkUserId);
+  if (!entities) {
+    return null;
+  }
+
+  return createSuccessResponse({
+    entities,
+    isNewUser: false,
+  });
+}
+
+/**
+ * 根据fingerprint_id查询用户并返回响应数据
+ */
+async function getUserByFingerprintId(fingerprintId: string): Promise<XUserResponse | null> {
+  const result = await fetchLatestUserContextByFingerprintId(fingerprintId);
+  if (!result) {
+    return null;
+  }
+
+  const { totalUsersOnDevice, hasAnonymousUser, ...entities } = result;
+
+  return createSuccessResponse({
+    entities,
+    isNewUser: false,
+    options: {
+      totalUsersOnDevice,
+      hasAnonymousUser,
+    },
+  });
+}
+
+/**
+ * 通用的fingerprint处理逻辑
+ */
+async function handleFingerprintRequest(request: NextRequest, options: { createIfNotExists?: boolean; } = {}) {
+  // 从请求中提取fingerprint ID
+  const fingerprintId = extractFingerprintFromNextRequest(request);
+  // 验证fingerprint ID
+  if (!fingerprintId) {
+    return createErrorResponse('Invalid or missing fingerprint ID');
+  }
+  console.log('Received fingerprintId:', fingerprintId);
+
+  const { userId: clerkUserId } = await auth();
+  try {
+    // 优先根据 Clerk ID 查询（如果已登录）
+    let existingUserResult: XUserResponse | null = null;
+    if (clerkUserId) {
+      // 已登录一律按照clerkUserId去查
+      existingUserResult = await getUserByClerkId(clerkUserId);
+      if (existingUserResult && existingUserResult.xUser.fingerprintId !== fingerprintId) {
+        // 说明当前用户的指纹ID发生了改变，为什么呢？因为它使用同一账号去注册Clerk，Clerk判定是同一用户！
+        // 这个时候一定以登录用户clerkUserId为准
+        // 但是考虑到同一指纹ID本身可以绑定多个账号，所以这里什么都不做
+        // 就是以当前登录用户去查他自己的数据就行！
+        console.warn(`Current login user used diff fp_ids: ${clerkUserId}, db_fp_id=${existingUserResult.xUser.fingerprintId}, req_fp_id=${fingerprintId}`);
+      }
+    } else {
+      // 其次才是检查是否已存在该fingerprint的用户
+      existingUserResult = await getUserByFingerprintId(fingerprintId);
+    }
+    if (existingUserResult) {
+      return NextResponse.json(existingUserResult);
+    }
+
+    // 如果不存在用户且不允许创建，返回404
+    if (!options.createIfNotExists) {
+      return createErrorResponse('User not found', 404);
+    }
+
+    const sourceRef = extractSourceRef(request);
+
+    // 创建新的匿名用户
+    const { newUser, credit } = await userAggregateService.initAnonymousUser(
+      fingerprintId,
+      { sourceRef: sourceRef??  undefined}
+    );
+
+    console.log(`Created new anonymous user ${newUser.userId} with fingerprint ${fingerprintId}`);
+
+    // 返回创建结果
+    const response = createSuccessResponse({
+      entities: {
+        user: newUser,
+        credit,
+        subscription: null,
+      },
+      isNewUser: true,
+    });
+    return NextResponse.json(response);
+
+  } catch (error) {
+    console.error('Fingerprint request error:', error);
+    return createErrorResponse('Internal server error', 500);
+  }
+}
+
+/**
+ * 匿名用户初始化API
+ * POST /api/user/anonymous/init
+ */
+export async function POST(request: NextRequest) {
+  return handleFingerprintRequest(request, { createIfNotExists: true });
+}