flowchart LR
    A[用戶] -->|1. 注冊| B[提交賬號密碼]
    B --> C{驗(yàn)證合法性
（用戶名唯一等）}
    C -->|合法| D[創(chuàng)建用戶記錄
（密碼加密存儲）]
    A -->|2. 登錄| E[提交賬號密碼]
    E --> F{驗(yàn)證賬號密碼
（與數(shù)據(jù)庫比對）}
    F -->|通過| G[生成JWT令牌
（包含用戶ID等信息）]
    A -->|3. 訪問受保護(hù)接口| H[請求頭攜帶JWT]
    H --> I[Passport攔截請求]
    I --> J[JWT策略驗(yàn)證令牌]
    J -->|有效| K[解析用戶信息
（附在req.user）]
    K --> L[接口處理邏輯]
    J -->|無效| M[返回401未授權(quán)]

# 核心依賴：Passport本地策略、JWT策略、Nest集成包、加密
pnpm add @nestjs/passport passport passport-local @nestjs/jwt passport-jwt bcryptjs
# 類型定義（開發(fā)依賴）
pnpm add -D @types/passport-local @types/passport-jwt @types/bcryptjs

// src/auth/auth.controller.ts
import { Controller, Post, Body, HttpException } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { genSalt, hash } from 'bcryptjs';
import { User } from '../users/entities/user.entity'; // 用戶實(shí)體（含id/username/password/role）

@Controller('auth')
export class AuthController {
  constructor(
    @InjectRepository(User) private userRepo: Repository<User>,
  ) {}

  // 注冊接口
  @Post('register')
  async register(
    @Body() dto: { username: string; password: string },
  ) {
    // 1. 驗(yàn)證用戶名是否已存在（防重復(fù)注冊）
    const existUser = await this.userRepo.findOne({
      where: { username: dto.username },
    });
    if (existUser) {
      throw new HttpException('用戶名已存在', 400);
    }

    // 2. 密碼加密（核心！bcrypt自動加鹽，無需手動處理）
    const salt = await genSalt(10); // 生成鹽值（復(fù)雜度10）
    const hashedPassword = await hash(dto.password, salt);

    // 3. 創(chuàng)建用戶記錄（存入數(shù)據(jù)庫，角色默認(rèn)為普通用戶）
    await this.userRepo.save({
      username: dto.username,
      password: hashedPassword, // 存儲加密后的密碼
      role: 'user', // 初始角色（后續(xù)可通過管理員修改）
    });

    return { message: '注冊成功，請登錄' };
  }
}

// src/auth/local.strategy.ts
import { BadRequestException } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { InjectRepository } from '@nestjs/typeorm';
import { compareSync } from 'bcryptjs'; // 密碼比對（bcrypt加密）
import { Strategy } from 'passport-local';
import { Repository } from 'typeorm';
import { User } from '../users/entities/user.entity'; // 用戶實(shí)體

// 繼承PassportStrategy，指定策略類型為local
export class LocalStrategy extends PassportStrategy(Strategy) {
  constructor(
    @InjectRepository(User) private userRepo: Repository<User>,
  ) {
    super({
      usernameField: 'username', // 對應(yīng)請求體中的“用戶名”字段
      passwordField: 'password', // 對應(yīng)請求體中的“密碼”字段
    });
  }

  // 驗(yàn)證邏輯：Passport會自動調(diào)用該方法
  async validate(username: string, password: string) {
    // 1. 根據(jù)用戶名查用戶（需額外查詢密碼，默認(rèn)不返回）
    const user = await this.userRepo
      .createQueryBuilder('user')
      .addSelect('user.password') // 顯式查詢密碼
      .where('user.username = :username', { username })
      .getOne();

    // 2. 校驗(yàn)用戶是否存在、密碼是否匹配
    if (!user || !compareSync(password, user.password)) {
      throw new BadRequestException('用戶名或密碼錯(cuò)誤');
    }

    // 3. 返回用戶信息（后續(xù)會被注入到req.user中）
    return user;
  }
}

// src/auth/auth.module.ts
import { Module } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { JwtModule } from '@nestjs/jwt';
import { PassportModule } from '@nestjs/passport';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from '../users/entities/user.entity';
import { AuthService } from './auth.service';
import { LocalStrategy } from './local.strategy';
import { JwtStrategy } from './jwt.strategy';

// 異步配置JWT（從環(huán)境變量讀取密鑰）
const jwtModule = JwtModule.registerAsync({
  inject: [ConfigService],
  useFactory: (config: ConfigService) => ({
    secret: config.get('JWT_SECRET', 'dev-secret-123'), // 密鑰（生產(chǎn)環(huán)境需復(fù)雜）
    signOptions: { expiresIn: '4h' }, // JWT過期時(shí)間（4小時(shí)）
  }),
});

@Module({
  imports: [
    TypeOrmModule.forFeature([User]), // 導(dǎo)入用戶Repository
    PassportModule,
    jwtModule, // 注冊JWT模塊
  ],
  providers: [AuthService, LocalStrategy, JwtStrategy], // 注入服務(wù)和策略
  exports: [AuthService, JwtModule], // 導(dǎo)出JWT模塊，供其他模塊使用
})
export class AuthModule {}

// src/auth/auth.service.ts
import { Injectable } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import { User } from '../users/entities/user.entity';

@Injectable()
export class AuthService {
  constructor(private jwtService: JwtService) {}

  // 生成JWT（登錄成功后調(diào)用）
  login(user: Partial<User>) {
    // Payload：存儲用戶核心信息（避免敏感數(shù)據(jù)，如密碼）
    const payload = { 
      id: user.id, 
      username: user.username, 
      role: user.role // 角色信息，后續(xù)RBAC權(quán)限控制用
    };
    // 簽名生成JWT令牌
    const token = this.jwtService.sign(payload);
    return { token }; // 返回給客戶端
  }
}

