Web_BAI_Manage_ApiServer/docs/api.md

# 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`。