@windrun-huaiin/backend-core 29.0.3 → 31.0.0

package/dist/services/database/transaction.service.js

@@ -16,7 +16,7 @@ class TransactionService {
                     orderId: data.orderId,
                     orderStatus: data.orderStatus || constants.OrderStatus.CREATED,
                     paymentStatus: data.paymentStatus || constants.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/dist/services/database/transaction.service.mjs

@@ -14,7 +14,7 @@ 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/dist/services/database/user.service.js

@@ -63,7 +63,7 @@ class UserService {
     findByClerkUserId(clerkUserId, tx) {
         return tslib.__awaiter(this, void 0, void 0, function* () {
             const client = prisma.checkAndFallbackWithNonTCClient(tx);
-            // DB的部分索引与这里的状态查询相对应，因而可以使用findUnique
+            // Partial DB indexes match this status filter, so findUnique is valid here.
             return yield client.user.findUnique({
                 where: {
                     clerkUserId,
@@ -137,7 +137,7 @@ class UserService {
             return { users, total };
         });
     }
-    // 批量创建匿名用户
+    // Create anonymous users in bulk
     createBatchAnonymousUsers(fingerprintIds, tx) {
         return tslib.__awaiter(this, void 0, void 0, function* () {
             const client = prisma.checkAndFallbackWithNonTCClient(tx);

package/dist/services/database/user.service.mjs

@@ -61,7 +61,7 @@ class UserService {
     findByClerkUserId(clerkUserId, tx) {
         return __awaiter(this, void 0, void 0, function* () {
             const client = checkAndFallbackWithNonTCClient(tx);
-            // DB的部分索引与这里的状态查询相对应，因而可以使用findUnique
+            // Partial DB indexes match this status filter, so findUnique is valid here.
             return yield client.user.findUnique({
                 where: {
                     clerkUserId,
@@ -135,7 +135,7 @@ class UserService {
             return { users, total };
         });
     }
-    // 批量创建匿名用户
+    // Create anonymous users in bulk
     createBatchAnonymousUsers(fingerprintIds, tx) {
         return __awaiter(this, void 0, void 0, function* () {
             const client = checkAndFallbackWithNonTCClient(tx);

package/dist/services/stripe/webhook-handler.js

@@ -236,7 +236,7 @@ function handleInvoicePaid(invoice) {
             periodEnd: utils.viewLocalTime(subPeriodEnd),
         });
         if (isInitialPayment) {
-            // 首次订阅校验
+            // check
             const nonActiveSubscription = yield subscription_service.subscriptionService.getNonActiveSubscription(userId);
             if (!nonActiveSubscription) {
                 throw new Error(`Subscription status is ACTIVE for user ${userId}, forbidden to re-active!`);
@@ -263,7 +263,7 @@ function handleInvoicePaid(invoice) {
             return;
         }
         if (isRenewal) {
-            // 续订时，一定要查到订阅记录
+            // must query it's subscription db record
             const subscription = yield subscription_service.subscriptionService.findByPaySubscriptionId(subscriptionId);
             if (!subscription) {
                 throw new Error(`Subscription not found for renewal: ${subscriptionId}`);
@@ -274,8 +274,8 @@ function handleInvoicePaid(invoice) {
                 throw new Error(`Renewal invoice ${invoice.id} already processed as ${existingOrder.orderId}, skipping.`);
             }
             // 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
                 ? moneyPriceConfig.getCreditsFromPriceId(subscription.priceId)
                 : subscription.creditsAllocated;
@@ -386,7 +386,7 @@ function handleInvoicePaymentFailed(invoice) {
         }
         const subscriptionId = parentDetails.subscription;
         const subscriptionMetadata = parentDetails.metadata || {};
-        // 支付ID
+        // PaymentIntentId
         const paymentIntentId = yield stripeConfig.fetchPaymentId(invoice.id);
         console.log('Invoice payment failed event key-info:', {
             invoiceId: invoice.id,

package/dist/services/stripe/webhook-handler.mjs

@@ -234,7 +234,7 @@ function handleInvoicePaid(invoice) {
             periodEnd: viewLocalTime(subPeriodEnd),
         });
         if (isInitialPayment) {
-            // 首次订阅校验
+            // check
             const nonActiveSubscription = yield subscriptionService.getNonActiveSubscription(userId);
             if (!nonActiveSubscription) {
                 throw new Error(`Subscription status is ACTIVE for user ${userId}, forbidden to re-active!`);
@@ -261,7 +261,7 @@ function handleInvoicePaid(invoice) {
             return;
         }
         if (isRenewal) {
-            // 续订时，一定要查到订阅记录
+            // must query it's subscription db record
             const subscription = yield subscriptionService.findByPaySubscriptionId(subscriptionId);
             if (!subscription) {
                 throw new Error(`Subscription not found for renewal: ${subscriptionId}`);
@@ -272,8 +272,8 @@ function handleInvoicePaid(invoice) {
                 throw new Error(`Renewal invoice ${invoice.id} already processed as ${existingOrder.orderId}, skipping.`);
             }
             // 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;
@@ -384,7 +384,7 @@ function handleInvoicePaymentFailed(invoice) {
         }
         const subscriptionId = parentDetails.subscription;
         const subscriptionMetadata = parentDetails.metadata || {};
-        // 支付ID
+        // PaymentIntentId
         const paymentIntentId = yield fetchPaymentId(invoice.id);
         console.log('Invoice payment failed event key-info:', {
             invoiceId: invoice.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windrun-huaiin/backend-core",
-  "version": "29.0.3",
+  "version": "31.0.0",
   "description": "Shared backend primitives: Prisma schema/client, database services, routing helpers",
   "type": "module",
   "main": "./dist/index.js",
@@ -139,7 +139,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@clerk/nextjs": "^7.0.5",
+    "@clerk/nextjs": "^7.3.3",
     "@upstash/redis": "^1.34.0",
     "@upstash/qstash": "^2.7.0",
     "@upstash/lock": "^0.2.1",
@@ -148,9 +148,9 @@
     "svix": "^1.86.0",
     "tslib": "^2.8.1",
     "zod": "^4.3.6",
-    "@windrun-huaiin/contracts": "^29.0.0",
-    "@windrun-huaiin/lib": "^29.0.0",
-    "@windrun-huaiin/third-ui": "^29.0.3"
+    "@windrun-huaiin/lib": "^31.0.0",
+    "@windrun-huaiin/third-ui": "^31.0.0",
+    "@windrun-huaiin/contracts": "^31.0.0"
   },
   "devDependencies": {
     "@rollup/plugin-alias": "^5.1.1",
@@ -163,7 +163,7 @@
   },
   "peerDependencies": {
     "@windrun-huaiin/contracts": ">=22.0.0",
-    "@clerk/nextjs": "^7.0.5",
+    "@clerk/nextjs": "^7.3.3",
     "@prisma/client": "^7.8.0",
     "next": "16.1.6",
     "stripe": "22.0.2",
@@ -172,6 +172,13 @@
   "publishConfig": {
     "access": "public"
   },
+  "author": "windrun-huaiin",
+  "homepage": "https://d8ger.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caofanCPU/next-ai-build.git",
+    "directory": "packages/backend-core"
+  },
   "scripts": {
     "build": "rm -rf dist && rollup -c rollup.config.mjs",
     "build:prod": "rm -rf dist && rollup -c rollup.config.mjs",

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

@@ -23,9 +23,9 @@ import { finalizeUserContext } from '@core/context/user-context-finalizer';
 import type { CoreJsonObject } from '@core/db/prisma-model-type';
 
 
-// ==================== 类型定义 ====================
+// ==================== Type Definitions ====================
 
-/** 成功响应数据 */
+/** Successful response payload */
 interface XUserResponse {
   success: true;
   xUser: XUser;
@@ -36,14 +36,14 @@ interface XUserResponse {
   hasAnonymousUser?: boolean;
 }
 
-/** 错误响应数据 */
+/** Error response payload */
 interface ErrorResponse {
   error: string;
 }
 
-// ==================== 工具函数 ====================
+// ==================== Utilities ====================
 
-/** 创建成功响应对象 */
+/** Create a successful response payload */
 function createSuccessResponse(params: {
   entities: UserContextEntities;
   isNewUser: boolean;
@@ -64,7 +64,7 @@ function createSuccessResponse(params: {
   return finalizeUserContext(response);
 }
 
-/** 创建错误响应 */
+/** Create an error response */
 function createErrorResponse(message: string, status = 400): NextResponse {
   const errorResponse: ErrorResponse = { error: message };
   return NextResponse.json(errorResponse, { status });
@@ -552,7 +552,7 @@ function finalizeAttribution(sourceRef: SourceRefData) {
   sourceRef.sourceType = 'direct';
 }
 
-// 提取用户首次访问来源
+// Extract the user's first-touch attribution source.
 function extractSourceRef(request: NextRequest): SourceRefData | null {
   const headerRef = request.headers.get('referer') || request.headers.get('referrer');
   const customRef = request.headers.get('x-source-ref');
@@ -603,7 +603,7 @@ function extractSourceRef(request: NextRequest): SourceRefData | null {
 
 
 /**
- * 根据fingerprint_id查询用户并返回响应数据
+ * Query the user by Clerk user ID and return response data.
  */
 async function getUserByClerkId(clerkUserId: string): Promise<XUserResponse | null> {
   const entities = await fetchUserContextByClerkUserId(clerkUserId);
@@ -618,7 +618,7 @@ async function getUserByClerkId(clerkUserId: string): Promise<XUserResponse | nu
 }
 
 /**
- * 根据fingerprint_id查询用户并返回响应数据
+ * Query the user by fingerprint ID and return response data.
  */
 async function getUserByFingerprintId(fingerprintId: string): Promise<XUserResponse | null> {
   const result = await fetchLatestUserContextByFingerprintId(fingerprintId);
@@ -639,12 +639,12 @@ async function getUserByFingerprintId(fingerprintId: string): Promise<XUserRespo
 }
 
 /**
- * 通用的fingerprint处理逻辑
+ * Shared fingerprint request handling logic.
  */
 async function handleFingerprintRequest(request: NextRequest, options: { createIfNotExists?: boolean; } = {}) {
-  // 从请求中提取fingerprint ID
+  // Extract the fingerprint ID from the request.
   const fingerprintId = extractFingerprintFromNextRequest(request);
-  // 验证fingerprint ID
+  // Validate the fingerprint ID.
   if (!fingerprintId) {
     return createErrorResponse('Invalid or missing fingerprint ID');
   }
@@ -653,27 +653,26 @@ async function handleFingerprintRequest(request: NextRequest, options: { createI
   const authIdentity = await getOptionalServerAuthIdentity();
   const clerkUserId = authIdentity?.providerUserId ?? null;
   try {
-    // 优先根据 Clerk ID 查询（如果已登录）
+    // Prefer Clerk user ID lookup when the user is authenticated.
     let existingUserResult: XUserResponse | null = null;
     if (clerkUserId) {
-      // 已登录一律按照clerkUserId去查
+      // Authenticated users are always resolved by clerkUserId.
       existingUserResult = await getUserByClerkId(clerkUserId);
       if (existingUserResult && existingUserResult.xUser.fingerprintId !== fingerprintId) {
-        // 说明当前用户的指纹ID发生了改变，为什么呢？因为它使用同一账号去注册Clerk，Clerk判定是同一用户！
-        // 这个时候一定以登录用户clerkUserId为准
-        // 但是考虑到同一指纹ID本身可以绑定多个账号，所以这里什么都不做
-        // 就是以当前登录用户去查他自己的数据就行！
+        // The authenticated user's fingerprint changed. Clerk still identifies the account as the same user.
+        // Trust clerkUserId as the source of truth and keep resolving the user's own data by login identity.
+        // A single fingerprint can be associated with multiple accounts, so no mutation is needed here.
         console.warn(`Current login user used diff fp_ids: ${clerkUserId}, db_fp_id=${existingUserResult.xUser.fingerprintId}, req_fp_id=${fingerprintId}`);
       }
     } else {
-      // 其次才是检查是否已存在该fingerprint的用户
+      // For anonymous requests, fall back to fingerprint lookup.
       existingUserResult = await getUserByFingerprintId(fingerprintId);
     }
     if (existingUserResult) {
       return NextResponse.json(existingUserResult);
     }
 
-    // 如果不存在用户且不允许创建，返回404
+    // If the user does not exist and creation is disabled, return 404.
     if (!options.createIfNotExists) {
       return createErrorResponse('User not found', 404);
     }
@@ -689,7 +688,7 @@ async function handleFingerprintRequest(request: NextRequest, options: { createI
       console.log(`Created new anonymous user ${anonymousInitResult.user.userId} with fingerprint ${fingerprintId}`);
     }
 
-    // 返回创建结果
+    // Return the created or existing context.
     const response = createSuccessResponse({
       entities: {
         user: anonymousInitResult.user,
@@ -711,7 +710,7 @@ async function handleFingerprintRequest(request: NextRequest, options: { createI
 }
 
 /**
- * 匿名用户初始化API
+ * Anonymous user initialization API.
  * POST /api/user/anonymous/init
  */
 export async function POST(request: NextRequest) {

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