# 微信小程序登录接口文档

## 概述
- 接口用于微信小程序登录，前端通过 `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>`）。
- 若 `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，可在接口层扩展）。