@windrun-huaiin/backend-core 30.0.0 → 31.0.0

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);
       }
 

package/src/services/database/constants.ts

@@ -2,80 +2,80 @@
 // Keep in sync with DB CHECK constraints
 
 export const UserStatus = {
-  // 匿名用户
+  // Anonymous user
   ANONYMOUS: 'anonymous',
-  // 注册用户
+  // Registered user
   REGISTERED: 'registered',
-  // 管理员介入管控
+  // Frozen by admin intervention
   FROZEN: 'frozen',
-  // 用户注销，数据软删除，用户数据将不可复用
+  // Soft-deleted user data that must not be reused
   DELETED: 'deleted',
 } as const;
 
 export const SubscriptionStatus = {
-  // 初始状态或注销后状态
+  // Initial or post-cancellation state
   INCOMPLETE: 'incomplete',
-  // 订阅试用期
+  // Trial subscription period
   TRIALING: 'trialing',
-  // 有效订阅激活
+  // Active subscription
   ACTIVE: 'active',
-  // 订阅过期
+  // Past-due subscription
   PAST_DUE: 'past_due',
-  // 取消订阅
+  // Canceled subscription
   CANCELED: 'canceled',
 } as const;
 
 export const OrderStatus = {
-  // 初始状态
+  // Initial state
   CREATED: 'created',
-  // 中间状态，待支付，可能是支付失败事件触发
+  // Intermediate state, awaiting payment; may be triggered by a payment failure event
   PENDING_UNPAID: 'pending_unpaid',
-  // 中间状态(也可是最终状态)，支付成功，后续可变为「退款或取消」
+  // Intermediate or final state; payment succeeded and may later become refunded or canceled
   SUCCESS: 'success',
-  // 中间状态(也可是最终状态)，CheckOut失败或者是支付失败，后续可变为「退款或取消」
+  // Intermediate or final state; checkout or payment failed and may later become refunded or canceled
   FAILED: 'failed',
-  // 最终状态，已退款
+  // Final state, refunded
   REFUNDED: 'refunded',
-  // 最终状态，已取消
+  // Final state, canceled
   CANCELED: 'canceled',
 } as const;
 
 export const TransactionType = {
-  // 订阅订单
+  // Subscription order
   SUBSCRIPTION: 'subscription',
-  // 即付订单
+  // One-time payment order
   ONE_TIME: 'one_time',
 } as const;
 
 export const CreditType = {
-  // 订阅积分
+  // Subscription credits
   PAID: 'paid',
-  // 即付积分
+  // One-time paid credits
   ONE_TIME_PAID: 'one_time_paid',
-  // 免费积分
+  // Free credits
   FREE: 'free',
 } as const;
 
 export const OperationType = {
-  // 系统奖励积分
+  // System-granted credits
   SYS_GIFT: 'system_gift',
-  // 用户消费积分
+  // User credit consumption
   CONSUME: 'consume',
-  // 用户充值积分
+  // User credit recharge
   RECHARGE: 'recharge',
-  // 管理员介入冻结积分
+  // Admin credit freeze
   FREEZE: 'freeze',
-  // 管理员介入解冻积分
+  // Admin credit unfreeze
   UNFREEZE: 'unfreeze',
-  // 管理员介入赠送积分
+  // Admin credit increase
   ADJUST_INCREASE: 'adjust_increase',
-  // 管理员介入抹去积分
+  // Admin credit decrease
   ADJUST_DECREASE: 'adjust_decrease',
-  // 清理积分，事件触发或者是积分过期触发
+  // Credit purge triggered by an event or expiration
   PURGE: 'purge',
 } as const;
 
