create-pardx-scaffold 0.1.0

package/template/apps/api/libs/infra/common/filter/exception/api.exception.ts

@@ -0,0 +1,168 @@
+/**
+ * ApiException - Enhanced exception using @repo/contracts
+ * 增强版 ApiException，使用 @repo/contracts 中的错误定义
+ */
+
+import { HttpException } from '@nestjs/common';
+import {
+  ApiErrorCode,
+  AllErrorTypes,
+  getErrorType,
+  getHttpStatus,
+  getErrorMessage,
+} from '@repo/contracts/errors';
+
+// Domain mapping for i18n namespace
+const ERROR_DOMAIN_MAP: Record<string, string> = {
+  // User errors (2xx)
+  '20': 'user',
+  '21': 'user',
+  // Common errors (9xx)
+  '90': 'common',
+  '91': 'common',
+  '92': 'common',
+  '99': 'common',
+};
+
+function getDomainFromCode(errorCode: string): string {
+  const prefix = errorCode.slice(0, 2);
+  return ERROR_DOMAIN_MAP[prefix] || 'common';
+}
+
+export class ApiException extends HttpException {
+  public readonly errorCode: ApiErrorCode;
+  public readonly errorType: string;
+  public readonly errorData: unknown;
+  public readonly domain: string;
+
+  /**
+   * Create exception from error type string (backward compatible)
+   * 从错误类型字符串创建异常（向后兼容）
+   */
+  constructor(errorType: string, data: unknown = null) {
+    // Find error code from type
+    const entry = Object.entries(AllErrorTypes).find(
+      ([, type]) => type === errorType,
+    );
+
+    if (!entry) {
+      throw new Error(`Unknown error type: ${errorType}`);
+    }
+
+    const errorCode = entry[0] as ApiErrorCode;
+    const httpStatus = getHttpStatus(errorCode);
+    const message = getErrorMessage(errorType);
+
+    super('', httpStatus);
+
+    this.errorCode = errorCode;
+    this.errorType = errorType;
+    this.errorData = data;
+    this.domain = getDomainFromCode(errorCode);
+    this.name = 'ApiException';
+  }
+
+  /**
+   * Create exception from error code (recommended)
+   * 从错误码创建异常（推荐方式）
+   */
+  static fromCode(errorCode: ApiErrorCode, data: unknown = null): ApiException {
+    const errorType = getErrorType(errorCode);
+    if (!errorType) {
+      throw new Error(`Unknown error code: ${errorCode}`);
+    }
+    return new ApiException(errorType, data);
+  }
+
+  /**
+   * Get error code
+   */
+  getErrorCode(): ApiErrorCode {
+    return this.errorCode;
+  }
+
+  /**
+   * Get error message without i18n (fallback)
+   */
+  getErrorMessageWithoutI18n(): string {
+    return getErrorMessage(this.errorType);
+  }
+
+  /**
+   * Get localized error message using i18n
+   * 使用 i18n 获取本地化错误消息
+   *
+   * Uses namespace: errors.{domain}.{errorType}
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  getErrorMessage(i18n: any): string {
+    // Use errors.{domain}.{errorType} namespace
+    const key = `errors.${this.domain}.${this.errorType}`;
+    const message = i18n.t(key, { lang: i18n.lang });
+
+    if (message && message !== key) {
+      return message;
+    }
+
+    // Fallback to error type
+    return this.getErrorMessageWithoutI18n() || this.errorType || '';
+  }
+
+  /**
+   * Get error data
+   */
+  getErrorData(): unknown {
+    return this.errorData;
+  }
+
+  /**
+   * Get error type
+   */
+  getErrorType(): string {
+    return this.errorType;
+  }
+
+  /**
+   * Convert to JSON response format
+   * 转换为 JSON 响应格式
+   *
+   * Note: `code` is numeric for backward compatibility
+   * `error.errorCode` is string for type safety
+   */
+  toJSON(): {
+    code: number;
+    msg: string;
+    data: null;
+    error: {
+      errorCode: string;
+      errorType: string;
+      errorData: unknown;
+    };
+  } {
+    return {
+      code: Number(this.errorCode),
+      msg: this.errorType,
+      data: null,
+      error: {
+        errorCode: this.errorCode,
+        errorType: this.errorType,
+        errorData: this.errorData,
+      },
+    };
+  }
+}
+
+/**
+ * Helper function to throw ApiException from error code
+ * 从错误码抛出 ApiException 的辅助函数
+ *
+ * @example
+ * throw apiError(UserErrorCode.UserNotFound);
+ * throw apiError(UserErrorCode.InvalidPassword, { attempts: 3 });
+ */
+export function apiError(
+  errorCode: ApiErrorCode,
+  data: unknown = null,
+): ApiException {
+  return ApiException.fromCode(errorCode, data);
+}

