create-pardx-scaffold 0.1.0

package/template/apps/api/libs/infra/common/middleware/request.middleware.ts

@@ -0,0 +1,109 @@
+import { Inject, Injectable, NestMiddleware } from '@nestjs/common';
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { IncomingMessage, ServerResponse } from 'http';
+import { v4 as uuidv4 } from 'uuid';
+import { createNamespace } from 'cls-hooked';
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+
+import { getReqMainInfo } from '@/utils/logger.util';
+import * as parser from 'accept-language-parser';
+import ipUtil from '@/utils/ip.util';
+import enviroment from '@/utils/enviroment.util';
+
+// Trace ID 请求头名称
+export const TRACE_ID_HEADER = 'x-trace-id';
+
+// 扩展 FastifyRequest 类型
+declare module 'fastify' {
+  interface FastifyRequest {
+    traceId: string;
+    locale: string;
+    realIp: string;
+  }
+}
+
+export const clsNamespace = createNamespace('app');
+
+/**
+ * 获取或生成 Trace ID
+ * 优先从请求头获取 (支持分布式追踪)，否则生成新的 UUID
+ */
+function getOrCreateTraceId(req: IncomingMessage | FastifyRequest): string {
+  const headerTraceId = req.headers[TRACE_ID_HEADER];
+  if (headerTraceId && typeof headerTraceId === 'string') {
+    return headerTraceId;
+  }
+  return uuidv4();
+}
+
+/**
+ * RequestMiddleware
+ *
+ * 重要说明：在 Fastify 适配器下，NestMiddleware 的 use 方法接收的参数类型
+ * 实际上是原生的 Node.js 对象（IncomingMessage 和 ServerResponse），
+ * 而不是 Fastify 的封装对象（FastifyRequest 和 FastifyReply）。
+ *
+ * 这是因为：
+ * 1. NestJS 中间件接口设计为接收原生对象，以保持与不同 HTTP 框架的兼容性
+ * 2. Fastify 适配器通过 middie 包处理中间件，传递的是原生对象
+ * 3. 虽然类型声明可以使用 FastifyRequest/FastifyReply，但运行时实际是原生对象
+ *
+ * 解决方案：
+ * - 使用泛型参数明确指定类型：NestMiddleware<IncomingMessage, ServerResponse>
+ * - 或者保持 any 类型，在运行时通过类型断言访问 Fastify 特有的属性
+ */
+@Injectable()
+export default class RequestMiddleware implements NestMiddleware<
+  IncomingMessage,
+  ServerResponse
+> {
+  constructor(
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+  ) {}
+
+  async use(req: IncomingMessage, res: ServerResponse, next: () => void) {
+    clsNamespace.bind(req);
+    clsNamespace.bind(res);
+
+    // 获取或生成 Trace ID (支持分布式追踪)
+    const traceId = getOrCreateTraceId(req);
+
+    // 添加到请求对象 (便于 Controller/Service 访问)
+    // 注意：在中间件中，req 是原生 IncomingMessage
+    // 但在 Controller 中，可以通过 context.switchToHttp().getRequest<FastifyRequest>() 获取 FastifyRequest
+    (req as any).traceId = traceId;
+
+    // 添加到响应头 (使用原生 Node.js API)
+    res.setHeader(TRACE_ID_HEADER, traceId);
+
+    // 解析语言
+    const acceptLanguage = req.headers['accept-language'] || '';
+    const languages = parser.parse(acceptLanguage);
+    let primaryLanguage = languages[0]?.code || 'en';
+    if (!['zh-CN', 'en'].includes(primaryLanguage)) {
+      primaryLanguage = 'en';
+    }
+    (req as any).locale = primaryLanguage;
+
+    // 提取 IP 地址
+    // 注意：ipUtil.extractIp 期望 FastifyRequest，但中间件中接收的是 IncomingMessage
+    // 这里使用类型断言，因为 IncomingMessage 和 FastifyRequest 在 headers 属性上兼容
+    const realIp = ipUtil.extractIp(req as any);
+    (req as any).realIp = realIp;
+
+    clsNamespace.run(() => {
+      clsNamespace.set('traceID', traceId);
+      next();
+      // 记录日志 (包含 traceId)
+      // 注意：getReqMainInfo 期望 FastifyRequest/FastifyReply，但中间件中是原生对象
+      // 使用类型断言以兼容现有函数
+      if (enviroment.isProduction()) {
+        this.logger.info('RequestMiddleware', {
+          traceId,
+          ...getReqMainInfo(req as any, res as any),
+        });
+      }
+    });
+  }
+}

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

