wz-golang-server/docs/WeChatMiniLogin.md

微信小程序登录接口文档

概述

• 接口用于微信小程序登录，前端通过 code 换取 openid/session_key，后端自动创建或更新 t_user 与 t_platform_user。
• 成功后返回用户ID与平台用户ID，供前端后续业务使用。

基础信息

• 方法: POST
• 路径: /api/open/wechat/mini/login
• Content-Type: application/json

请求头

• Content-Type: application/json
• Authorization: 不需要（已加入登录白名单）
• 安全校验（当 security.enable: true 时必须）:
  • X-App-Timestamp: 毫秒时间戳
  • X-App-Sign: MD5(timestamp + secret_key)

请求参数

字段	类型	必填	说明
code	string	是	微信登录 wx.login 返回的 code
phoneCode	string	否	快速手机号登录返回的 phoneCode（优先使用）
encryptedData	string	否	getPhoneNumber 返回的加密数据
iv	string	否	getPhoneNumber 返回的解密向量
nickname	string	否	用户昵称
avatarUrl	string	否	用户头像URL
phone	string	否	手机号（不传或空字符串将写入为 NULL）
gender	int	否	性别：0-未知，1-男，2-女
platformExtra	object	否	平台扩展字段（如城市、语言等）

请求示例

{
  "code": "wx_login_code",
  "phoneCode": "8064f569d035bf3a9b4c7fc223bbbc589bf442c0557e0ae51039031d883668f5",
  "encryptedData": "EZyKBdrHgQoAjgMDPNGXRGOjsPrB8LHcupwFCztA3IBNvbdkrSsk6iU6FqQsrn5TfpMJeTzHJ2l7lg6e+EBqqDXVgVEgQxkTWlxBS6mwUN4NgRI2FanA0wPFAWMZGmn7jKgEJhu8xKGSihcI111Y/mq+3T6gDzjZvkz32MhngL5/wBEjDQbBdBXfvY6FveyV7CinM0j17wE7pbjNIFrExw==",
  "iv": "DMzzMUAx5ke1S8nFItBHSg==",
  "nickname": "张三",
  "avatarUrl": "https://example.com/avatar.png",
  "phone": "13800000000",
  "gender": 1,
  "platformExtra": {
    "city": "Shenzhen",
    "language": "zh_CN"
  }
}

响应参数

字段	类型	说明
userId	int64	用户ID（t_user.id）
platformUserId	int64	平台用户ID（t_platform_user.id）
openid	string	微信 openid
unionid	string	微信 unionid（可能为空）
sessionKey	string	微信 session_key
phone	string	手机号（如成功获取）
token	string	登录令牌（用于鉴权）
isNewPlatform	bool	是否新创建平台用户
isNewUser	bool	是否新创建用户

成功响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "userId": 10001,
    "platformUserId": 20001,
    "openid": "oL1oU5gS6Q...",
    "unionid": "o6_bmasdasds...",
    "sessionKey": "HKq6lZzG2u...",
    "phone": "13800000000",
    "token": "c6f7f1e4-5a3b-4f4e-9d0b-6b3f7b8c5e3a",
    "isNewPlatform": false,
    "isNewUser": false
  }
}

错误响应示例

{
  "code": 400,
  "message": "微信接口错误: 40163 code been used",
  "data": null
}

业务说明

• 首次登录时会创建 t_user 与 t_platform_user。
• 之后登录会更新 platform_session_key、last_login_time，并按需更新 nickname/avatarUrl/gender/phone。
• phoneCode 优先于 encryptedData+iv 用于获取手机号；两者都不提供时不更新手机号。
• 返回 token 可直接用于鉴权（Authorization: Bearer <token>）。
• 若未传 avatarUrl，系统会从 docs/avatar.md 列表中随机取一张作为默认头像。
• 新用户默认密码为 123456（仅在获取到手机号时设置），昵称为手机号格式 138****0000。
• 若 wechat.mini_program.app_id/app_secret 未配置，将返回错误。

配置说明

配置文件中新增：

wechat:
  mini_program:
    app_id: "wx_your_app_id"
    app_secret: "wx_your_app_secret"

相关配置与限制

• 若启用安全校验（security.enable: true），该接口仍需携带签名头。
• 默认未做登录态发放（如需 JWT/Token，可在接口层扩展）。