feat(player): 玩家端短信找回密码

支持手机号验证码重置密码，重置成功后跳转登录页；SMS 增加 reset_password 场景与 purpose 隔离。

Co-authored-by: Cursor <cursoragent@cursor.com>

apps/api/src/domains/identity/auth.controller.ts

@@ -1,12 +1,14 @@
-import { Controller, Get, Post, Delete, Body, UseGuards, Query, Param } from '@nestjs/common';
+import { Controller, Get, Post, Delete, Body, UseGuards, Query, Param, Req } from '@nestjs/common';
+import type { Request } from 'express';
 import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { AuthService } from './auth.service';
 import { InvitesService } from './invites.service';
 import { SystemConfigService } from '../../shared/config/system-config.service';
-import { LoginDto, ChangePasswordDto, RegisterDto, GenerateInviteDto } from './auth.dto';
+import { LoginDto, ChangePasswordDto, RegisterDto, GenerateInviteDto, ForgotPasswordDto } from './auth.dto';
 import { Public, CurrentUser } from '../../shared/common/decorators';
 import { JwtAuthGuard } from './guards';
 import { jsonResponse } from '../../shared/common/filters';
+import { getClientIp } from '../../shared/common/client-ip.util';
 
 @ApiTags('Auth')
 @Controller()
@@ -45,6 +47,20 @@ export class AuthController {
     return jsonResponse(result);
   }
 
+  @Public()
+  @Post('player/auth/forgot-password')
+  async playerForgotPassword(@Body() dto: ForgotPasswordDto, @Req() req: Request) {
+    const result = await this.auth.resetPasswordByPhone({
+      phone: dto.phone,
+      countryCode: dto.countryCode,
+      smsCode: dto.smsCode,
+      sessionId: dto.sessionId,
+      newPassword: dto.newPassword,
+      ipAddress: getClientIp(req),
+    });
+    return jsonResponse(result);
+  }
+
   @UseGuards(JwtAuthGuard)
   @ApiBearerAuth()
   @Get('manage/invite')

apps/api/src/domains/identity/auth.dto.ts

@@ -66,6 +66,29 @@ export class ChangePasswordDto {
   newPassword!: string;
 }
 
+export class ForgotPasswordDto {
+  @ApiProperty({ description: '本地手机号，不含国家区号' })
+  @IsString()
+  phone!: string;
+
+  @ApiProperty({ description: '国家区号，不含 +，如 86' })
+  @IsString()
+  countryCode!: string;
+
+  @ApiProperty({ description: '短信验证码' })
+  @IsString()
+  smsCode!: string;
+
+  @ApiProperty({ description: '发送验证码返回的 sessionId' })
+  @IsString()
+  sessionId!: string;
+
+  @ApiProperty()
+  @IsString()
+  @MinLength(8)
+  newPassword!: string;
+}
+
 export class GenerateInviteDto {
   @ApiProperty({ required: false, description: 'Decimal cashback rate, e.g. 0.01 = 1%. Admin only.' })
   @IsOptional()

apps/api/src/domains/identity/auth.service.ts

@@ -9,6 +9,7 @@ import { PrismaService } from '../../shared/prisma/prisma.service';
 import { SystemConfigService } from '../../shared/config/system-config.service';
 import { InvitesService } from './invites.service';
 import { SmsService } from './sms/sms.service';
+import { AuditService } from '../operations/audit/audit.service';
 import { normalizePhone, resolvePlayerLoginCandidates, stripLocalPhoneDigits } from './sms/phone.util';
 
 const MAX_LOGIN_FAILS = 5;
@@ -30,6 +31,7 @@ export class AuthService {
     private systemConfig: SystemConfigService,
     private invites: InvitesService,
     private sms: SmsService,
+    private audit: AuditService,
   ) {}
 
   /** 平台管理员 / 代理统一登录（按 userType 签发对应 JWT） */
@@ -227,6 +229,7 @@ export class AuthService {
       countryCode: data.countryCode,
       code: data.smsCode.trim(),
       sessionId: data.sessionId.trim(),
+      expectedPurpose: 'register',
     });
 
     const { parentId, sponsorId, inviteId } = await this.resolveInviteSponsor(data.inviteCode);
@@ -362,6 +365,83 @@ export class AuthService {
     return { success: true };
   }
 