@@ -0,0 +1,11 @@
+{
+  "name": "@pardx/common",
+  "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/common/pipes/transform-root.pipe.ts

@@ -0,0 +1,12 @@
+import { PipeTransform, Injectable, ArgumentMetadata } from '@nestjs/common';
+
+@Injectable()
+export class TransformRootPipe implements PipeTransform {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  transform(value: any, _metadata: ArgumentMetadata) {
+    if (value?.folderId && value.folderId === 'root') {
+      value.folderId = undefined;
+    }
+    return value;
+  }
+}

package/template/apps/api/libs/infra/common/ts-rest/index.ts

@@ -0,0 +1,26 @@
+/**
+ * ts-rest Utilities Export
+ * ts-rest 工具导出
+ *
+ * 提供标准化的响应辅助函数：
+ * - success(data) - 成功响应
+ * - created(data) - 创建成功响应 (201)
+ * - deleted() - 删除成功响应
+ * - paginated(list, total, page, limit) - 分页响应
+ * - error(errorCode) - 错误码响应
+ * - errorFromType(type, code, status) - 错误类型响应
+ * - errorSimple(code, msg) - 简单错误响应
+ */
+
+export {
+  success,
+  created,
+  deleted,
+  deletedWithData,
+  paginated,
+  error,
+  errorFromType,
+  errorSimple,
+  serializeDates,
+  type TsRestResponse,
+} from './response.helper';

package/template/apps/api/libs/infra/common/ts-rest/response.helper.ts

@@ -0,0 +1,233 @@
+/**
+ * ts-rest Response Helpers
+ * ts-rest 响应辅助工具
+ *
+ * 提供标准化的响应格式：
+ * - 成功响应：{ code: 200, msg: 'ok', data: ... }
+ * - 错误响应：{ code: xxx, msg: 'xxxx', error?: ... }
+ *
+ * 配合 createApiResponse 定义的 Contract 使用
+ */
+
+import {
+  ApiErrorCode,
+  getErrorType,
+  getHttpStatus,
+  getErrorMessage,
+} from '@repo/contracts/errors';
+
+/**
+ * 标准成功响应格式
+ */
+interface SuccessBody<T> {
+  code: number;
+  msg: string;
+  data: T;
+}
+
+/**
+ * 标准错误响应格式
+ */
+interface ErrorBody {
+  code: number;
+  msg: string;
+  error?: unknown;
+}
+
+/**
+ * ts-rest 处理器响应类型
+ */
+export type TsRestResponse<T, S extends number = 200> = {
+  status: S;
+  body: SuccessBody<T> | ErrorBody;
+};
+
+/**
+ * 创建成功响应
+ *
+ * @example
+ * ```typescript
+ * @TsRestHandler(c.getItem)
+ * async getItem() {
+ *   return tsRestHandler(c.getItem, async ({ params }) => {
+ *     const data = await this.service.findById(params.id);
+ *     return success(data);
+ *   });
+ * }
+ * ```
+ */
+export function success<T>(data: T, status: 200 = 200): TsRestResponse<T, 200> {
+  return {
+    status,
+    body: {
+      code: 200,
+      msg: 'ok',
+      data: serializeDates(data),
+    },
+  };
+}
+
+/**
+ * 创建分页成功响应
+ *
+ * @example
+ * ```typescript
+ * return paginated(items, total, query.page, query.limit);
+ * ```
+ */
+export function paginated<T>(
+  list: T[],
+  total: number,
+  page: number,
+  limit: number,
+): TsRestResponse<
+  { list: T[]; total: number; page: number; limit: number },
+  200
+> {
+  return success({ list, total, page, limit });
+}
+
+/**
+ * 创建 201 响应（创建成功）
+ */
+export function created<T>(data: T): TsRestResponse<T, 201> {
+  return {
+    status: 201,
+    body: {
+      code: 200,
+      msg: 'ok',
+      data: serializeDates(data),
+    },
+  };
+}
+
+/**
+ * 创建删除成功响应
+ */
+export function deleted(): TsRestResponse<{ success: boolean }, 200> {
+  return {
+    status: 200,
+    body: {
+      code: 200,
+      msg: 'ok',
+      data: { success: true },
+    },
+  };
+}
+
+export function deletedWithData<T>(data: T): TsRestResponse<T, 200> {
+  return {
+    status: 200,
+    body: {
+      code: 200,
+      msg: 'ok',
+      data: serializeDates(data),
+    },
+  };
+}
+
+/**
+ * 从错误码创建错误响应
+ *
+ * @example
+ * ```typescript
+ * if (!item) {
+ *   return error(CommonErrorCode.NotFound);
+ * }
+ * ```
+ */
+export function error(
+  errorCode: ApiErrorCode,
+  errorData?: unknown,
+): TsRestResponse<never> {
+  const errorType = getErrorType(errorCode) || 'unknown';
+  const httpStatus = getHttpStatus(errorCode);
+  const numericCode = Number(errorCode);
+  const msg = getErrorMessage(errorType);
+
+  return {
+    status: httpStatus as 200,
+    body: {
+      code: numericCode,
+      msg,
+      error: errorData,
+    },
+  };
+}
+
+/**
+ * 从错误类型字符串创建错误响应
+ *
+ * @example
+ * ```typescript
+ * return errorFromType('userNotFound', 200401, 404);
+ * ```
+ */
+export function errorFromType(
+  errorType: string,
+  errorCode: number,
+  httpStatus: number = 400,
+  errorData?: unknown,
+): TsRestResponse<never> {
+  const msg = getErrorMessage(errorType);
+
+  return {
+    status: httpStatus as 200,
+    body: {
+      code: errorCode,
+      msg,
+      error: errorData,
+    },
+  };
+}
+
+/**
+ * 创建简单错误响应（不带 error 详情）
+ */
+export function errorSimple(
+  code: number,
+  msg: string,
+  httpStatus: number = 400,
+): TsRestResponse<never> {
+  return {
+    status: httpStatus as 200,
+    body: {
+      code,
+      msg,
+    },
+  };
+}
+
+/**
+ * 递归地将对象中的 Date 类型转换为 ISO 字符串
+ * 用于确保 ts-rest 响应符合 zod schema（Date 字段定义为 z.coerce.date()）
+ *
+ * @example
+ * ```typescript
+ * const data = await this.service.findById(id);
+ * return success(serializeDates(data));
+ * ```
+ */
+export function serializeDates<T>(obj: T): any {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+
+  if (obj instanceof Date) {
+    return obj.toISOString() as unknown as T;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => serializeDates(item)) as unknown as T;
+  }
+
+  if (typeof obj === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = serializeDates(value);
+    }
+    return result as T;
+  }
+
+  return obj;
+}