-// 支付厂商类型
+// Payment provider types
 export const PaySupplier = {
   STRIPE: 'Stripe',
   APPLE: 'Apple',
@@ -83,18 +83,18 @@ export const PaySupplier = {
 } as const;
 
 export const BillingReason = {
-  // 首次订阅
+  // Initial subscription
   SUBSCRIPTION_CREATE: 'subscription_create',
-  // 续订
+  // Subscription renewal
   SUBSCRIPTION_CYCLE: 'subscription_cycle',
 } as const;
 
 export const PaymentStatus = {
-  // 已支付
+  // Paid
   PAID: 'paid',
-  // 待支付
+  // Pending payment
   UN_PAID: 'un_paid',
-  // 无需支付
+  // No payment required
   NO_PAYMENT_REQUIRED: 'no_payment_required',
 } as const;
 

package/src/services/database/credit.service.ts

@@ -300,7 +300,7 @@ export class CreditService {
     this.ensureNonNegative(normalized, 'initializeCredit');
     const client = checkAndFallbackWithNonTCClient(tx);
 
-    // 这里使用upsert语义是为了代码复用，处理匿名初始化和匿名->注册的初始化
+    // Use upsert semantics to share initialization logic for anonymous users and anonymous-to-registered upgrades.
     const credit =  await client.credit.upsert({
       where: {
         userId: init.userId
@@ -636,7 +636,7 @@ export class CreditService {
       data: updateData as Prisma.CreditUpdateInput,
     });
 
-    // 强制留痕，即使是积分变化为0也记录，操作留痕
+    // Always write an audit entry, even when the credit change is zero.
     const usage = await this.recordCreditAuditLog(client, userId, OperationType.PURGE, normalizedDeduction, { feature: reason, operationReferId })
 
     return { credit, usage };

package/src/services/database/transaction.service.ts

@@ -43,7 +43,7 @@ export class TransactionService {
         orderId: data.orderId,
         orderStatus: data.orderStatus || OrderStatus.CREATED,
         paymentStatus: data.paymentStatus || PaymentStatus.UN_PAID,
-        orderExpiredAt: data.orderExpiredAt || new Date(Date.now() + 30 * 60 * 1000), // 默认30分钟过期
+        orderExpiredAt: data.orderExpiredAt || new Date(Date.now() + 30 * 60 * 1000), // Default expiration: 30 minutes
         paySupplier: data.paySupplier,
         payTransactionId: data.payTransactionId,
         paySubscriptionId: data.paySubscriptionId,

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

@@ -83,7 +83,7 @@ export class UserService {
   async findByClerkUserId(clerkUserId: string, tx?: Prisma.TransactionClient): Promise<User | null> {
     const client = checkAndFallbackWithNonTCClient(tx);
 
-    // DB的部分索引与这里的状态查询相对应，因而可以使用findUnique
+    // Partial DB indexes match this status filter, so findUnique is valid here.
     return await client.user.findUnique({
       where: { 
         clerkUserId,
@@ -183,7 +183,7 @@ export class UserService {
     return { users, total };
   }
 
-  // 批量创建匿名用户
+  // Create anonymous users in bulk
   async createBatchAnonymousUsers(
     fingerprintIds: string[],
     tx?: Prisma.TransactionClient

package/src/services/stripe/webhook-handler.ts

@@ -292,7 +292,7 @@ async function handleInvoicePaid(invoice: Stripe.Invoice) {
   });
 
   if (isInitialPayment) {
-    // 首次订阅校验
+    // check
     const nonActiveSubscription = await subscriptionService.getNonActiveSubscription(userId);
     if (!nonActiveSubscription) {
       throw new Error(`Subscription status is ACTIVE for user ${userId}, forbidden to re-active!`);
@@ -324,7 +324,7 @@ async function handleInvoicePaid(invoice: Stripe.Invoice) {
   }
 
   if (isRenewal) {
-    // 续订时，一定要查到订阅记录
+    // must query it's subscription db record
     const subscription = await subscriptionService.findByPaySubscriptionId(subscriptionId);
     if (!subscription) {
       throw new Error(`Subscription not found for renewal: ${subscriptionId}`);
@@ -337,8 +337,8 @@ async function handleInvoicePaid(invoice: Stripe.Invoice) {
     }
 
     // Get credits from current price configuration (handles plan upgrades/downgrades)
-    // 优先从配置中取，取不到就以上个周期的为准作为Fallback，后续有问题再人工补偿，优先保证能用
-    // 只要配置正确，这里就不会出错！
+    // Prefer values from configuration; fall back to the previous cycle value if unavailable. Manual remediation will be applied later if issues occur, prioritizing functional availability
+    // No error occurs here as long as the configuration is correct!
     const creditsForRenewal = subscription.priceId
       ? getCreditsFromPriceId(subscription.priceId)
       : subscription.creditsAllocated;
@@ -467,7 +467,7 @@ async function handleInvoicePaymentFailed(invoice: Stripe.Invoice) {
   const subscriptionId = parentDetails.subscription;
   const subscriptionMetadata = parentDetails.metadata || {};
 
-  // 支付ID
+  // PaymentIntentId
   const paymentIntentId = await fetchPaymentId(invoice.id)
 
   console.log('Invoice payment failed event key-info:', {