create-pardx-scaffold 0.1.0

package/template/apps/api/libs/infra/redis/tsconfig.lib.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "outDir": "../../dist/libs/redis"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test", "**/*spec.ts"]
+}

package/template/apps/api/libs/infra/shared-db/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Transaction Module
+ * 事务模块导出
+ */
+
+export { TransactionModule } from './transaction.module';
+export { UnitOfWorkService } from './unit-of-work.service';
+export type { TransactionOptions } from './unit-of-work.service';
+export {
+  getTransactionClient,
+  runInTransactionContext,
+  isInTransaction,
+} from './transaction-context';
+export { TransactionalServiceBase } from './transactional-service.base';

package/template/apps/api/libs/infra/shared-db/transaction-context.ts

@@ -0,0 +1,51 @@
+/**
+ * Transaction Context
+ * 事务上下文管理
+ *
+ * 使用 AsyncLocalStorage 在调用链中传递事务客户端
+ * 让 db 服务层能够自动感知当前是否在事务中
+ */
+
+import { AsyncLocalStorage } from 'async_hooks';
+import { PrismaClient } from '@prisma/client';
+
+/**
+ * Transaction context storage
+ * 事务上下文存储
+ */
+const transactionContext = new AsyncLocalStorage<PrismaClient>();
+
+/**
+ * Get current transaction client if in a transaction
+ * 获取当前事务客户端（如果在事务中）
+ *
+ * @returns Transaction client or undefined
+ */
+export function getTransactionClient(): PrismaClient | undefined {
+  return transactionContext.getStore();
+}
+
+/**
+ * Run callback with transaction context
+ * 在事务上下文中运行回调
+ *
+ * @param tx - Transaction client
+ * @param callback - Callback function
+ * @returns Result of callback
+ */
+export async function runInTransactionContext<T>(
+  tx: PrismaClient,
+  callback: () => Promise<T>,
+): Promise<T> {
+  return transactionContext.run(tx, callback);
+}
+
+/**
+ * Check if currently in a transaction
+ * 检查当前是否在事务中
+ *
+ * @returns True if in transaction
+ */
+export function isInTransaction(): boolean {
+  return transactionContext.getStore() !== undefined;
+}

package/template/apps/api/libs/infra/shared-db/transaction.module.ts

@@ -0,0 +1,15 @@
+/**
+ * Transaction Module
+ * 事务模块
+ */
+
+import { Module } from '@nestjs/common';
+import { UnitOfWorkService } from './unit-of-work.service';
+import { PrismaModule } from '@/prisma/prisma.module';
+
+@Module({
+  imports: [PrismaModule],
+  providers: [UnitOfWorkService],
+  exports: [UnitOfWorkService],
+})
+export class TransactionModule {}

package/template/apps/api/libs/infra/shared-db/transaction.perf.spec.ts