+  async resetPasswordByPhone(data: {
+    phone: string;
+    countryCode: string;
+    smsCode: string;
+    sessionId: string;
+    newPassword: string;
+    ipAddress?: string;
+  }) {
+    const settings = await this.systemConfig.getPlayerAccountSettings();
+    if (!settings.allowPasswordChange) {
+      throw appForbidden('PASSWORD_CHANGE_DISABLED');
+    }
+
+    if (!data.newPassword || data.newPassword.length < 8) {
+      throw appBadRequest('PASSWORD_MIN_LENGTH');
+    }
+    if (!data.smsCode?.trim() || !data.sessionId?.trim()) {
+      throw appBadRequest('SMS_CODE_REQUIRED');
+    }
+
+    await this.sms.verifyCode({
+      phone: data.phone,
+      countryCode: data.countryCode,
+      code: data.smsCode.trim(),
+      sessionId: data.sessionId.trim(),
+      expectedPurpose: 'reset_password',
+    });
+
+    const player = await this.findPlayerByPhone(data.countryCode, data.phone);
+    if (!player) {
+      throw appBadRequest('PHONE_NOT_REGISTERED');
+    }
+    if (player.status === 'DISABLED') {
+      throw appForbidden('ACCOUNT_DISABLED');
+    }
+
+    const hash = await this.hashPassword(data.newPassword);
+    await this.prisma.userAuth.update({
+      where: { userId: player.id },
+      data: {
+        passwordHash: hash,
+        loginFailCount: 0,
+        lockedUntil: null,
+      },
+    });
+    await this.prisma.userPreference.updateMany({
+      where: { userId: player.id },
+      data: { managedPassword: null },
+    });
+
+    await this.audit.log({
+      operatorId: player.id,
+      operatorType: 'PLAYER',
+      action: 'FORGOT_PASSWORD_RESET',
+      module: 'identity',
+      targetType: 'user',
+      targetId: player.id.toString(),
+      ipAddress: data.ipAddress,
+    });
+
+    return { success: true };
+  }
+
+  private async findPlayerByPhone(countryCode: string, phone: string) {
+    const dial = countryCode.replace(/\D/g, '');
+    const phoneLocal = stripLocalPhoneDigits(phone);
+    const pref = await this.prisma.userPreference.findFirst({
+      where: {
+        phoneCountryDial: dial,
+        phoneLocal,
+        user: { deletedAt: null, userType: 'PLAYER' },
+      },
+      select: { user: { select: { id: true, status: true } } },
+    });
+    return pref?.user ?? null;
+  }
+
   async hashPassword(password: string): Promise<string> {
     return bcrypt.hash(password, 10);
   }

apps/api/src/domains/identity/sms/sms.controller.ts

@@ -20,6 +20,7 @@ export class SmsController {
       countryCode: dto.countryCode.trim(),
       locale: dto.locale,
       clientIp: getClientIp(req),
+      purpose: dto.purpose,
     });
     return jsonResponse(result);
   }

apps/api/src/domains/identity/sms/sms.dto.ts

@@ -1,5 +1,6 @@
-import { IsString, IsOptional } from 'class-validator';
+import { IsString, IsOptional, IsIn } from 'class-validator';
 import { ApiProperty } from '@nestjs/swagger';
