create-pardx-scaffold 0.1.0

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

@@ -0,0 +1,24 @@
+/**
+ * Cache Module
+ *
+ * 提供缓存装饰器功能的 NestJS 模块。
+ * 导入此模块以启用 @Cacheable, @CacheEvict, @CachePut 装饰器。
+ */
+
+import { Module, Global } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { RedisModule } from '@app/redis';
+import { CacheInterceptor } from './cache.interceptor';
+
+@Global()
+@Module({
+  imports: [RedisModule],
+  providers: [
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: CacheInterceptor,
+    },
+  ],
+  exports: [],
+})
+export class CacheDecoratorModule {}

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

@@ -0,0 +1,33 @@
+/**
+ * Cache Decorators Module Exports
+ */
+
+export {
+  // Decorators
+  Cacheable,
+  CacheEvict,
+  CachePut,
+  // Types
+  CacheOptions,
+  CacheEvictOptions,
+  HierarchicalKeyConfig,
+  // Key Generators - Basic
+  defaultKeyGenerator,
+  objectKeyGenerator,
+  compositeKeyGenerator,
+  // Key Generators - Hierarchical (支持分层缓存)
+  hierarchicalKeyGenerator,
+  simpleHierarchicalKeyGenerator,
+  userKeyGenerator,
+  spaceKeyGenerator,
+  // Hash Utilities
+  hashObject,
+  hashParams,
+  // Metadata Keys
+  CACHE_METADATA_KEY,
+  CACHE_EVICT_METADATA_KEY,
+  CACHE_PUT_METADATA_KEY,
+} from './cache.decorator';
+
+export { CacheInterceptor } from './cache.interceptor';
+export { CacheDecoratorModule } from './cache.module';

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

