Web_BAI_Manage_ApiServer/docs/api.md

API 接口文档

文档说明

本文档描述当前项目中已经真实实现并可直接调用的后端接口。 当前接口统一特征如下：

• 基础路径（生产）：https://bai-api.blv-oa.com/api
• 基础路径（本地）：http://localhost:3000/api
• 响应格式：JSON
• 业务响应结构统一为：code、msg、data
• 当前公开接口统一使用 POST 方法
• 微信写接口统一要求 Content-Type: application/json

---

一、统一响应格式

成功响应

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

失败响应

{
  "code": 400,
  "msg": "错误信息",
  "data": {}
}

---

二、系统接口

1. HelloWorld 测试接口

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

响应示例

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

2. 健康检查接口

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

响应示例

{
  "code": 200,
  "msg": "服务运行正常",
  "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
  • 完整用户信息

响应示例

{
  "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",
      "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_picture": "https://example.com/avatar.png"
}

参数说明

参数名	类型	必填	说明
users_name	string	是	用户姓名
users_phone_code	string	是	微信手机号获取凭证 code，后端将据此换取真实手机号
users_picture	string	是	用户头像 URL

处理逻辑

• 从 Authorization 对应的 PocketBase auth record 读取当前用户 openid
• 校验 Authorization
• 不再从 body 读取 users_wx_code
• 使用 users_phone_code 调微信官方接口换取真实手机号
• 将真实手机号写入数据库字段 users_phone
• 若用户首次从“三项资料均为空”变为“三项资料均完整”，则将 users_type 从 游客 升级为 注册用户
• 返回更新后的完整用户信息

响应示例

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

响应示例

{
  "code": 200,
  "msg": "刷新成功",
  "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。