create-pardx-scaffold 0.1.0

package/template/apps/api/libs/infra/common/decorators/ts-rest-controller.decorator.ts

@@ -0,0 +1,63 @@
+import { Controller, VERSION_NEUTRAL, ControllerOptions } from '@nestjs/common';
+import { VERSION_METADATA } from '@nestjs/common/constants';
+
+/**
+ * TsRestController 装饰器 - 版本中立控制器
+ *
+ * **仅用于不需要版本控制的特殊端点**，如版本检查 API。
+ * 设置 VERSION_NEUTRAL 让请求无需 x-api-version header 即可访问。
+ *
+ * **适用场景**:
+ * - 版本检查 API (/api/version)
+ * - 健康检查端点
+ * - 其他需要无版本访问的公共端点
+ *
+ * **注意**: 普通 API 控制器应使用 `@Controller({ version: API_VERSION.V1 })`
+ *
+ * 支持多种用法：
+ *
+ * 1. 无参数:
+ *    ```typescript
+ *    @TsRestController()
+ *    export class AppVersionController { }
+ *    ```
+ *
+ * 2. 带路径前缀:
+ *    ```typescript
+ *    @TsRestController('version')
+ *    export class AppVersionController { }
+ *    ```
+ *
+ * 3. 带配置选项:
+ *    ```typescript
+ *    @TsRestController({ path: 'health' })
+ *    export class HealthController { }
+ *    ```
+ */
+export function TsRestController(): ClassDecorator;
+export function TsRestController(prefix: string | string[]): ClassDecorator;
+export function TsRestController(
+  options: Omit<ControllerOptions, 'version'>,
+): ClassDecorator;
+export function TsRestController(
+  prefixOrOptions?: string | string[] | Omit<ControllerOptions, 'version'>,
+): ClassDecorator {
+  return (target: Function) => {
+    if (prefixOrOptions === undefined) {
+      // @TsRestController()
+      Controller()(target);
+    } else if (
+      typeof prefixOrOptions === 'string' ||
+      Array.isArray(prefixOrOptions)
+    ) {
+      // @TsRestController('path') 或 @TsRestController(['path1', 'path2'])
+      Controller(prefixOrOptions)(target);
+    } else {
+      // @TsRestController({ path: 'admin', host: '...' })
+      Controller(prefixOrOptions as ControllerOptions)(target);
+    }
+
+    // 设置 VERSION_NEUTRAL，让 NestJS 放行，由 ts-rest 处理路由
+    Reflect.defineMetadata(VERSION_METADATA, VERSION_NEUTRAL, target);
+  };
+}

package/template/apps/api/libs/infra/common/decorators/validation.decorator.ts

