create-pardx-scaffold 0.1.0

package/template/apps/api/libs/infra/utils/logger.util.ts

@@ -0,0 +1,121 @@
+import * as winston from 'winston';
+import DailyRotateFile from 'winston-daily-rotate-file';
+import * as _ from 'lodash';
+import * as path from 'path';
+import { FastifyReply, FastifyRequest } from 'fastify';
+
+/**
+ * 获取项目根目录路径
+ * 处理 Windows 环境下 $(pwd) 未展开的问题
+ */
+function getProjectRoot(): string {
+  let projectRoot = process.env.PROJECT_ROOT;
+
+  // 如果 PROJECT_ROOT 包含 $(pwd)，则替换为实际的工作目录
+  if (projectRoot && projectRoot.includes('$(pwd)')) {
+    projectRoot = projectRoot.replace('$(pwd)', process.cwd());
+  }
+
+  // 如果 PROJECT_ROOT 未设置或为空，使用当前工作目录
+  if (!projectRoot) {
+    projectRoot = process.cwd();
+  }
+
+  return projectRoot;
+}
+
+/** 日志输出模式类型 */
+export type LogOutputMode = 'console' | 'file' | 'both';
+
+/**
+ * 生成 winston 配置
+ * @param output 日志输出模式 (从 YAML config.app.nestLogOutput 获取)
+ */
+export function getWinstonConfig(output: LogOutputMode = 'file'): {
+  format: winston.Logform.Format;
+  transports: winston.transport[];
+} {
+  const projectRoot = getProjectRoot();
+  const logsDir = path.join(projectRoot, 'logs');
+  const transports: winston.transport[] = [];
+
+  // 文件输出 (file 或 both 模式)
+  if (output === 'file' || output === 'both') {
+    transports.push(
+      new DailyRotateFile({
+        dirname: logsDir,
+        filename: `${process.env.MICRO_SERVER_NAME}-%DATE%-info.log`,
+        level: 'info',
+        zippedArchive: true,
+        datePattern: 'YYYY-MM-DD',
+        maxSize: '20m',
+        maxFiles: '14d',
+      }),
+      new DailyRotateFile({
+        dirname: logsDir,
+        filename: `${process.env.MICRO_SERVER_NAME}-%DATE%-error.log`,
+        level: 'error',
+        zippedArchive: true,
+        datePattern: 'YYYY-MM-DD',
+        maxSize: '20m',
+        maxFiles: '14d',
+      }),
+      new DailyRotateFile({
+        dirname: logsDir,
+        filename: `${process.env.MICRO_SERVER_NAME}-%DATE%-warn.log`,
+        level: 'warn',
+        zippedArchive: true,
+        datePattern: 'YYYY-MM-DD',
+        maxSize: '20m',
+        maxFiles: '14d',
+      }),
+    );
+  }
+
+  // 控制台输出 (console 或 both 模式)
+  if (output === 'console' || output === 'both') {
+    transports.push(new winston.transports.Console());
+  }
+
+  // 格式化配置
+  const formats = [winston.format.timestamp(), winston.format.json()];
+
+  // if (output !== 'file') {
+  formats.push(winston.format.prettyPrint()); // 日志格式化
+  // }
+
+  return {
+    format: winston.format.combine(...formats),
+    transports: transports,
+  };
+}
+
+export function getReqMainInfo(
+  req: FastifyRequest,
+  res: FastifyReply,
+): Record<string, unknown> {
+  return {
+    ..._.pick(req, [
+      'ip',
+      'hostname',
+      'method',
+      'url',
+      'body',
+      'user',
+      'httpVersion',
+      'headers',
+    ]),
+    ..._.pick(res, ['statusCode']),
+  };
+}
+
+// 访问日志
+// export const accessLogger = winston.createLogger(getWinstonConfig('ACCESS'))
+// // 调用其他系统的请求日志
+// export const requestLogger = winston.createLogger(getWinstonConfig('REQUEST'))
+// // DB 日志
+// export const dbLogger = winston.createLogger(getWinstonConfig('DB'))
+// // 通用日志
+// export const logger = winston.createLogger(getWinstonConfig('DEFAULT'))
+// // 系统错误日志
+// export const errorLogger = winston.createLogger(getWinstonConfig('ERROR'))

package/template/apps/api/libs/infra/utils/object.util.ts

@@ -0,0 +1,3 @@
+// Re-export from shared package
+export { default } from '@repo/utils/object';
+export * from '@repo/utils/object';

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

