310 lines
7.5 KiB
Markdown
310 lines
7.5 KiB
Markdown
# API 接口文档
|
||
|
||
## 文档说明
|
||
|
||
本文档描述当前项目中**已经真实实现**并可直接调用的后端接口。
|
||
当前接口统一特征如下：
|
||
|
||
- 基础路径（生产）：`https://bai-api.blv-oa.com/pb/api`
|
||
- 基础路径（本地）：`http://localhost:8090/pb/api`
|
||
- 响应格式：JSON
|
||
- 业务响应结构统一为：`statusCode`、`errMsg`、`data`
|
||
- 当前公开接口统一使用 **POST** 方法
|
||
- 微信写接口统一要求 `Content-Type: application/json`
|
||
|
||
---
|
||
|
||
## 一、统一响应格式
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"statusCode": 200,
|
||
"errMsg": "操作成功",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 失败响应
|
||
|
||
```json
|
||
{
|
||
"statusCode": 400,
|
||
"errMsg": "错误信息",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 二、系统接口
|
||
|
||
### 1. HelloWorld 测试接口
|
||
|
||
- **接口地址**：`/test-helloworld`
|
||
- **请求方式**：`POST`
|
||
- **请求头**：无特殊要求
|
||
- **请求体**：可为空 `{}`
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"statusCode": 200,
|
||
"errMsg": "请求成功",
|
||
"data": {
|
||
"message": "Hello, World!",
|
||
"timestamp": "2026-03-20T00:00:00.000Z",
|
||
"status": "success"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 健康检查接口
|
||
|
||
- **接口地址**：`/health`
|
||
- **请求方式**：`POST`
|
||
- **请求头**：无特殊要求
|
||
- **请求体**：可为空 `{}`
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"statusCode": 200,
|
||
"errMsg": "服务运行正常",
|
||
"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，用于换取 `openid` |
|
||
|
||
### 处理逻辑
|
||
|
||
- 使用 `users_wx_code` 向微信服务端换取 `openid`
|
||
- 如果数据库中不存在该用户，则自动创建新账号：
|
||
- 初始化 `users_type = 游客`
|
||
- 如果数据库中已存在该用户，则直接登录
|
||
- 返回：
|
||
- `status`
|
||
- `is_info_complete`
|
||
- `token`
|
||
- 完整用户信息
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"statusCode": 200,
|
||
"errMsg": "登录成功",
|
||
"data": {
|
||
"status": "login_success",
|
||
"is_info_complete": true,
|
||
"token": "jwt-token",
|
||
"user": {
|
||
"users_id": "U202603190001",
|
||
"users_type": "注册用户",
|
||
"users_name": "张三",
|
||
"users_phone": "13800138000",
|
||
"users_tag": "核心客户",
|
||
"users_phone_masked": "138****8000",
|
||
"users_picture": "ATT-1743123456789-abc123",
|
||
"users_picture_url": "https://bai-api.blv-oa.com/pb/api/files/pbc_xxx/recordId/avatar.png",
|
||
"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`
|
||
- `Authorization: Bearer <token>`
|
||
|
||
### 请求参数
|
||
|
||
```json
|
||
{
|
||
"users_name": "张三",
|
||
"users_phone_code": "2b7d9f2e3c4a5b6d7e8f",
|
||
"users_phone": "13800138000",
|
||
"users_tag": "核心客户",
|
||
"users_picture": "ATT-1743123456789-abc123",
|
||
"users_id_pic_a": "ATT-1743123456789-id-a",
|
||
"users_id_pic_b": "ATT-1743123456789-id-b",
|
||
"users_title_picture": "ATT-1743123456789-title"
|
||
}
|
||
```
|
||
|
||
### 参数说明
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `users_name` | string | 否 | 用户姓名；非空时才更新 |
|
||
| `users_phone_code` | string | 否 | 微信手机号获取凭证 code；若提供，服务端优先据此换取真实手机号 |
|
||
| `users_phone` | string | 否 | 直接写入的手机号；仅在未提供 `users_phone_code` 时生效 |
|
||
| `users_tag` | string | 否 | 用户标签；非空时才更新 |
|
||
| `users_picture` | string | 否 | 用户头像附件的 `attachments_id`；非空时才更新 |
|
||
| `users_id_pic_a` | string | 否 | 证件正面附件的 `attachments_id` |
|
||
| `users_id_pic_b` | string | 否 | 证件反面附件的 `attachments_id` |
|
||
| `users_title_picture` | string | 否 | 资质附件的 `attachments_id` |
|
||
|
||
### 处理逻辑
|
||
|
||
- 从 `Authorization` 对应的 PocketBase auth record 读取当前用户 `openid`
|
||
- 校验 `Authorization`
|
||
- 不再从 body 读取 `users_wx_code`
|
||
- 所有字段均允许不传或传空
|
||
- 若传入 `users_phone_code`，优先调用微信接口换取真实手机号并写入 `users_phone`
|
||
- 若未传 `users_phone_code` 但传入 `users_phone`，则直接写入数据库字段 `users_phone`
|
||
- 未传或传空的字段不会清空数据库中的已有值；只有非空字段才会更新
|
||
- `users_picture`、`users_id_pic_a`、`users_id_pic_b`、`users_title_picture` 均按 `attachments_id` 存储，服务端查询用户信息时会自动补充对应文件流链接
|
||
- 若用户首次从“三项资料均为空”变为“三项资料均完整”，则将 `users_type` 从 `游客` 升级为 `注册用户`
|
||
- 返回更新后的完整用户信息
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"statusCode": 200,
|
||
"errMsg": "信息更新成功",
|
||
"data": {
|
||
"status": "update_success",
|
||
"user": {
|
||
"users_id": "U202603190001",
|
||
"users_type": "注册用户",
|
||
"users_name": "张三",
|
||
"users_phone": "13800138000",
|
||
"users_tag": "核心客户",
|
||
"users_phone_masked": "138****8000",
|
||
"users_picture": "ATT-1743123456789-abc123",
|
||
"users_picture_url": "https://bai-api.blv-oa.com/pb/api/files/pbc_xxx/recordId/avatar.png",
|
||
"users_id_pic_a": "ATT-1743123456789-id-a",
|
||
"users_id_pic_a_url": "https://bai-api.blv-oa.com/pb/api/files/pbc_xxx/recordId/id-a.png",
|
||
"users_id_pic_b": "ATT-1743123456789-id-b",
|
||
"users_id_pic_b_url": "https://bai-api.blv-oa.com/pb/api/files/pbc_xxx/recordId/id-b.png",
|
||
"users_title_picture": "ATT-1743123456789-title",
|
||
"users_title_picture_url": "https://bai-api.blv-oa.com/pb/api/files/pbc_xxx/recordId/title.png",
|
||
"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`
|
||
- **请求头**：
|
||
- `Authorization: Bearer <token>`
|
||
|
||
> 说明：本接口**不要求旧 `Authorization`**。
|
||
|
||
### 请求体
|
||
|
||
- 无 body 参数，可传 `{}` 或空体
|
||
|
||
### 处理逻辑
|
||
|
||
- 仅通过当前 `Authorization` 对应认证用户定位身份
|
||
- 若用户存在，则签发新的 JWT token
|
||
- 若用户不存在，则返回 `404`
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"statusCode": 200,
|
||
"errMsg": "刷新成功",
|
||
"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
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
不需要旧 `Authorization`。
|
||
|
||
|