@@ -0,0 +1,226 @@
+/**
+ * Transaction Performance Tests
+ * 事务性能测试
+ *
+ * 验证事务管理的性能开销和正确性
+ *
+ * 注意：这些测试使用纯 JavaScript 模拟，不依赖完整的 NestJS/Prisma 运行时
+ */
+
+import { AsyncLocalStorage } from 'async_hooks';
+
+/**
+ * 模拟 AsyncLocalStorage 性能测试
+ */
+describe('AsyncLocalStorage Performance', () => {
+  const als = new AsyncLocalStorage<{ txClient: object }>();
+
+  it('should have minimal overhead for context operations', () => {
+    const iterations = 10000;
+    const times: number[] = [];
+
+    for (let i = 0; i < iterations; i++) {
+      const start = performance.now();
+
+      // 模拟 runInTransactionContext
+      als.run({ txClient: {} }, () => {
+        // 模拟 getTransactionClient
+        const store = als.getStore();
+        return store?.txClient;
+      });
+
+      times.push(performance.now() - start);
+    }
+
+    const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
+    const p99Time = times.sort((a, b) => a - b)[Math.floor(iterations * 0.99)];
+
+    console.log(`AsyncLocalStorage Performance (${iterations} iterations):`);
+    console.log(`  - Average: ${(avgTime * 1000).toFixed(2)}μs`);
+    console.log(`  - P99: ${(p99Time * 1000).toFixed(2)}μs`);
+
+    // AsyncLocalStorage 操作应该 < 0.1ms
+    expect(avgTime).toBeLessThan(0.1);
+  });
+
+  it('should handle nested context correctly', () => {
+    let outerValue: object | undefined;
+    let innerValue: object | undefined;
+
+    const outerCtx = { txClient: { id: 'outer' } };
+    const innerCtx = { txClient: { id: 'inner' } };
+
+    als.run(outerCtx, () => {
+      outerValue = als.getStore()?.txClient;
+
+      // 嵌套上下文不应该覆盖外层
+      als.run(innerCtx, () => {
+        innerValue = als.getStore()?.txClient;
+      });
+
+      // 退出嵌套后应该恢复外层
+      expect(als.getStore()?.txClient).toBe(outerCtx.txClient);
+    });
+
+    expect(outerValue).toBe(outerCtx.txClient);
+    expect(innerValue).toBe(innerCtx.txClient);
+  });
+});
+
+/**
+ * 模拟 Symbol 事务存储性能测试
+ */
+describe('Symbol Transaction Storage Performance', () => {
+  const TX_CLIENT = Symbol('TX_CLIENT');
+
+  it('should have minimal overhead for symbol operations', () => {
+    const iterations = 10000;
+    const times: number[] = [];
+    const context: Record<symbol, object> = {};
+    const mockClient = { id: 'mock-tx' };
+
+    for (let i = 0; i < iterations; i++) {
+      const start = performance.now();
+
+      // 模拟 setTransactionClient
+      context[TX_CLIENT] = mockClient;
+
+      // 模拟 getTransactionClient
+      const client = context[TX_CLIENT];
+
+      // 模拟 clearTransactionClient
+      delete context[TX_CLIENT];
+
+      times.push(performance.now() - start);
+    }
+
+    const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
+    const p99Time = times.sort((a, b) => a - b)[Math.floor(iterations * 0.99)];
+
+    console.log(`Symbol Storage Performance (${iterations} iterations):`);
+    console.log(`  - Average: ${(avgTime * 1000).toFixed(2)}μs`);
+    console.log(`  - P99: ${(p99Time * 1000).toFixed(2)}μs`);
+
+    // Symbol 操作应该 < 0.01ms
+    expect(avgTime).toBeLessThan(0.01);
+  });
+});
+
+/**
+ * 模拟 @Transactional 装饰器开销测试
+ */
+describe('Transactional Decorator Overhead', () => {
+  const TX_CLIENT = Symbol('TX_CLIENT');
+
+  // 模拟装饰器包装函数
+  function simulateTransactionalWrapper(
+    context: Record<symbol, object>,
+    originalMethod: () => Promise<unknown>,
+    mockTx: object,
+  ): () => Promise<unknown> {
+    return async () => {
+      // 检查是否已在事务中
+      if (context[TX_CLIENT]) {
+        return originalMethod();
+      }
+
+      const startTime = Date.now();
+
+      try {
+        // 模拟 $transaction
+        context[TX_CLIENT] = mockTx;
+        const result = await originalMethod();
+        return result;
+      } finally {
+        delete context[TX_CLIENT];
+        const duration = Date.now() - startTime;
+        // 模拟日志（生产环境下条件日志）
+        if (process.env.NODE_ENV === 'dev' || duration > 1000) {
+          // console.log 在生产环境下被跳过
+        }
+      }
+    };
+  }
+
+  it('should have minimal wrapper overhead', async () => {
+    const iterations = 1000;
+    const times: number[] = [];
+    const context: Record<symbol, object> = {};
+    const mockTx = { id: 'mock-tx' };
+
+    const originalMethod = async () => {
+      // 模拟简单操作
+      return { success: true };
+    };
+
+    const wrappedMethod = simulateTransactionalWrapper(
+      context,
+      originalMethod,
+      mockTx,
+    );
+
+    for (let i = 0; i < iterations; i++) {
+      const start = performance.now();
+      await wrappedMethod();
+      times.push(performance.now() - start);
+    }
+
+    const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
+    const p99Time = times.sort((a, b) => a - b)[Math.floor(iterations * 0.99)];
+
+    console.log(`Decorator Wrapper Performance (${iterations} iterations):`);
+    console.log(`  - Average: ${avgTime.toFixed(3)}ms`);
+    console.log(`  - P99: ${p99Time.toFixed(3)}ms`);
+
+    // 装饰器包装开销应该 < 1ms
+    expect(avgTime).toBeLessThan(1);
+  });
+
+  it('should skip transaction creation for nested calls', async () => {
+    const context: Record<symbol, object> = {};
+    const mockTx = { id: 'mock-tx' };
+    let transactionCreated = 0;
+
+    const createTransaction = async () => {
+      transactionCreated++;
+      context[TX_CLIENT] = mockTx;
+    };
+
+    const wrappedMethod = async () => {
+      if (!context[TX_CLIENT]) {
+        await createTransaction();
+      }
+      // 嵌套调用
+      if (!context[TX_CLIENT]) {
+        await createTransaction();
+      }
+    };
+
+    await wrappedMethod();
+
+    // 应该只创建一次事务
+    expect(transactionCreated).toBe(1);
+  });
+});
+
+/**
+ * 性能基准目标
+ */
+describe('Performance Benchmarks Summary', () => {
+  it('should document performance targets', () => {
+    const targets = {
+      asyncLocalStorageOverhead: '< 0.1ms per operation',
+      symbolStorageOverhead: '< 0.01ms per operation',
+      decoratorWrapperOverhead: '< 1ms per transaction',
+      nestedTransactionDetection: '< 0.01ms',
+      totalTransactionOverhead: '< 5ms (excluding DB operations)',
+    };
+
+    console.log('\n=== Transaction Performance Targets ===');
+    Object.entries(targets).forEach(([key, value]) => {
+      console.log(`  ${key}: ${value}`);
+    });
+
+    expect(true).toBe(true);
+  });
+});

