feat: 添加 PocketBase 管理端与自定义 hooks 的 API 文档

- 新增 openapi.yaml 文件,定义管理端与自定义 hooks 的接口文档,包括系统、微信认证、平台认证、字典管理、附件管理、文档管理、购物车和订单等接口。
- 新增 order.yaml 文件,定义订单相关的接口,包括查询订单列表、查询订单详情、新增订单记录、修改订单记录和删除订单记录的请求和响应结构。
- 新增 openapi-wx/openapi.yaml 文件,定义 PocketBase 原生 API 文档,包含企业信息、附件信息、产品信息、文档信息、购物车和订单的接口。
- 新增 pocketbase.scheme.js 文件,包含 PocketBase 集合的创建和更新逻辑,定义了多个集合的字段、索引和权限规则。
This commit is contained in:
2026-04-08 20:14:22 +08:00
parent e47060f54f
commit 0bdaf54eed
36 changed files with 4391 additions and 2418 deletions

View File

@@ -0,0 +1,372 @@
paths:
cartList:
post:
tags: [购物车]
summary: 查询购物车列表
description: |
调用自定义 hooks API 查询当前登录用户的购物车列表。
请求头请自行携带 `Authorization: Bearer <token>`。
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CartListRequest'
example:
keyword: 模糊搜索关键字|string
cart_status: 购物车状态|string
cart_number: 购物车名称或分组号|string
responses:
'200':
description: 查询成功
content:
application/json:
schema:
$ref: '#/components/schemas/CartListResponse'
'400':
description: 参数错误
'401':
description: token 无效或已过期
'415':
description: 请求体必须为 application/json
'500':
description: 服务端错误
cartDetail:
post:
tags: [购物车]
summary: 查询购物车详情
description: |
调用自定义 hooks API 按 `cart_id` 查询单条购物车记录。
请求头请自行携带 `Authorization: Bearer <token>`。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CartDetailRequest'
example:
cart_id: 购物车业务ID|string
responses:
'200':
description: 查询成功
content:
application/json:
schema:
$ref: '#/components/schemas/CartRecord'
'400':
description: 参数错误
'401':
description: token 无效或已过期
'403':
description: 无权访问该购物车记录
'404':
description: 未找到对应购物车记录
'415':
description: 请求体必须为 application/json
'500':
description: 服务端错误
cartCreate:
post:
tags: [购物车]
summary: 新增购物车记录
description: |
调用自定义 hooks API 新增购物车记录。
服务端会基于当前 token 自动写入 `cart_owner` 并生成 `cart_id`。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CartCreateRequest'
example:
cart_number: 可选;未传时服务端自动生成|string
cart_product_id: tbl_product_list 的 PocketBase recordId|string
cart_product_quantity: 产品数量|integer
cart_status: 购物车状态|string
cart_at_price: 加入购物车时价格|integer
cart_remark: 备注|string
responses:
'200':
description: 创建成功
content:
application/json:
schema:
$ref: '#/components/schemas/CartRecord'
'400':
description: 参数错误或创建失败
'401':
description: token 无效或已过期
'415':
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
'500':
description: 服务端错误
cartUpdate:
post:
tags: [购物车]
summary: 修改购物车记录
description: |
调用自定义 hooks API 按 `cart_id` 更新购物车记录。
请求头请自行携带 `Authorization: Bearer <token>`。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CartUpdateRequest'
example:
cart_id: 购物车业务ID|string
cart_number: 购物车名称或分组号|string
cart_product_id: tbl_product_list 的 PocketBase recordId|string
cart_product_quantity: 产品数量|integer
cart_status: 购物车状态|string
cart_at_price: 加入购物车时价格|integer
cart_remark: 备注|string
responses:
'200':
description: 更新成功
content:
application/json:
schema:
$ref: '#/components/schemas/CartRecord'
'400':
description: 参数错误或更新失败
'401':
description: token 无效或已过期
'403':
description: 无权访问该购物车记录
'404':
description: 未找到待修改记录
'415':
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
'500':
description: 服务端错误
cartDelete:
post:
tags: [购物车]
summary: 删除购物车记录
description: |
调用自定义 hooks API 按 `cart_id` 删除购物车记录。
当前后端实现以实际 hooks 逻辑为准。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CartDeleteRequest'
example:
cart_id: 购物车业务ID|string
responses:
'200':
description: 删除成功
content:
application/json:
schema:
$ref: '#/components/schemas/CartDeleteResponse'
'400':
description: 参数错误或删除失败
'401':
description: token 无效或已过期
'403':
description: 无权访问该购物车记录
'404':
description: 未找到待删除记录
'415':
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
'500':
description: 服务端错误
components:
schemas:
CartRecord:
type: object
properties:
pb_id:
type: string
description: PocketBase记录主键id
created:
type: string
description: PocketBase系统创建时间
updated:
type: string
description: PocketBase系统更新时间
cart_id:
type: string
description: 购物车业务ID
cart_number:
type: string
description: 购物车名称或分组号
cart_create:
type: string
description: 购物车项创建时间
cart_owner:
type: string
description: 购物车所有者openid
cart_product_id:
type: string
description: 关联产品的 PocketBase recordId
cart_product_business_id:
type: string
description: 关联产品的业务 ID即 prod_list_id用于展示
cart_product_quantity:
type: [integer, number]
description: 产品数量
cart_status:
type: string
description: 购物车状态
cart_at_price:
type: [integer, number]
description: 加入购物车时价格
cart_remark:
type: string
description: 备注
is_delete:
type: [integer, number]
description: 删除标记
product_name:
type: string
description: 产品名称
product_modelnumber:
type: string
description: 产品型号
product_basic_price:
type: [integer, number, 'null']
description: 产品基础价格
example:
pb_id: PocketBase记录主键id|string
created: PocketBase系统创建时间|string
updated: PocketBase系统更新时间|string
cart_id: 购物车业务ID|string
cart_number: 购物车名称或分组号|string
cart_create: 购物车项创建时间|string
cart_owner: 购物车所有者openid|string
cart_product_id: tbl_product_list 的 PocketBase recordId|string
cart_product_business_id: 产品业务ID|string
cart_product_quantity: 产品数量|integer
cart_status: 购物车状态|string
cart_at_price: 加入购物车时价格|integer
cart_remark: 备注|string
is_delete: 删除标记|integer
product_name: 产品名称|string
product_modelnumber: 产品型号|string
product_basic_price: 产品基础价格|integer
CartListRequest:
type: object
properties:
keyword:
type: string
description: 模糊搜索关键字
cart_status:
type: string
description: 购物车状态
cart_number:
type: string
description: 购物车名称或分组号
example:
keyword: 模糊搜索关键字|string
cart_status: 购物车状态|string
cart_number: 购物车名称或分组号|string
CartDetailRequest:
type: object
required: [cart_id]
properties:
cart_id:
type: string
description: 购物车业务ID
example:
cart_id: 购物车业务ID|string
CartCreateRequest:
type: object
required: [cart_product_id, cart_product_quantity, cart_at_price]
properties:
cart_number:
type: string
cart_product_id:
type: string
description: tbl_product_list 的 PocketBase recordId
cart_product_quantity:
type: [integer, number]
cart_status:
type: string
cart_at_price:
type: [integer, number]
cart_remark:
type: string
example:
cart_number: 可选;未传时服务端自动生成|string
cart_product_id: tbl_product_list 的 PocketBase recordId|string
cart_product_quantity: 产品数量|integer
cart_status: 购物车状态|string
cart_at_price: 加入购物车时价格|integer
cart_remark: 备注|string
CartUpdateRequest:
type: object
required: [cart_id]
properties:
cart_id:
type: string
cart_number:
type: string
cart_product_id:
type: string
description: tbl_product_list 的 PocketBase recordId
cart_product_quantity:
type: [integer, number]
cart_status:
type: string
cart_at_price:
type: [integer, number]
cart_remark:
type: string
example:
cart_id: 购物车业务ID|string
cart_number: 购物车名称或分组号|string
cart_product_id: tbl_product_list 的 PocketBase recordId|string
cart_product_quantity: 产品数量|integer
cart_status: 购物车状态|string
cart_at_price: 加入购物车时价格|integer
cart_remark: 备注|string
CartDeleteRequest:
type: object
required: [cart_id]
properties:
cart_id:
type: string
example:
cart_id: 购物车业务ID|string
CartListResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/CartRecord'
example:
items:
- pb_id: PocketBase记录主键id|string
created: PocketBase系统创建时间|string
updated: PocketBase系统更新时间|string
cart_id: 购物车业务ID|string
cart_number: 购物车名称或分组号|string
cart_create: 购物车项创建时间|string
cart_owner: 购物车所有者openid|string
cart_product_id: tbl_product_list 的 PocketBase recordId|string
cart_product_business_id: 产品业务ID|string
cart_product_quantity: 产品数量|integer
cart_status: 购物车状态|string
cart_at_price: 加入购物车时价格|integer
cart_remark: 备注|string
CartDeleteResponse:
type: object
properties:
cart_id:
type: string
is_delete:
type: [integer, number]
example:
cart_id: 购物车业务ID|string
is_delete: 删除标记|integer

