create-pardx-scaffold 0.1.0

package/template/apps/api/libs/domain/auth/src/auth.guard.ts

@@ -0,0 +1,173 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Inject,
+  Injectable,
+} from '@nestjs/common';
+import { AuthService } from './auth.service';
+import { JwtService } from '@nestjs/jwt';
+import { CommonErrorCode } from '@repo/contracts/errors';
+import { apiError } from '@/filter/exception/api.exception';
+import { ConfigService } from '@nestjs/config';
+import { JwtConfig } from '@/config/validation';
+import stringUtil from '@/utils/string.util';
+import { UserInfoService } from '@app/db';
+import { RedisService } from '@app/redis';
+import { FastifyRequest, FastifyReply } from 'fastify';
+import enviromentUtil from '@/utils/enviroment.util';
+import { Reflector } from '@nestjs/core';
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+import { MPTRAIL_HEADER } from '@repo/constants';
+
+@Injectable()
+export class AuthGuard implements CanActivate {
+  private readonly outOfAnonymityPathConfig;
+  private readonly outOfUserPathConfig;
+
+  constructor(
+    private readonly auth: AuthService,
+    private readonly jwt: JwtService,
+    private readonly config: ConfigService,
+    private readonly reflector: Reflector,
+    private readonly redis: RedisService,
+    private readonly user: UserInfoService,
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+  ) {
+    this.outOfAnonymityPathConfig =
+      this.config.getOrThrow<string[]>('outOfAnonymityPath');
+    this.outOfUserPathConfig =
+      this.config.getOrThrow<string[]>('outOfUserPath');
+  }
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest<FastifyRequest>();
+    const response = context.switchToHttp().getResponse<FastifyReply>();
+    const requestMethod = request.method.toLowerCase();
+    const requestPath = stringUtil.trimSlashes(
+      stringUtil.splitString(request.url, '?')[0],
+    );
+
+    // 检查是否在白名单路径中
+    if (
+      this.outOfUserPathConfig[requestMethod]?.some((path) =>
+        new RegExp(`^${path.replace(/:\w+/g, '[^/]+')}$`).test(
+          requestPath.replace('api/', ''),
+        ),
+      )
+    ) {
+      return true;
+    }
+
+    // 从方法处理器获取元数据
+    let authTypes = this.reflector.get<string[]>('auths', context.getHandler());
+    if (!authTypes) {
+      authTypes = this.reflector.get<string[]>('auths', context.getClass());
+    }
+
+    const [authType = 'api', guardType = 'api'] = authTypes || ['api', 'api'];
+    const isMpTest = request.headers[MPTRAIL_HEADER] === 'true';
+    let userId,
+      isAdmin = false,
+      isAnonymity = false;
+
+    if (!process.env.MODE_USER_ID) {
+      let access;
+      if (guardType === 'sse') {
+        access = decodeURIComponent(request.query['access_token'] as string);
+      } else {
+        access = this.auth.extractTokenFromHeader(request);
+        if (!access) {
+          throw apiError(CommonErrorCode.UnAuthorized);
+        }
+      }
+      if (!access) {
+        throw apiError(CommonErrorCode.UnAuthorized);
+      }
+
+      let payload;
+      try {
+        const jwtConfig = this.config.getOrThrow<JwtConfig>('jwt');
+        payload = await this.jwt.verifyAsync(access, {
+          secret: jwtConfig.secret,
+        });
+      } catch (error) {
+        throw apiError(CommonErrorCode.UnAuthorized);
+      }
+
+      userId = payload?.sub;
+      isAnonymity = payload?.isAnonymity;
+      isAdmin = payload?.isAdmin;
+
+      if (isAnonymity) {
+        throw apiError(CommonErrorCode.UnAuthorized);
+      }
+
+      // 将 JWT payload 中的用户信息设置到 request 中
+      (request as any).userInfo = {
+        id: userId,
+        nickname: payload?.nickname,
+        code: payload?.code,
+        headerImg: payload?.headerImg,
+        sex: payload?.sex,
+        isAdmin: isAdmin,
+        isAnonymity: isAnonymity,
+      };
+    } else {
+      if (process.env.NODE_ENV === 'prod') {
+        console.error(
+          '!!! CRITICAL SECURITY ERROR: MODE_USER_ID is set in prod environment! !!!',
+        );
+        throw apiError(CommonErrorCode.UnAuthorized);
+      }
+
+      console.warn(
+        '!!! WARNING: Auth Guard is running in insecure bypass mode. DO NOT USE IN PROD. !!!',
+      );
+      console.warn(
+        `!!! Bypass mode activated with userId: ${process.env.MODE_USER_ID} !!!`,
+      );
+
+      userId = process.env.MODE_USER_ID;
+      isAdmin = true;
+      isAnonymity = false;
+    }
+
+    if (!userId) {
+      throw apiError(CommonErrorCode.UnAuthorized);
+    }
+
+    if (
+      request.method.toLowerCase() === 'post' &&
+      process.env?.PREVIEW_MODE === 'true' &&
+      enviromentUtil.isWeChatMiniProgram(request) &&
+      isMpTest &&
+      process.env?.PREVIEW_USER_ID
+    ) {
+      throw apiError(CommonErrorCode.UnAuthorized);
+    }
+
+    if (authType === 'admin' && !isAdmin) {
+      throw apiError(CommonErrorCode.UnAuthorized);
+    }
+
+    // 检查匿名用户访问限制
+    if (
+      this.outOfAnonymityPathConfig[requestMethod]?.some((path) =>
+        new RegExp(`^${path.replace(/:\w+/g, '[^/]+')}$`).test(
+          requestPath.replace('api/', ''),
+        ),
+      ) &&
+      (request as any).isAnonymity
+    ) {
+      throw apiError(CommonErrorCode.UnAuthorized);
+    }
+
+    // 将用户信息设置到request对象中
+    (request as any).userId = userId;
+    (request as any).isAnonymity = isAnonymity;
+    (request as any).isAdmin = isAdmin;
+
+    return true;
+  }
+}

