112 lines
3.9 KiB
Markdown
112 lines
3.9 KiB
Markdown
# 微信小程序登录接口文档
|
||
|
||
## 概述
|
||
- 接口用于微信小程序登录，前端通过 `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 | 否 | 平台扩展字段（如城市、语言等） |
|
||
|
||
### 请求示例
|
||
```json
|
||
{
|
||
"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 | 是否新创建用户 |
|
||
|
||
### 成功响应示例
|
||
```json
|
||
{
|
||
"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
|
||
}
|
||
}
|
||
```
|
||
|
||
## 错误响应示例
|
||
```json
|
||
{
|
||
"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` 未配置，将返回错误。
|
||
|
||
## 配置说明
|
||
配置文件中新增：
|
||
```yaml
|
||
wechat:
|
||
mini_program:
|
||
app_id: "wx_your_app_id"
|
||
app_secret: "wx_your_app_secret"
|
||
```
|
||
|
||
## 相关配置与限制
|
||
- 若启用安全校验（`security.enable: true`），该接口仍需携带签名头。
|
||
- 默认未做登录态发放（如需 JWT/Token，可在接口层扩展）。
|