View File

@@ -0,0 +1,103 @@
openapi: 3.1.0
info:
title: BAI PocketBase Manage Hooks API
version: 1.0.0-manage-folder
description: |
面向管理端与自定义 hooks 的接口文档。
本目录仅收敛自定义 hooks API不包含 PocketBase 原生 records API。
文档约定:
- 不单独配置鉴权组件;如接口需要登录,请直接在说明中关注 `Authorization: Bearer <token>`
- 示例字段值统一使用 `<字段说明>|<类型>` 风格
- 当前 `tbl_auth_users.openid` 为全平台统一身份锚点
servers:
- url: https://bai-api.blv-oa.com
description: 生产环境
- url: http://localhost:8090
description: PocketBase 本地环境
tags:
- name: 系统
description: hooks 系统基础接口
- name: 微信认证
description: hooks 微信认证与资料接口
- name: 平台认证
description: hooks 平台用户认证接口
- name: 字典管理
description: hooks 字典管理接口
- name: 附件管理
description: hooks 附件管理接口
- name: 文档管理
description: hooks 文档管理接口
- name: 文档历史
description: hooks 文档历史接口
- name: 购物车
description: hooks 购物车接口
- name: 订单
description: hooks 订单接口
paths:
/pb/api/system/test-helloworld:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1system~1test-helloworld'
/pb/api/system/health:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1system~1health'
/pb/api/system/users-count:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1system~1users-count'
/pb/api/system/refresh-token:
$ref: '../openapi.yaml#/paths/~1pb~1api~1system~1refresh-token'
/pb/api/wechat/login:
$ref: '../openapi.yaml#/paths/~1pb~1api~1wechat~1login'
/pb/api/wechat/profile:
$ref: '../openapi.yaml#/paths/~1pb~1api~1wechat~1profile'
/pb/api/platform/register:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1platform~1register'
/pb/api/platform/login:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1platform~1login'
/pb/api/dictionary/list:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1dictionary~1list'
/pb/api/dictionary/detail:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1dictionary~1detail'
/pb/api/dictionary/create:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1dictionary~1create'
/pb/api/dictionary/update:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1dictionary~1update'
/pb/api/dictionary/delete:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1dictionary~1delete'
/pb/api/attachment/list:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1attachment~1list'
/pb/api/attachment/detail:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1attachment~1detail'
/pb/api/attachment/upload:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1attachment~1upload'
/pb/api/attachment/delete:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1attachment~1delete'
/pb/api/document/list:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1document~1list'
/pb/api/document/detail:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1document~1detail'
/pb/api/document/create:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1document~1create'
/pb/api/document/update:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1document~1update'
/pb/api/document/delete:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1document~1delete'
/pb/api/document-history/list:
$ref: '../openapi-manage.yaml#/paths/~1pb~1api~1document-history~1list'
/pb/api/cart/list:
$ref: './cart.yaml#/paths/cartList'
/pb/api/cart/detail:
$ref: './cart.yaml#/paths/cartDetail'
/pb/api/cart/create:
$ref: './cart.yaml#/paths/cartCreate'
/pb/api/cart/update:
$ref: './cart.yaml#/paths/cartUpdate'
/pb/api/cart/delete:
$ref: './cart.yaml#/paths/cartDelete'
/pb/api/order/list:
$ref: './order.yaml#/paths/orderList'
/pb/api/order/detail:
$ref: './order.yaml#/paths/orderDetail'
/pb/api/order/create:
$ref: './order.yaml#/paths/orderCreate'
/pb/api/order/update:
$ref: './order.yaml#/paths/orderUpdate'
/pb/api/order/delete:
$ref: './order.yaml#/paths/orderDelete'