@@ -0,0 +1,120 @@
+import { registerDecorator, ValidationArguments } from 'class-validator';
+import { ApiException } from '../filter/exception/api.exception';
+import { ErrorMessageEnums } from '../enums/error-codes';
+import stringUtil from '@/utils/string.util';
+
+// 自定义装饰器
+export function LengthValidator(
+  min: number,
+  max: number,
+  errorTypeMin: string,
+  errorTypeMax: string,
+  field: string = '',
+  validateErrorType: string = 'invalidParameters',
+) {
+  return function (object: object, propertyName: string) {
+    const errorMin = ErrorMessageEnums[errorTypeMin];
+    const errorMax = ErrorMessageEnums[errorTypeMax];
+    registerDecorator({
+      name: 'LengthValidator',
+      target: object.constructor,
+      propertyName: propertyName,
+      constraints: [min, max, errorMin.errorCode, errorMax.errorCode],
+      options: {
+        message: (args: ValidationArguments) => {
+          if (typeof args.value !== 'string') return `类型必须为字符串`;
+          if (args.value.length < min) return errorMin.message;
+          if (args.value.length > max) return errorMax.message;
+          return '';
+        },
+      },
+      validator: {
+        validate(value: any, args: ValidationArguments) {
+          const [min, max] = args.constraints;
+          if (typeof value !== 'string') {
+            throw new ApiException(validateErrorType, { field });
+          }
+          if (value.length < min) {
+            throw new ApiException(errorTypeMin, { field });
+          } else if (value.length > max) {
+            throw new ApiException(errorTypeMax, { field });
+          }
+          return true;
+        },
+      },
+    });
+  };
+}
+
+// 自定义装饰器
+export function IsDateFormat(
+  field: string,
+  canbeNull: boolean = true,
+  errorType: string = 'invalidParameters',
+) {
+  return function (object: object, propertyName: string) {
+    const error = ErrorMessageEnums[errorType];
+    registerDecorator({
+      name: 'IsDateFormat',
+      target: object.constructor,
+      propertyName: propertyName,
+      options: {
+        message: (args: ValidationArguments) => {
+          if (typeof args.value !== 'string') return `类型必须为字符串格式`;
+          if (!/^\d{4}-\d{2}-\d{2}$/.test(args.value)) return error.message;
+          return '';
+        },
+      },
+      validator: {
+        validate(value: any) {
+          if (!value && canbeNull) return true;
+          if (typeof value !== 'string') {
+            throw new ApiException(errorType, { field });
+          }
+          if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+            throw new ApiException(errorType, { field });
+          }
+          return true;
+        },
+      },
+    });
+  };
+}
+
+// 自定义装饰器
+export function IsUUIDFormat(
+  field: string,
+  canbeNull: boolean = true,
+  errorType: string = 'invalidParameters',
+) {
+  return function (object: object, propertyName: string) {
+    const error = ErrorMessageEnums[errorType];
+    registerDecorator({
+      name: 'IsUUIDFormat',
+      target: object.constructor,
+      propertyName: propertyName,
+      options: {
+        message: (args: ValidationArguments) => {
+          if (typeof args.value !== 'string') return `类型必须为字符串格式`;
+          if (!stringUtil.isUUID(args.value)) return error.message;
+          return '';
+        },
+      },
+      validator: {
+        validate(value: any) {
+          if (['folderId', 'parentId'].includes(field) && value == 'root') {
+            value = null;
+          }
+          if (!value && canbeNull) return true;
+          if (typeof value !== 'string') {
+            throw new ApiException(errorType, { field });
+          }
+          if (!stringUtil.isUUID(value)) {
+            throw new ApiException(errorType, { field });
+          }
+          return true;
+        },
+      },
+    });
+  };
+}

package/template/apps/api/libs/infra/common/decorators/version/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Version Decorators Module Exports
+ */
+
+export {
+  // Decorators
+  ApiVersion,
+  VersionNeutral,
+  DeprecatedVersion,
+  // Constants
+  API_VERSION_HEADER,
+  DEFAULT_API_VERSION,
+  VERSION_METADATA_KEY,
+  SUPPORTED_VERSIONS,
+  // Types
+  SupportedVersion,
+  // Utilities
+  isSupportedVersion,
+  getVersionFromRequest,
+  compareVersions,
+} from './version.decorator';
+
+export { VersionInterceptor } from './version.interceptor';
+export { VersionDecoratorModule } from './version.module';

package/template/apps/api/libs/infra/common/decorators/version/version.decorator.ts