package/template/apps/api/libs/infra/shared-db/transactional-service.base.ts

@@ -0,0 +1,102 @@
+/**
+ * Transactional Service Base
+ * 事务感知服务基类
+ *
+ * 所有 db 服务层应该继承此基类，以支持事务上下文
+ * 自动检测是否在事务中，如果在事务中则使用事务客户端，否则使用常规客户端
+ *
+ * 支持两种事务方式：
+ * 1. @Transactional 装饰器（使用 Symbol 存储，适合单个服务内部事务）
+ * 2. UnitOfWorkService（使用 AsyncLocalStorage，适合跨服务事务）
+ *
+ * 两种方式可以协同工作，服务层会自动检测并使用正确的事务客户端
+ */
+
+import { PrismaClient } from '@prisma/client';
+import { PrismaService } from '@app/prisma';
+import {
+  getTransactionClient as getAsyncTransactionClient,
+  isInTransaction as isInAsyncTransaction,
+} from './transaction-context';
+import { getTransactionClient as getSymbolTransactionClient } from '@/decorators/transaction/transactional.decorator';
+
+/**
+ * Base class for transactional services
+ * 事务感知服务基类
+ */
+export abstract class TransactionalServiceBase {
+  constructor(protected readonly prisma: PrismaService) {}
+
+  /**
+   * Get write client (transaction-aware)
+   * 获取写客户端（事务感知）
+   *
+   * 优先使用 AsyncLocalStorage 中的事务客户端（UnitOfWorkService）
+   * 其次使用 Symbol 中的事务客户端（@Transactional 装饰器）
+   * 最后使用常规写客户端
+   *
+   * Returns transaction client if in a transaction,
+   * otherwise returns regular write client.
+   */
+  protected getWriteClient(): PrismaClient {
+    // 1. 优先检查 AsyncLocalStorage（UnitOfWorkService）
+    const asyncTxClient = getAsyncTransactionClient();
+    if (asyncTxClient) {
+      return asyncTxClient;
+    }
+
+    // 2. 检查 Symbol（@Transactional 装饰器）
+    const symbolTxClient = getSymbolTransactionClient(this);
+    if (symbolTxClient) {
+      return symbolTxClient;
+    }
+
+    // 3. 使用常规写客户端
+    return this.prisma.write;
+  }
+
+  /**
+   * Get read client
+   * 获取读客户端
+   *
+   * Note: In transaction, read operations should also use write client
+   * to ensure consistency (read-after-write)
+   */
+  protected getReadClient(): PrismaClient {
+    // 如果在事务中，使用事务客户端以确保读取一致性
+    // 如果不在事务中，使用读客户端
+
+    // 1. 优先检查 AsyncLocalStorage（UnitOfWorkService）
+    const asyncTxClient = getAsyncTransactionClient();
+    if (asyncTxClient) {
+      return asyncTxClient;
+    }
+
+    // 2. 检查 Symbol（@Transactional 装饰器）
+    const symbolTxClient = getSymbolTransactionClient(this);
+    if (symbolTxClient) {
+      return symbolTxClient;
+    }
+
+    // 3. 使用常规读客户端
+    return this.prisma.read;
+  }
+
+  /**
+   * Check if currently in a transaction
+   * 检查当前是否在事务中
+   */
+  protected isInTransaction(): boolean {
+    // 检查 AsyncLocalStorage
+    if (isInAsyncTransaction()) {
+      return true;
+    }
+
+    // 检查 Symbol
+    if (getSymbolTransactionClient(this)) {
+      return true;
+    }
+
+    return false;
+  }
+}