package/template/apps/api/libs/infra/common/filter/exception/exception.ts

@@ -0,0 +1,47 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Inject,
+} from '@nestjs/common';
+
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+import { getReqMainInfo } from '@/utils/logger.util';
+
+@Catch()
+export class ExceptionsFilter implements ExceptionFilter {
+  constructor(
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+  ) {}
+
+  catch(exception: any, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse();
+    const request = ctx.getRequest();
+
+    const status =
+      exception instanceof HttpException
+        ? exception.getStatus()
+        : HttpStatus.INTERNAL_SERVER_ERROR;
+    let msg =
+      exception.message || (status >= 500 ? 'Service Error' : 'Client Error');
+    if (
+      Object.prototype.toString.call(response) === '[object Object]' &&
+      response.message
+    ) {
+      msg = response.message;
+    }
+
+    this.logger.error(
+      msg,
+      getReqMainInfo(request, { ...response, statusCode: status }),
+    );
+    response.status(status).json({
+      code: status,
+      msg: `Service Error: ${exception}`,
+    });
+  }
+}

package/template/apps/api/libs/infra/common/filter/exception/http.exception.ts

@@ -0,0 +1,126 @@
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  HttpException,
+  Inject,
+  BadRequestException,
+} from '@nestjs/common';
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { I18nContext } from 'nestjs-i18n';
+import { ApiException } from '@/filter/exception/api.exception';
+
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+import { errorFromType } from '@/ts-rest/response.helper';
+
+@Catch(HttpException, ApiException)
+export class HttpExceptionFilter implements ExceptionFilter {
+  constructor(
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+  ) {}
+
+  catch(exception: HttpException | ApiException, host: ArgumentsHost) {
+    // console.log('TECHWU HttpExceptionFilter', exception);
+    const { channel, message } = this.getChannelFromHost(host);
+    // console.log('TECHWU exception', exception);
+    if (channel) {
+      this.logger.error(exception.message, exception.stack);
+      channel.nack(message, false, false);
+    } else {
+      const i18n = I18nContext.current(host);
+      const ctx = host.switchToHttp();
+      const response = ctx.getResponse<FastifyReply>();
+      const request = ctx.getRequest<FastifyRequest>();
+      const status = exception.getStatus();
+
+      // 特殊处理参数校验失败
+      let validationErrors = null;
+
+      if (exception instanceof BadRequestException) {
+        const exceptionResponse = exception.getResponse() as any;
+        if (exceptionResponse && exceptionResponse.message) {
+          if (Array.isArray(exceptionResponse.message)) {
+            validationErrors = exceptionResponse.message;
+          } else {
+            validationErrors = [exceptionResponse.message];
+          }
+        }
+      }
+      const responseBody = this.buildResponseBody(
+        exception,
+        request,
+        status,
+        i18n,
+        validationErrors,
+      );
+
+      const { timestamp, path, ...responseRet } = responseBody;
+      // console.log('TECHWU , responseBody', responseBody)
+      response.status(status).send(responseRet);
+    }
+  }
+
+  private getChannelFromHost(host: ArgumentsHost): {
+    channel: any;
+    message: any;
+  } {
+    try {
+      const ctx = host.switchToRpc();
+      const context = ctx.getContext();
+      const channel = context.getChannelRef ? context.getChannelRef() : null;
+      const message = context.getMessage ? context.getMessage() : null;
+      return { channel, message };
+    } catch (error) {
+      console.error('获取通道或消息时发生错误', error);
+      return { channel: null, message: null };
+    }
+  }
+
+  private buildResponseBody(
+    exception: HttpException,
+    request: FastifyRequest,
+    status: number,
+    i18n: I18nContext,
+    validationErrors?: string[] | null,
+  ): any {
+    const isApiException = exception instanceof ApiException;
+    const timestamp = new Date().toLocaleString('zh-CN', {
+      timeZone: 'Asia/Shanghai',
+    });
+    const path = request.url;
+
+    // Get traceId for error tracking
+    const traceId = request.traceId;
+
+    // Get error code
+    const code = isApiException ? exception.getErrorCode() : status;
+
+    // Get error message
+    const message = isApiException
+      ? exception.getErrorMessage(i18n)
+      : exception.message || exception.getResponse();
+
+    // Get error data
+    const data = isApiException ? exception.getErrorData() : undefined;
+
+    const responseBody: any = {
+      code,
+      msg: message, // 使用 msg 与成功响应保持一致
+      traceId, // 添加 traceId 便于问题追踪
+      timestamp,
+      path,
+    };
+
+    // Add enhanced error details for ApiException
+    if (isApiException) {
+      responseBody.error = data;
+    }
+    // 如果是参数校验失败，添加详细的错误信息
+    if (validationErrors && validationErrors.length > 0) {
+      responseBody.error.errorData = validationErrors;
+    }
+
+    return responseBody;
+  }
+}