package/template/apps/api/libs/domain/auth/src/auth.module.ts

@@ -0,0 +1,23 @@
+import { Module } from '@nestjs/common';
+import { AuthGuard } from './auth.guard';
+import { AuthService } from './auth.service';
+import { AuthValidationService } from './auth-validation.service';
+import { ConfigModule } from '@nestjs/config';
+import { RedisModule } from '@app/redis';
+import { JwtModule } from '@app/jwt/jwt.module';
+import { UserInfoModule, FileSourceModule } from '@app/db';
+import { FileCdnModule } from '@app/clients/internal/file-cdn';
+
+@Module({
+  imports: [
+    ConfigModule,
+    RedisModule,
+    JwtModule,
+    UserInfoModule,
+    FileSourceModule,
+    FileCdnModule,
+  ],
+  providers: [AuthGuard, AuthService, AuthValidationService],
+  exports: [AuthGuard, AuthService, AuthValidationService],
+})
+export class AuthModule {}

package/template/apps/api/libs/domain/auth/src/auth.service.ts

@@ -0,0 +1,198 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+import { AuthClient } from '@app/auth';
+import stringUtil from '@/utils/string.util';
+import { JwtService } from '@nestjs/jwt';
+import { RedisService } from '@app/redis';
+import { UserInfo } from '@prisma/client';
+import { UserInfoService, FileSourceService } from '@app/db';
+import { FastifyRequest } from 'fastify';
+import { PardxApp } from '@/config/dto/config.dto';
+import { UserErrorCode, CommonErrorCode } from '@repo/contracts/errors';
+import { LoginSuccess } from '@repo/contracts';
+import { apiError } from '@/filter/exception/api.exception';
+import { FileCdnClient } from '@app/clients/internal/file-cdn';
+
+@Injectable()
+export class AuthService {
+  constructor(
+    private readonly redis: RedisService,
+    private readonly jwt: JwtService,
+    private readonly user: UserInfoService,
+    private readonly fileSource: FileSourceService,
+    private readonly fileCdn: FileCdnClient,
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+  ) {}
+
+  /**
+   * 登录成功后的处理函数
+   *
+   * @param user 用户信息
+   * @returns 登录成功后的结果信息
+   */
+  async loginSuccess(
+    user: Partial<UserInfo>,
+    deviceInfo: PardxApp.HeaderData,
+  ): Promise<LoginSuccess> {
+    return await this.refreshTokenByUser(user, deviceInfo);
+  }
+
+  extractTokenFromHeader(request: FastifyRequest): string | undefined {
+    const authorizationHeader = request.headers['authorization'] as
+      | string
+      | undefined;
+    if (!authorizationHeader) return undefined;
+    const [type, token] = authorizationHeader.split(' ');
+    return type === 'Bearer' ? token : undefined;
+  }
+
+  async getUserId(access: string): Promise<string | null> {
+    const userId = await this.redis.getData('access', access);
+    if (!userId) return null;
+    return userId;
+  }
+
+  async getUserSession(userId: string): Promise<AuthClient.Session> {
+    const session: AuthClient.Session = await this.redis.getData(
+      'session',
+      userId,
+    );
+    if (!session) return null;
+    return session;
+  }
+
+  async getUserSessionByRefresh(refresh: string): Promise<AuthClient.Session> {
+    const userId = await this.redis.getData('refresh', refresh);
+    if (!userId) return null;
+    return (await this.redis.getData('session', userId)) as AuthClient.Session;
+  }
+
+  async getUserSessionByAccess(access: string): Promise<AuthClient.Session> {
+    const userId = await this.redis.getData('access', access);
+    if (!userId) return null;
+    return (await this.redis.getData('session', userId)) as AuthClient.Session;
+  }
+
+  /**
+   * 移除原先的会话
+   *
+   * @param userId 用户ID
+   * @returns 返回新生成的AuthClient.Session对象
+   */
+  async removeSessions(userId: string): Promise<void> {
+    const prev = await this.redis.getData('session', userId);
+    if (prev) {
+      await this.redis.deleteData('refresh', prev.refresh);
+    }
+  }
+
+  async refreshTokenByUser(
+    user: Partial<UserInfo>,
+    deviceInfo: PardxApp.HeaderData,
+  ): Promise<LoginSuccess> {
+    const tokens: AuthClient.Session = await this.generateTokens(user);
+
+    await this.redis.saveData('session', tokens.userId, tokens);
+    await this.redis.saveData('refresh', tokens.refresh, tokens.userId);
+    await this.redis.saveData('access', tokens.access, tokens.userId);
+
+    return {
+      refresh: tokens.refresh,
+      expire: tokens.expire,
+      access: tokens.access,
+      accessExpire: tokens.accessExpire,
+      isAnonymity: tokens.isAnonymity,
+      user,
+    };
+  }
+
+  /**
+   * 创建匿名用户
+   * 根据设备信息创建匿名用户
+   *
+   * @param deviceInfo 设备信息
+   * @returns 创建的匿名用户
+   */
+  async createAnonyminyUser(
+    _deviceInfo: PardxApp.HeaderData,
+  ): Promise<Partial<UserInfo> | null> {
+    // TODO: Implement anonymous user creation with new schema
+    throw apiError(CommonErrorCode.InternalServerError, {
+      message: 'Anonymous user creation not implemented',
+    });
+  }
+
+  /**
+   * 刷新会话
+   * 根据 refresh token 刷新用户会话并返回 LoginSuccess 格式的数据
+   *
+   * @param refresh refresh token
+   * @param deviceInfo 设备信息
+   * @returns LoginSuccess 格式的登录数据
+   */
+  async refreshSession(
+    refresh: string,
+    deviceInfo: PardxApp.HeaderData,
+  ): Promise<LoginSuccess> {
+    const session = await this.getUserSessionByRefresh(refresh);
+    if (!session || session.isAnonymity) {
+      throw apiError(CommonErrorCode.UnAuthorized);
+    }
+
+    const user = await this.user.get({ id: session.userId });
+    if (!user) {
+      throw apiError(UserErrorCode.UserNotFound);
+    }
+
+    return await this.refreshTokenByUser(user, deviceInfo);
+  }
+
+  async generateTokens(user: Partial<UserInfo>): Promise<AuthClient.Session> {
+    const refresh = stringUtil.stringGen(64);
+    const accessTtl = this.redis.getExpireIn('access'); // 10分钟
+    const ttl = this.redis.getExpireIn('refresh'); // 30天
+    const isAnonymity = user?.isAnonymity;
+
+    // Convert avatarFileId to headerImg URL
+    let headerImg: string | undefined;
+    if (user.avatarFileId) {
+      const avatarFile = await this.fileSource.get({
+        id: user.avatarFileId,
+      });
+      if (avatarFile) {
+        headerImg = await this.fileCdn.getImageVolcengineCdn(
+          avatarFile.vendor,
+          avatarFile.bucket,
+          avatarFile.key,
+          '360:360:360:360',
+        );
+      }
+    }
+
+    // 为了与 JWT 标准保持一致，我们选择了 sub 作为属性名来保存 userId
+    // 将用户基本信息放入 JWT payload，避免每次都需要查询数据库
+    const access = await this.jwt.signAsync({
+      sub: user.id,
+      isAnonymity: isAnonymity,
+      isAdmin: user.isAdmin,
+      // 添加常用用户信息字段，避免每次都需要 getUserInfo
+      nickname: user.nickname,
+      code: user.code,
+      headerImg,
+      sex: user.sex,
+    });
+    const now = Date.now();
+    const expire = now + ttl * 1000;
+    const accessExpire = now + accessTtl * 1000;
+
+    return {
+      userId: user.id,
+      refresh,
+      access,
+      expire,
+      accessExpire,
+      isAnonymity,
+    };
+  }
+}

