@windrun-huaiin/backend-core 10.0.1

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

@@ -0,0 +1,498 @@
+import {
+  creditService,
+  CreditType,
+  OperationType,
+  OrderStatus,
+  PaymentStatus,
+  PaySupplier,
+  subscriptionService,
+  SubscriptionStatus,
+  transactionService,
+  TransactionType,
+} from '../database/index';
+import type { Subscription, Transaction } from '../database/prisma-model-type';
+import { runInTransaction } from '../../prisma/prisma-transaction-util';
+
+type NullableString = string | null | undefined;
+
+type BasicOrderContext = {
+  userId: string;
+  subIdKey: bigint;
+  orderId: string;
+  paySubscriptionId: string,
+  creditsGranted: number;
+  priceId?: NullableString;
+  priceName?: NullableString;
+  periodStart: Date | null;
+  periodEnd: Date | null;
+  invoiceId: string;
+  hostedInvoiceUrl?: NullableString;
+  invoicePdf?: NullableString;
+  billingReason?: NullableString;
+  paymentIntentId?: string;
+  paidAt:  Date | null;
+  paidEmail: string | null;
+};
+
+type RenewalOrderContext = BasicOrderContext & {
+  // 续订时以Stripe的发票价格为准
+  amountPaidCents: number;
+  currency: string;
+}
+
+type SubscriptionCancelContext = {
+  userId: string;
+  subIdKey: bigint;
+  orderId: string;
+  canceledAt: Date;
+  cancellationDetail?: string 
+};
+
+type SubscriptionRefundContext = {
+  transaction: Transaction;
+  subscription?: Subscription | null;
+};
+
+type OneTimeRefundContext = {
+  transaction: Transaction;
+};
+
+class BillingAggregateService {
+
+  async recordSubscriptionInitPayment(
+    context: BasicOrderContext
+  ): Promise<void> {
+    await runInTransaction(async (tx) => {
+      const now = new Date();
+      // 订阅截止时间统一为到期日最后1s
+      const originSubPeriodEnd = context.periodEnd;
+      const specialEnd = originSubPeriodEnd ? new Date(originSubPeriodEnd.setHours(23, 59, 59, 999)) : originSubPeriodEnd;
+      const updatedSubscription = await subscriptionService.updateSubscription(
+        context.subIdKey,
+        {
+          status: SubscriptionStatus.ACTIVE,
+          orderId: context.orderId ?? undefined,
+          paySubscriptionId: context.paySubscriptionId,
+          priceId: context.priceId ?? undefined,
+          priceName: context.priceName ?? undefined,
+          creditsAllocated: context.creditsGranted || 0,
+          subPeriodStart: context.periodStart,
+          subPeriodEnd: specialEnd,
+          updatedAt: now,
+        },
+        tx
+      );
+
+
+      await transactionService.update(
+        context.orderId,
+        {
+          orderStatus: OrderStatus.SUCCESS,
+          paymentStatus: PaymentStatus.PAID,
+          paySubscriptionId: context.paySubscriptionId,
+          subPeriodStart: context.periodStart,
+          subPeriodEnd: context.periodEnd,
+          payInvoiceId: context.invoiceId,
+          hostedInvoiceUrl: context.hostedInvoiceUrl ?? undefined,
+          invoicePdf: context.invoicePdf ?? undefined,
+          billingReason: context.billingReason ?? undefined,
+          payTransactionId: context.paymentIntentId ?? undefined,
+          paidEmail: context.paidEmail ?? undefined,
+          paidAt: context.paidAt,
+          payUpdatedAt: now,
+        },
+        tx
+      );
+
+      if (context.creditsGranted > 0) {
+        await creditService.rechargeCredit(
+          context.userId,
+          { paid: context.creditsGranted },
+          {
+            feature: TransactionType.SUBSCRIPTION,
+            operationReferId: context.orderId,
+          },
+          tx
+        );
+      }
+
+      await tx.credit.update({
+        where: { userId: context.userId },
+        data: {
+          paidStart: context.periodStart,
+          paidEnd: context.periodEnd,
+        },
+      });
+
+      return updatedSubscription;
+    })
+  }
+
+
+  async completeOneTimeCheckout(
+    params: {
+      userId: string;
+      orderId: string;
+      creditsGranted: number;
+      paymentStatus: PaymentStatus;
+      payTransactionId: string;
+      paidAt: Date;
+      paidEmail?: NullableString;
+      oneTimePaidStart: Date;
+      oneTimePaidEnd: Date;
+    }
+  ): Promise<void> {
+    await runInTransaction(async (tx) => {
+      const now = new Date();
+
+      await transactionService.update(
+        params.orderId,
+        {
+          orderStatus: OrderStatus.SUCCESS,
+          paymentStatus: params.paymentStatus,
+          payTransactionId: params.payTransactionId,
+          paidAt: now,
+          paidEmail: params.paidEmail ?? undefined,
+          payUpdatedAt: now,
+        },
+        tx
+      );
+
+      if (params.creditsGranted > 0) {
+        await creditService.rechargeCredit(
+          params.userId,
+          { oneTimePaid: params.creditsGranted },
+          {
+            feature: TransactionType.ONE_TIME,
+            operationReferId: params.orderId,
+          },
+          tx
+        );
+      }
+
+      await tx.credit.update({
+        where: { userId: params.userId },
+        data: {
+          oneTimePaidStart: params.oneTimePaidStart,
+          oneTimePaidEnd: params.oneTimePaidEnd,
+        },
+      });
+    });
+  }
+
+  async recordInitialInvoiceDetails(
+    params: {
+      orderId: string;
+      invoiceId: string;
+      paymentIntentId: string,
+      hostedInvoiceUrl?: NullableString;
+      invoicePdf?: NullableString;
+      billingReason?: NullableString;
+    }
+  ): Promise<void> {
+    await runInTransaction(async (tx) => {
+      await transactionService.update(
+        params.orderId,
+        {
+          payInvoiceId: params.invoiceId,
+          payTransactionId: params.paymentIntentId,
+          hostedInvoiceUrl: params.hostedInvoiceUrl ?? undefined,
+          invoicePdf: params.invoicePdf ?? undefined,
+          billingReason: params.billingReason ?? undefined,
+          payUpdatedAt: new Date(),
+        },
+        tx
+      );
+    });
+  }
+
+  async recordSubscriptionRenewalPayment(
+    context: RenewalOrderContext
+  ): Promise<void> {
+    await runInTransaction(async (tx) => {
+      await transactionService.createTransaction(
+        {
+          userId: context.userId,
+          orderId: context.orderId,
+          orderStatus: OrderStatus.SUCCESS,
+          paymentStatus: PaymentStatus.PAID,
+          paySupplier: PaySupplier.STRIPE,
+          paySubscriptionId: context.paySubscriptionId ?? undefined,
+          subPeriodStart: context.periodStart ?? undefined,
+          subPeriodEnd: context.periodEnd ?? undefined,
+          payInvoiceId: context.invoiceId,
+          hostedInvoiceUrl: context.hostedInvoiceUrl ?? undefined,
+          invoicePdf: context.invoicePdf ?? undefined,
+          billingReason: context.billingReason ?? undefined,
+          payTransactionId: context.paymentIntentId ?? undefined,
+          priceId: context.priceId ?? undefined,
+          priceName: context.priceName ?? undefined,
+          type: TransactionType.SUBSCRIPTION,
+          amount: context.amountPaidCents / 100,
+          currency: context.currency.toUpperCase(),
+          creditsGranted: context.creditsGranted,
+          paidAt: context.paidAt ?? undefined,
+          paidEmail: context.paidEmail,
+          payUpdatedAt: new Date(),
+        },
+        tx
+      );
+      // 订阅截止时间统一为到期日最后1s
+      const originSubPeriodEnd = context.periodEnd;
+      const specialEnd = originSubPeriodEnd ? new Date(originSubPeriodEnd.setHours(23, 59, 59, 999)) : originSubPeriodEnd;
+
+      await subscriptionService.updateSubscription(
+        context.subIdKey,
+        {
+          status: SubscriptionStatus.ACTIVE,
+          orderId: context.orderId,
+          subPeriodStart: context.periodStart,
+          subPeriodEnd: specialEnd,
+          updatedAt: new Date(),
+        },
+        tx
+      );
+
+      if (context.creditsGranted > 0) {
+        await creditService.rechargeCredit(
+          context.userId,
+          { paid: context.creditsGranted },
+          {
+            feature: `${TransactionType.SUBSCRIPTION}_renewal`,
+            operationReferId: context.orderId,
+          },
+          tx
+        );
+      }
+
+      await tx.credit.update({
+        where: { userId: context.userId },
+        data: {
+          paidStart: context.periodStart,
+          paidEnd: context.periodEnd,
+        },
+      });
+    });
+  }
+
+  async recordInitialPaymentFailure(
+    params: {
+      orderId: string;
+      invoiceId: string;
+      paymentIntentId: string;
+      detail?: string;
+    }
+  ): Promise<void> {
+    await runInTransaction(async (tx) => {
+      await transactionService.updateStatus(
+        params.orderId,
+        OrderStatus.FAILED,
+        {
+          paymentStatus: PaymentStatus.UN_PAID,
+          payInvoiceId: params.invoiceId,
+          payTransactionId: params.paymentIntentId,
+          payUpdatedAt: new Date(),
+          paidDetail: params.detail ?? undefined,
+          orderDetail: params.detail ?? undefined,
+        },
+        tx
+      );
+    });
+  }
+
+  async recordRenewalPaymentFailure(
+    context: RenewalOrderContext
+  ): Promise<void> {
+    await runInTransaction(async (tx) => {
+      await transactionService.createTransaction(
+        {
+          userId: context.userId,
+          orderId: context.orderId,
+          orderStatus: OrderStatus.FAILED,
+          paymentStatus: PaymentStatus.UN_PAID,
+          paySupplier: PaySupplier.STRIPE,
+          paySubscriptionId: context.paySubscriptionId ?? undefined,
+          payInvoiceId: context.invoiceId,
+          billingReason: context.billingReason ?? undefined,
+          payTransactionId: context.paymentIntentId ?? undefined,
+          priceId: context.priceId ?? undefined,
+          priceName: context.priceName ?? undefined,
+          type: TransactionType.SUBSCRIPTION,
+          amount: context.amountPaidCents / 100,
+          currency: context.currency.toUpperCase(),
+          creditsGranted: 0,
+          paidAt: context.paidAt ?? undefined,
+          paidEmail: context.paidEmail,
+          payUpdatedAt: new Date(),
+          orderDetail: 'Subscription renewal payment failed',
+        },
+        tx
+      );
+
+      await creditService.payFailedWatcher(
+        {
+          userId: context.userId,
+          feature: `${TransactionType.SUBSCRIPTION}_renewal_failed`,
+          operationReferId: context.orderId,
+          creditType: CreditType.PAID,
+          operationType: OperationType.RECHARGE,
+          creditsChange: 0,
+        },
+        tx
+      );
+
+      await subscriptionService.updateSubscription(
+        context.subIdKey,
+        {
+          status: SubscriptionStatus.PAST_DUE,
+          orderId: context.orderId,
+          updatedAt: new Date(),
+        },
+        tx
+      );
+    });
+  }
+
+  async syncSubscriptionFromStripe(
+    params: {
+      subscription: Subscription;
+      status: string;
+      periodStart: Date;
+      periodEnd: Date;
+      orderId: string,
+      isUserCancel: boolean
+    }
+  ): Promise<void> {
+    await runInTransaction(async (tx) => {
+      if (params.isUserCancel) {
+          // 记录用户取消订阅的时间信息
+          await transactionService.update(
+            params.orderId,
+            {
+              subLastTryCancelAt: new Date(),
+            },
+            tx
+          );
+      }
+      await subscriptionService.updateSubscription(
+        params.subscription.id,
+        {
+          status: params.status,
+          subPeriodStart: params.periodStart,
+          subPeriodEnd: params.periodEnd,
+          updatedAt: new Date(),
+        },
+        tx
+      );
+    });
+  }
+
+  async processSubscriptionCancel(
+    context: SubscriptionCancelContext
+  ): Promise<void> {
+    await runInTransaction(async (tx) => {
+      // 更新订单, 记录取消信息
+      await transactionService.update(
+        context.orderId,
+        {
+          subPeriodCanceledAt: context.canceledAt,
+          subCancellationDetail: context.cancellationDetail ?? undefined
+        },
+        tx
+      )
+      // 更新订阅信息
+      await subscriptionService.updateStatus(context.subIdKey, SubscriptionStatus.CANCELED, tx);
+
+      // 清理积分并留痕
+      await creditService.purgePaidCredit(context.userId, 'cancel_subscription_purge', context.orderId, tx);
+    })
+  }
+  
+
+  async processSubscriptionRefund(
+    context: SubscriptionRefundContext
+  ): Promise<void> {
+    await runInTransaction(async (tx) => {
+      const now = new Date();
+
+      await transactionService.update(
+        context.transaction.orderId,
+        {
+          orderStatus: OrderStatus.REFUNDED,
+          paymentStatus: PaymentStatus.UN_PAID,
+          payUpdatedAt: now,
+        },
+        tx
+      );
+
+      const subscription =
+        context.subscription ??
+        (context.transaction.paySubscriptionId
+          ? await subscriptionService.findByPaySubscriptionId(context.transaction.paySubscriptionId, tx)
+          : null);
+
+      if (subscription) {
+        await subscriptionService.updateSubscription(
+          subscription.id,
+          {
+            status: SubscriptionStatus.CANCELED,
+            updatedAt: now,
+          },
+          tx
+        );
+      }
+
+      const credit = await creditService.getCredit(context.transaction.userId, tx);
+      const paidBalance = Math.max(credit?.balancePaid ?? 0, 0);
+
+      if (paidBalance > 0) {
+        await creditService.consumeCredit(
+          context.transaction.userId,
+          { paid: paidBalance },
+          {
+            feature: OrderStatus.REFUNDED,
+            operationReferId: context.transaction.orderId,
+          },
+          tx
+        );
+      }
+    });
+  }
+
+  async processOneTimeRefund(
+    context: OneTimeRefundContext
+  ): Promise<void> {
+    await runInTransaction(async (tx) => {
+      const now = new Date();
+
+      await transactionService.update(
+        context.transaction.orderId,
+        {
+          orderStatus: OrderStatus.REFUNDED,
+          paymentStatus: PaymentStatus.UN_PAID,
+          payUpdatedAt: now,
+        },
+        tx
+      );
+
+      const credit = await creditService.getCredit(context.transaction.userId, tx);
+      const currentBalance = Math.max(credit?.balanceOneTimePaid ?? 0, 0);
+      const granted = Math.max(context.transaction.creditsGranted ?? 0, 0);
+      const amountToConsume = Math.min(currentBalance, granted);
+
+      if (amountToConsume > 0) {
+        await creditService.consumeCredit(
+          context.transaction.userId,
+          { oneTimePaid: amountToConsume },
+          {
+            feature: OrderStatus.REFUNDED,
+            operationReferId: context.transaction.orderId,
+          },
+          tx
+        );
+      }
+    });
+  }
+}
+
+export const billingAggregateService = new BillingAggregateService();