package/template/apps/api/libs/infra/shared-db/unit-of-work.service.ts

@@ -0,0 +1,142 @@
+/**
+ * Unit of Work Service
+ * 工作单元服务 - 统一管理跨服务事务
+ *
+ * 职责：
+ * 1. 提供统一的事务管理接口
+ * 2. 支持跨多个 db 服务的事务操作
+ * 3. 自动处理事务的提交和回滚
+ * 4. 支持嵌套事务检测
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class SignService {
+ *   constructor(
+ *     private readonly uow: UnitOfWorkService,
+ *     private readonly userService: UserService,
+ *   ) {}
+ *
+ *   async createAccount(data: CreateAccountDto) {
+ *     return await this.uow.execute(async () => {
+ *       // 在事务中调用服务层方法，服务层会自动使用事务客户端
+ *       const user = await this.userService.createUser(data);
+ *       return { user };
+ *     });
+ *   }
+ * }
+ * ```
+ */
+
+import { Injectable } from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+import { PrismaService } from '@app/prisma';
+import { runInTransactionContext } from './transaction-context';
+
+/**
+ * Transaction options
+ * 事务选项
+ */
+export interface TransactionOptions {
+  maxWait?: number;
+  timeout?: number;
+  isolationLevel?:
+    | 'ReadUncommitted'
+    | 'ReadCommitted'
+    | 'RepeatableRead'
+    | 'Serializable';
+}
+
+/**
+ * Unit of Work Service
+ * 工作单元服务
+ */
+@Injectable()
+export class UnitOfWorkService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  /**
+   * Execute a callback within a transaction
+   * 在事务中执行回调
+   *
+   * 使用 AsyncLocalStorage 在调用链中传递事务客户端
+   * db 服务层会自动检测并使用事务客户端
+   *
+   * @param callback - Callback function (no need to pass tx parameter)
+   * @param options - Transaction options
+   * @returns Result of the callback
+   */
+  async execute<T>(
+    callback: () => Promise<T>,
+    options?: TransactionOptions,
+  ): Promise<T> {
+    return await this.prisma.write.$transaction(async (tx) => {
+      // 在事务上下文中运行回调
+      // db 服务层会自动通过 getTransactionClient() 获取事务客户端
+      return await runInTransactionContext(
+        tx as unknown as PrismaClient,
+        callback,
+      );
+    }, options);
+  }
+
+  /**
+   * Execute with retry on deadlock/conflict
+   * 在死锁/冲突时重试执行
+   *
+   * @param callback - Callback function
+   * @param options - Transaction options with retry config
+   * @returns Result of the callback
+   */
+  async executeWithRetry<T>(
+    callback: () => Promise<T>,
+    options?: TransactionOptions & {
+      maxRetries?: number;
+      retryDelay?: number;
+    },
+  ): Promise<T> {
+    const maxRetries = options?.maxRetries ?? 3;
+    const retryDelay = options?.retryDelay ?? 100;
+    const { maxRetries: _, retryDelay: __, ...txOptions } = options || {};
+
+    let lastError: Error | undefined;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await this.execute(callback, txOptions);
+      } catch (error) {
+        lastError = error as Error;
+        if (this.isRetryableError(error) && attempt < maxRetries) {
+          await this.sleep(retryDelay * Math.pow(2, attempt));
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw lastError || new Error('Transaction failed after max retries');
+  }
+
+  /**
+   * Check if error is retryable
+   * 检查错误是否可重试
+   */
+  private isRetryableError(error: unknown): boolean {
+    if (!error || typeof error !== 'object') return false;
+
+    const prismaCode = (error as { code?: string }).code;
+    const retryableCodes = ['P2034', 'P2028', '40001', '40P01'];
+    if (prismaCode && retryableCodes.includes(prismaCode)) {
+      return true;
+    }
+
+    const message = (error as { message?: string }).message || '';
+    return retryableCodes.some((code) => message.includes(code));
+  }
+
+  /**
+   * Sleep for specified milliseconds
+   * 睡眠指定毫秒数
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/template/apps/api/libs/infra/shared-services/email/dto/email.dto.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+
+// ============================================================================
+// Email Configuration Schemas
+// ============================================================================
+
+export const EmailKeysSchema = z.object({
+  accessKey: z.string(),
+  accessSecret: z.string(),
+  host: z.string(),
+  port: z.number(),
+  secure: z.boolean(),
+  user: z.string(),
+  pass: z.string(),
+});
+
+export const EmailTemplateSchema = z.object({
+  name: z.string(),
+  subject: z.string(),
+  from: z.string(),
+  templateInvokeName: z.string(),
+  codeExpire: z.number().optional(),
+  frequency: z.number().optional(),
+  sub: z.record(z.string()).nullable().optional(),
+});
+
+export const EmailConfigSchema = z.object({
+  vendor: z.string(),
+  apiUser: z.string(),
+  apiKey: z.string(),
+  domain: z.string(),
+  name: z.string(),
+  templates: z.array(EmailTemplateSchema),
+});
+
+// ============================================================================
+// Email Message Schemas
+// ============================================================================
+
+export const EmailSubValuesSchema = z.object({
+  name: z.string(),
+  code: z.string(),
+});
+
+export const SignalMessageSchema = z.object({
+  to: z.string().email(),
+  subject: z.string().optional(),
+  templateInvokeName: z.string(),
+  sub: z.record(z.array(z.string())),
+  options: z.any().optional(),
+  queueMailId: z.string().optional(),
+  metadata: z.record(z.any()).optional(),
+});
+
+// ============================================================================
+// Email Account Schemas
+// ============================================================================
+
+export const EmailAccountSchema = z.object({
+  email: z.string().email(),
+  name: z.string(),
+});
+
+export const EmailAccountInputSchema = EmailAccountSchema.partial();
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type EmailKeys = z.infer<typeof EmailKeysSchema>;
+export type EmailTemplate = z.infer<typeof EmailTemplateSchema>;
+export type EmailConfig = z.infer<typeof EmailConfigSchema>;
+export type EmailSubValues = z.infer<typeof EmailSubValuesSchema>;
+export type SignalMessage = z.infer<typeof SignalMessageSchema>;
+export type EmailAccount = z.infer<typeof EmailAccountSchema>;
+
+// ============================================================================
+// Legacy Namespace (for backward compatibility)
+// ============================================================================
+
+export namespace PardxEmailSender {
+  export type EmailKeys = z.infer<typeof EmailKeysSchema>;
+  export type Config = z.infer<typeof EmailConfigSchema>;
+  export type SignalMessage = z.infer<typeof SignalMessageSchema>;
+  export type RegisterEmailSub = z.infer<typeof EmailSubValuesSchema>;
+  export type EmailTemplate = z.infer<typeof EmailTemplateSchema>;
+}

package/template/apps/api/libs/infra/shared-services/email/email.module.ts

@@ -0,0 +1,27 @@
+/**
+ * Email Service Module
+ *
+ * 职责：提供邮件发送的业务逻辑服务
+ */
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { HttpModule } from '@nestjs/axios';
+import { RedisModule } from '@app/redis';
+import { RabbitmqModule } from '@app/rabbitmq';
+import { VerifyModule } from '@app/clients/internal/verify';
+import { SystemTaskQueueModule } from '@app/db';
+import { EmailService } from './email.service';
+
+@Module({
+  imports: [
+    ConfigModule,
+    HttpModule,
+    RedisModule,
+    RabbitmqModule,
+    VerifyModule,
+    SystemTaskQueueModule,
+  ],
+  providers: [EmailService],
+  exports: [EmailService],
+})
+export class EmailServiceModule {}