package/template/apps/api/libs/domain/auth/src/auth.ts

@@ -0,0 +1,66 @@
+import { applyDecorators, SetMetadata, UseGuards } from '@nestjs/common';
+import { AuthGuard } from './auth.guard';
+import { ApiBearerAuth } from '@nestjs/swagger';
+
+/**
+ * Auth 装饰器选项
+ */
+export interface AuthOptions {
+  /**
+   * 是否启用 RBAC 权限检查
+   * @default true
+   */
+  enableRbac?: boolean;
+
+  /**
+   * 是否启用模块权限检查
+   * 启用后会自动检查 @RequireModulePermission 等装饰器配置的权限
+   * @default true
+   */
+  enableModulePermission?: boolean;
+}
+
+/**
+ * 基础认证装饰器
+ * 现在已集成 RBAC 权限检查和模块权限检查功能
+ *
+ * @deprecated 该装饰器已废弃，请使用新的统一装饰器：
+ * - 简单认证: @SimpleAuth()
+ * - 只读操作: @ReadOnlyAuth(module, resource)
+ * - 管理员权限: @AdminAuth(isSuperAdmin?)
+ *
+ * 详见文档: apps/api/docs/Controller装饰器优化记录.md
+ *
+ * @param authType 认证类型：'api' | 'admin'
+ * @param guardType Guard类型：'sse' | 'api'
+ * @param options 选项对象或布尔值（向后兼容 enableRbac）
+ * @returns 装饰器组合
+ *
+ * @example
+ * // ❌ 旧写法（已废弃）
+ * @Auth()
+ * @RequireModulePermission('recruitment', 'job', 'create')
+ *
+ * // ✅ 新写法（推荐）
+ * @ReadOnlyAuth('recruitment', 'job')
+ */
+export function Auth(
+  authType: 'api' | 'admin' = 'api',
+  guardType: 'sse' | 'api' = 'api',
+  options: AuthOptions | boolean = {},
+) {
+  // 向后兼容：如果 options 是布尔值，转换为对象
+  const normalizedOptions: AuthOptions =
+    typeof options === 'boolean' ? { enableRbac: options } : options;
+
+  const { enableRbac = true, enableModulePermission = true } =
+    normalizedOptions;
+
+  return applyDecorators(
+    SetMetadata('auths', [authType, guardType]),
+    SetMetadata('enableRbac', enableRbac),
+    SetMetadata('enableModulePermission', enableModulePermission),
+    UseGuards(AuthGuard),
+    ApiBearerAuth,
+  );
+}