@@ -0,0 +1,229 @@
+/**
+ * Event Decorators
+ *
+ * 提供方法级别的事件装饰器，用于解耦业务逻辑。
+ * 支持同步和异步事件触发，与 NestJS EventEmitter 深度融合。
+ *
+ * @example
+ * ```typescript
+ * // 触发事件 - 方法执行后触发
+ * @EmitEvent('user.updated')
+ * async updateUser(userId: string, data: any) { ... }
+ *
+ * // 监听事件
+ * @OnEvent('user.updated')
+ * async handleUserUpdated(payload: UserUpdatedPayload) { ... }
+ *
+ * // 条件触发
+ * @EmitEvent('user.created', { condition: (result) => result !== null })
+ * async createUser(data: any) { ... }
+ * ```
+ */
+
+import { SetMetadata, applyDecorators } from '@nestjs/common';
+
+// ============================================================================
+// Metadata Keys
+// ============================================================================
+
+export const EMIT_EVENT_METADATA_KEY = 'event:emit';
+export const EMIT_EVENTS_METADATA_KEY = 'event:emit:multiple';
+
+// ============================================================================
+// Event Names (建议统一在此定义)
+// ============================================================================
+
+/**
+ * 系统事件名称常量
+ * 使用点号分隔的命名约定: domain.action
+ */
+export const EventNames = {
+  // 用户相关事件
+  USER: {
+    CREATED: 'user.created',
+    UPDATED: 'user.updated',
+    DELETED: 'user.deleted',
+    LOGIN: 'user.login',
+    LOGOUT: 'user.logout',
+    PASSWORD_CHANGED: 'user.password.changed',
+  },
+  // 缓存相关事件
+  CACHE: {
+    INVALIDATED: 'cache.invalidated',
+    REFRESHED: 'cache.refreshed',
+  },
+  // 认证相关事件
+  AUTH: {
+    TOKEN_CREATED: 'auth.token.created',
+    TOKEN_REFRESHED: 'auth.token.refreshed',
+    TOKEN_REVOKED: 'auth.token.revoked',
+  },
+} as const;
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * 事件发射配置选项
+ */
+export interface EmitEventOptions {
+  /** 事件名称 */
+  eventName: string;
+
+  /**
+   * 是否异步触发 (不阻塞方法返回)
+   * 默认: true
+   */
+  async?: boolean;
+
+  /**
+   * 是否在方法执行前触发
+   * 默认: false (方法执行后触发)
+   */
+  beforeInvocation?: boolean;
+
+  /**
+   * 条件表达式 - 决定是否触发事件
+   * 接收方法返回值，返回 true 则触发
+   * 默认: 总是触发
+   */
+  condition?: (result: any, args: any[]) => boolean;
+
+  /**
+   * 自定义 payload 生成器
+   * 接收方法参数和返回值，返回事件 payload
+   * 默认: { args, result }
+   */
+  payloadGenerator?: (args: any[], result: any) => any;
+}
+
+/**
+ * 事件 Payload 基础类型
+ */
+export interface BaseEventPayload<T = any> {
+  /** 事件触发时间 */
+  timestamp: Date;
+  /** 方法参数 */
+  args: any[];
+  /** 方法返回值 */
+  result: T;
+  /** 额外上下文 */
+  context?: Record<string, any>;
+}
+
+// ============================================================================
+// Decorators
+// ============================================================================
+
+/**
+ * @EmitEvent - 方法执行后触发事件
+ *
+ * @param eventName - 事件名称
+ * @param options - 可选配置
+ *
+ * @example
+ * ```typescript
+ * @EmitEvent(EventNames.USER.UPDATED)
+ * async updateUser(userId: string, data: any) {
+ *     return await this.prisma.userInfo.update({ where: { id: userId }, data });
+ * }
+ *
+ * @EmitEvent(EventNames.USER.CREATED, {
+ *     condition: (result) => result !== null,
+ *     payloadGenerator: (args, result) => ({ userId: result.id, email: result.email }),
+ * })
+ * async createUser(data: CreateUserDto) { ... }
+ * ```
+ */
+export function EmitEvent(
+  eventName: string,
+  options?: Partial<Omit<EmitEventOptions, 'eventName'>>,
+): MethodDecorator {
+  const eventOptions: EmitEventOptions = {
+    eventName,
+    async: true,
+    beforeInvocation: false,
+    ...options,
+  };
+
+  return SetMetadata(EMIT_EVENT_METADATA_KEY, eventOptions);
+}
+
+/**
+ * @EmitEvents - 方法执行后触发多个事件
+ *
+ * @param events - 事件配置数组
+ *
+ * @example
+ * ```typescript
+ * @EmitEvents([
+ *     { eventName: EventNames.USER.UPDATED },
+ *     { eventName: EventNames.CACHE.INVALIDATED, payloadGenerator: (args) => ({ key: `user:${args[0]}` }) },
+ * ])
+ * async updateUser(userId: string, data: any) { ... }
+ * ```
+ */
+export function EmitEvents(
+  events: Array<{
+    eventName: string;
+    options?: Partial<Omit<EmitEventOptions, 'eventName'>>;
+  }>,
+): MethodDecorator {
+  const eventConfigs = events.map((e) => ({
+    eventName: e.eventName,
+    async: true,
+    beforeInvocation: false,
+    ...e.options,
+  }));
+
+  return SetMetadata(EMIT_EVENTS_METADATA_KEY, eventConfigs);
+}
+
+// ============================================================================
+// Payload Generators
+// ============================================================================
+
+/**
+ * 默认 payload 生成器
+ */
+export function defaultPayloadGenerator(
+  args: any[],
+  result: any,
+): BaseEventPayload {
+  return {
+    timestamp: new Date(),
+    args,
+    result,
+  };
+}
+
+/**
+ * 用户事件 payload 生成器
+ */
+export function userEventPayloadGenerator(args: any[], result: any) {
+  const userId = args[0];
+  return {
+    timestamp: new Date(),
+    userId,
+    user: result,
+    args,
+    result,
+  };
+}
+
+/**
+ * 缓存失效事件 payload 生成器
+ */
+export function cacheInvalidatePayloadGenerator(
+  cacheName: string,
+  keyGenerator?: (...args: any[]) => string,
+) {
+  return (args: any[], result: any) => ({
+    timestamp: new Date(),
+    cacheName,
+    cacheKey: keyGenerator ? keyGenerator(...args) : args[0],
+    args,
+    result,
+  });
+}

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

