@windrun-huaiin/backend-core 30.0.0 → 31.0.1

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:', {