package/template/apps/api/libs/domain/auth/src/decorators/presets.decorator.ts

@@ -0,0 +1,50 @@
+import { applyDecorators } from '@nestjs/common';
+import { Auth } from '../auth';
+import { RequireSuperAdmin } from './rbac.decorator';
+/**
+ * 管理员权限预设
+ *
+ * @param requireSuper 是否要求系统超级管理员（默认 false，只要求团队管理员）
+ *
+ * @example
+ * @AdminAuth() // 团队管理员
+ *
+ * @AdminAuth(true) // 系统超级管理员
+ * async systemSettings() {}
+ */
+export function AdminAuth() {
+  return applyDecorators(Auth('api', 'api'), RequireSuperAdmin());
+}
+/**
+ * 纯认证装饰器（无团队上下文，无权限检查）
+ * 适用于用户个人信息相关接口
+ *
+ * @example
+ * @SimpleAuth()
+ * async getUserProfile() {}
+ */
+export function SimpleAuth() {
+  return Auth('api', 'api', {
+    enableModulePermission: false,
+    enableRbac: false,
+  });
+}
+
+/**
+ * SSE 认证装饰器（无团队上下文，无权限检查）
+ * 适用于 Server-Sent Events 端点
+ *
+ * 注意：SSE 端点因为 EventSource 不支持自定义 headers，
+ * 所以需要从 query 参数获取 access_token
+ *
+ * @example
+ * @SseAuth()
+ * @Sse('message/unread')
+ * async getUnreadMessageCountStream() {}
+ */
+export function SseAuth() {
+  return Auth('api', 'sse', {
+    enableModulePermission: false,
+    enableRbac: false,
+  });
+}

package/template/apps/api/libs/domain/auth/src/decorators/rbac.decorator.ts