@@ -0,0 +1,155 @@
+/**
+ * Event Interceptor
+ *
+ * 拦截器实现，处理 @EmitEvent, @EmitEvents 装饰器的事件触发逻辑。
+ * 与 NestJS EventEmitter2 深度融合。
+ */
+
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+  Inject,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
+import { tap } from 'rxjs/operators';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+
+import {
+  EMIT_EVENT_METADATA_KEY,
+  EMIT_EVENTS_METADATA_KEY,
+  EmitEventOptions,
+  defaultPayloadGenerator,
+} from './event.decorator';
+
+@Injectable()
+export class EventInterceptor implements NestInterceptor {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly eventEmitter: EventEmitter2,
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+  ) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const handler = context.getHandler();
+    const className = context.getClass().name;
+    const methodName = handler.name;
+
+    // 获取单个事件配置
+    const singleEvent = this.reflector.get<EmitEventOptions>(
+      EMIT_EVENT_METADATA_KEY,
+      handler,
+    );
+
+    // 获取多个事件配置
+    const multipleEvents = this.reflector.get<EmitEventOptions[]>(
+      EMIT_EVENTS_METADATA_KEY,
+      handler,
+    );
+
+    // 合并所有事件配置
+    const eventConfigs: EmitEventOptions[] = [];
+    if (singleEvent) {
+      eventConfigs.push(singleEvent);
+    }
+    if (multipleEvents) {
+      eventConfigs.push(...multipleEvents);
+    }
+
+    // 如果没有事件配置，直接执行
+    if (eventConfigs.length === 0) {
+      return next.handle();
+    }
+
+    // 获取方法参数
+    const args = context.getArgs();
+
+    // 处理 beforeInvocation 事件
+    const beforeEvents = eventConfigs.filter((e) => e.beforeInvocation);
+    for (const event of beforeEvents) {
+      this.emitEvent(event, args, undefined, className, methodName);
+    }
+
+    // 处理 afterInvocation 事件
+    const afterEvents = eventConfigs.filter((e) => !e.beforeInvocation);
+    if (afterEvents.length === 0) {
+      return next.handle();
+    }
+
+    return next.handle().pipe(
+      tap((result) => {
+        for (const event of afterEvents) {
+          this.emitEvent(event, args, result, className, methodName);
+        }
+      }),
+    );
+  }
+
+  /**
+   * 触发事件
+   */
+  private emitEvent(
+    options: EmitEventOptions,
+    args: any[],
+    result: any,
+    className: string,
+    methodName: string,
+  ): void {
+    try {
+      // 检查条件
+      if (options.condition && !options.condition(result, args)) {
+        this.logger.debug('Event condition not met, skipping', {
+          eventName: options.eventName,
+          className,
+          methodName,
+        });
+        return;
+      }
+
+      // 生成 payload
+      const payloadGenerator =
+        options.payloadGenerator || defaultPayloadGenerator;
+      const payload = payloadGenerator(args, result);
+
+      // 添加上下文信息
+      const enrichedPayload = {
+        ...payload,
+        __meta: {
+          eventName: options.eventName,
+          source: `${className}.${methodName}`,
+          emittedAt: new Date().toISOString(),
+        },
+      };
+
+      // 触发事件
+      if (options.async !== false) {
+        // 异步触发 (不阻塞)
+        setImmediate(() => {
+          this.eventEmitter.emit(options.eventName, enrichedPayload);
+          this.logger.debug('Event emitted (async)', {
+            eventName: options.eventName,
+            source: `${className}.${methodName}`,
+          });
+        });
+      } else {
+        // 同步触发
+        this.eventEmitter.emit(options.eventName, enrichedPayload);
+        this.logger.debug('Event emitted (sync)', {
+          eventName: options.eventName,
+          source: `${className}.${methodName}`,
+        });
+      }
+    } catch (error) {
+      this.logger.error('Event emission error', {
+        eventName: options.eventName,
+        className,
+        methodName,
+        error: error.message,
+      });
+    }
+  }
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Event Decorator Module
+ *
+ * 提供事件装饰器功能的 NestJS 模块。
+ * 导入此模块以启用 @EmitEvent, @EmitEvents 装饰器。
+ */
+
+import { Module, Global } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { EventEmitterModule } from '@nestjs/event-emitter';
+import { EventInterceptor } from './event.interceptor';
+import { CacheEventHandler } from './handlers/cache-event.handler';
+import { CacheDecoratorModule } from '../cache/cache.module';
+import { RedisModule } from '@app/redis';
+
+@Global()
+@Module({
+  imports: [
+    CacheDecoratorModule,
+    RedisModule,
+    EventEmitterModule.forRoot({
+      // 通配符支持
+      wildcard: true,
+      // 分隔符
+      delimiter: '.',
+      // 新监听器优先
+      newListener: false,
+      // 移除监听器时触发
+      removeListener: false,
+      // 最大监听器数量
+      maxListeners: 20,
+      // 启用详细内存泄漏警告
+      verboseMemoryLeak: true,
+      // 忽略错误
+      ignoreErrors: false,
+    }),
+  ],
+  providers: [
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: EventInterceptor,
+    },
+    CacheEventHandler,
+  ],
+  exports: [CacheEventHandler],
+})
+export class EventDecoratorModule {}

package/template/apps/api/libs/infra/common/decorators/event/handlers/cache-event.handler.ts

