更新记录

1.0.0（2026-06-10） 下载此版本

111

平台兼容性

微信快捷登录绑定手机号联调开发文档

版本：v1.0
日期：2026-06-09
范围：微信小程序快捷登录后，校验是否绑定手机号；未绑定则只允许进入绑定手机号流程。

目标

微信快捷登录成功后，用户必须完成手机号绑定后才能使用账号功能。前端当前会在微信登录拿到 token 后立即调用安全手机查询接口进行校验：

1. POST /user/login/wechat 获取 token。
2. GET /user/secure-phone 校验当前账号是否已有有效手机号。
3. 若未绑定，提示用户去 /pages/login/bind-phone。
4. 未绑定期间，前端只放行查询安全手机、发送绑定验证码、提交绑定手机号这三个接口。
5. 用户在强制绑定页退出且未绑定成功，前端会清空登录态。

数据表依据

手机号不要放在 user 表中判断。当前账号体系中，相关表职责如下：

绑定完成后建议同时满足：

前端当前契约

1. 微信快捷登录

POST /user/login/wechat

请求：

{
  "code": "wx.login 返回的一次性 code"
}

成功响应：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "token": "jwt-token",
    "user": {
      "id": 10001,
      "nickname": "微信用户_123456",
      "avatarUrl": ""
    },
    "isNewUser": false,
    "needBindPhone": true,
    "loginType": "wechat_mp"
  }
}

字段要求：

前端说明：

• 前端会保存 token。
• 前端不会只依赖 needBindPhone，会继续调用 GET /user/secure-phone 做最终校验。
• 如果 GET /user/secure-phone 返回空手机号、非 11 位手机号或接口失败，前端都会进入强制绑定流程。

2. 查询安全手机号

GET /user/secure-phone

请求头：

Authorization: Bearer <token>

已绑定响应：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "phone": "***"
  }
}

未绑定响应：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "phone": ""
  }
}

前端判断：

/^1\d{10}$/.test(data.phone)

只有命中 11 位手机号格式才视为已绑定。

3. 发送绑定手机号验证码

POST /user/sms/send

请求头：

Authorization: Bearer <token>

请求：

{
  "phone": "***",
  "scene": "bind_phone_after_wechat"
}

要求：

• scene = bind_phone_after_wechat 时必须校验登录态。
• 该接口要允许“微信已登录但未绑定手机号”的临时用户调用。
• 验证码建议 5 分钟有效。

4. 绑定手机号

POST /user/phone/bind

请求头：

Authorization: Bearer <token>

请求：

{
  "phone": "***",
  "code": "123456"
}

成功响应：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "phone": "***"
  }
}

绑定成功后后端应写入或确认：

推荐错误码：

后端推荐权限规则

前端已经做了未绑定状态拦截，但后端如果要严格保证“未绑定手机号没有使用权限”，建议在鉴权通过后增加一层手机号绑定校验。

放行接口

未绑定手机号的已登录用户必须能调用：

登录注册、忘记密码等未登录接口继续按现有白名单处理。

拦截逻辑建议

1. AuthenticationInterceptor 校验 JWT，解析 userId。
2. 若请求路径属于绑定手机号放行列表，直接放行。
3. 查询 user_secure_phone 是否存在 user_id = 当前用户 且 is_valid = 1。
4. 若不存在，返回 PHONE_NOT_BOUND：
   code = 1004
   message = 手机号未绑定
   solution = 请先完成手机号绑定
5. 若存在，放行后续业务接口。

注意：

• 不建议通过 user.phone 判断，因为 user 表没有手机号字段。
• 如果要同时要求手机号登录身份存在，可再检查 user_auth_identity 是否存在 identity_type = mobile。
• 为避免每个请求都查库，可以后续考虑 JWT claim 或短期缓存；第一版联调建议先查 user_secure_phone，逻辑更直观。

前端已完成的配合点

联调测试用例

和现有文档的差异

docs/wechat-login-api.md 更偏向微信登录基础接口；本文档补充的是“微信登录后手机号绑定权限”的联调契约。后续如果后端完成强权限拦截，建议把本文档作为验收标准。