package/src/services/aggregate/index.ts

@@ -0,0 +1,2 @@
+export { userAggregateService } from './user.aggregate.service';
+export { billingAggregateService } from './billing.aggregate.service';

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

@@ -0,0 +1,168 @@
+import { CreditType, OperationType, UserStatus } from '../database/constants';
+import { creditService, subscriptionService, userService } from '../database/index';
+import type { Credit, Prisma, User } from '../database/prisma-model-type';
+import { freeAmount, freeRegisterAmount } from '../../lib/credit-init';
+import { runInTransaction } from '../../prisma/prisma-transaction-util';
+
+
+export class UserAggregateService {
+
+  async initAnonymousUser(
+    fingerprintId: string,
+    options?: { sourceRef?: Prisma.InputJsonValue; }
+  ): Promise<{ newUser: User; credit: Credit; }> {
+    return runInTransaction(async (tx) => {
+      const newUser = await userService.createUser(
+        {
+          fingerprintId,
+          sourceRef: options?.sourceRef,
+          status: UserStatus.ANONYMOUS,
+        },
+        tx
+      );
+
+      const credit = await creditService.initializeCreditWithFree(
+        {
+          userId: newUser.userId,
+          feature: 'anonymous_user_init',
+          creditType: CreditType.FREE,
+          operationType: OperationType.SYS_GIFT,
+          operationReferId: newUser.userId,
+          creditsChange: freeAmount,
+        },
+        tx
+      );
+
+      await subscriptionService.initializeSubscription(newUser.userId, tx);
+
+      return { newUser, credit };
+    });
+  }
+
+  /**
+   * 创建新的注册用户
+   *
+   * 初始化步骤（与 credit 平行）：
+   * 1. 创建 User 记录
+   * 2. 初始化 Credit 记录（免费积分）
+   * 3. 初始化 Subscription 记录（占位符，status=INCOMPLETE）
+   * 4. 记录 CreditUsage（审计）
+   *
+   * 后续当用户通过 Stripe 订阅时：
+   * - session.completed 或 invoice.paid 会 UPDATE subscription 记录
+   * - 不需要 CREATE，只需 UPDATE 确保逻辑一致
+   */
+  async createNewRegisteredUser(
+    clerkUserId: string,
+    email?: string,
+    fingerprintId?: string,
+    userName?: string,
+    sourceRef?: Prisma.InputJsonValue,
+  ): Promise<{ newUser: User; credit: Credit; }> {
+    return runInTransaction(async (tx) => {
+      const newUser = await userService.createUser(
+        {
+          clerkUserId,
+          email,
+          fingerprintId,
+          userName,
+          sourceRef,
+          status: UserStatus.REGISTERED,
+        },
+        tx
+      );
+
+      const credit = await creditService.initializeCreditWithFree(
+        {
+          userId: newUser.userId,
+          feature: 'user_registration_init',
+          creditType: CreditType.FREE,
+          operationType: OperationType.SYS_GIFT,
+          operationReferId: newUser.userId,
+          creditsChange: freeRegisterAmount,
+        },
+      );
+
+      await subscriptionService.initializeSubscription(newUser.userId, tx);
+      return { newUser, credit };
+    });
+  }
+
+  // 注意积分审查日志的处理
+  async upgradeToRegistered(
+    userId: string,
+    email: string,
+    clerkUserId: string,
+    userName?: string,
+  ): Promise<{ updateUser: User; credit: Credit; }> {
+    return runInTransaction(async (tx) => {
+      const updateUser = await userService.upgradeToRegistered(
+        userId,
+        {
+          email,
+          clerkUserId,
+          userName
+        },
+        tx
+      );
+
+      // 先清空匿名积分并审计日志留痕
+      await creditService.purgeFreeCredit(userId, 'user_registered_purge', userId, tx);
+      // 再初始化完成注册获得免费积分
+      const credit = await creditService.initializeCreditWithFree(
+        {
+          userId: updateUser.userId,
+          feature: 'user_registration_init',
+          creditType: CreditType.FREE,
+          operationType: OperationType.SYS_GIFT,
+          operationReferId: userId,
+          creditsChange: freeRegisterAmount,
+        }, 
+        tx
+      );
+      
+      return { updateUser: updateUser, credit: credit };
+    });
+  }
+
+  async handleUserUnregister(clerkUserId: string): Promise<string | null> { 
+    return runInTransaction(async (tx) => {
+      // 根据clerkUserId查找用户
+      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，防止反复注册薅羊毛
+      await userService.unregister(user.userId);
+      // 清空积分
+      await creditService.purgeCredit(userId, 'soft_delete_user', userId, tx);
+      
+      const subscription = await subscriptionService.getActiveSubscription(userId, tx);
+      if (subscription) {
+        // 如果有订阅信息，则要更新
+        await subscriptionService.cancelSubscription(subscription.id, true, tx);
+      }
+
+      return user.userId;
+    });
+  }
+
+  private async findUserWithRelations(
+    userId: string,
+    tx: Prisma.TransactionClient
+  ) {
+    return tx.user.findUnique({
+      where: { userId },
+      include: {
+        credit: true,
+        subscription: true,
+        transactions: true,
+        creditAuditLogs: true,
+      },
+    });
+  }
+}
+
+export const userAggregateService = new UserAggregateService();

package/src/services/context/index.ts

@@ -0,0 +1 @@
+export * from './user-context-service';