outsource/HaniBlindBox
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dca7ba7b1c
HaniBlindBox/docs/API迁移详细文档/阶段2-用户认证系统.md
zpc da39817b89 初始化项目
2026-01-02 15:46:56 +08:00

10 KiB
Raw Blame History

阶段2：用户认证系统

阶段概述

时间: 2周
目标: 实现完整的用户认证体系，包括微信小程序登录、手机号验证码登录、JWT Token管理等
优先级: P0 (最高优先级)

详细任务清单

2.1 微信小程序登录 (4天)

任务描述

实现微信小程序授权登录，支持code换取openid和用户信息获取

具体工作

  • 集成微信小程序SDK
  • 实现code换取openid接口
  • 处理unionid绑定逻辑
  • 实现用户注册和登录逻辑
  • 添加防抖锁机制

核心接口实现

微信小程序登录接口
POST /api/v1/auth/wechat/miniprogram
Content-Type: application/json

Request:
{
  "code": "string",           // 微信登录code
  "pid": 0                    // 推荐人ID（可选）
}

Response:
{
  "status": 1,
  "msg": "登录成功",
  "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."  // JWT Token
}

技术实现要点

// 微信小程序服务接口
public interface IWechatMiniProgramService
{
    Task<WechatAuthResult> GetOpenIdAsync(string code);
    Task<WechatUserInfo> GetUserInfoAsync(string accessToken, string openId);
}

// 登录控制器
[ApiController]
[Route("api/v1/auth")]
public class AuthController : ControllerBase
{
    [HttpPost("wechat/miniprogram")]
    public async Task<IActionResult> WechatMiniProgramLogin([FromBody] WechatLoginRequest request)
    {
        // 1. 验证code
        // 2. 获取openid和unionid
        // 3. 查找或创建用户
        // 4. 生成JWT Token
        // 5. 记录登录日志
    }
}

2.2 手机号验证码登录 (3天)

任务描述

实现手机号+验证码登录方式，支持短信验证码发送和验证

具体工作

  • 集成短信服务SDK
  • 实现验证码发送接口
  • 实现验证码验证逻辑
  • 添加验证码防刷机制
  • 实现手机号登录接口

核心接口实现

发送验证码接口
POST /api/v1/auth/sms/send
Content-Type: application/json

Request:
{
  "phone": "13800138000"
}

Response:
{
  "status": 1,
  "msg": "验证码已发送",
  "data": {
    "countdown": 60           // 倒计时秒数
  }
}
手机号登录接口
POST /api/v1/auth/mobile/login
Content-Type: application/json

Request:
{
  "mobile": "13800138000",
  "code": "123456",
  "pid": 0                    // 推荐人ID（可选）
}

Response:
{
  "status": 1,
  "msg": "登录成功",
  "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."  // JWT Token
}

技术实现要点

// 短信服务接口
public interface ISmsService
{
    Task<bool> SendVerificationCodeAsync(string phone);
    Task<bool> VerifyCodeAsync(string phone, string code);
}

// Redis缓存验证码
public class SmsService : ISmsService
{
    public async Task<bool> SendVerificationCodeAsync(string phone)
    {
        var code = GenerateCode();
        var key = $"VerificationCode:{phone}";
        await _redis.SetAsync(key, code, TimeSpan.FromMinutes(5));
        return await SendSmsAsync(phone, code);
    }
}

2.3 JWT Token管理 (2天)

任务描述

实现JWT Token的生成、验证、刷新机制

具体工作

  • 配置JWT认证中间件
  • 实现Token生成逻辑
  • 实现Token验证中间件
  • 添加Token刷新机制
  • 实现用户信息缓存

核心接口实现

Token刷新接口
POST /api/v1/auth/refresh
Authorization: Bearer {token}

Response:
{
  "status": 1,
  "msg": "刷新成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200
  }
}

技术实现要点

// JWT配置
public class JwtSettings
{
    public string SecretKey { get; set; }
    public string Issuer { get; set; }
    public string Audience { get; set; }
    public int ExpirationMinutes { get; set; } = 120;
}

// JWT服务
public interface IJwtService
{
    string GenerateToken(User user);
    ClaimsPrincipal ValidateToken(string token);
    Task<string> RefreshTokenAsync(string token);
}

2.4 用户信息管理 (2天)

任务描述

实现用户基本信息的获取和更新功能

具体工作

  • 实现用户信息获取接口
  • 实现用户信息更新接口
  • 实现头像上传功能
  • 添加用户状态管理

核心接口实现

获取用户信息接口
GET /api/v1/user/profile
Authorization: Bearer {token}

Response:
{
  "status": 1,
  "msg": "请求成功",
  "data": {
    "userinfo": {
      "id": 123,
      "uid": "U123456",
      "nickname": "用户昵称",
      "headimg": "https://example.com/avatar.jpg",
      "mobile": "138****8000",
      "mobile_is": 1,
      "money": "100.00",
      "money2": "50.00",
      "integral": "200.00",
      "score": "300.00",
      "vip": 1,
      "vip_imgurl": "https://example.com/vip.png",
      "coupon": 5,
      "day": 30
    }
  }
}
更新用户信息接口
POST /api/v1/user/profile/update
Authorization: Bearer {token}
Content-Type: application/json