@@ -0,0 +1,168 @@
+/**
+ * API Version Decorators
+ *
+ * 提供 API 版本控制装饰器，支持 Header 和 URI 版本控制。
+ * 与当前 api/... 前缀结构兼容，不改变现有路由。
+ *
+ * 版本控制策略:
+ * - 使用 Header: x-api-version 指定版本
+ * - 默认版本: 1 (VERSION_NEUTRAL)
+ * - 支持版本兼容性检查
+ *
+ * @example
+ * ```typescript
+ * // Controller 级别版本控制
+ * @Controller('users')
+ * @ApiVersion('2')
+ * export class UsersV2Controller { ... }
+ *
+ * // Method 级别版本控制
+ * @Get()
+ * @ApiVersion(['1', '2'])  // 支持多版本
+ * async getUsers() { ... }
+ * ```
+ */
+
+import { SetMetadata, applyDecorators, Version } from '@nestjs/common';
+import { ApiHeader } from '@nestjs/swagger';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+export const API_VERSION_HEADER = 'x-api-version';
+export const DEFAULT_API_VERSION = '1';
+export const VERSION_METADATA_KEY = 'api:version';
+
+/**
+ * 当前支持的 API 版本列表
+ */
+export const SUPPORTED_VERSIONS = ['1', '2'] as const;
+export type SupportedVersion = (typeof SUPPORTED_VERSIONS)[number];
+
+// ============================================================================
+// Decorators
+// ============================================================================
+
+/**
+ * @ApiVersion - API 版本控制装饰器
+ *
+ * 使用 NestJS 内置的 @Version 装饰器，配合 Header 版本控制策略。
+ *
+ * @param version - 版本号或版本号数组
+ *
+ * @example
+ * ```typescript
+ * // 单版本
+ * @ApiVersion('2')
+ * @Controller('users')
+ * export class UsersV2Controller { ... }
+ *
+ * // 多版本兼容
+ * @Get()
+ * @ApiVersion(['1', '2'])
+ * async getUsers() { ... }
+ * ```
+ */
+export function ApiVersion(
+  version: SupportedVersion | SupportedVersion[],
+): MethodDecorator & ClassDecorator {
+  return applyDecorators(
+    Version(version),
+    SetMetadata(VERSION_METADATA_KEY, version),
+    ApiHeader({
+      name: API_VERSION_HEADER,
+      description: `API 版本号 (支持: ${SUPPORTED_VERSIONS.join(', ')})`,
+      required: false,
+      schema: {
+        type: 'string',
+        default: DEFAULT_API_VERSION,
+        enum: [...SUPPORTED_VERSIONS],
+      },
+    }),
+  );
+}
+
+/**
+ * @VersionNeutral - 版本中立装饰器
+ *
+ * 标记方法或控制器不受版本控制影响，适用于所有版本。
+ *
+ * @example
+ * ```typescript
+ * @VersionNeutral()
+ * @Get('health')
+ * async healthCheck() { ... }
+ * ```
+ */
+export function VersionNeutral(): MethodDecorator & ClassDecorator {
+  return applyDecorators(
+    Version('neutral' as any), // VERSION_NEUTRAL
+    SetMetadata(VERSION_METADATA_KEY, 'neutral'),
+  );
+}
+
+/**
+ * @DeprecatedVersion - 废弃版本警告装饰器
+ *
+ * 标记即将废弃的 API 版本，会在响应头中添加 Deprecation 警告。
+ *
+ * @param message - 废弃说明
+ * @param sunsetDate - 停止服务日期 (可选)
+ *
+ * @example
+ * ```typescript
+ * @DeprecatedVersion('请升级到 v2 API', '2025-06-01')
+ * @Get()
+ * async getUsers() { ... }
+ * ```
+ */
+export function DeprecatedVersion(
+  message: string,
+  sunsetDate?: string,
+): MethodDecorator {
+  return (
+    target: any,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) => {
+    SetMetadata('api:deprecated', { message, sunsetDate })(
+      target,
+      propertyKey,
+      descriptor,
+    );
+    return descriptor;
+  };
+}
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * 检查版本是否受支持
+ */
+export function isSupportedVersion(
+  version: string,
+): version is SupportedVersion {
+  return SUPPORTED_VERSIONS.includes(version as SupportedVersion);
+}
+
+/**
+ * 获取版本从请求头
+ */
+export function getVersionFromRequest(request: any): string {
+  return request.headers?.[API_VERSION_HEADER] || DEFAULT_API_VERSION;
+}
+
+/**
+ * 比较版本号
+ * @returns -1 if v1 < v2, 0 if v1 == v2, 1 if v1 > v2
+ */
+export function compareVersions(v1: string, v2: string): number {
+  const num1 = parseInt(v1, 10);
+  const num2 = parseInt(v2, 10);
+  if (num1 < num2) return -1;
+  if (num1 > num2) return 1;
+  return 0;
+}

package/template/apps/api/libs/infra/common/decorators/version/version.interceptor.ts

@@ -0,0 +1,97 @@
+/**
+ * Version Interceptor
+ *
+ * 拦截器实现，处理 API 版本控制逻辑：
+ * - 添加版本响应头
+ * - 处理废弃版本警告
+ * - 版本日志记录
+ */
+
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+  Inject,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
+import { tap } from 'rxjs/operators';
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+
+import {
+  API_VERSION_HEADER,
+  DEFAULT_API_VERSION,
+  VERSION_METADATA_KEY,
+  SUPPORTED_VERSIONS,
+} from './version.decorator';
+
+@Injectable()
+export class VersionInterceptor implements NestInterceptor {
+  constructor(
+    private readonly reflector: Reflector,
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+  ) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const request = context.switchToHttp().getRequest();
+    const response = context.switchToHttp().getResponse();
+    const handler = context.getHandler();
+    const controller = context.getClass();
+
+    // 获取请求的版本
+    const requestVersion =
+      request.headers?.[API_VERSION_HEADER] || DEFAULT_API_VERSION;
+
+    // 获取方法或控制器的版本元数据
+    const methodVersion = this.reflector.get<string | string[]>(
+      VERSION_METADATA_KEY,
+      handler,
+    );
+    const controllerVersion = this.reflector.get<string | string[]>(
+      VERSION_METADATA_KEY,
+      controller,
+    );
+
+    // 获取废弃信息
+    const deprecatedInfo = this.reflector.get<{
+      message: string;
+      sunsetDate?: string;
+    }>('api:deprecated', handler);
+
+    // 添加版本响应头
+    response.header('x-api-version', requestVersion);
+    response.header('x-supported-versions', SUPPORTED_VERSIONS.join(', '));
+
+    // 处理废弃版本警告
+    if (deprecatedInfo) {
+      response.header('Deprecation', 'true');
+      response.header('X-Deprecation-Message', deprecatedInfo.message);
+      if (deprecatedInfo.sunsetDate) {
+        response.header('Sunset', deprecatedInfo.sunsetDate);
+      }
+
+      this.logger.warn('Deprecated API version used', {
+        path: request.url,
+        method: request.method,
+        version: requestVersion,
+        message: deprecatedInfo.message,
+        sunsetDate: deprecatedInfo.sunsetDate,
+      });
+    }
+
+    return next.handle().pipe(
+      tap(() => {
+        // 可选: 记录版本使用日志
+        this.logger.debug('API request processed', {
+          path: request.url,
+          method: request.method,
+          version: requestVersion,
+          controllerVersion,
+          methodVersion,
+        });
+      }),
+    );
+  }
+}

