create-pardx-scaffold 0.1.0

package/template/apps/api/libs/infra/prisma/middleware/soft-delete.middleware.ts

@@ -0,0 +1,179 @@
+/**
+ * Soft Delete Middleware
+ * 软删除中间件
+ *
+ * 自动处理软删除逻辑：
+ * 1. 查询操作自动添加 isDeleted: false 条件
+ * 2. 删除操作自动转换为软删除（update isDeleted = true）
+ *
+ * Prisma 7.x 更新：
+ * - 使用 $extends 替代已移除的 $use 方法
+ * - 返回扩展后的 PrismaClient 实例
+ *
+ * @example
+ * ```typescript
+ * const prisma = new PrismaClient();
+ * const extendedPrisma = setupSoftDeleteMiddleware(prisma);
+ * // 使用 extendedPrisma 而不是原始的 prisma
+ * await extendedPrisma.userInfo.findMany(); // 自动添加 isDeleted: false
+ * ```
+ */
+
+import { PrismaClient, Prisma } from '@prisma/client';
+
+/**
+ * 查询操作列表
+ */
+const QUERY_ACTIONS = [
+  'findFirst',
+  'findMany',
+  'findUnique',
+  'findFirstOrThrow',
+  'findUniqueOrThrow',
+  'count',
+  'aggregate',
+  'groupBy',
+];
+
+/**
+ * 删除操作列表
+ */
+const DELETE_ACTIONS = ['delete', 'deleteMany'];
+
+/**
+ * 不支持软删除的模型列表（这些模型没有 isDeleted 字段）
+ *
+ * 分类说明
+ */
+const NON_SOFT_DELETE_MODELS = [
+  // 系统/配置表
+  'SystemTaskQueue',
+] as const;
+
+/**
+ * 检查模型是否支持软删除
+ */
+export function isSoftDeleteModel(modelName: string | undefined): boolean {
+  if (!modelName) return false;
+  // 如果模型在不支持软删除的列表中，返回 false
+  return !NON_SOFT_DELETE_MODELS.includes(modelName as any);
+}
+
+/**
+ * 检查 where 条件是否已显式指定 isDeleted
+ * 支持嵌套的 OR/AND/NOT 条件
+ */
+function hasExplicitIsDeleted(
+  where: Record<string, unknown> | undefined,
+): boolean {
+  if (!where) return false;
+
+  // 直接检查 isDeleted 字段
+  if ('isDeleted' in where) return true;
+
+  // 检查 OR 条件
+  if (Array.isArray(where.OR)) {
+    for (const condition of where.OR) {
+      if (hasExplicitIsDeleted(condition as Record<string, unknown>)) {
+        return true;
+      }
+    }
+  }
+
+  // 检查 AND 条件
+  if (Array.isArray(where.AND)) {
+    for (const condition of where.AND) {
+      if (hasExplicitIsDeleted(condition as Record<string, unknown>)) {
+        return true;
+      }
+    }
+  }
+
+  // 检查 NOT 条件
+  if (where.NOT) {
+    if (Array.isArray(where.NOT)) {
+      for (const condition of where.NOT) {
+        if (hasExplicitIsDeleted(condition as Record<string, unknown>)) {
+          return true;
+        }
+      }
+    } else {
+      if (hasExplicitIsDeleted(where.NOT as Record<string, unknown>)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * 设置软删除中间件
+ * Prisma 7.x: 使用 $extends 创建扩展客户端
+ *
+ * 注意：由于 Prisma 7.x 的 $extends API 限制，delete 操作的转换需要使用模型特定的扩展
+ * 当前实现仅处理查询操作的软删除过滤
+ *
+ * @param prisma - Prisma 客户端实例
+ * @returns 扩展后的 PrismaClient 实例
+ */
+export function setupSoftDeleteMiddleware(prisma: PrismaClient): PrismaClient {
+  // 保存原始 prisma client 的引用，以便在 delete 操作中使用
+  const originalPrisma = prisma;
+
+  return prisma.$extends({
+    query: {
+      $allOperations({ operation, model, args, query }) {
+        // 检查是否为软删除模型
+        if (!isSoftDeleteModel(model)) {
+          return query(args);
+        }
+
+        // 处理查询操作：自动添加 isDeleted: false
+        if (QUERY_ACTIONS.includes(operation)) {
+          const newArgs = { ...args };
+          if (!newArgs.where) {
+            newArgs.where = {};
+          }
+
+          // 只有在未显式指定 isDeleted 时才自动添加
+          if (!hasExplicitIsDeleted(newArgs.where)) {
+            newArgs.where = {
+              ...newArgs.where,
+              isDeleted: false,
+            };
+          }
+
+          return query(newArgs);
+        }
+
+        // 对于 delete 和 deleteMany 操作，我们需要使用不同的方法
+        // 在 Prisma 7.x 中，我们不能在 $extends 中直接将一个操作转换为另一个操作
+        // 这些操作需要在使用时手动处理，或者使用模型特定的扩展
+        // 暂时让这些操作通过，后续可以通过其他方式处理
+        return query(args);
+      },
+    },
+  }) as PrismaClient;
+}
+
+/**
+ * 硬删除工具函数
+ * 当确实需要物理删除时使用
+ *
+ * @example
+ * ```typescript
+ * await hardDelete(prisma.userInfo, { id: 'xxx' });
+ * ```
+ */
+export async function hardDelete<T>(
+  model: {
+    delete: (args: { where: T }) => Promise<unknown>;
+  },
+  where: T,
+): Promise<unknown> {
+  // 直接调用原始 delete，绕过中间件的软删除转换
+  // 注意：由于中间件会拦截 delete，这个函数实际上需要使用 $executeRaw
+  // 这里只是一个概念示例，实际使用时需要使用原始 SQL
+  return model.delete({ where });
+}

package/template/apps/api/libs/infra/prisma/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@pardx/prisma",
+  "version": "0.0.1",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "private": true,
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "lint": "eslint \"src/**/*.ts\" --fix"
+  }
+}

package/template/apps/api/libs/infra/prisma/prisma/index.ts

@@ -0,0 +1,3 @@
+export * from './prisma.module';
+export * from './prisma.service';
+export * from './types';

package/template/apps/api/libs/infra/prisma/prisma/prisma.module.ts

@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common';
+import { PrismaService } from '@/prisma/prisma.service';
+import { PrismaWriteModule } from '@/prisma-write/prisma-write.module';
+import { PrismaReadModule } from '@/prisma-read/prisma-read.module';
+import { RedisModule } from '@app/redis';
+import { ConfigModule } from '@nestjs/config';
+@Module({
+  imports: [PrismaWriteModule, PrismaReadModule, RedisModule, ConfigModule],
+  providers: [PrismaService],
+  exports: [PrismaService],
+})
+export class PrismaModule {}

package/template/apps/api/libs/infra/prisma/prisma/prisma.service.ts

@@ -0,0 +1,18 @@
+import { Injectable } from '@nestjs/common';
+import { PrismaReadService } from '@/prisma-read/prisma-read.service';
+import { PrismaWriteService } from '@/prisma-write/prisma-write.service';
+
+@Injectable()
+export class PrismaService {
+  constructor(
+    private readonly prismaRead: PrismaReadService,
+    private readonly prismaWrite: PrismaWriteService,
+  ) {}
+  get read() {
+    return this.prismaRead.client;
+  }
+
+  get write() {
+    return this.prismaWrite.client;
+  }
+}

package/template/apps/api/libs/infra/prisma/prisma/types.ts

@@ -0,0 +1,6 @@
+import { IsNotEmpty } from 'class-validator';
+
+export class AppDbConfig {
+  @IsNotEmpty()
+  url: string;
+}

package/template/apps/api/libs/infra/prisma/prisma-read/prisma-read.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { DbMetricsModule } from '../db-metrics/src/db-metrics.module';
+import { PrismaReadService } from './prisma-read.service';
+
+@Module({
+  imports: [ConfigModule, DbMetricsModule],
+  providers: [PrismaReadService],
+  exports: [PrismaReadService],
+})
+export class PrismaReadModule {}

package/template/apps/api/libs/infra/prisma/prisma-read/prisma-read.service.ts

@@ -0,0 +1,280 @@
+import {
+  Injectable,
+  OnModuleInit,
+  OnModuleDestroy,
+  Inject,
+  Optional,
+} from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+import { PrismaPg } from '@prisma/adapter-pg';
+import { Pool } from 'pg';
+import bigintUtil from '@/utils/bigint.util';
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+import {
+  DbMetricsService,
+  QueryContext,
+} from '../db-metrics/src/db-metrics.service';
+import { setupSoftDeleteMiddleware } from '../middleware/soft-delete.middleware';
+import enviroment from '@/utils/enviroment.util';
+
+/**
+ * Prisma Read Service
+ * Prisma 读服务
+ *
+ * Provides read-only database access with:
+ * - Query performance monitoring
+ * - Slow query detection with configurable thresholds
+ * - Prometheus metrics integration
+ * - BigInt serialization support
+ *
+ * 提供只读数据库访问，包含：
+ * - 查询性能监控
+ * - 可配置阈值的慢查询检测
+ * - Prometheus 指标集成
+ * - BigInt 序列化支持
+ */
+@Injectable()
+export class PrismaReadService implements OnModuleInit, OnModuleDestroy {
+  private prisma: PrismaClient;
+  private pool: Pool;
+
+  constructor(
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+    @Optional() private readonly dbMetrics?: DbMetricsService,
+  ) {
+    // Prisma 7.x: 使用 @prisma/adapter-pg 驱动适配器
+    // 对于读写分离，优先使用 READ_DATABASE_URL
+    const connectionString =
+      process.env.READ_DATABASE_URL || process.env.DATABASE_URL;
+
+    if (!connectionString) {
+      throw new Error(
+        'DATABASE_URL or READ_DATABASE_URL environment variable is not set',
+      );
+    }
+
+    // 创建 pg 连接池
+    this.pool = new Pool({
+      connectionString,
+      // 连接池配置，与 Prisma 6 保持一致
+      connectionTimeoutMillis: 5000,
+      idleTimeoutMillis: 300000, // 5分钟
+      max: 10, // 最大连接数
+    });
+
+    // 创建 Prisma 适配器 - 直接传入 Pool 实例
+    const adapter = new PrismaPg(this.pool);
+
+    // 使用适配器创建 PrismaClient
+    const basePrisma = new PrismaClient({ adapter });
+
+    // Prisma 7.x: 使用 $extends 替代 $use
+    // 先应用软删除扩展，再应用监控扩展
+    this.prisma = this.setupExtensions(basePrisma);
+  }
+
+  /**
+   * Setup Prisma extensions for query monitoring and soft delete
+   * Prisma 7.x: 使用 $extends 替代 $use
+   * 设置 Prisma 扩展用于查询监控和软删除
+   */
+  private setupExtensions(basePrisma: PrismaClient): PrismaClient {
+    // 保存引用以便在回调中使用
+    const dbMetrics = this.dbMetrics;
+    const fallbackLog = this.fallbackLog.bind(this);
+
+    // 先应用软删除扩展
+    const withSoftDelete = setupSoftDeleteMiddleware(basePrisma);
+
+    // 应用监控扩展
+    return withSoftDelete.$extends({
+      query: {
+        $allOperations({ operation, model, args, query }) {
+          // Start tracking
+          const ctx: QueryContext = dbMetrics?.recordQueryStart() ?? {
+            startTime: Date.now(),
+            traceId: 'unknown',
+          };
+
+          // 执行查询并处理结果
+          const result = query(args);
+
+          // 处理 Promise 结果
+          if (result instanceof Promise) {
+            return result
+              .then((res) => {
+                const serialized = bigintUtil.serialize(res);
+                if (dbMetrics) {
+                  dbMetrics.recordQueryEnd(
+                    ctx,
+                    {
+                      model: model || 'unknown',
+                      action: operation,
+                      dbType: 'read',
+                    },
+                    'success',
+                    args,
+                  );
+                } else {
+                  fallbackLog(
+                    ctx.startTime,
+                    { model, action: operation, args },
+                    'success',
+                  );
+                }
+                return serialized;
+              })
+              .catch((error) => {
+                // Record error
+                if (dbMetrics) {
+                  dbMetrics.recordQueryEnd(
+                    ctx,
+                    {
+                      model: model || 'unknown',
+                      action: operation,
+                      dbType: 'read',
+                    },
+                    'error',
+                    args,
+                    error as Error,
+                  );
+                } else {
+                  fallbackLog(
+                    ctx.startTime,
+                    { model, action: operation, args },
+                    'error',
+                    error as Error,
+                  );
+                }
+                throw error;
+              });
+          }
+
+          // 同步结果处理
+          try {
+            const serialized = bigintUtil.serialize(result);
+            if (dbMetrics) {
+              dbMetrics.recordQueryEnd(
+                ctx,
+                {
+                  model: model || 'unknown',
+                  action: operation,
+                  dbType: 'read',
+                },
+                'success',
+                args,
+              );
+            } else {
+              fallbackLog(
+                ctx.startTime,
+                { model, action: operation, args },
+                'success',
+              );
+            }
+            return serialized;
+          } catch (error) {
+            if (dbMetrics) {
+              dbMetrics.recordQueryEnd(
+                ctx,
+                {
+                  model: model || 'unknown',
+                  action: operation,
+                  dbType: 'read',
+                },
+                'error',
+                args,
+                error as Error,
+              );
+            } else {
+              fallbackLog(
+                ctx.startTime,
+                { model, action: operation, args },
+                'error',
+                error as Error,
+              );
+            }
+            throw error;
+          }
+        },
+      },
+    }) as any;
+  }
+
+  /**
+   * Fallback logging when DbMetricsService is not injected
+   * 当 DbMetricsService 未注入时的回退日志记录
+   */
+  private fallbackLog(
+    startTime: number,
+    params: { model?: string; action: string; args?: unknown },
+    status: 'success' | 'error',
+    error?: Error,
+  ): void {
+    const duration = Date.now() - startTime;
+    const logData = {
+      message: 'ReadDB Query 执行信息',
+      detail: {
+        耗时: `${duration}ms`,
+        时间: new Date().toISOString(),
+        操作: `${params.model}.${params.action}`,
+        参数: JSON.stringify(params.args),
+        状态: status,
+      },
+    };
+
+    if (status === 'error' && error) {
+      this.logger.error({
+        ...logData,
+        error: { name: error.name, message: error.message },
+      });
+    } else if (duration > 1000) {
+      this.logger.warn({
+        message: 'ReadDB Query 性能警告',
+        detail: {
+          操作: `${params.model}.${params.action}`,
+          耗时: `${duration}ms`,
+          提示: '此操作的执行时间超过了1000ms，请考虑优化',
+        },
+      });
+    } else {
+      this.logger.info(logData);
+    }
+  }
+
+  /**
+   * Get the Prisma client instance
+   * 获取 Prisma 客户端实例
+   */
+  get client(): PrismaClient {
+    return this.prisma;
+  }
+
+  async onModuleInit() {
+    await this.prisma.$connect();
+    if (enviroment.isProduction()) {
+      this.logger.info('PrismaReadService connected to database');
+    }
+  }
+
+  async onModuleDestroy() {
+    try {
+      await this.prisma.$disconnect();
+    } catch (error) {
+      this.logger.warn('Error disconnecting Prisma client', { error });
+    }
+
+    // 检查 pool 是否已经关闭，避免重复调用 end()
+    if (this.pool && !this.pool.ended) {
+      try {
+        await this.pool.end();
+      } catch (error) {
+        this.logger.warn('Error closing database pool', { error });
+      }
+    }
+
+    if (enviroment.isProduction()) {
+      this.logger.info('PrismaReadService disconnected from database');
+    }
+  }
+}

package/template/apps/api/libs/infra/prisma/prisma-write/prisma-write.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+import { PrismaWriteService } from './prisma-write.service';
+import { ConfigModule } from '@nestjs/config';
+import { DbMetricsModule } from '../db-metrics/src/db-metrics.module';
+
+@Module({
+  imports: [ConfigModule, DbMetricsModule],
+  providers: [PrismaWriteService],
+  exports: [PrismaWriteService],
+})
+export class PrismaWriteModule {}