+import type { SmsPurpose } from './sms.types';
 
 export class SendSmsCodeDto {
   @ApiProperty({ example: '13800138000', description: '本地手机号，不含国家区号' })
@@ -14,6 +15,11 @@ export class SendSmsCodeDto {
   @IsOptional()
   @IsString()
   locale?: string;
+
+  @ApiProperty({ required: false, enum: ['register', 'reset_password'] })
+  @IsOptional()
+  @IsIn(['register', 'reset_password'])
+  purpose?: SmsPurpose;
 }
 
 export class VerifySmsCodeDto {

apps/api/src/domains/identity/sms/sms.service.ts

@@ -3,13 +3,15 @@ import { ConfigService } from '@nestjs/config';
 import { randomUUID } from 'node:crypto';
 import { normalizeLocale } from '@thebet365/shared';
 import { RedisService } from '../../../shared/redis/redis.service';
-import { appBadRequest, appTooManyRequests } from '../../../shared/common/app-error';
+import { PrismaService } from '../../../shared/prisma/prisma.service';
+import { SystemConfigService } from '../../../shared/config/system-config.service';
+import { appBadRequest, appForbidden, appTooManyRequests } from '../../../shared/common/app-error';
 import { ChuanglanClient } from './chuanglan/client';
 import { loadSmsBusinessConfig } from './chuanglan/config';
 import { generateSixDigitCode } from './code';
-import { normalizePhone } from './phone.util';
-import { renderVerifySms } from './templates';
-import type { SmsLang } from './sms.types';
+import { normalizePhone, stripLocalPhoneDigits } from './phone.util';
+import { renderResetPasswordSms, renderVerifySms } from './templates';
+import type { SmsLang, SmsPurpose } from './sms.types';
 
 const codeKey = (sessionId: string) => `sms:code:${sessionId}`;
 const phoneRateKey = (phone: string) => `sms:rate:phone:${phone}`;
@@ -29,6 +31,8 @@ export class SmsService {
   constructor(
     private redis: RedisService,
     private chuanglan: ChuanglanClient,
+    private prisma: PrismaService,
+    private systemConfig: SystemConfigService,
     config: ConfigService,
   ) {
     this.smsCfg = loadSmsBusinessConfig(config);
@@ -39,9 +43,15 @@ export class SmsService {
     countryCode: string;
     locale?: string;
     clientIp: string;
+    purpose?: SmsPurpose;
   }): Promise<{ sessionId: string }> {
+    const purpose: SmsPurpose = params.purpose ?? 'register';
     const phone = normalizePhone(params.countryCode, params.phone);
 
+    if (purpose === 'reset_password') {
+      await this.assertPlayerCanResetPassword(params.countryCode, params.phone);
+    }
+
     const [phoneLimited, ipLimited] = await Promise.all([
       this.redis.exists(phoneRateKey(phone)),
       this.redis.exists(ipRateKey(params.clientIp)),
@@ -53,7 +63,10 @@ export class SmsService {
     const code = generateSixDigitCode();
     const sessionId = randomUUID();
     const lang = mapLocaleToSmsLang(params.locale);
-    const msg = renderVerifySms(lang, code);
+    const msg =
+      purpose === 'reset_password'
+        ? renderResetPasswordSms(lang, code)
+        : renderVerifySms(lang, code);
 
     const result = await this.chuanglan.sendSms(phone, msg, sessionId);
     if (!result.success) {
@@ -63,7 +76,7 @@ export class SmsService {
     await Promise.all([
       this.redis.set(
         codeKey(sessionId),
-        JSON.stringify({ phone, code }),
+        JSON.stringify({ phone, code, purpose }),
         this.smsCfg.codeTtlSeconds,
       ),
       this.redis.set(phoneRateKey(phone), '1', this.smsCfg.rateLimitSeconds),
@@ -78,6 +91,7 @@ export class SmsService {
     countryCode: string;
     code: string;
     sessionId: string;
+    expectedPurpose?: SmsPurpose;
   }): Promise<void> {
     const phone = normalizePhone(params.countryCode, params.phone);
     const raw = await this.redis.get(codeKey(params.sessionId));
@@ -85,11 +99,43 @@ export class SmsService {
       throw appBadRequest('SMS_CODE_EXPIRED');
     }
 
-    const cached = JSON.parse(raw) as { phone: string; code: string };
+    const cached = JSON.parse(raw) as { phone: string; code: string; purpose?: SmsPurpose };
+    const cachedPurpose: SmsPurpose = cached.purpose ?? 'register';
+    const expectedPurpose = params.expectedPurpose ?? 'register';
+
+    if (cachedPurpose !== expectedPurpose) {
+      throw appBadRequest('SMS_CODE_INVALID');
+    }
     if (cached.phone !== phone || cached.code !== params.code.trim()) {
       throw appBadRequest('SMS_CODE_INVALID');
     }
 
     await this.redis.del(codeKey(params.sessionId));
   }
+
+  private async assertPlayerCanResetPassword(countryCode: string, phone: string): Promise<void> {
+    const dial = countryCode.replace(/\D/g, '');
+    const phoneLocal = stripLocalPhoneDigits(phone);
+
+    const pref = await this.prisma.userPreference.findFirst({
+      where: {
+        phoneCountryDial: dial,
+        phoneLocal,
+        user: { deletedAt: null, userType: 'PLAYER' },
+      },
+      include: { user: { select: { status: true } } },
+    });
+
+    if (!pref) {
+      throw appBadRequest('PHONE_NOT_REGISTERED');
+    }
+    if (pref.user.status === 'DISABLED') {
+      throw appForbidden('ACCOUNT_DISABLED');
+    }
+
+    const settings = await this.systemConfig.getPlayerAccountSettings();
+    if (!settings.allowPasswordChange) {
+      throw appForbidden('PASSWORD_CHANGE_DISABLED');
+    }
+  }
 }

apps/api/src/domains/identity/sms/sms.types.ts

@@ -1,5 +1,7 @@
 export type SmsLang = 'zh' | 'en' | 'vi' | 'ms' | 'kh';
 
+export type SmsPurpose = 'register' | 'reset_password';
+
 export interface ChuanglanSendResponse {
   code: string;
   message: string;

apps/api/src/domains/identity/sms/templates.ts

@@ -14,3 +14,18 @@ export function renderVerifySms(lang: SmsLang | undefined, code: string): string
   const tpl = TEMPLATES[key] ?? TEMPLATES.default ?? TEMPLATES.zh;
   return tpl.replace('{code}', code);
 }
+
+const RESET_TEMPLATES: Record<string, string> = {
+  default: '您正在重置密码，验证码：{code}。5分钟内有效，请勿泄露。',
+  zh: '您正在重置密码，验证码：{code}。5分钟内有效，请勿泄露。',
+  en: 'Password reset code: {code}. Valid for 5 minutes. Do not share.',
+  vi: 'Mã đặt lại mật khẩu: {code}. Có hiệu lực trong 5 phút.',
+  ms: 'Kod tetapan semula kata laluan: {code}. Sah selama 5 minit.',
+  kh: 'កូដកំណត់ពាក្យសម្ងាត់ឡើងវិញ៖ {code} ។ មានសុពលភាព ៥ នាទី។',
+};
+
+export function renderResetPasswordSms(lang: SmsLang | undefined, code: string): string {
+  const key = lang?.trim() || 'zh';
+  const tpl = RESET_TEMPLATES[key] ?? RESET_TEMPLATES.default ?? RESET_TEMPLATES.zh;
+  return tpl.replace('{code}', code);
+}