package/template/apps/api/libs/infra/i18n/en/errors.json

@@ -0,0 +1,77 @@
+{
+  "user": {
+    "oauthAccountAlreadyExist": "OAuth Account Already Exists",
+    "userNotFound": "User Not Found",
+    "userAlreadyExists": "User Already Exists",
+    "invalidPassword": "Invalid Password",
+    "invalidVerifyCode": "Invalid Verification Code",
+    "writeAccessTokenFail": "Failed to write access token",
+    "ssoHostNameError": "Invalid SSO hostname error",
+    "oauthTokenInvalid": "OAuth Token Invalid",
+    "nicknameIsTooLong": "Nickname is too long",
+    "nicknameIsTooShort": "Nickname is too short",
+    "emailIsInvalid": "Email is invalid"
+  },
+  "common": {
+    "idMustUUID": "ID must be a valid UUID format",
+    "innerError": "Internal Parameter Error",
+    "internalServerError": "Internal Server Error",
+    "badRequest": "Bad Request",
+    "unknown": "Unknown Error",
+    "getStorageNull": "User Storage Content Not Found",
+    "dbCreateError": "Database Creation Failed",
+    "dbUpdateError": "Database Update Failed",
+    "dbDeleteError": "Database Delete Failed",
+    "dbQueryError": "Database Query Failed",
+    "templateNotFound": "Template Not Found",
+    "invalidParameters": "Invalid Parameters",
+    "signatureError": "Signature Error",
+    "tooManyFolders": "Too Many Folders",
+    "tooManyFiles": "Too Many Files",
+    "notFound": "Resource Not Found",
+    "planIsNotExist": "Plan does not exist",
+    "planIsDeleted": "Plan has been deleted",
+    "recommendPlanNotFound": "Coming Soon",
+    "createOrderFail": "Failed to create order",
+    "orderIsNotExist": "Order does not exist",
+    "systemUnHealthy": "System unhealthy",
+    "parameterError": "Parameter Error",
+    "getProviderUserInfoError": "Failed to Retrieve User Information",
+    "rabbitmqQueueIsNotExist": "MQ Queue Not Found",
+    "storageResponseFailed": "Failed to Access Storage",
+    "batchDeleteFolderFail": "Failed to Batch Delete Folders",
+    "initiateMultipartUploadError": "Initiate Multipart Upload Error",
+    "qrcodeGenerateError": "QR Code Generation Error",
+    "fileServiceUnsupportedVendor": "Unsupported File Service Vendor",
+    "qiniuZipDownloadError": "Qiniu Zip Download Error",
+    "qiniuQueryFopStatusError": "Qiniu Query FOP Status Error",
+    "qiniuUploaderError": "Qiniu Uploader Error",
+    "s3NoSuchKey": "No Such Key in bucket",
+    "s3NoSuchBucket": "No Such Bucket",
+    "unAuthorized": "Unauthorized",
+    "unauthorizedByKey": "Unauthorized by Key",
+    "tooFrequent": "Too Many Requests, Please Try Again Later",
+    "invalidToken": "Invalid Token",
+    "invalidEnv": "Invalid Env Config",
+    "invalidRedis": "Invalid Redis",
+    "textCensorValidFailed": "Text censor validation failed",
+    "featureAlreadyExists": "Feature name already exists",
+    "featureNotFound": "Feature not found",
+    "featureHasPermissions": "Feature has associated permissions, cannot delete",
+    "someFeaturesHavePermissions": "Some features have associated permissions, cannot delete",
+    "wechatAccessTokenError": "Wechat access token error, please check your credentials or re-obtain the access token",
+    "wechatMiniProgramQRCodeError": "Failed to get mini program QR code",
+    "llmJinaAiEmbeddingError": "Jina AI embedding API call failed, please try again later",
+    "llmJinaAiRerankError": "Jina AI rerank API call failed, please try again later",
+    "llmJinaAiReadError": "Jina AI read API call failed, please try again later",
+    "llmJinaAiSearchError": "Jina AI search API call failed, please try again later",
+    "llmJinaAiClassifyError": "Jina AI classify API call failed, please try again later",
+    "llmJinaAiSegmentError": "Jina AI segment API call failed, please try again later",
+    "llmJinaAiGRelatedError": "Jina AI related content API call failed, please try again later",
+    "llmJinaAiDeepsearchError": "Jina AI deep search API call failed, please try again later",
+    "s3ClientInitializationError": "S3 Client Initialization Failed",
+    "invalidVideoUri": "Invalid video URI format, must be in s3:// format",
+    "invalidTaskId": "Task ID cannot be empty",
+    "missingVendor": "Either vendor or videoUri must be provided"
+  }
+}

