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

---

一、统一响应格式

成功响应

{
  "statusCode": 200,
  "errMsg": "操作成功",
  "data": {}
}

失败响应

{
  "statusCode": 400,
  "errMsg": "错误信息",
  "data": {}
}

---

二、系统接口

1. HelloWorld 测试接口

• 接口地址：/test-helloworld
• 请求方式：POST
• 请求头：无特殊要求
• 请求体：可为空 {}

响应示例

{
  "statusCode": 200,
  "errMsg": "请求成功",
  "data": {
    "message": "Hello, World!",
    "timestamp": "2026-03-20T00:00:00.000Z",
    "status": "success"
  }
}

2. 健康检查接口

• 接口地址：/health
• 请求方式：POST
• 请求头：无特殊要求
• 请求体：可为空 {}

响应示例

{
  "statusCode": 200,
  "errMsg": "服务运行正常",
  "data": {
    "status": "healthy",
    "timestamp": "2026-03-20T00:00:00.000Z"
  }
}

---

三、微信小程序接口

1. 登录/注册合一

• 接口地址：/wechat/login
• 请求方式：POST
• 请求头：
  • Content-Type: application/json

请求参数

{
  "users_wx_code": "0a1b2c3d4e5f6g"
}

参数说明

参数名	类型	必填	说明
users_wx_code	string	是	微信小程序登录临时凭证 code，用于换取 openid

处理逻辑

• 使用 users_wx_code 向微信服务端换取 openid
• 如果数据库中不存在该用户，则自动创建新账号：
  • 初始化 users_type = 游客
• 如果数据库中已存在该用户，则直接登录
• 返回：
  • status
  • is_info_complete
  • token
  • 完整用户信息

响应示例

{
  "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>

请求参数

{
  "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 从 游客 升级为 注册用户
• 返回更新后的完整用户信息

响应示例

{
  "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

响应示例

{
  "statusCode": 200,
  "errMsg": "刷新成功",
  "data": {
    "token": "new-jwt-token"
  }
}

---

四、错误码说明

错误码	说明
200	成功
400	请求参数错误
401	请求头缺失、令牌无效或用户身份不匹配
404	用户不存在或路由不存在
415	请求体不是 application/json
429	请求过于频繁
500	服务器内部错误

---

五、调用建议

1. 所有微信写接口都使用 JSON

请求头应设置：

Content-Type: application/json

2. 资料接口与资料详情接口都要带标准 JWT 头

Authorization: Bearer <token>

3. refresh-token 接口当前只需要：

Authorization: Bearer <token>

不需要旧 Authorization。