@@ -0,0 +1,67 @@
+import { SetMetadata } from '@nestjs/common';
+
+// 超级管理员检查装饰器
+export const RequireSuperAdmin = () => SetMetadata('superAdmin', true);
+
+/**
+ * 细粒度模块权限装饰器
+ */
+export interface ModulePermissionMeta {
+  module: string;
+  resource: string;
+  action: string;
+}
+
+// 模块权限检查装饰器的元数据 key
+export const MODULE_PERMISSION_KEY = 'modulePermission';
+
+/**
+ * 模块权限检查装饰器
+ * 用于细粒度的模块级权限控制
+ *
+ * @example
+ * @RequireModulePermission('recruitment', 'job', 'create')
+ * async createJob() { ... }
+ */
+export const RequireModulePermission = (
+  module: string,
+  resource: string,
+  action: string,
+) =>
+  SetMetadata(MODULE_PERMISSION_KEY, {
+    module,
+    resource,
+    action,
+  } as ModulePermissionMeta);
+
+/**
+ * 多个模块权限检查装饰器（满足任一条件即可）
+ *
+ * @example
+ * ```typescript
+ * @RequireAnyModulePermission([
+ *   { module: 'recruitment', resource: 'job', action: 'read' },
+ *   { module: 'recruitment', resource: 'candidate', action: 'read' },
+ * ])
+ * async viewRecruitmentData() { ... }
+ * ```
+ */
+export const RequireAnyModulePermission = (
+  permissions: ModulePermissionMeta[],
+) => SetMetadata('anyModulePermission', permissions);
+
+/**
+ * 多个模块权限检查装饰器（必须满足所有条件）
+ *
+ * @example
+ * ```typescript
+ * @RequireAllModulePermissions([
+ *   { module: 'recruitment', resource: 'job', action: 'read' },
+ *   { module: 'recruitment', resource: 'candidate', action: 'create' },
+ * ])
+ * async createCandidateForJob() { ... }
+ * ```
+ */
+export const RequireAllModulePermissions = (
+  permissions: ModulePermissionMeta[],
+) => SetMetadata('allModulePermissions', permissions);

package/template/apps/api/libs/domain/auth/src/decorators/resource-owner.decorator.ts

@@ -0,0 +1,67 @@
+import { SetMetadata, UseGuards, applyDecorators } from '@nestjs/common';
+
+export const RESOURCE_OWNER_KEY = 'resource_owner_check';
+
+/**
+ * 资源所有者检查配置
+ */
+export interface ResourceOwnerCheck {
+  resourceType: 'fileSystem';
+  paramSource: 'params' | 'query' | 'body';
+  resourceIdField: string; // 资源 ID 在请求参数中的字段名
+  allowSystemAdmin?: boolean; // 是否允许系统管理员访问（默认 true）
+}
+
+/**
+ * 要求请求者是资源所有者
+ *
+ * @example
+ * // 基础用法 - 会议记录
+ * @RequireResourceOwner({
+ *     resourceType: 'meetingRecord',
+ *     paramSource: 'params',
+ *     resourceIdField: 'id',
+ * })
+ * async deleteMeeting() {}
+ *
+ * @example
+ * // 文件系统（文件/文件夹）
+ * @RequireResourceOwner({
+ *     resourceType: 'fileSystem',
+ *     paramSource: 'params',
+ *     resourceIdField: 'fileId',
+ * })
+ * async deleteFile() {}
+ *
+ * @example
+ * // 只允许所有者
+ * @RequireResourceOwner({
+ *     resourceType: 'candidate',
+ *     paramSource: 'params',
+ *     resourceIdField: 'id',
+ * })
+ * async deleteCandidate() {}
+ *
+ * @example
+ * // 候选人 - 检查上传者
+ * @RequireResourceOwner({
+ *     resourceType: 'candidate',
+ *     paramSource: 'params',
+ *     resourceIdField: 'candidateId',
+ * })
+ * async updateCandidate() {}
+ */
+export const RequireResourceOwner = (
+  check: ResourceOwnerCheck,
+): MethodDecorator => {
+  // 导入 Guard（延迟导入避免循环依赖）
+  const { ResourceOwnerGuard } = require('../guards/resource-owner.guard');
+
+  return applyDecorators(
+    SetMetadata(RESOURCE_OWNER_KEY, {
+      ...check,
+      allowSystemAdmin: check.allowSystemAdmin ?? true,
+    }),
+    UseGuards(ResourceOwnerGuard),
+  );
+};

package/template/apps/api/libs/domain/auth/src/dto/auth.dto.ts

@@ -0,0 +1,10 @@
+export namespace AuthClient {
+  export interface Session {
+    userId: string;
+    access: string;
+    accessExpire: number;
+    refresh: string;
+    expire: number;
+    isAnonymity: boolean;
+  }
+}