feat: 实现微信小程序后端接口与用户认证系统
新增微信登录/注册合一接口、资料完善接口和token刷新接口 重构用户服务层，支持自动维护用户类型和资料完整度 引入JWT认证中间件和请求验证中间件 更新文档与测试用例，支持dist构建部署
This commit is contained in:
377
back-end/dist/spec/openapi.yaml
vendored
Normal file
377
back-end/dist/spec/openapi.yaml
vendored
Normal file
@@ -0,0 +1,377 @@
|
||||
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: 服务端异常
|
||||
Reference in New Issue
Block a user