XuJiacheng
72e974672e
新增微信登录/注册合一接口、资料完善接口和token刷新接口 重构用户服务层，支持自动维护用户类型和资料完整度 引入JWT认证中间件和请求验证中间件 更新文档与测试用例，支持dist构建部署
286 lines
5.7 KiB
Markdown
286 lines
5.7 KiB
Markdown
# API 接口文档
|
||
|
||
## 文档说明
|
||
|
||
本文档描述当前项目中**已经真实实现**并可直接调用的后端接口。
|
||
当前接口统一特征如下：
|
||
|
||
- 基础路径（生产）：`https://bai-api.blv-oa.com/api`
|
||
- 基础路径（本地）：`http://localhost:3000/api`
|
||
- 响应格式：JSON
|
||
- 业务响应结构统一为：`code`、`msg`、`data`
|
||
- 当前公开接口统一使用 **POST** 方法
|
||
- 微信写接口统一要求 `Content-Type: application/json`
|
||
|
||
---
|
||
|
||
## 一、统一响应格式
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 失败响应
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"msg": "错误信息",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 二、系统接口
|
||
|
||
### 1. HelloWorld 测试接口
|
||
|
||
- **接口地址**：`/test-helloworld`
|
||
- **请求方式**：`POST`
|
||
- **请求头**：无特殊要求
|
||
- **请求体**：可为空 `{}`
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "请求成功",
|
||
"data": {
|
||
"message": "Hello, World!",
|
||
"timestamp": "2026-03-20T00:00:00.000Z",
|
||
"status": "success"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 健康检查接口
|
||
|
||
- **接口地址**：`/health`
|
||
- **请求方式**：`POST`
|
||
- **请求头**：无特殊要求
|
||
- **请求体**：可为空 `{}`
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "服务运行正常",
|
||
"data": {
|
||
"status": "healthy",
|
||
"timestamp": "2026-03-20T00:00:00.000Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、微信小程序接口
|
||
|
||
## 1. 登录/注册合一
|
||
|
||
- **接口地址**：`/wechat/login`
|
||
- **请求方式**：`POST`
|
||
- **请求头**：
|
||
- `Content-Type: application/json`
|
||
|
||
### 请求参数
|
||
|
||
```json
|
||
{
|
||
"users_wx_code": "0a1b2c3d4e5f6g"
|
||
}
|
||
```
|
||
|
||
### 参数说明
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `users_wx_code` | string | 是 | 微信小程序登录临时凭证 code，用于换取 `users_wx_openid` |
|
||
|
||
### 处理逻辑
|
||
|
||
- 使用 `users_wx_code` 向微信服务端换取 `users_wx_openid`
|
||
- 如果数据库中不存在该用户，则自动创建新账号：
|
||
- 初始化 `users_type = 游客`
|
||
- 如果数据库中已存在该用户，则直接登录
|
||
- 返回：
|
||
- `status`
|
||
- `is_info_complete`
|
||
- `token`
|
||
- 完整用户信息
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "登录成功",
|
||
"data": {
|
||
"status": "login_success",
|
||
"is_info_complete": true,
|
||
"token": "jwt-token",
|
||
"user": {
|
||
"users_id": "U202603190001",
|
||
"users_type": "注册用户",
|
||
"users_name": "张三",
|
||
"users_phone": "13800138000",
|
||
"users_phone_masked": "138****8000",
|
||
"users_picture": "https://example.com/avatar.png",
|
||
"users_wx_openid": "oAbCdEfGh123456789",
|
||
"company_id": "C10001",
|
||
"company": null,
|
||
"pb_id": "abc123xyz",
|
||
"created": "2026-03-20T00:00:00.000Z",
|
||
"updated": "2026-03-20T00:00:00.000Z"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 完善/修改用户资料
|
||
|
||
- **接口地址**：`/wechat/profile`
|
||
- **请求方式**：`POST`
|
||
- **请求头**：
|
||
- `Content-Type: application/json`
|
||
- `users_wx_openid: 微信用户唯一标识`
|
||
- `Authorization: Bearer <token>`
|
||
|
||
### 请求参数
|
||
|
||
```json
|
||
{
|
||
"users_name": "张三",
|
||
"users_phone_code": "2b7d9f2e3c4a5b6d7e8f",
|
||
"users_picture": "https://example.com/avatar.png"
|
||
}
|
||
```
|
||
|
||
### 参数说明
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `users_name` | string | 是 | 用户姓名 |
|
||
| `users_phone_code` | string | 是 | 微信手机号获取凭证 code，后端将据此换取真实手机号 |
|
||
| `users_picture` | string | 是 | 用户头像 URL |
|
||
|
||
### 处理逻辑
|
||
|
||
- 从请求头 `users_wx_openid` 读取当前用户身份
|
||
- 校验 `Authorization`
|
||
- 不再从 body 读取 `users_wx_code`
|
||
- 使用 `users_phone_code` 调微信官方接口换取真实手机号
|
||
- 将真实手机号写入数据库字段 `users_phone`
|
||
- 若用户首次从“三项资料均为空”变为“三项资料均完整”，则将 `users_type` 从 `游客` 升级为 `注册用户`
|
||
- 返回更新后的完整用户信息
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "信息更新成功",
|
||
"data": {
|
||
"status": "update_success",
|
||
"user": {
|
||
"users_id": "U202603190001",
|
||
"users_type": "注册用户",
|
||
"users_name": "张三",
|
||
"users_phone": "13800138000",
|
||
"users_phone_masked": "138****8000",
|
||
"users_picture": "https://example.com/avatar.png",
|
||
"users_wx_openid": "oAbCdEfGh123456789",
|
||
"company_id": "",
|
||
"company": null,
|
||
"pb_id": "abc123xyz",
|
||
"created": "2026-03-20T00:00:00.000Z",
|
||
"updated": "2026-03-20T00:10:00.000Z"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 刷新 token
|
||
|
||
- **接口地址**：`/wechat/refresh-token`
|
||
- **请求方式**：`POST`
|
||
- **请求头**：
|
||
- `users_wx_openid: 微信用户唯一标识`
|
||
|
||
> 说明：本接口**不要求旧 `Authorization`**。
|
||
|
||
### 请求体
|
||
|
||
- 无 body 参数，可传 `{}` 或空体
|
||
|
||
### 处理逻辑
|
||
|
||
- 仅通过请求头中的 `users_wx_openid` 定位用户
|
||
- 若用户存在，则签发新的 JWT token
|
||
- 若用户不存在，则返回 `404`
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "刷新成功",
|
||
"data": {
|
||
"token": "new-jwt-token"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
|---|---|
|
||
| `200` | 成功 |
|
||
| `400` | 请求参数错误 |
|
||
| `401` | 请求头缺失、令牌无效或用户身份不匹配 |
|
||
| `404` | 用户不存在或路由不存在 |
|
||
| `415` | 请求体不是 `application/json` |
|
||
| `429` | 请求过于频繁 |
|
||
| `500` | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 五、调用建议
|
||
|
||
### 1. 所有微信写接口都使用 JSON
|
||
|
||
请求头应设置：
|
||
|
||
```http
|
||
Content-Type: application/json
|
||
```
|
||
|
||
### 2. 资料接口与资料详情接口都要带标准 JWT 头
|
||
|
||
```http
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
### 3. `refresh-token` 接口当前只需要：
|
||
|
||
```http
|
||
users_wx_openid: <openid>
|
||
```
|
||
|
||
不需要旧 `Authorization`。
|