@@ -0,0 +1,11 @@
+{
+  "name": "@pardx/utils",
+  "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/utils/prisma-error.util.ts

@@ -0,0 +1,397 @@
+/**
+ * Prisma Error Handler Utility
+ * 统一处理 Prisma 数据库操作错误
+ *
+ * 使用四种错误码区分操作类型：
+ * - DbCreateError: 创建操作失败
+ * - DbUpdateError: 更新操作失败
+ * - DbDeleteError: 删除操作失败
+ * - DbQueryError: 查询操作失败
+ *
+ * 具体错误详情通过 ApiException 的 data 字段返回
+ */
+
+import { Prisma } from '@prisma/client';
+import { ApiErrorCode, CommonErrorCode } from '@repo/contracts/errors';
+import { ApiException, apiError } from '@/filter/exception/api.exception';
+
+/**
+ * 数据库操作类型
+ */
+export enum DbOperationType {
+  CREATE = 'create',
+  UPDATE = 'update',
+  DELETE = 'delete',
+  QUERY = 'query',
+}
+
+/**
+ * Prisma 错误类型枚举
+ */
+export enum PrismaErrorType {
+  // 已知请求错误
+  UNIQUE_CONSTRAINT = 'UNIQUE_CONSTRAINT', // P2002 - 唯一约束冲突
+  FOREIGN_KEY_CONSTRAINT = 'FOREIGN_KEY_CONSTRAINT', // P2003 - 外键约束失败
+  CONSTRAINT_FAILED = 'CONSTRAINT_FAILED', // P2004 - 约束失败
+  RECORD_NOT_FOUND = 'RECORD_NOT_FOUND', // P2025 - 记录不存在
+  REQUIRED_RELATION_VIOLATION = 'REQUIRED_RELATION_VIOLATION', // P2014 - 必需关系违规
+  RELATED_RECORD_NOT_FOUND = 'RELATED_RECORD_NOT_FOUND', // P2015 - 关联记录不存在
+  QUERY_INTERPRETATION_ERROR = 'QUERY_INTERPRETATION_ERROR', // P2016 - 查询解释错误
+  RECORDS_NOT_CONNECTED = 'RECORDS_NOT_CONNECTED', // P2017 - 记录未连接
+  REQUIRED_CONNECTED_RECORDS_NOT_FOUND = 'REQUIRED_CONNECTED_RECORDS_NOT_FOUND', // P2018 - 必需连接记录不存在
+  INPUT_ERROR = 'INPUT_ERROR', // P2019 - 输入错误
+  VALUE_TOO_LONG = 'VALUE_TOO_LONG', // P2000 - 值过长
+  NULL_CONSTRAINT = 'NULL_CONSTRAINT', // P2011 - 非空约束违规
+  MISSING_REQUIRED_VALUE = 'MISSING_REQUIRED_VALUE', // P2012 - 缺少必需值
+  TRANSACTION_CONFLICT = 'TRANSACTION_CONFLICT', // P2034 - 事务写冲突/死锁
+  TRANSACTION_API_ERROR = 'TRANSACTION_API_ERROR', // P2028 - 事务 API 错误
+
+  // 初始化错误
+  CONNECTION_ERROR = 'CONNECTION_ERROR', // 数据库连接错误
+
+  // 验证错误
+  VALIDATION_ERROR = 'VALIDATION_ERROR', // 查询验证错误
+
+  // 未知错误
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
+}
+
+/**
+ * Prisma 错误详情接口
+ */
+export interface PrismaErrorDetail {
+  /** 错误类型 */
+  type: PrismaErrorType;
+  /** 原始 Prisma 错误码 */
+  prismaCode?: string;
+  /** 错误描述 */
+  description: string;
+  /** 相关字段（如唯一约束冲突时的字段名） */
+  fields?: string[];
+  /** 相关模型名 */
+  model?: string;
+  /** 目标对象（用于约束错误） */
+  target?: string | string[];
+  /** 原始错误消息 */
+  originalMessage?: string;
+}
+
+/**
+ * 操作类型到错误码的映射
+ */
+const OPERATION_ERROR_CODE_MAP: Record<DbOperationType, CommonErrorCode> = {
+  [DbOperationType.CREATE]: CommonErrorCode.DbCreateError,
+  [DbOperationType.UPDATE]: CommonErrorCode.DbUpdateError,
+  [DbOperationType.DELETE]: CommonErrorCode.DbDeleteError,
+  [DbOperationType.QUERY]: CommonErrorCode.DbQueryError,
+};
+
+/**
+ * Prisma 错误码到错误类型的映射
+ */
+const PRISMA_ERROR_CODE_MAP: Record<string, PrismaErrorType> = {
+  P2000: PrismaErrorType.VALUE_TOO_LONG,
+  P2002: PrismaErrorType.UNIQUE_CONSTRAINT,
+  P2003: PrismaErrorType.FOREIGN_KEY_CONSTRAINT,
+  P2004: PrismaErrorType.CONSTRAINT_FAILED,
+  P2011: PrismaErrorType.NULL_CONSTRAINT,
+  P2012: PrismaErrorType.MISSING_REQUIRED_VALUE,
+  P2014: PrismaErrorType.REQUIRED_RELATION_VIOLATION,
+  P2015: PrismaErrorType.RELATED_RECORD_NOT_FOUND,
+  P2016: PrismaErrorType.QUERY_INTERPRETATION_ERROR,
+  P2017: PrismaErrorType.RECORDS_NOT_CONNECTED,
+  P2018: PrismaErrorType.REQUIRED_CONNECTED_RECORDS_NOT_FOUND,
+  P2019: PrismaErrorType.INPUT_ERROR,
+  P2025: PrismaErrorType.RECORD_NOT_FOUND,
+  P2028: PrismaErrorType.TRANSACTION_API_ERROR,
+  P2034: PrismaErrorType.TRANSACTION_CONFLICT,
+};
+
+/**
+ * 错误类型描述映射
+ */
+const ERROR_TYPE_DESCRIPTION_MAP: Record<PrismaErrorType, string> = {
+  [PrismaErrorType.UNIQUE_CONSTRAINT]: '数据已存在，违反唯一约束',
+  [PrismaErrorType.FOREIGN_KEY_CONSTRAINT]: '外键约束失败，关联数据不存在',
+  [PrismaErrorType.CONSTRAINT_FAILED]: '数据库约束检查失败',
+  [PrismaErrorType.RECORD_NOT_FOUND]: '记录不存在',
+  [PrismaErrorType.REQUIRED_RELATION_VIOLATION]: '必需的关联关系违规',
+  [PrismaErrorType.RELATED_RECORD_NOT_FOUND]: '关联记录不存在',
+  [PrismaErrorType.QUERY_INTERPRETATION_ERROR]: '查询解释错误',
+  [PrismaErrorType.RECORDS_NOT_CONNECTED]: '记录未建立连接',
+  [PrismaErrorType.REQUIRED_CONNECTED_RECORDS_NOT_FOUND]:
+    '必需的连接记录不存在',
+  [PrismaErrorType.INPUT_ERROR]: '输入数据错误',
+  [PrismaErrorType.VALUE_TOO_LONG]: '字段值超出长度限制',
+  [PrismaErrorType.NULL_CONSTRAINT]: '字段不能为空',
+  [PrismaErrorType.MISSING_REQUIRED_VALUE]: '缺少必需的字段值',
+  [PrismaErrorType.TRANSACTION_CONFLICT]: '事务冲突或死锁，请重试',
+  [PrismaErrorType.TRANSACTION_API_ERROR]: '事务执行错误',
+  [PrismaErrorType.CONNECTION_ERROR]: '数据库连接错误',
+  [PrismaErrorType.VALIDATION_ERROR]: '查询参数验证错误',
+  [PrismaErrorType.UNKNOWN_ERROR]: '未知数据库错误',
+};
+
+/**
+ * Prisma 错误处理器
+ *
+ * @example
+ * ```typescript
+ * // 在 Service 中使用
+ * async createUser(data: CreateUserInput) {
+ *   try {
+ *     return await this.prisma.write.user.create({ data });
+ *   } catch (error) {
+ *     PrismaErrorHandler.handle(error, DbOperationType.CREATE);
+ *   }
+ * }
+ *
+ * // 使用便捷方法
+ * async updateUser(id: string, data: UpdateUserInput) {
+ *   try {
+ *     return await this.prisma.write.user.update({ where: { id }, data });
+ *   } catch (error) {
+ *     PrismaErrorHandler.handleUpdate(error);
+ *   }
+ * }
+ * ```
+ */
+export class PrismaErrorHandler {
+  /**
+   * 处理 Prisma 错误并抛出 ApiException
+   * @param error 原始错误
+   * @param operationType 操作类型
+   * @throws ApiException
+   */
+  static handle(error: unknown, operationType: DbOperationType): never {
+    const errorDetail = this.parseError(error);
+    const errorCode = OPERATION_ERROR_CODE_MAP[operationType];
+
+    throw apiError(errorCode as ApiErrorCode, errorDetail);
+  }
+
+  /**
+   * 处理创建操作错误
+   */
+  static handleCreate(error: unknown): never {
+    return this.handle(error, DbOperationType.CREATE);
+  }
+
+  /**
+   * 处理更新操作错误
+   */
+  static handleUpdate(error: unknown): never {
+    return this.handle(error, DbOperationType.UPDATE);
+  }
+
+  /**
+   * 处理删除操作错误
+   */
+  static handleDelete(error: unknown): never {
+    return this.handle(error, DbOperationType.DELETE);
+  }
+
+  /**
+   * 处理查询操作错误
+   */
+  static handleQuery(error: unknown): never {
+    return this.handle(error, DbOperationType.QUERY);
+  }
+
+  /**
+   * 解析 Prisma 错误，提取详细信息
+   */
+  static parseError(error: unknown): PrismaErrorDetail {
+    // 处理 Prisma 已知请求错误
+    if (error instanceof Prisma.PrismaClientKnownRequestError) {
+      return this.parseKnownRequestError(error);
+    }
+
+    // 处理 Prisma 验证错误
+    if (error instanceof Prisma.PrismaClientValidationError) {
+      return {
+        type: PrismaErrorType.VALIDATION_ERROR,
+        description:
+          ERROR_TYPE_DESCRIPTION_MAP[PrismaErrorType.VALIDATION_ERROR],
+        originalMessage: error.message,
+      };
+    }
+
+    // 处理 Prisma 初始化/连接错误
+    if (error instanceof Prisma.PrismaClientInitializationError) {
+      return {
+        type: PrismaErrorType.CONNECTION_ERROR,
+        description:
+          ERROR_TYPE_DESCRIPTION_MAP[PrismaErrorType.CONNECTION_ERROR],
+        originalMessage: error.message,
+      };
+    }
+
+    // 处理未知错误
+    const originalMessage =
+      error instanceof Error ? error.message : String(error);
+    return {
+      type: PrismaErrorType.UNKNOWN_ERROR,
+      description: ERROR_TYPE_DESCRIPTION_MAP[PrismaErrorType.UNKNOWN_ERROR],
+      originalMessage,
+    };
+  }
+
+  /**
+   * 解析 Prisma 已知请求错误
+   */
+  private static parseKnownRequestError(
+    error: Prisma.PrismaClientKnownRequestError,
+  ): PrismaErrorDetail {
+    const errorType =
+      PRISMA_ERROR_CODE_MAP[error.code] || PrismaErrorType.UNKNOWN_ERROR;
+    const meta = error.meta as Record<string, unknown> | undefined;
+
+    const detail: PrismaErrorDetail = {
+      type: errorType,
+      prismaCode: error.code,
+      description: ERROR_TYPE_DESCRIPTION_MAP[errorType],
+      originalMessage: error.message,
+    };
+
+    // 提取 meta 信息
+    if (meta) {
+      // 模型名称
+      if (typeof meta.modelName === 'string') {
+        detail.model = meta.modelName;
+      }
+
+      // 目标字段（用于唯一约束等）
+      if (meta.target) {
+        detail.target = meta.target as string | string[];
+        if (Array.isArray(meta.target)) {
+          detail.fields = meta.target as string[];
+        }
+      }
+
+      // 字段名
+      if (Array.isArray(meta.field_name)) {
+        detail.fields = meta.field_name as string[];
+      } else if (typeof meta.field_name === 'string') {
+        detail.fields = [meta.field_name];
+      }
+
+      // cause 信息（P2025 特有）
+      if (typeof meta.cause === 'string') {
+        detail.description = `${detail.description}: ${meta.cause}`;
+      }
+    }
+
+    return detail;
+  }
+
+  /**
+   * 判断错误是否为 Prisma 错误
+   */
+  static isPrismaError(error: unknown): boolean {
+    return (
+      error instanceof Prisma.PrismaClientKnownRequestError ||
+      error instanceof Prisma.PrismaClientValidationError ||
+      error instanceof Prisma.PrismaClientInitializationError ||
+      error instanceof Prisma.PrismaClientRustPanicError ||
+      error instanceof Prisma.PrismaClientUnknownRequestError
+    );
+  }
+
+  /**
+   * 判断是否为可重试的错误（事务冲突/死锁）
+   */
+  static isRetryableError(error: unknown): boolean {
+    if (error instanceof Prisma.PrismaClientKnownRequestError) {
+      // P2034: 写冲突或死锁
+      // P2028: 事务 API 错误
+      return ['P2034', 'P2028'].includes(error.code);
+    }
+    return false;
+  }
+
+  /**
+   * 判断是否为唯一约束冲突错误
+   */
+  static isUniqueConstraintError(error: unknown): boolean {
+    return (
+      error instanceof Prisma.PrismaClientKnownRequestError &&
+      error.code === 'P2002'
+    );
+  }
+
+  /**
+   * 判断是否为记录不存在错误
+   */
+  static isRecordNotFoundError(error: unknown): boolean {
+    return (
+      error instanceof Prisma.PrismaClientKnownRequestError &&
+      error.code === 'P2025'
+    );
+  }
+
+  /**
+   * 判断是否为外键约束错误
+   */
+  static isForeignKeyError(error: unknown): boolean {
+    return (
+      error instanceof Prisma.PrismaClientKnownRequestError &&
+      error.code === 'P2003'
+    );
+  }
+
+  /**
+   * 获取唯一约束冲突的字段名
+   */
+  static getUniqueConstraintFields(error: unknown): string[] | null {
+    if (!this.isUniqueConstraintError(error)) {
+      return null;
+    }
+
+    const prismaError = error as Prisma.PrismaClientKnownRequestError;
+    const meta = prismaError.meta as Record<string, unknown> | undefined;
+
+    if (meta?.target && Array.isArray(meta.target)) {
+      return meta.target as string[];
+    }
+
+    return null;
+  }
+}
+
+/**
+ * 便捷的错误处理装饰器工厂函数
+ * 用于自动捕获并处理 Prisma 错误
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @HandlePrismaError(DbOperationType.CREATE)
+ *   async createUser(data: CreateUserInput) {
+ *     return await this.prisma.write.user.create({ data });
+ *   }
+ * }
+ * ```
+ */
+export function HandlePrismaError(operationType: DbOperationType) {
+  return function (
+    _target: object,
+    _propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ) {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = async function (...args: unknown[]) {
+      try {
+        return await originalMethod.apply(this, args);
+      } catch (error) {
+        if (PrismaErrorHandler.isPrismaError(error)) {
+          PrismaErrorHandler.handle(error, operationType);
+        }
+        throw error;
+      }
+    };
+
+    return descriptor;
+  };
+}

package/template/apps/api/libs/infra/utils/response.ts

@@ -0,0 +1,23 @@
+import { ApiProperty } from '@nestjs/swagger';
+import bigintUtil from './bigint.util';
+
+export class Response<T> {
+  constructor(code = 200, msg?: string, data?: T) {
+    this.code = code;
+    this.msg = msg || 'ok';
+    this.data = data || undefined;
+  }
+
+  @ApiProperty({ type: 'number', default: 200 })
+  code: number;
+
+  @ApiProperty({ type: 'string', default: 'ok' })
+  msg?: string;
+
+  @ApiProperty()
+  data?: T;
+
+  static ok<T>(data?: T): Response<T> {
+    return new Response(200, 'ok', bigintUtil.serialize(data));
+  }
+}

package/template/apps/api/libs/infra/utils/serialize.util.ts

@@ -0,0 +1,3 @@
+// Re-export from shared package
+export { default } from '@repo/utils/serialize';
+export * from '@repo/utils/serialize';

package/template/apps/api/libs/infra/utils/string.util.ts

@@ -0,0 +1,3 @@
+// Re-export from shared package
+export { default } from '@repo/utils/string';
+export * from '@repo/utils/string';

package/template/apps/api/libs/infra/utils/timer.util.ts

@@ -0,0 +1,3 @@
+// Re-export from shared package
+export { default } from '@repo/utils/timer';
+export * from '@repo/utils/timer';

package/template/apps/api/libs/infra/utils/urlencode.util.ts

@@ -0,0 +1,3 @@
+// Re-export from shared package
+export { default } from '@repo/utils/urlencode';
+export * from '@repo/utils/urlencode';

package/template/apps/api/libs/infra/utils/validate.util.ts

@@ -0,0 +1,3 @@
+// Re-export from shared package
+export { default } from '@repo/utils/validate';
+export * from '@repo/utils/validate';

package/template/apps/api/nest-cli.json

@@ -0,0 +1,25 @@
+{
+    "$schema": "https://json.schemastore.org/nest-cli",
+    "collection": "@nestjs/schematics",
+    "sourceRoot": "src",
+    "entryFile": "apps/api/src/main",
+    "compilerOptions": {
+        "deleteOutDir": true,
+        "assets": [
+            {
+                "include": ".env*",
+                "watchAssets": true
+            },
+            {
+                "include": "config.local.yaml",
+                "watchAssets": true
+            },
+            {
+                "include": "libs/infra/i18n/**/*",
+                "watchAssets": true
+            }
+        ],
+        "builder": "tsc",
+        "tsConfigPath": "tsconfig.build.json"
+    }
+}