@@ -0,0 +1,159 @@
+/**
+ * Cache Event Handler
+ *
+ * 处理缓存相关事件，用于缓存失效和刷新。
+ * 与 RedisService 深度融合。
+ */
+
+import { Injectable, Inject } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+import { RedisService } from '@app/redis';
+import { EventNames } from '../event.decorator';
+
+/**
+ * 缓存失效事件 Payload
+ */
+export interface CacheInvalidatedPayload {
+  cacheName: string;
+  cacheKey?: string;
+  pattern?: string;
+  reason?: string;
+  timestamp: Date;
+}
+
+/**
+ * 用户更新事件 Payload
+ */
+export interface UserUpdatedPayload {
+  userId: string;
+  user?: any;
+  timestamp: Date;
+}
+
+/**
+ * 团队成员变更事件 Payload
+ */
+
+@Injectable()
+export class CacheEventHandler {
+  constructor(
+    private readonly redis: RedisService,
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+  ) {}
+
+  /**
+   * 处理通用缓存失效事件
+   */
+  @OnEvent(EventNames.CACHE.INVALIDATED)
+  async handleCacheInvalidated(
+    payload: CacheInvalidatedPayload,
+  ): Promise<void> {
+    try {
+      if (payload.pattern) {
+        // 按模式清除
+        await this.invalidateByPattern(payload.cacheName, payload.pattern);
+      } else if (payload.cacheKey) {
+        // 按 key 清除
+        await this.redis.deleteData(payload.cacheName, payload.cacheKey);
+      }
+
+      this.logger.debug('Cache invalidated via event', {
+        cacheName: payload.cacheName,
+        cacheKey: payload.cacheKey,
+        pattern: payload.pattern,
+        reason: payload.reason,
+      });
+    } catch (error) {
+      this.logger.error('Cache invalidation error', {
+        cacheName: payload.cacheName,
+        error: error.message,
+      });
+    }
+  }
+
+  /**
+   * 处理用户更新事件 - 失效用户缓存
+   */
+  @OnEvent(EventNames.USER.UPDATED)
+  async handleUserUpdated(payload: UserUpdatedPayload): Promise<void> {
+    try {
+      if (payload.userId) {
+        await this.redis.deleteData('userInfo', payload.userId);
+        this.logger.debug('User cache invalidated', {
+          userId: payload.userId,
+          event: EventNames.USER.UPDATED,
+        });
+      }
+    } catch (error) {
+      this.logger.error('User cache invalidation error', {
+        userId: payload.userId,
+        error: error.message,
+      });
+    }
+  }
+
+  /**
+   * 处理用户删除事件 - 失效用户缓存
+   */
+  @OnEvent(EventNames.USER.DELETED)
+  async handleUserDeleted(payload: UserUpdatedPayload): Promise<void> {
+    try {
+      if (payload.userId) {
+        await this.redis.deleteData('userInfo', payload.userId);
+        this.logger.debug('User cache invalidated on delete', {
+          userId: payload.userId,
+          event: EventNames.USER.DELETED,
+        });
+      }
+    } catch (error) {
+      this.logger.error('User cache invalidation error on delete', {
+        userId: payload.userId,
+        error: error.message,
+      });
+    }
+  }
+
+  /**
+   * 按模式失效缓存
+   */
+  private async invalidateByPattern(
+    cacheName: string,
+    pattern: string,
+  ): Promise<void> {
+    const fullPattern = this.redis.getRedisKey(cacheName, pattern);
+    const keys = await this.scanKeys(fullPattern);
+
+    if (keys.length > 0) {
+      await Promise.all(keys.map((key) => this.redis.del(key)));
+      this.logger.debug('Cache invalidated by pattern', {
+        cacheName,
+        pattern,
+        count: keys.length,
+      });
+    }
+  }
+
+  /**
+   * 扫描匹配 pattern 的所有 keys
+   */
+  private async scanKeys(pattern: string): Promise<string[]> {
+    const keys: string[] = [];
+    let cursor = '0';
+
+    do {
+      const result = await this.redis.redis.scan(
+        cursor,
+        'MATCH',
+        pattern,
+        'COUNT',
+        100,
+      );
+      cursor = result[0];
+      keys.push(...result[1]);
+    } while (cursor !== '0');
+
+    return keys;
+  }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Event Decorators Module Exports
+ */
+
+export {
+  // Decorators
+  EmitEvent,
+  EmitEvents,
+  // Types
+  EmitEventOptions,
+  BaseEventPayload,
+  // Event Names
+  EventNames,
+  // Payload Generators
+  defaultPayloadGenerator,
+  userEventPayloadGenerator,
+  cacheInvalidatePayloadGenerator,
+  // Metadata Keys
+  EMIT_EVENT_METADATA_KEY,
+  EMIT_EVENTS_METADATA_KEY,
+} from './event.decorator';
+
+export { EventInterceptor } from './event.interceptor';
+export { EventDecoratorModule } from './event.module';
+export {
+  CacheEventHandler,
+  CacheInvalidatedPayload,
+  UserUpdatedPayload,
+} from './handlers/cache-event.handler';