// src/auth/auth.controller.ts
import { Controller, Post, Req, UseGuards } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
import { AuthService } from './auth.service';

@Controller('auth')
export class AuthController {
  constructor(private authService: AuthService) {}

  // 登錄接口：使用local策略驗(yàn)證
  @UseGuards(AuthGuard('local'))
  @Post('login')
  login(@Req() req) {
    // req.user由LocalStrategy的validate方法返回
    return this.authService.login(req.user);
  }
}

// src/auth/jwt.strategy.ts
import { UnauthorizedException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { User } from '../users/entities/user.entity';
import { AuthService } from './auth.service';

export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(
    private config: ConfigService,
    private authService: AuthService,
  ) {
    super({
      // 從請求頭的Authorization: Bearer <JWT>中提取令牌
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      secretOrKey: config.get('JWT_SECRET'), // 用相同密鑰解密
      ignoreExpiration: false, // 不忽略過期（過期則返回401）
    });
  }

  // 驗(yàn)證JWT有效性（解密后調(diào)用）
  async validate(payload: Partial<User>) {
    // 可額外校驗(yàn)用戶狀態(tài)（如是否被禁用）
    const user = await this.authService.findUserById(payload.id);
    if (!user) {
      throw new UnauthorizedException('令牌無效或用戶不存在');
    }
    return user; // 返回用戶信息，注入到req.user
  }
}

// src/auth/jwt-auth.guard.ts
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  // 處理驗(yàn)證結(jié)果
  handleRequest(err: any, user: any) {
    if (err || !user) {
      throw new UnauthorizedException('請先登錄');
    }
    return user;
  }
}

// src/users/users.controller.ts
import { Controller, Get, Req, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '../auth/jwt-auth.guard';

@Controller('users')
export class UsersController {
  // 需登錄才能訪問的接口：獲取當(dāng)前用戶信息
  @UseGuards(JwtAuthGuard)
  @Get('info')
  getUserInfo(@Req() req) {
    // req.user由JwtStrategy的validate方法返回
    return req.user;
  }
}

// src/auth/roles.guard.ts
import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private requiredRoles: string[]) {} // 接收需要的角色列表

  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const user = request.user; // 從req.user中獲取用戶角色（JWT驗(yàn)證后注入）

    // 校驗(yàn)用戶角色是否在允許的列表中
    const hasPermission = this.requiredRoles.some(role => user.role === role);
    if (!hasPermission) {
      throw new ForbiddenException('無權(quán)限訪問，需管理員權(quán)限');
    }
    return true;
  }
}

// 自定義裝飾器：簡化角色配置（如@Roles('admin')）
import { SetMetadata } from '@nestjs/common';
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

// src/admin/admin.controller.ts
import { Controller, Get, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '../auth/jwt-auth.guard';
import { RolesGuard, Roles } from '../auth/roles.guard';

@Controller('admin')
@UseGuards(JwtAuthGuard) // 先驗(yàn)證登錄狀態(tài)
export class AdminController {
  // 僅角色為admin的用戶可訪問：查詢所有用戶（管理員權(quán)限）
  @Get('all-users')
  @Roles('admin') // 指定需要的角色
  @UseGuards(new RolesGuard(['admin'])) // 應(yīng)用角色守衛(wèi)
  getAllUsers() {
    // 業(yè)務(wù)邏輯：查詢數(shù)據(jù)庫所有用戶信息
    return { data: [], message: '所有用戶列表' };
  }
}

// src/auth/auth.service.ts（新增刷新令牌邏輯）
import { InjectRedis } from '@nestjs-modules/ioredis';
import { Redis } from 'ioredis';
import { v4 as uuidv4 } from 'uuid'; // 生成唯一刷新令牌

@Injectable()
export class AuthService {
  // ... 其他代碼 ...

  // 登錄時(shí)生成雙令牌
  async loginWithDoubleToken(user: Partial<User>) {
    // 1. 生成訪問令牌（短有效期）
    const accessToken = this.jwtService.sign(
      { sub: user.id, username: user.username, role: user.role },
      { expiresIn: '30m' },
    );

    // 2. 生成刷新令牌（唯一ID，長有效期）
    const refreshToken = uuidv4();
    const refreshTokenExpire = 7 * 24 * 60 * 60; // 7天（秒）

    // 3. 刷新令牌存儲到Redis（支持主動作廢）
    await this.redis.set(
      `refresh_token:${refreshToken}`,
      user.id,
      'EX',
      refreshTokenExpire,
    );

    return {
      accessToken,
      refreshToken,
      expiresIn: 30 * 60, // 訪問令牌有效期（秒）
    };
  }

  // 刷新訪問令牌
  async refreshToken(refreshToken: string) {
    // 1. 驗(yàn)證刷新令牌是否存在于Redis
    const userId = await this.redis.get(`refresh_token:${refreshToken}`);
    if (!userId) {
      throw new UnauthorizedException('刷新令牌無效或已過期');
    }

    // 2. 查詢用戶信息
    const user = await this.findUserById(Number(userId));
    if (!user) {
      throw new UnauthorizedException('用戶不存在');
    }

    // 3. 生成新的訪問令牌
    const newAccessToken = this.jwtService.sign(
      { sub: user.id, username: user.username, role: user.role },
      { expiresIn: '30m' },
    );

    return { accessToken: newAccessToken, expiresIn: 30 * 60 };
  }

  // 登出：刪除Redis中的刷新令牌（主動作廢）
  async logout(refreshToken: string) {
    await this.redis.del(`refresh_token:${refreshToken}`);
    return { message: '登出成功' };
  }
}