@windrun-huaiin/backend-core 30.0.0 → 31.0.1

package/src/app/api/webhook/clerk/user/route.ts

@@ -11,7 +11,7 @@ import { headers } from 'next/headers';
 import { NextRequest, NextResponse } from 'next/server';
 import { Webhook } from 'svix';
 
-// 定义Clerk Webhook事件类型
+// Clerk webhook event type definition
 interface ClerkWebhookEvent {
   data: {
     id: string;
@@ -41,12 +41,12 @@ interface ClerkWebhookEvent {
 }
 export async function POST(request: NextRequest) {
   try {
-    // 获取原始请求体
+    // Read the raw request body.
     const rawBody = await request.text();
 
     let event: ClerkWebhookEvent;
 
-    // 开发环境跳过签名校验
+    // Skip signature verification in development.
     if (process.env.NODE_ENV === 'development') {
       console.log('Development mode: skipping webhook signature verification');
       try {
@@ -59,13 +59,13 @@ export async function POST(request: NextRequest) {
         );
       }
     } else {
-      // 生产环境进行签名校验
+      // Verify the signature in production.
       const headerPayload = await headers();
       const svix_id = headerPayload.get('svix-id');
       const svix_timestamp = headerPayload.get('svix-timestamp');
       const svix_signature = headerPayload.get('svix-signature');
 
-      // 如果缺少必要的header，返回错误
+      // Reject requests missing required headers.
       if (!svix_id || !svix_timestamp || !svix_signature) {
         return NextResponse.json(
           { error: 'Missing webhook headers' },
@@ -73,7 +73,7 @@ export async function POST(request: NextRequest) {
         );
       }
 
-      // 获取webhook signing secret
+      // Load the webhook signing secret.
       const webhookSecret = process.env.CLERK_WEBHOOK_SECRET;
       if (!webhookSecret) {
         console.error('CLERK_WEBHOOK_SECRET is not configured');
@@ -83,7 +83,7 @@ export async function POST(request: NextRequest) {
         );
       }
 
-      // 验证webhook签名
+      // Verify the webhook signature.
       try {
         const wh = new Webhook(webhookSecret);
         event = wh.verify(rawBody, {
@@ -110,7 +110,7 @@ export async function POST(request: NextRequest) {
     let processingResult = { success: true, message: 'Event processed successfully' };
 
     try {
-      // 处理不同的事件类型
+      // Dispatch by event type.
       const { type } = event;
 
       switch (type) {
@@ -155,7 +155,7 @@ export async function POST(request: NextRequest) {
 }
 
 /**
- * 处理用户创建事件
+ * Handle the user.created event.
  */
 async function handleUserCreated(event: ClerkWebhookEvent) {
   const { data } = event;
@@ -174,7 +174,7 @@ async function handleUserCreated(event: ClerkWebhookEvent) {
     userName
   });
 
-  // 检查必要参数
+  // Validate required fields.
   if (!fingerprintId) {
     console.error('Missing fingerprintId in webhook data, process flow error');
     return;
@@ -186,17 +186,17 @@ async function handleUserCreated(event: ClerkWebhookEvent) {
   }
 
   try {
-    // 按fingerprintId查询该设备的所有未注销过的用户记录，注销过的记录相当于是死数据
+    // Find all non-deleted users for this device fingerprint.
     const existingUsers = await userService.findListByFingerprintId(fingerprintId);
     if (!existingUsers || existingUsers.length === 0) {
       console.error('Invalid fingerprintId in webhook data, process flow error');
       return;
     }
 
-    // 查找email相同的记录
+    // Find an existing user with the same email.
     const sameEmailUser = existingUsers.find(user => user.email === email);
     if (sameEmailUser) {
-      // 同一账号，检查是否需要更新clerkUserId
+      // Same account; update clerkUserId if needed.
       if (sameEmailUser.clerkUserId !== clerkUserId) {
         await userService.updateUser(sameEmailUser.userId, { clerkUserId, userName: userName, status: UserStatus.REGISTERED });
         console.log(`Updated clerkUserId for user ${sameEmailUser.userId}`);
@@ -206,16 +206,16 @@ async function handleUserCreated(event: ClerkWebhookEvent) {
       return;
     }
 
-    // 查找匿名用户（email为空且clerkUserId为空）
+    // Find an anonymous user with no email or clerkUserId.
     const anonymousUser = existingUsers.find(user => !user.email && !user.clerkUserId && user.status === UserStatus.ANONYMOUS );
     if (anonymousUser) {
-      // 匿名用户升级
+      // Upgrade the anonymous user.
       await userAggregateService.upgradeToRegistered(anonymousUser.userId, email, clerkUserId, userName);
       console.log(`Successfully upgraded anonymous user ${anonymousUser.userId} to registered user`);
       return;
     }
 
-    // 同设备新账号，创建新用户
+    // New account on the same device; create a new user.
     await userAggregateService.createNewRegisteredUser(clerkUserId, email, fingerprintId, userName);
     console.log(`Created new user for device ${fingerprintId} with email ${email}`);
     
@@ -226,7 +226,7 @@ async function handleUserCreated(event: ClerkWebhookEvent) {
 }
 
 /**
- * 处理用户删除事件
+ * Handle the user.deleted event.
  */
 async function handleUserDeleted(event: ClerkWebhookEvent) {
   const { data } = event;

package/src/auth/auth-utils.ts

@@ -4,9 +4,6 @@ import { userService } from '../services/database/index';
 import { User } from '../services/database/prisma-model-type';
 import { AUTH_ERRORS, AUTH_HEADERS, type AuthProvider, type ProviderIdentity } from './auth-shared';
 
-/**
- * 认证结果类型
- */
 export interface AuthResult {
   userId: string;
   user: User;
@@ -15,7 +12,7 @@ export interface AuthResult {
 }
 
 /**
- * 从中间件设置的 Clerk ID 获取完整用户信息
+ * Fetch User's info from header field by Middleware
  */
 export async function getAuthenticatedUser(req: NextRequest): Promise<AuthResult> {
   try {
@@ -43,7 +40,7 @@ export async function getAuthenticatedUser(req: NextRequest): Promise<AuthResult
 }
 
 /**
- * 要求用户必须已认证，返回用户ID
+ * Require Auth, success back user's id
  */
 export async function requireAuth(req: NextRequest): Promise<string> {
   const auth = await getAuthenticatedUser(req);
@@ -51,15 +48,15 @@ export async function requireAuth(req: NextRequest): Promise<string> {
 }
 
 /**
- * 要求用户必须已认证，返回完整用户信息
+ * Require Auth, success back user's info
  */
 export async function requireAuthWithUser(req: NextRequest): Promise<AuthResult> {
   return await getAuthenticatedUser(req);
 }
 
 /**
- * 服务端场景下获取当前已认证身份（如果存在）
- * 适用于只依赖登录态、不需要查询业务用户的逻辑
+ * Only use in server side
+ * Server Component / Server Action, just need user's login status
  */
 export async function getOptionalServerAuthIdentity(): Promise<ProviderIdentity | null> {
   try {
@@ -79,8 +76,8 @@ export async function getOptionalServerAuthIdentity(): Promise<ProviderIdentity
 }
 
 /**
- * 服务端场景下获取当前已认证用户（如果存在）
- * 适用于 Server Component / Server Action 中基于登录态控制展示的逻辑
+ * Only use in server side
+ * Server Component / Server Action, need user's login status and user's data, will check db
  */
 export async function getOptionalServerAuthUser(): Promise<AuthResult | null> {
   try {
@@ -107,7 +104,7 @@ export async function getOptionalServerAuthUser(): Promise<AuthResult | null> {
 }
 
 /**
- * API Route版本的认证工具函数
+ * API Route Auth Util
  */
 export class ApiAuthUtils {
   private req: NextRequest;
@@ -116,23 +113,14 @@ export class ApiAuthUtils {
     this.req = req;
   }
 
-  /**
-   * 要求用户必须已认证，返回用户ID
-   */
   async requireAuth(): Promise<string> {
     return await requireAuth(this.req);
   }
 
-  /**
-   * 要求用户必须已认证，返回完整用户信息
-   */
   async requireAuthWithUser(): Promise<AuthResult> {
     return await requireAuthWithUser(this.req);
   }
 
-  /**
-   * 获取用户ID（如果已认证）
-   */
   async getUserId(): Promise<string | null> {
     try {
       const auth = await getAuthenticatedUser(this.req);
@@ -142,9 +130,6 @@ export class ApiAuthUtils {
     }
   }
 
-  /**
-   * 获取完整用户信息（如果已认证）
-   */
   async getUser(): Promise<AuthResult | null> {
     try {
       return await getAuthenticatedUser(this.req);

package/src/lib/money-price-config.ts

@@ -12,7 +12,7 @@ export const moneyPriceConfig: MoneyPriceConfig = {
     stripe: {
       provider: 'stripe',
       enabled: true,
-      // 订阅模式产品
+      // Subscription products
       subscriptionProducts: {
         F1: {
           key: 'F1',
@@ -70,7 +70,7 @@ export const moneyPriceConfig: MoneyPriceConfig = {
           }
         }
       },
-      // 积分包产品
+      // Credit pack products
       creditPackProducts: {
         F1: {
           key: 'F1',
@@ -106,56 +106,56 @@ export const moneyPriceConfig: MoneyPriceConfig = {
   }
 };
 
-// ============ 应用层wrapper - 隐藏moneyPriceConfig细节 ============
+// ============ Application-level wrappers that hide moneyPriceConfig details ============
 
 /**
- * 获取当前激活的支付供应商配置
+ * Get the currently active payment provider configuration.
  *
- * 🔒 安全设计：
- * - wrapper函数隐藏moneyPriceConfig
- * - util层负责从config中提取激活的provider配置
- * - 外部只能通过这个wrapper访问，看不到config对象
+ * Security design:
+ * - Wrapper functions keep moneyPriceConfig private.
+ * - Utility functions extract the active provider configuration from the config.
+ * - External callers can access only this wrapper, not the full config object.
  *
- * @returns 当前激活的支付供应商配置
+ * @returns The currently active payment provider configuration.
  */
 export function getActiveProviderConfig(): PaymentProviderConfig {
   return getActiveProviderConfigUtil(moneyPriceConfig);
 }
 
 /**
- * 根据 priceId 获取对应的积分数量
+ * Get the credit amount for a price ID.
  *
- * 🔒 安全设计：
- * - wrapper函数隐藏moneyPriceConfig
- * - util层负责解析config并提取结果
- * - 外部只能通过这个wrapper访问，看不到config对象
+ * Security design:
+ * - Wrapper functions keep moneyPriceConfig private.
+ * - Utility functions parse the config and extract the result.
+ * - External callers can access only this wrapper, not the full config object.
  *
- * @param priceId - 查询的价格ID
- * @param _provider - 保留参数（向后兼容），暂未使用
- * @returns 对应的积分数量，或null
+ * @param priceId - Price ID to query.
+ * @param _provider - Reserved for backward compatibility; currently unused.
+ * @returns The matching credit amount, or null.
  */
 export function getCreditsFromPriceId(priceId?: string, _provider?: string): number | null {
   return getCreditsFromPriceIdUtil(priceId, moneyPriceConfig);
 }
 
 /**
- * 根据查询参数获取价格配置
+ * Get price configuration by query parameters.
  *
- * 支持三种查询方式：
- * 1. 按 priceId 查询：getPriceConfig(priceId='price_xxx')
- * 2. 按 plan 和 billingType 查询：getPriceConfig(undefined, 'P2', 'monthly')
- * 3. 按 plan 查询：getPriceConfig(undefined, 'P2')
+ * Supported query modes:
+ * 1. By priceId: getPriceConfig(priceId='price_xxx')
+ * 2. By plan and billingType: getPriceConfig(undefined, 'P2', 'monthly')
+ * 3. By plan: getPriceConfig(undefined, 'P2')
  *
- * 🔒 安全设计：
- * - wrapper函数隐藏moneyPriceConfig
- * - util层负责解析config并提取匹配的结果
- * - 外部只能通过这个wrapper访问，看不到config对象
+ * Security design:
+ * - Wrapper functions keep moneyPriceConfig private.
+ * - Utility functions parse the config and extract the matching result.
+ * - External callers can access only this wrapper, not the full config object.
  *
- * @param priceId - 查询的价格ID（可选）
- * @param plan - 查询的套餐名称如'P2'、'U3'（可选）
- * @param billingType - 查询的计费类型如'monthly'、'yearly'（可选）
- * @param _provider - 保留参数（向后兼容），暂未使用
- * @returns 匹配的价格配置，包含计算好的元数据（priceName、description、interval）
+ * @param priceId - Optional price ID to query.
+ * @param plan - Optional plan name, such as 'P2' or 'U3'.
+ * @param billingType - Optional billing type, such as 'monthly' or 'yearly'.
+ * @param _provider - Reserved for backward compatibility; currently unused.
+ * @returns The matching price config with derived metadata: priceName, description, and interval.
  */
 export function getPriceConfig(
   priceId?: string,
@@ -165,4 +165,3 @@ export function getPriceConfig(
 ): (EnhancePricePlan & { priceName: string; description: string; interval?: string }) | null {
   return getPriceConfigUtil(priceId, plan, billingType, moneyPriceConfig);
 }
-

package/src/lib/stripe-config.ts

@@ -97,7 +97,7 @@ export const createCheckoutSession = async (
 
   // One-time payment specific configuration
   if (isSubscriptionMode) {
-    // 在这里注入订单元数据，以保证后续事件处理能根据订单去匹配处理，只能在订阅模式里设置数据，否则Stripe报错
+    // Attach order metadata for later event matching. Stripe only allows this in subscription mode.
     sessionParams.subscription_data = subscriptionData;
   } else {
     // One-time payments don't create invoices
@@ -129,7 +129,7 @@ export const createCheckoutSession = async (
   }
 };
 
-// 根据发票ID去查支付ID
+// Resolve the payment ID from an invoice ID.
 export const fetchPaymentId = async (invoiceId: string ): Promise<string> => {
   const fullInvoice = await getStripe().invoices.retrieve(invoiceId, {
     expand: ['payments']
@@ -193,7 +193,7 @@ export const createOrGetCustomer = async (params: {
     }
   }
 
-  // 创建新客户
+  // Create a new customer.
   const customerParams: Stripe.CustomerCreateParams = {
     metadata: {
       user_id: userId,

package/src/prisma/prisma-transaction-util.ts

@@ -1,7 +1,7 @@
 import { getBackendCorePrisma } from './prisma';
 import type { Prisma } from '@core/db/prisma-model-type';
 
-// 事务工具类，回滚时打印回滚日志
+// Transaction helper that logs rollback details on failure.
 export async function runInTransaction<T>(
   fn: (tx: Prisma.TransactionClient) => Promise<T>,
   operationName?: string

package/src/prisma/prisma.ts

@@ -41,7 +41,7 @@ const globalForPrisma = globalThis as unknown as {
   __prisma_ssl_warning_logged?: boolean;
 };
 
-// ==================== 日志配置 ====================
+// ==================== Logging Configuration ====================
 const getLogConfig = () => {
   if (process.env.PRISMA_DEBUG === 'true') {
     return [
@@ -125,42 +125,41 @@ function registerDevelopmentQueryLogger(prismaClient: BackendCoreHostPrismaClien
     globalForPrisma[ID_KEY] = listenerId;
     console.log(`Prisma Query Logger Registered | Listener ID: ${listenerId} | Instance ID: ${instanceId}`);
 
-    // --- 自定义SQL拼接 ---
+    // --- Custom SQL interpolation ---
     const interpolate = (query: string, params: string) => {
-      // 1. 【核心修改】：安全检查和参数解析
+      // 1. Validate and parse parameters safely.
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       let parameters: any[] = [];
       try {
-        // 尝试解析 params 字符串
-        // 如果 params 是空字符串 ""，或者不是有效的 JSON，这里会捕获错误
+        // Parse the params string. Empty strings or invalid JSON are handled by the catch block.
         parameters = params && params.length > 0 ? JSON.parse(params) : [];
         // eslint-disable-next-line unused-imports/no-unused-vars
       } catch (e) {
-        // 如果无法解析，则直接返回原始查询，跳过替换
+        // If parsing fails, return the original query without interpolation.
         return query; 
       }
       
-      // 确保 parameters 是一个数组
+      // Ensure parameters is an array.
       if (!Array.isArray(parameters)) {
-          console.warn('Prisma params解析结果不是数组，跳过参数替换。Result:', parameters);
+          console.warn('Prisma params did not parse to an array; skipping parameter interpolation. Result:', parameters);
           return query;
       }
 
-      // 如果没有参数，直接返回查询
+      // If there are no parameters, return the query as-is.
       if (parameters.length === 0) {
         return query;
       }
 
-      // 2. 将参数列表的值进行安全的字符串化处理
+      // 2. Safely stringify parameter values.
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const safeValues = parameters.map((p: any) => {
         if (p === null) return 'NULL';
-        // 对字符串类型的值加上单引号并转义（这是SQL安全的关键）
+        // Quote and escape string values for readable SQL logging.
         if (typeof p === 'string') return `'${p.replace(/'/g, "''")}'`; 
-        return p; // 数字、布尔值等直接返回
+        return p; // Numbers, booleans, and similar values can be returned directly.
       });
 
-      // 3. 循环替换 $1, $2, ...
+      // 3. Replace $1, $2, ... placeholders.
       let sql = query;
       for (let i = 0; i < safeValues.length; i++) {
         const placeholder = new RegExp('\\$' + (i + 1) + '(?!\\d)', 'g');
@@ -176,23 +175,23 @@ function registerDevelopmentQueryLogger(prismaClient: BackendCoreHostPrismaClien
       const interpolatedSql = interpolate(event.query, event.params);
       
       const clean = interpolatedSql
-        .replace(/"[^"]+"\./g, '')           // 去 "表".
-        .replace(/= '([^']+)'/g, `= '$1'`)   // 已经替换成单引号，此处可以优化
-        .replace(/"/g, '');                  // 彻底灭双引号
+        .replace(/"[^"]+"\./g, '')           // Remove "table". prefixes.
+        .replace(/= '([^']+)'/g, `= '$1'`)   // Keep normalized quoted values.
+        .replace(/"/g, '');                  // Remove remaining double quotes.
 
       console.log('─'.repeat(60));
       console.log(`Prisma Instance ID: ${instanceId} | Listener ID: ${listenerId}`);
       console.log(`${clean};`);
-      console.log(`⏰ 耗时: ${ms}ms, ${slow}`);
+      console.log(`Duration: ${ms}ms, ${slow}`);
     };
-    // 注册包装后的 handler
+    // Register the wrapped handler.
     prismaClient.$on?.('query' as never, wrappedHandler);
 
     globalForPrisma[REGISTERED_KEY] = true;
   }
 }
 
-// ==================== 便捷方法, 入参事务客户端不存在或者不传, 就返回全局非事务客户端 ====================
+// ==================== Client Helper: fall back to the global non-transaction client when no transaction client is provided ====================
 export function checkAndFallbackWithNonTCClient(tx?: Prisma.TransactionClient): Prisma.TransactionClient | BackendCorePrismaClient {
   return tx ?? getBackendCorePrisma();
 }

package/src/services/aggregate/billing.aggregate.service.ts

@@ -35,7 +35,7 @@ type BasicOrderContext = {
 };
 
 type RenewalOrderContext = BasicOrderContext & {
-  // 续订时以Stripe的发票价格为准
+  // Use Stripe invoice price as the source of truth for renewal
   amountPaidCents: number;
   currency: string;
 }
@@ -64,7 +64,7 @@ class BillingAggregateService {
   ): Promise<void> {
     await runInTransaction(async (tx) => {
       const now = new Date();
-      // 订阅截止时间统一为到期日最后1s
+        // Set subscription expiry to the last second of the expiration date
       const originSubPeriodEnd = context.periodEnd;
       const specialEnd = originSubPeriodEnd ? new Date(originSubPeriodEnd.setHours(23, 59, 59, 999)) : originSubPeriodEnd;
       const updatedSubscription = await subscriptionService.updateSubscription(
@@ -237,7 +237,7 @@ class BillingAggregateService {
         },
         tx
       );
-      // 订阅截止时间统一为到期日最后1s
+      // Set subscription expiry to the last second of the expiration date
       const originSubPeriodEnd = context.periodEnd;
       const specialEnd = originSubPeriodEnd ? new Date(originSubPeriodEnd.setHours(23, 59, 59, 999)) : originSubPeriodEnd;
 
@@ -365,7 +365,7 @@ class BillingAggregateService {
   ): Promise<void> {
     await runInTransaction(async (tx) => {
       if (params.isUserCancel) {
-          // 记录用户取消订阅的时间信息
+          // Record the time when the user unsubscribes
           await transactionService.update(
             params.orderId,
             {
@@ -391,7 +391,7 @@ class BillingAggregateService {
     context: SubscriptionCancelContext
   ): Promise<void> {
     await runInTransaction(async (tx) => {
-      // 更新订单, 记录取消信息
+      // Update the order and log cancellation details
       await transactionService.update(
         context.orderId,
         {
@@ -400,10 +400,10 @@ class BillingAggregateService {
         },
         tx
       )
-      // 更新订阅信息
+      // Update subscription information
       await subscriptionService.updateStatus(context.subIdKey, SubscriptionStatus.CANCELED, tx);
 
-      // 清理积分并留痕
+      // Clear credits and keep audit trail
       await creditService.purgePaidCredit(context.userId, 'cancel_subscription_purge', context.orderId, tx);
     })
   }

package/src/services/aggregate/user.aggregate.service.ts

@@ -40,17 +40,17 @@ export class UserAggregateService {
   }
 
   /**
-   * 创建新的注册用户
+   * Create a new registered user
    *
-   * 初始化步骤（与 credit 平行）：
-   * 1. 创建 User 记录
-   * 2. 初始化 Credit 记录（免费积分）
-   * 3. 初始化 Subscription 记录（占位符，status=INCOMPLETE）
-   * 4. 记录 CreditUsage（审计）
+   * Initialization steps (parallel to credit):
+   * 1. Create User record
+   * 2. Initialize Credit record (free credits)
+   * 3. Initialize Subscription record (placeholder, status=INCOMPLETE)
+   * 4. Record CreditUsage (audit)
    *
-   * 后续当用户通过 Stripe 订阅时：
-   * - session.completed 或 invoice.paid 会 UPDATE subscription 记录
-   * - 不需要 CREATE，只需 UPDATE 确保逻辑一致
+   * When the user subscribes via Stripe later:
+   * - session.completed or invoice.paid will UPDATE the subscription record
+   * - No CREATE needed, only UPDATE to ensure logical consistency
    */
   async createNewRegisteredUser(
     clerkUserId: string,
@@ -89,7 +89,7 @@ export class UserAggregateService {
     });
   }
 
-  // 注意积分审查日志的处理
+  // Note: Handle credit review logs
   async upgradeToRegistered(
     userId: string,
     email: string,
@@ -107,9 +107,9 @@ export class UserAggregateService {
         tx
       );
 
-      // 先清空匿名积分并审计日志留痕
+      // Clear anonymous credits first and audit for traceability
       await creditService.purgeFreeCredit(userId, 'user_registered_purge', userId, tx);
-      // 再初始化完成注册获得免费积分
+      // Then initialize free credits upon successful registration
       const credit = await creditService.initializeCreditWithFree(
         {
           userId: updateUser.userId,
@@ -128,21 +128,21 @@ export class UserAggregateService {
 
   async handleUserUnregister(clerkUserId: string): Promise<string | null> { 
     return runInTransaction(async (tx) => {
-      // 根据clerkUserId查找用户
+      // query DB user
       const user = await userService.findByClerkUserId(clerkUserId, tx);
       if (!user) {
         console.log(`User with clerkUserId ${clerkUserId} not found`);
         return null;
       }
       const userId = user.userId;
-      // 更改用户状态，保留user信息尤其是FingerprintId，防止反复注册薅羊毛
+      // Update user status and retain user info (especially FingerprintId) to prevent repeated registration abuse
       await userService.unregister(user.userId, tx);
-      // 清空积分
+      // Clear credits
       await creditService.purgeCredit(userId, 'soft_delete_user', userId, tx);
       
       const subscription = await subscriptionService.getActiveSubscription(userId, tx);
       if (subscription) {
-        // 如果有订阅信息，则要更新
+        // Update subscription info if it exists
         await subscriptionService.cancelSubscription(subscription.id, true, tx);
       }