微信扫码统一账号体系接口设计文档

一、用户体系设计

核心标识

• unionid：同一个微信用户在同一开放平台下唯一，作为用户表主键。
• openid：不同端（小程序、公众号、网页）不一样，用来区分来源。

用户表字段建议

user (
  id bigint pk auto_increment,
  unionid varchar(64) unique not null,
  openid_mp varchar(64),    -- 公众号 openid
  openid_mini varchar(64),  -- 小程序 openid
  openid_web varchar(64),   -- 网页端 openid
  nickname varchar(64),
  avatar varchar(255),
  create_time datetime,
  update_time datetime
)

二、接口定义

1. 小程序端登录

接口地址

POST /api/auth/miniLogin

请求参数

{
  "code": "wx.login返回的code"
}

后台处理逻辑

1. 调用微信 code2session 换取 openid、unionid。
2. 查库： 如果存在 unionid → 返回用户信息。 如果不存在 → 新建用户。

响应示例

{
  "success": true,
  "data": {
    "userId": 1001,
    "unionid": "xxx",
    "token": "jwt-token-xxx"
  }
}

2. 网页端生成扫码登录二维码

接口地址

POST /api/auth/createLoginQRCode

请求参数

{
  "scene": "web_login", 
  "expireSeconds": 300
}

后台处理逻辑

1. 生成 login_token（UUID）。
2. 存入 Redis：login_token → 未确认。
3. 返回二维码地址（可用小程序码 / 普通二维码）。

响应示例

{
  "success": true,
  "data": {
    "loginToken": "uuid-123456",
    "qrcodeUrl": "https://xxx.com/qrcode/uuid-123456.png"
  }
}

3. 小程序扫码确认登录

接口地址

POST /api/auth/scanLoginConfirm

请求参数

{
  "loginToken": "uuid-123456",
  "miniCode": "wx.login code"
}

后台处理逻辑

1. 通过 miniCode 调用 code2session → 获取 unionid。
2. 查库，获取对应用户。
3. 更新 Redis：login_token → 用户ID，状态=已确认。

响应示例

{
  "success": true,
  "message": "确认成功"
}

4. 网页端轮询二维码状态

接口地址

GET /api/auth/checkLoginStatus?loginToken=uuid-123456

响应示例

• 未扫码：

{
  "success": true,
  "data": {
    "status": "pending"
  }
}

• 已扫码确认：

{
  "success": true,
  "data": {
    "status": "confirmed",
    "userId": 1001,
    "token": "jwt-token-xxx"
  }
}

三、业务流程总结

1. 网页端 → 请求 /createLoginQRCode → 获取 login_token + 二维码。
2. 用户打开小程序扫码 → 小程序调用 /scanLoginConfirm 携带 login_token + 用户身份。
3. 后台 → 标记 login_token 已绑定某用户。
4. 网页端 → 调用 /checkLoginStatus 轮询，拿到用户信息 + token，完成登录。