微信掃碼統(tǒng)一賬號體系接口設(shè)計文檔

一、用戶體系設(shè)計

核心標(biāo)識

• unionid：同一個微信用戶在同一開放平臺下唯一，作為用戶表主鍵。
• openid：不同端（小程序、公眾號、網(wǎng)頁）不一樣，用來區(qū)分來源。

用戶表字段建議

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),   -- 網(wǎng)頁端 openid
  nickname varchar(64),
  avatar varchar(255),
  create_time datetime,
  update_time datetime
)

二、接口定義

1. 小程序端登錄

接口地址

POST /api/auth/miniLogin

請求參數(shù)

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

后臺處理邏輯

1. 調(diào)用微信 code2session 換取 openid、unionid。
2. 查庫： 如果存在 unionid → 返回用戶信息。 如果不存在 → 新建用戶。

響應(yīng)示例

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

2. 網(wǎng)頁端生成掃碼登錄二維碼

接口地址

POST /api/auth/createLoginQRCode

請求參數(shù)

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

后臺處理邏輯

1. 生成 login_token（UUID）。
2. 存入 Redis：login_token → 未確認(rèn)。
3. 返回二維碼地址（可用小程序碼 / 普通二維碼）。

響應(yīng)示例

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

3. 小程序掃碼確認(rèn)登錄

接口地址

POST /api/auth/scanLoginConfirm

請求參數(shù)

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

后臺處理邏輯

1. 通過 miniCode 調(diào)用 code2session → 獲取 unionid。
2. 查庫，獲取對應(yīng)用戶。
3. 更新 Redis：login_token → 用戶ID，狀態(tài)=已確認(rèn)。

響應(yīng)示例

{
  "success": true,
  "message": "確認(rèn)成功"
}

4. 網(wǎng)頁端輪詢二維碼狀態(tài)

接口地址

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

響應(yīng)示例

• 未掃碼：

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

• 已掃碼確認(rèn)：

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

三、業(yè)務(wù)流程總結(jié)

1. 網(wǎng)頁端 → 請求 /createLoginQRCode → 獲取 login_token + 二維碼。
2. 用戶打開小程序掃碼 → 小程序調(diào)用 /scanLoginConfirm 攜帶 login_token + 用戶身份。
3. 后臺 → 標(biāo)記 login_token 已綁定某用戶。
4. 網(wǎng)頁端 → 調(diào)用 /checkLoginStatus 輪詢，拿到用戶信息 + token，完成登錄。