package/template/apps/api/libs/infra/common/guards/index.ts

@@ -0,0 +1 @@
+export * from './version.guard';

package/template/apps/api/libs/infra/common/guards/version.guard.ts

@@ -0,0 +1,312 @@
+import {
+  Injectable,
+  CanActivate,
+  ExecutionContext,
+  HttpException,
+  SetMetadata,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { FastifyRequest, FastifyReply } from 'fastify';
+import {
+  APP_BUILD_HEADER,
+  MIN_APP_BUILD_HEADER,
+  MIN_CLIENT_GENERATION,
+  PLATFORM_HEADER,
+  API_CONTRACT_HEADER,
+  PLATFORMS,
+  CONTRACTS,
+  MIN_SUPPORTED_CONTRACT,
+  CURRENT_CONTRACT,
+  type ApiContract,
+  type Platform,
+} from '@repo/constants';
+
+/**
+ * 跳过版本检查的装饰器 key
+ */
+export const SKIP_VERSION_CHECK = 'skipVersionCheck';
+
+/**
+ * 跳过版本检查装饰器
+ * @example
+ * ```typescript
+ * @SkipVersionCheck()
+ * @Get('health')
+ * health() { return { status: 'ok' }; }
+ * ```
+ */
+export const SkipVersionCheck = () => SetMetadata(SKIP_VERSION_CHECK, true);
+
+/**
+ * 版本上下文接口
+ * 注入到 request 中供 Service 使用
+ */
+export interface VersionContext {
+  /** 平台类型 */
+  platform: Platform;
+  /** API 合约版本 (APP 专用) */
+  contract?: ApiContract;
+  /** 支持的能力列表 */
+  features: readonly string[];
+  /** APP 构建号 */
+  appBuild?: string;
+}
+
+// 扩展 FastifyRequest 类型
+declare module 'fastify' {
+  interface FastifyRequest {
+    versionContext?: VersionContext;
+  }
+}
+
+/**
+ * Version Guard
+ * 统一版本校验 Guard，支持 Web 和 APP 双轨校验
+ *
+ * 校验策略:
+ * - Web 客户端: 使用 Generation (代际号) 校验，不兼容时返回 426 强制刷新
+ * - APP 客户端: 使用 Contract (合约版本) 校验，通过 Adapter 兼容旧版本
+ *
+ * @example
+ * ```typescript
+ * // 全局注册
+ * app.useGlobalGuards(new VersionGuard(new Reflector()));
+ *
+ * // 跳过特定路由
+ * @SkipVersionCheck()
+ * @Get('health')
+ * health() { return { status: 'ok' }; }
+ *
+ * // 在 Service 中使用版本上下文
+ * @Injectable()
+ * class MyService {
+ *   getUser(req: FastifyRequest) {
+ *     const ctx = req.versionContext;
+ *     if (ctx?.features.includes('user-v2')) {
+ *       return this.getUserV2();
+ *     }
+ *     return this.getUserV1();
+ *   }
+ * }
+ * ```
+ */
+@Injectable()
+export class VersionGuard implements CanActivate {
+  constructor(private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    // 检查是否跳过版本检查
+    const skipVersionCheck = this.reflector.getAllAndOverride<boolean>(
+      SKIP_VERSION_CHECK,
+      [context.getHandler(), context.getClass()],
+    );
+
+    if (skipVersionCheck) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest<FastifyRequest>();
+    const response = context.switchToHttp().getResponse<FastifyReply>();
+
+    const platform =
+      (request.headers[PLATFORM_HEADER] as string) || PLATFORMS.WEB;
+    const appBuild = request.headers[APP_BUILD_HEADER] as string;
+    const contract = request.headers[API_CONTRACT_HEADER] as ApiContract;
+
+    // Web 客户端: Generation 校验
+    if (platform === PLATFORMS.WEB || !platform) {
+      return this.validateWebClient(request, appBuild, response);
+    }
+
+    // APP 客户端: Contract 校验
+    return this.validateAppClient(
+      request,
+      platform as Platform,
+      appBuild,
+      contract,
+      response,
+    );
+  }
+
+  /**
+   * Web 客户端校验
+   * 使用 Generation (代际号) 进行校验
+   */
+  private validateWebClient(
+    request: FastifyRequest,
+    appBuild: string,
+    response: FastifyReply,
+  ): boolean {
+    // 开发环境或未提供版本时跳过检查
+    if (!appBuild || appBuild === 'dev' || appBuild === 'server') {
+      // 设置默认版本上下文
+      request.versionContext = {
+        platform: PLATFORMS.WEB,
+        features: CONTRACTS[CURRENT_CONTRACT].features,
+        appBuild,
+      };
+      return true;
+    }
+
+    // 提取代际号
+    const clientGeneration = this.extractGeneration(appBuild);
+
+    // 检查兼容性
+    if (clientGeneration < MIN_CLIENT_GENERATION) {
+      // 设置最低版本 header
+      const minAppBuild = this.getMinAppBuild();
+      response.header(MIN_APP_BUILD_HEADER, minAppBuild);
+
+      throw new HttpException(
+        {
+          code: 426,
+          msg: '客户端版本过旧，请刷新页面',
+          data: {
+            clientBuild: appBuild,
+            clientGeneration,
+            minGeneration: MIN_CLIENT_GENERATION,
+            minBuild: minAppBuild,
+          },
+        },
+        426, // HTTP 426 Upgrade Required
+      );
+    }
+
+    // 设置版本上下文
+    request.versionContext = {
+      platform: PLATFORMS.WEB,
+      features: CONTRACTS[CURRENT_CONTRACT].features,
+      appBuild,
+    };
+
+    return true;
+  }
+
+  /**
+   * APP 客户端校验
+   * 使用 Contract (合约版本) 进行校验
+   */
+  private validateAppClient(
+    request: FastifyRequest,
+    platform: Platform,
+    appBuild: string,
+    contract: ApiContract,
+    response: FastifyReply,
+  ): boolean {
+    // 检查 Contract 是否提供
+    if (!contract) {
+      // 如果没有提供 contract，使用默认最新版本
+      request.versionContext = {
+        platform,
+        contract: CURRENT_CONTRACT,
+        features: CONTRACTS[CURRENT_CONTRACT].features,
+        appBuild,
+      };
+      return true;
+    }
+
+    // 检查 Contract 是否支持
+    if (!CONTRACTS[contract]) {
+      throw new HttpException(
+        {
+          code: 400,
+          msg: '不支持的 API 版本，请升级 APP',
+          data: {
+            providedContract: contract,
+            supportedContracts: Object.keys(CONTRACTS),
+            minContract: MIN_SUPPORTED_CONTRACT,
+          },
+        },
+        400,
+      );
+    }
+
+    const contractConfig = CONTRACTS[contract];
+
+    // 检查 Contract 是否已过期 (sunset)
+    if (contractConfig.sunset && new Date() > new Date(contractConfig.sunset)) {
+      throw new HttpException(
+        {
+          code: 426,
+          msg: '当前版本已停止支持，请升级 APP',
+          data: {
+            expiredContract: contract,
+            minContract: MIN_SUPPORTED_CONTRACT,
+            sunsetDate: contractConfig.sunset,
+          },
+        },
+        426,
+      );
+    }
+
+    // 检查 APP Build 是否满足最低要求
+    if (appBuild && platform !== PLATFORMS.WEB) {
+      const minBuild = contractConfig.minBuild[platform as 'ios' | 'android'];
+      const buildNumber = this.extractBuildNumber(appBuild);
+
+      if (minBuild && buildNumber > 0 && buildNumber < minBuild) {
+        throw new HttpException(
+          {
+            code: 426,
+            msg: '请升级 APP 以继续使用',
+            data: {
+              currentBuild: buildNumber,
+              minBuild,
+              platform,
+            },
+          },
+          426,
+        );
+      }
+    }
+
+    // 设置版本上下文
+    request.versionContext = {
+      platform,
+      contract,
+      features: contractConfig.features,
+      appBuild,
+    };
+
+    // 如果 Contract 已废弃，添加警告 header
+    if (contractConfig.deprecated) {
+      response.header('X-Api-Deprecated', 'true');
+      response.header('X-Api-Upgrade-To', CURRENT_CONTRACT);
+    }
+
+    return true;
+  }
+
+  /**
+   * 从构建版本中提取代际号
+   * @param buildVersion 构建版本字符串 (格式: YYYY.MM.DD-hash-gNN)
+   * @returns 代际号，无法解析时返回 0
+   */
+  private extractGeneration(buildVersion: string): number {
+    const match = buildVersion.match(/-g(\d+)$/);
+    return match ? parseInt(match[1], 10) : 0;
+  }
+
+  /**
+   * 从 APP Build 中提取构建号
+   * @param appBuild APP 构建版本字符串 (格式: 数字或版本号)
+   * @returns 构建号，无法解析时返回 0
+   */
+  private extractBuildNumber(appBuild: string): number {
+    // 如果是纯数字，直接返回
+    const numericBuild = parseInt(appBuild, 10);
+    if (!isNaN(numericBuild)) {
+      return numericBuild;
+    }
+    // 否则尝试从版本号中提取
+    const match = appBuild.match(/(\d+)/);
+    return match ? parseInt(match[1], 10) : 0;
+  }
+
+  /**
+   * 获取最低兼容的构建版本
+   */
+  private getMinAppBuild(): string {
+    return `0000.00.00-000000-g${MIN_CLIENT_GENERATION}`;
+  }
+}

package/template/apps/api/libs/infra/common/interceptor/mask/index.ts

@@ -0,0 +1 @@
+export * from './mask.interceptor';