Request:
{
  "nickname": "新昵称",
  "headimg": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Response:
{
  "status": 1,
  "msg": "修改成功"
}

2.5 手机号绑定功能 (2天)

任务描述

实现用户手机号绑定和解绑功能

具体工作

  • 实现手机号绑定接口
  • 处理已有手机号用户合并逻辑
  • 实现绑定验证码验证
  • 添加绑定状态检查

核心接口实现

绑定手机号接口
POST /api/v1/user/bind-mobile
Authorization: Bearer {token}
Content-Type: application/json

Request:
{
  "mobile": "13800138000",
  "code": "123456"
}

Response:
{
  "status": 1,
  "msg": "绑定成功",
  "data": {
    "token": "new_token_if_user_merged"  // 如果用户合并则返回新token
  }
}

2.6 登录记录和统计 (1天)

任务描述

实现用户登录记录和统计功能

具体工作

  • 记录用户登录日志
  • 实现IP地址解析
  • 添加登录统计功能
  • 实现登录记录接口

2.7 账号注销功能 (0.5天)

任务描述

实现用户账号注销功能

具体工作

  • 实现账号注销接口
  • 处理用户数据清理逻辑
  • 添加注销确认机制

核心接口实现

注销账号接口
POST /api/v1/user/logout-account
Authorization: Bearer {token}

Response:
{
  "status": 1,
  "msg": "注销成功"
}

核心接口实现

记录登录接口
POST /api/v1/user/record-login
Authorization: Bearer {token}
Content-Type: application/json

Request:
{
  "device": "miniprogram",
  "device_info": "iPhone 12"
}

Response:
{
  "status": 1,
  "msg": "登录成功",
  "data": {
    "uid": "U123456",
    "nickname": "用户昵称",
    "headimg": "https://example.com/avatar.jpg"
  }
}

数据模型设计

用户表 (Users)

public class User
{
    public int Id { get; set; }
    public string Uid { get; set; }
    public string OpenId { get; set; }
    public string UnionId { get; set; }
    public string GzhOpenId { get; set; }
    public string Nickname { get; set; }
    public string Headimg { get; set; }
    public string Mobile { get; set; }
    public decimal Money { get; set; }
    public decimal Money2 { get; set; }
    public decimal Integral { get; set; }
    public decimal Score { get; set; }
    public int Vip { get; set; }
    public int Pid { get; set; }
    public string ClickId { get; set; }
    public int IsTest { get; set; }
    public DateTime AddTime { get; set; }
    public DateTime? UpdateTime { get; set; }
}

用户账户表 (UserAccounts)

public class UserAccount
{
    public int Id { get; set; }
    public int UserId { get; set; }
    public string AccountToken { get; set; }
    public string TokenNum { get; set; }
    public long TokenTime { get; set; }
    public long LastLoginTime { get; set; }
    public long LastLoginIp { get; set; }
    public string LastLoginIp1 { get; set; }
    public string IpProvince { get; set; }
    public string IpCity { get; set; }
    public string IpAdcode { get; set; }
}

登录日志表 (UserLoginLogs)

public class UserLoginLog
{
    public int Id { get; set; }
    public int UserId { get; set; }
    public string Platform { get; set; }
    public string IpAddress { get; set; }
    public string Location { get; set; }
    public string Device { get; set; }
    public string DeviceInfo { get; set; }
    public DateTime LoginTime { get; set; }
}

验收标准

功能验收

  • 微信小程序登录流程完整可用
  • 手机号验证码登录流程完整可用
  • JWT Token生成和验证正常
  • 用户信息获取和更新正常
  • 手机号绑定功能正常
  • 登录记录功能正常
  • 账号注销功能正常

性能验收

  • 登录接口响应时间 < 500ms
  • 验证码发送成功率 > 95%
  • Token验证响应时间 < 50ms
  • 支持并发登录 > 100 QPS

安全验收

  • 验证码有效期和防刷机制正常
  • JWT Token安全性验证通过
  • 用户信息加密存储
  • 防重放攻击机制有效

风险点和注意事项

技术风险

  1. 微信API调用: 确保微信小程序配置正确
  2. 短信服务: 短信服务商稳定性和到达率
  3. JWT安全: Token密钥管理和过期策略
  4. 并发处理: 登录高并发场景处理

解决方案

  1. 充分测试: 各种登录场景的完整测试
  2. 监控告警: 关键接口的监控和告警
  3. 降级方案: 短信服务异常时的降级处理
  4. 安全审计: 定期进行安全漏洞扫描

下一阶段准备

为阶段3准备的内容

  • 用户权限和角色管理基础
  • 用户等级和VIP系统基础
  • 用户资产管理基础（余额、积分等）
  • 推荐关系管理基础

交接文档

  • 认证系统架构说明
  • JWT Token使用指南
  • 微信集成配置文档
  • 短信服务配置文档

阶段2完成标志: 用户可以通过微信小程序和手机号两种方式正常登录，获取和更新个人信息，系统具备完整的认证和授权能力。