package/template/apps/api/libs/infra/common/decorators/version/version.module.ts

@@ -0,0 +1,21 @@
+/**
+ * Version Decorator Module
+ *
+ * 提供 API 版本控制功能的全局模块。
+ */
+
+import { Global, Module } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { VersionInterceptor } from './version.interceptor';
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: VersionInterceptor,
+    },
+  ],
+  exports: [],
+})
+export class VersionDecoratorModule {}

package/template/apps/api/libs/infra/common/enums/action.enum.ts

@@ -0,0 +1,7 @@
+export enum Action {
+  Manage = 'manage',
+  Create = 'create',
+  Read = 'read',
+  Update = 'update',
+  Delete = 'delete',
+}

package/template/apps/api/libs/infra/common/enums/error-codes.ts

@@ -0,0 +1,71 @@
+/**
+ * Error Codes Bridge File
+ * 错误码桥接文件
+ *
+ * Re-exports error codes from @repo/contracts and provides
+ * backward-compatible ErrorMessageEnums for existing code.
+ *
+ * Migration Guide:
+ * - New code: import { UserErrorCode } from '@repo/contracts/errors';
+ * - New code: import { apiError } from '@/filter/exception/api.exception';
+ */
+
+// Re-export all error codes from @repo/contracts
+export {
+  ApiErrorCode,
+  UserErrorCode,
+  CommonErrorCode,
+  AllErrorTypes,
+  AllErrorHttpStatus,
+  getErrorType,
+  getHttpStatus,
+} from '@repo/contracts/errors';
+
+import { AllErrorTypes, AllErrorHttpStatus } from '@repo/contracts/errors';
+
+/**
+ * Error Message Definition Type
+ * Note: errorCode is now a string but numeric representation is kept for backward compatibility
+ */
+export interface ErrorMessageDefinition {
+  errorCode: number;
+  httpStatus: number;
+  message: string;
+}
+
+/**
+ * Generate ErrorMessageEnums from @repo/contracts
+ * 从 @repo/contracts 生成 ErrorMessageEnums
+ *
+ * This provides backward compatibility with the old error system.
+ * The message is just the errorType - actual messages come from i18n.
+ */
+function generateErrorMessageEnums(): Record<string, ErrorMessageDefinition> {
+  const result: Record<string, ErrorMessageDefinition> = {};
+
+  for (const [codeStr, errorType] of Object.entries(AllErrorTypes)) {
+    const code = Number(codeStr);
+    const httpStatus = AllErrorHttpStatus[codeStr] ?? 200;
+
+    result[errorType] = {
+      errorCode: code,
+      httpStatus,
+      message: errorType, // Message comes from i18n, this is just fallback
+    };
+  }
+
+  return result;
+}
+
+/**
+ * ErrorMessageEnums - Backward compatible mapping
+ * 向后兼容的错误消息映射
+ *
+ * @deprecated Use @repo/contracts/errors directly for new code
+ */
+export const ErrorMessageEnums = generateErrorMessageEnums();
+
+/**
+ * Type for ErrorMessageEnums keys
+ */
+export type ErrorType = keyof typeof ErrorMessageEnums;

package/template/apps/api/libs/infra/common/enums/role.enum.ts

@@ -0,0 +1,4 @@
+export enum Role {
+  User = 'user',
+  Admin = 'admin',
+}