View File

@@ -0,0 +1,371 @@
paths:
orderList:
post:
tags: [订单]
summary: 查询订单列表
description: |
调用自定义 hooks API 查询当前登录用户的订单列表。
请求头请自行携带 `Authorization: Bearer <token>`。
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/OrderListRequest'
example:
keyword: 模糊搜索关键字|string
order_status: 订单状态|string
order_source: 订单来源|string
responses:
'200':
description: 查询成功
content:
application/json:
schema:
$ref: '#/components/schemas/OrderListResponse'
'400':
description: 参数错误
'401':
description: token 无效或已过期
'415':
description: 请求体必须为 application/json
'500':
description: 服务端错误
orderDetail:
post:
tags: [订单]
summary: 查询订单详情
description: |
调用自定义 hooks API 按 `order_id` 查询单条订单记录。
请求头请自行携带 `Authorization: Bearer <token>`。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDetailRequest'
example:
order_id: 订单业务ID|string
responses:
'200':
description: 查询成功
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRecord'
'400':
description: 参数错误
'401':
description: token 无效或已过期
'403':
description: 无权访问该订单记录
'404':
description: 未找到对应订单记录
'415':
description: 请求体必须为 application/json
'500':
description: 服务端错误
orderCreate:
post:
tags: [订单]
summary: 新增订单记录
description: |
调用自定义 hooks API 新增订单记录。
服务端会基于当前 token 自动写入 `order_owner` 并生成 `order_id`。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCreateRequest'
example:
order_number: 可选;未传时服务端自动生成|string
order_source: 订单来源|string
order_status: 订单状态|string
order_source_id: 来源关联业务ID|string
order_snap:
字段名|string: 字段值|string
order_amount: 订单金额|integer
order_remark: 备注|string
responses:
'200':
description: 创建成功
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRecord'
'400':
description: 参数错误或创建失败
'401':
description: token 无效或已过期
'415':
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
'500':
description: 服务端错误
orderUpdate:
post:
tags: [订单]
summary: 修改订单记录
description: |
调用自定义 hooks API 按 `order_id` 更新订单记录。
请求头请自行携带 `Authorization: Bearer <token>`。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderUpdateRequest'
example:
order_id: 订单业务ID|string
order_number: 订单编号|string
order_source: 订单来源|string
order_status: 订单状态|string
order_source_id: 来源关联业务ID|string
order_snap:
字段名|string: 字段值|string
order_amount: 订单金额|integer
order_remark: 备注|string
responses:
'200':
description: 更新成功
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRecord'
'400':
description: 参数错误或更新失败
'401':
description: token 无效或已过期
'403':
description: 无权访问该订单记录
'404':
description: 未找到待修改记录
'415':
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
'500':
description: 服务端错误
orderDelete:
post:
tags: [订单]
summary: 删除订单记录
description: |
调用自定义 hooks API 按 `order_id` 删除订单记录。
当前后端实现以实际 hooks 逻辑为准。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDeleteRequest'
example:
order_id: 订单业务ID|string
responses:
'200':
description: 删除成功
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDeleteResponse'
'400':
description: 参数错误或删除失败
'401':
description: token 无效或已过期
'403':
description: 无权访问该订单记录
'404':
description: 未找到待删除记录
'415':
description: 请求体必须为 application/json
'429':
description: 重复请求过于频繁
'500':
description: 服务端错误
components:
schemas:
OrderRecord:
type: object
properties:
pb_id:
type: string
description: PocketBase记录主键id
created:
type: string
description: PocketBase系统创建时间
updated:
type: string
description: PocketBase系统更新时间
order_id:
type: string
description: 订单业务ID
order_number:
type: string
description: 订单编号
order_create:
type: string
description: 订单创建时间
order_owner:
type: string
description: 订单所有者openid
order_source:
type: string
description: 订单来源
order_status:
type: string
description: 订单状态
order_source_id:
type: string
description: 来源关联业务ID
order_snap:
type: object
additionalProperties: true
description: 订单快照
order_amount:
type: [integer, number]
description: 订单金额
order_remark:
type: string
description: 备注
is_delete:
type: [integer, number]
description: 删除标记
example:
pb_id: PocketBase记录主键id|string
created: PocketBase系统创建时间|string
updated: PocketBase系统更新时间|string
order_id: 订单业务ID|string
order_number: 订单编号|string
order_create: 订单创建时间|string
order_owner: 订单所有者openid|string
order_source: 订单来源|string
order_status: 订单状态|string
order_source_id: 来源关联业务ID|string
order_snap:
字段名|string: 字段值|string
order_amount: 订单金额|integer
order_remark: 备注|string
is_delete: 删除标记|integer
OrderListRequest:
type: object
properties:
keyword:
type: string
order_status:
type: string
order_source:
type: string
example:
keyword: 模糊搜索关键字|string
order_status: 订单状态|string
order_source: 订单来源|string
OrderDetailRequest:
type: object
required: [order_id]
properties:
order_id:
type: string
example:
order_id: 订单业务ID|string
OrderCreateRequest:
type: object
required: [order_source, order_source_id, order_snap, order_amount]
properties:
order_number:
type: string
order_source:
type: string
order_status:
type: string
order_source_id:
type: string
order_snap:
type: object
additionalProperties: true
order_amount:
type: [integer, number]
order_remark:
type: string
example:
order_number: 可选;未传时服务端自动生成|string
order_source: 订单来源|string
order_status: 订单状态|string
order_source_id: 来源关联业务ID|string
order_snap:
字段名|string: 字段值|string
order_amount: 订单金额|integer
order_remark: 备注|string
OrderUpdateRequest:
type: object
required: [order_id]
properties:
order_id:
type: string
order_number:
type: string
order_source:
type: string
order_status:
type: string
order_source_id:
type: string
order_snap:
type: object
additionalProperties: true
order_amount:
type: [integer, number]
order_remark:
type: string
example:
order_id: 订单业务ID|string
order_number: 订单编号|string
order_source: 订单来源|string
order_status: 订单状态|string
order_source_id: 来源关联业务ID|string
order_snap:
字段名|string: 字段值|string
order_amount: 订单金额|integer
order_remark: 备注|string
OrderDeleteRequest:
type: object
required: [order_id]
properties:
order_id:
type: string
example:
order_id: 订单业务ID|string
OrderListResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/OrderRecord'
example:
items:
- pb_id: PocketBase记录主键id|string
created: PocketBase系统创建时间|string
updated: PocketBase系统更新时间|string
order_id: 订单业务ID|string
order_number: 订单编号|string
order_create: 订单创建时间|string
order_owner: 订单所有者openid|string
order_source: 订单来源|string
order_status: 订单状态|string
order_source_id: 来源关联业务ID|string
order_snap:
字段名|string: 字段值|string
order_amount: 订单金额|integer
order_remark: 备注|string
OrderDeleteResponse:
type: object
properties:
order_id:
type: string
is_delete:
type: [integer, number]
example:
order_id: 订单业务ID|string
is_delete: 删除标记|integer