package/template/apps/api/libs/infra/i18n/en/events.json

@@ -0,0 +1 @@
+{}

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

@@ -0,0 +1,11 @@
+{
+  "name": "@pardx/i18n",
+  "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/i18n/zh-CN/errors.json

@@ -0,0 +1,77 @@
+{
+  "user": {
+    "oauthAccountAlreadyExist": "OAuth账户已存在",
+    "userNotFound": "用户不存在",
+    "userAlreadyExists": "用户已存在",
+    "invalidPassword": "密码无效",
+    "invalidVerifyCode": "无效的验证码",
+    "writeAccessTokenFail": "写入访问令牌失败",
+    "ssoHostNameError": "SSO主机名错误",
+    "oauthTokenInvalid": "OAuth Token无效",
+    "nicknameIsTooLong": "昵称过长",
+    "nicknameIsTooShort": "昵称过短",
+    "emailIsInvalid": "邮箱无效"
+  },
+  "common": {
+    "idMustUUID": "ID必须是有效的UUID格式",
+    "innerError": "内部参数错误",
+    "internalServerError": "服务器内部错误，请稍后重试",
+    "badRequest": "错误的请求",
+    "unknown": "未知错误",
+    "getStorageNull": "用户存储内容未找到",
+    "dbCreateError": "数据库创建失败",
+    "dbUpdateError": "数据库更新失败",
+    "dbDeleteError": "数据库删除失败",
+    "dbQueryError": "数据库查询失败",
+    "templateNotFound": "模板未找到",
+    "invalidParameters": "无效的参数",
+    "signatureError": "签名错误",
+    "tooManyFolders": "文件夹过多",
+    "tooManyFiles": "文件过多",
+    "notFound": "资源未找到",
+    "planIsNotExist": "套餐不存在",
+    "planIsDeleted": "套餐已经删除",
+    "recommendPlanNotFound": "敬请期待",
+    "createOrderFail": "创建订单失败",
+    "orderIsNotExist": "订单不存在",
+    "systemUnHealthy": "系统不健康",
+    "parameterError": "参数错误",
+    "getProviderUserInfoError": "获取用户信息失败",
+    "rabbitmqQueueIsNotExist": "MQ队列不存在",
+    "storageResponseFailed": "访问存储失败",
+    "batchDeleteFolderFail": "批量删除文件夹失败",
+    "initiateMultipartUploadError": "初始化分段上传错误",
+    "qrcodeGenerateError": "二维码生成错误",
+    "fileServiceUnsupportedVendor": "不支持的文件服务供应商",
+    "qiniuZipDownloadError": "七牛Zip下载错误",
+    "qiniuQueryFopStatusError": "七牛查询FOP状态错误",
+    "qiniuUploaderError": "七牛上传器错误",
+    "s3NoSuchKey": "存储桶中没有该文件",
+    "s3NoSuchBucket": "存储桶不存在",
+    "unAuthorized": "未授权",
+    "unauthorizedByKey": "未通过Key授权",
+    "tooFrequent": "请求过于频繁，请稍后再试",
+    "invalidToken": "无效的Token",
+    "invalidEnv": "错误的环境配置",
+    "invalidRedis": "无效的Redis",
+    "textCensorValidFailed": "文本审查验证失败",
+    "featureAlreadyExists": "功能名称已存在",
+    "featureNotFound": "功能未找到",
+    "featureHasPermissions": "功能存在关联权限，无法删除",
+    "someFeaturesHavePermissions": "部分功能存在关联权限，无法删除",
+    "wechatAccessTokenError": "微信访问令牌错误，请检查您的凭证或重新获取访问令牌",
+    "wechatMiniProgramQRCodeError": "获取小程序二维码失败",
+    "llmJinaAiEmbeddingError": "Jina AI 嵌入 API 调用失败，请稍后重试",
+    "llmJinaAiRerankError": "Jina AI 重新排序 API 调用失败，请稍后重试",
+    "llmJinaAiReadError": "Jina AI 读取 API 调用失败，请稍后重试",
+    "llmJinaAiSearchError": "Jina AI 搜索 API 调用失败，请稍后重试",
+    "llmJinaAiClassifyError": "Jina AI 分类 API 调用失败，请稍后重试",
+    "llmJinaAiSegmentError": "Jina AI 分段 API 调用失败，请稍后重试",
+    "llmJinaAiGRelatedError": "Jina AI 相关内容 API 调用失败，请稍后重试",
+    "llmJinaAiDeepsearchError": "Jina AI 深度搜索 API 调用失败，请稍后重试",
+    "s3ClientInitializationError": "S3 客户端初始化失败",
+    "invalidVideoUri": "无效的视频 URI 格式，必须是 s3:// 格式",
+    "invalidTaskId": "任务 ID 不能为空",
+    "missingVendor": "必须提供供应商信息（vendor）或视频 URI（videoUri）"
+  }
+}

package/template/apps/api/libs/infra/i18n/zh-CN/events.json

@@ -0,0 +1 @@
+{}

package/template/apps/api/libs/infra/jwt/dto/jwt.dto.ts

@@ -0,0 +1 @@
+import { IsNumber, IsNotEmpty } from 'class-validator';

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

@@ -0,0 +1,26 @@
+// new-jwt.module.ts
+import { JwtConfig } from '@/config/validation';
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { JwtModule as NestJwtModule, JwtService } from '@nestjs/jwt';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot(),
+    NestJwtModule.registerAsync({
+      imports: [ConfigModule],
+      useFactory: async (configService: ConfigService) => {
+        const config = configService.getOrThrow('jwt') as JwtConfig;
+        return {
+          secret: config.secret,
+          signOptions: {
+            expiresIn: config.expireIn,
+          },
+        };
+      },
+      inject: [ConfigService],
+    }),
+  ],
+  exports: [NestJwtModule], // 如果你打算在其他模块中使用这个 JWT 模块，记得导出它
+})
+export class JwtModule {}

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

@@ -0,0 +1,11 @@
+{
+  "name": "@pardx/jwt",
+  "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/db-metrics/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@pardx/db-metrics",
+  "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"
+  }
+}