XuJiacheng
72e974672e
新增微信登录/注册合一接口、资料完善接口和token刷新接口 重构用户服务层，支持自动维护用户类型和资料完整度 引入JWT认证中间件和请求验证中间件 更新文档与测试用例，支持dist构建部署
378 lines
12 KiB
YAML
378 lines
12 KiB
YAML
openapi: 3.1.0
|
||
info:
|
||
title: BAI Management API
|
||
description: BAI 管理系统后端 API 文档
|
||
version: 1.0.0
|
||
servers:
|
||
- url: https://bai-api.blv-oa.com
|
||
description: BAI-api生产环境
|
||
- url: http://localhost:3000
|
||
description: BAI-api本地开发环境
|
||
tags:
|
||
- name: 系统
|
||
description: 基础健康检查接口
|
||
- name: 微信小程序用户
|
||
description: 微信小程序注册、登录与鉴权接口
|
||
components:
|
||
securitySchemes:
|
||
bearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
schemas:
|
||
ApiResponse:
|
||
type: object
|
||
required: [code, msg, data]
|
||
properties:
|
||
code:
|
||
type: integer
|
||
description: 业务状态码
|
||
example: 200
|
||
msg:
|
||
type: string
|
||
description: 响应消息
|
||
example: 操作成功
|
||
data:
|
||
type: object
|
||
description: 响应数据
|
||
additionalProperties: true
|
||
HealthData:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: string
|
||
example: healthy
|
||
timestamp:
|
||
type: string
|
||
format: date-time
|
||
HelloWorldData:
|
||
type: object
|
||
properties:
|
||
message:
|
||
type: string
|
||
example: Hello, World!
|
||
timestamp:
|
||
type: string
|
||
format: date-time
|
||
status:
|
||
type: string
|
||
example: success
|
||
WechatProfileRequest:
|
||
type: object
|
||
required: [users_name, users_phone_code, users_picture]
|
||
properties:
|
||
users_name:
|
||
type: string
|
||
description: 用户姓名
|
||
example: 张三
|
||
users_phone_code:
|
||
type: string
|
||
description: 微信手机号获取凭证 code，由后端换取真实手机号后写入 users_phone
|
||
example: 2b7d9f2e3c4a5b6d7e8f
|
||
users_picture:
|
||
type: string
|
||
description: 用户头像 URL
|
||
example: https://example.com/avatar.png
|
||
WechatAuthRequest:
|
||
type: object
|
||
required: [users_wx_code]
|
||
properties:
|
||
users_wx_code:
|
||
type: string
|
||
description: 微信小程序登录临时凭证 code
|
||
example: 0a1b2c3d4e5f6g
|
||
CompanyInfo:
|
||
type: object
|
||
properties:
|
||
company_id:
|
||
type: string
|
||
example: C10001
|
||
company_name:
|
||
type: string
|
||
example: 示例科技有限公司
|
||
company_type:
|
||
type: string
|
||
example: 科技服务
|
||
company_entity:
|
||
type: string
|
||
example: 李四
|
||
company_usci:
|
||
type: string
|
||
example: 91330100XXXXXXXXXX
|
||
company_nationality:
|
||
type: string
|
||
example: 中国
|
||
company_province:
|
||
type: string
|
||
example: 浙江省
|
||
company_city:
|
||
type: string
|
||
example: 杭州市
|
||
company_postalcode:
|
||
type: string
|
||
example: "310000"
|
||
company_add:
|
||
type: string
|
||
example: 某某大道 100 号
|
||
company_status:
|
||
type: string
|
||
example: 正常
|
||
company_level:
|
||
type: string
|
||
example: A
|
||
company_remark:
|
||
type: string
|
||
example: 重点合作客户
|
||
UserInfo:
|
||
type: object
|
||
properties:
|
||
users_id:
|
||
type: string
|
||
example: U202603190001
|
||
users_type:
|
||
type: string
|
||
description: |
|
||
用户类型。
|
||
- `游客`：仅完成微信新号注册，尚未首次完整补充 `users_name`、`users_phone`、`users_picture`
|
||
- `注册用户`：用户曾从“三项资料均为空”首次补充为“三项资料均完整”
|
||
enum: [游客, 注册用户]
|
||
example: 游客
|
||
users_name:
|
||
type: string
|
||
example: 张三
|
||
users_phone:
|
||
type: string
|
||
example: "13800138000"
|
||
users_phone_masked:
|
||
type: string
|
||
example: "138****8000"
|
||
users_picture:
|
||
type: string
|
||
example: https://example.com/avatar.png
|
||
users_wx_openid:
|
||
type: string
|
||
example: oAbCdEfGh123456789
|
||
company_id:
|
||
type: string
|
||
example: C10001
|
||
company:
|
||
$ref: '#/components/schemas/CompanyInfo'
|
||
pb_id:
|
||
type: string
|
||
description: PocketBase 记录 id
|
||
example: abc123xyz
|
||
created:
|
||
type: string
|
||
format: date-time
|
||
updated:
|
||
type: string
|
||
format: date-time
|
||
WechatProfileResponseData:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: string
|
||
description: 信息编辑状态
|
||
enum: [update_success, update_failed]
|
||
user:
|
||
$ref: '#/components/schemas/UserInfo'
|
||
WechatAuthResponseData:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: string
|
||
description: 登录/注册结果状态
|
||
enum: [register_success, login_success]
|
||
is_info_complete:
|
||
type: boolean
|
||
description: 用户资料是否已完善
|
||
example: true
|
||
token:
|
||
type: string
|
||
description: JWT 令牌
|
||
user:
|
||
$ref: '#/components/schemas/UserInfo'
|
||
paths:
|
||
/api/test-helloworld:
|
||
post:
|
||
tags: [系统]
|
||
summary: Test endpoint
|
||
description: Returns a hello world message
|
||
responses:
|
||
'200':
|
||
description: Successful response
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ApiResponse'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/HelloWorldData'
|
||
/api/health:
|
||
post:
|
||
tags: [系统]
|
||
summary: 健康检查
|
||
description: 检查服务是否正常运行
|
||
responses:
|
||
'200':
|
||
description: 服务状态正常
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ApiResponse'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/HealthData'
|
||
/api/wechat/login:
|
||
post:
|
||
tags: [微信小程序用户]
|
||
summary: 微信小程序登录/注册合一
|
||
description: |
|
||
使用微信小程序临时登录凭证换取 openid。
|
||
若用户不存在，则自动创建新账号并返回完整用户信息；若已存在，则直接登录并返回完整用户信息。
|
||
登录/注册合一接口不处理手机号获取。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- users_wx_code
|
||
properties:
|
||
users_wx_code:
|
||
type: string
|
||
description: 微信小程序登录临时凭证 code
|
||
example: 0a1b2c3d4e5f6g
|
||
responses:
|
||
'200':
|
||
description: 登录或注册成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ApiResponse'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/WechatAuthResponseData'
|
||
'400':
|
||
description: 参数错误
|
||
'415':
|
||
description: 请求体格式错误，仅支持 application/json
|
||
'429':
|
||
description: 重复提交过于频繁
|
||
'500':
|
||
description: 服务端异常
|
||
/api/wechat/profile:
|
||
post:
|
||
tags: [微信小程序用户]
|
||
summary: 微信小程序用户信息编辑
|
||
description: |
|
||
从请求头 `users_wx_openid` 定位用户，不再从 body 中传 `users_wx_code`。
|
||
body 中传入 `users_name`、`users_phone_code`、`users_picture`。
|
||
后端会通过微信 `users_phone_code` 调用官方接口换取真实手机号，再写入 `users_phone`。
|
||
`users_name`、`users_phone_code`、`users_picture` 均为必填项。
|
||
当且仅当用户原先这三项资料全部为空，且本次首次完整补充三项资料时，系统自动将 `users_type` 从 `游客` 更新为 `注册用户`。
|
||
后续资料修改不会再影响已确定的 `users_type`。
|
||
返回更新后的完整用户信息，其中手机号等敏感字段需脱敏处理。
|
||
parameters:
|
||
- in: header
|
||
name: users_wx_openid
|
||
required: true
|
||
schema:
|
||
type: string
|
||
description: 微信用户唯一标识，用于数据库查询
|
||
- in: header
|
||
name: Authorization
|
||
required: true
|
||
schema:
|
||
type: string
|
||
description: 标准 JWT 认证头，格式为 `Bearer <token>`
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- users_name
|
||
- users_phone_code
|
||
- users_picture
|
||
properties:
|
||
users_name:
|
||
type: string
|
||
description: 用户姓名
|
||
example: 张三
|
||
users_phone_code:
|
||
type: string
|
||
description: 微信手机号获取凭证 code
|
||
example: 2b7d9f2e3c4a5b6d7e8f
|
||
users_picture:
|
||
type: string
|
||
description: 用户头像 URL
|
||
example: https://example.com/avatar.png
|
||
responses:
|
||
'200':
|
||
description: 信息更新成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ApiResponse'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/WechatProfileResponseData'
|
||
'400':
|
||
description: 参数错误
|
||
'401':
|
||
description: 请求头缺少 users_wx_openid 或 Authorization，或令牌无效
|
||
'415':
|
||
description: 请求体格式错误，仅支持 application/json
|
||
'404':
|
||
description: 用户不存在
|
||
'500':
|
||
description: 服务端异常
|
||
/api/wechat/refresh-token:
|
||
post:
|
||
tags: [微信小程序用户]
|
||
summary: 微信小程序刷新 token
|
||
description: |
|
||
小程序通过请求头中的 `users_wx_openid` 定位用户，并返回新的 JWT token。
|
||
本接口无 body 参数，请求方法固定为 POST。
|
||
本接口不要求旧 `Authorization`，仅依赖 `users_wx_openid` 识别用户并签发新 token。
|
||
parameters:
|
||
- in: header
|
||
name: users_wx_openid
|
||
required: true
|
||
schema:
|
||
type: string
|
||
description: 微信用户唯一标识，用于数据库查询
|
||
responses:
|
||
'200':
|
||
description: 刷新成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ApiResponse'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
token:
|
||
type: string
|
||
description: 新的 JWT 令牌
|
||
'404':
|
||
description: 未注册用户
|
||
'401':
|
||
description: 请求头缺少 users_wx_openid
|
||
'500':
|
||
description: 服务端异常
|