555 lines
18 KiB
YAML
555 lines
18 KiB
YAML
openapi: 3.1.0
|
||
info:
|
||
title: BAI PocketBase Native API - Cart
|
||
version: 1.0.0
|
||
description: |
|
||
PocketBase 原生 `tbl_cart` records API 文档。
|
||
本文件可单独导入使用，不依赖其他 YAML。
|
||
servers:
|
||
- url: https://bai-api.blv-oa.com
|
||
description: 生产环境
|
||
- url: http://localhost:8090
|
||
description: PocketBase 本地环境
|
||
tags:
|
||
- name: 购物车
|
||
description: PocketBase 原生购物车记录接口
|
||
paths:
|
||
/pb/api/collections/tbl_cart/records:
|
||
get:
|
||
operationId: getPocketBaseCartRecords
|
||
tags: [购物车]
|
||
summary: 查询购物车记录列表
|
||
description: |
|
||
使用 PocketBase 原生 records list 接口查询 `tbl_cart`。
|
||
|
||
说明：
|
||
- `cart_product_id` 是 relation 字段，默认仅返回关联记录 id。
|
||
- 如需同时返回 `tbl_product_list` 详情，请传 `expand=cart_product_id`。
|
||
parameters:
|
||
- name: filter
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
description: PocketBase 原生过滤表达式
|
||
example: 过滤表达式|string
|
||
- name: page
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
default: 1
|
||
- name: perPage
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
default: 20
|
||
- name: sort
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
example: 排序表达式|string
|
||
- name: expand
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
description: 关系字段展开；传 `cart_product_id` 时返回 `expand.cart_product_id`
|
||
example: 关联展开字段|string
|
||
responses:
|
||
'200':
|
||
description: 查询成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseCartListResponse'
|
||
'400':
|
||
description: 查询参数错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'401':
|
||
description: token 无效或已过期
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'403':
|
||
description: 无权访问
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'500':
|
||
description: 服务端错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
post:
|
||
operationId: postPocketBaseCartRecord
|
||
tags: [购物车]
|
||
summary: 创建购物车记录
|
||
description: |
|
||
使用 PocketBase 原生 records create 接口向 `tbl_cart` 新增记录。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseCartCreateRequest'
|
||
example:
|
||
cart_id: 购物车业务ID|string
|
||
cart_number: 购物车名称或分组号|string
|
||
cart_owner: 购物车所有者openid|string
|
||
cart_product_id: 产品业务ID|string
|
||
cart_product_quantity: 产品数量|integer
|
||
cart_status: 购物车状态|string
|
||
cart_at_price: 加入购物车时价格|number
|
||
cart_remark: 备注|string
|
||
responses:
|
||
'200':
|
||
description: 创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseCartRecord'
|
||
'400':
|
||
description: 参数错误或违反集合规则
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'401':
|
||
description: token 无效或已过期
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'403':
|
||
description: 无权访问
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'500':
|
||
description: 服务端错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
/pb/api/collections/tbl_cart/records/{recordId}:
|
||
patch:
|
||
operationId: patchPocketBaseCartRecordByRecordId
|
||
tags: [购物车]
|
||
summary: 更新购物车记录
|
||
parameters:
|
||
- name: recordId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
example: PocketBase记录主键|string
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseCartUpdateRequest'
|
||
example:
|
||
cart_number: 购物车名称或分组号|string
|
||
cart_owner: 购物车所有者openid|string
|
||
cart_product_id: 产品业务ID|string
|
||
cart_product_quantity: 产品数量|integer
|
||
cart_status: 购物车状态|string
|
||
cart_at_price: 加入购物车时价格|number
|
||
cart_remark: 备注|string
|
||
responses:
|
||
'200':
|
||
description: 更新成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseCartRecord'
|
||
'400':
|
||
description: 参数错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'401':
|
||
description: token 无效或已过期
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'404':
|
||
description: 记录不存在
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'500':
|
||
description: 服务端错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
delete:
|
||
operationId: deletePocketBaseCartRecordByRecordId
|
||
tags: [购物车]
|
||
summary: 删除购物车记录
|
||
parameters:
|
||
- name: recordId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
example: PocketBase记录主键|string
|
||
responses:
|
||
'204':
|
||
description: 删除成功
|
||
'401':
|
||
description: token 无效或已过期
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'404':
|
||
description: 记录不存在
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'500':
|
||
description: 服务端错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
/pb/api/batch:
|
||
post:
|
||
operationId: postPocketBaseCartBatchUpdate
|
||
tags: [购物车]
|
||
summary: 批量更新购物车记录
|
||
description: |
|
||
使用 PocketBase 原生 batch 接口批量更新 `tbl_cart` 记录。
|
||
|
||
说明：
|
||
- 这是 PocketBase 原生批处理接口，不是 hooks。
|
||
- 单次请求可提交多条 `PATCH /api/collections/tbl_cart/records/{recordId}` 子请求。
|
||
- 每条子请求仍按原生 collection rule 校验权限。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseCartBatchRequest'
|
||
example:
|
||
requests:
|
||
- method: PATCH|string
|
||
url: /api/collections/tbl_cart/records/PocketBase记录主键|string
|
||
headers:
|
||
Content-Type: application/json|string
|
||
body:
|
||
cart_number: 购物车名称或分组号|string
|
||
cart_product_quantity: 产品数量|integer
|
||
cart_status: 购物车状态|string
|
||
cart_at_price: 加入购物车时价格|number
|
||
cart_remark: 备注|string
|
||
- method: PATCH|string
|
||
url: /api/collections/tbl_cart/records/PocketBase记录主键|string
|
||
headers:
|
||
Content-Type: application/json|string
|
||
body:
|
||
cart_status: 购物车状态|string
|
||
cart_remark: 备注|string
|
||
responses:
|
||
'200':
|
||
description: 批量处理成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseBatchResponse'
|
||
'400':
|
||
description: 批处理参数错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'401':
|
||
description: token 无效或已过期
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'403':
|
||
description: 无权访问其中一条或多条记录
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
'500':
|
||
description: 服务端错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PocketBaseNativeError'
|
||
components:
|
||
schemas:
|
||
PocketBaseNativeError:
|
||
type: object
|
||
properties:
|
||
code:
|
||
type: [integer, string]
|
||
description: PocketBase错误码
|
||
message:
|
||
type: string
|
||
description: PocketBase错误信息
|
||
data:
|
||
type: object
|
||
additionalProperties: true
|
||
description: PocketBase错误数据
|
||
example:
|
||
code: 错误状态码|integer
|
||
message: PocketBase原生错误信息|string
|
||
data:
|
||
字段名|string: 字段值|string
|
||
PocketBaseRecordBase:
|
||
type: object
|
||
required: [id, collectionId, collectionName, created, updated]
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: PocketBase记录主键
|
||
collectionId:
|
||
type: string
|
||
description: 集合ID
|
||
collectionName:
|
||
type: string
|
||
description: 集合名称
|
||
created:
|
||
type: string
|
||
description: 记录创建时间
|
||
updated:
|
||
type: string
|
||
description: 记录更新时间
|
||
example:
|
||
id: PocketBase记录主键|string
|
||
collectionId: 集合ID|string
|
||
collectionName: 集合名称|string
|
||
created: 记录创建时间|string
|
||
updated: 记录更新时间|string
|
||
PocketBaseCartFields:
|
||
type: object
|
||
properties:
|
||
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: 产品业务ID
|
||
cart_product_quantity:
|
||
type: [integer, number]
|
||
description: 产品数量
|
||
cart_status:
|
||
type: string
|
||
description: 购物车状态
|
||
cart_at_price:
|
||
type: [number, integer]
|
||
description: 加入购物车时价格
|
||
cart_remark:
|
||
type: string
|
||
description: 备注
|
||
example:
|
||
cart_id: 购物车业务ID|string
|
||
cart_number: 购物车名称或分组号|string
|
||
cart_create: 购物车项创建时间|string
|
||
cart_owner: 购物车所有者openid|string
|
||
cart_product_id: 产品业务ID|string
|
||
cart_product_quantity: 产品数量|integer
|
||
cart_status: 购物车状态|string
|
||
cart_at_price: 加入购物车时价格|number
|
||
cart_remark: 备注|string
|
||
PocketBaseCartRecord:
|
||
allOf:
|
||
- $ref: '#/components/schemas/PocketBaseRecordBase'
|
||
- $ref: '#/components/schemas/PocketBaseCartFields'
|
||
- type: object
|
||
properties:
|
||
expand:
|
||
type: object
|
||
description: 关系字段展开结果（需请求参数 `expand=cart_product_id`）
|
||
properties:
|
||
cart_product_id:
|
||
$ref: '#/components/schemas/PocketBaseProductListExpand'
|
||
PocketBaseCartCreateRequest:
|
||
type: object
|
||
required: [cart_owner]
|
||
properties:
|
||
cart_id:
|
||
type: string
|
||
example: 购物车业务ID|string
|
||
cart_number:
|
||
type: string
|
||
example: 购物车名称或分组号|string
|
||
cart_owner:
|
||
type: string
|
||
example: 购物车所有者openid|string
|
||
cart_product_id:
|
||
type: string
|
||
example: 产品业务ID|string
|
||
cart_product_quantity:
|
||
type: [integer, number]
|
||
example: 产品数量|integer
|
||
cart_status:
|
||
type: string
|
||
example: 购物车状态|string
|
||
cart_at_price:
|
||
type: [number, integer]
|
||
example: 加入购物车时价格|number
|
||
cart_remark:
|
||
type: string
|
||
example: 备注|string
|
||
PocketBaseCartUpdateRequest:
|
||
type: object
|
||
properties:
|
||
cart_number:
|
||
type: string
|
||
example: 购物车名称或分组号|string
|
||
cart_owner:
|
||
type: string
|
||
example: 购物车所有者openid|string
|
||
cart_product_id:
|
||
type: string
|
||
example: 产品业务ID|string
|
||
cart_product_quantity:
|
||
type: [integer, number]
|
||
example: 产品数量|integer
|
||
cart_status:
|
||
type: string
|
||
example: 购物车状态|string
|
||
cart_at_price:
|
||
type: [number, integer]
|
||
example: 加入购物车时价格|number
|
||
cart_remark:
|
||
type: string
|
||
example: 备注|string
|
||
PocketBaseCartListResponse:
|
||
type: object
|
||
required: [page, perPage, totalItems, totalPages, items]
|
||
properties:
|
||
page:
|
||
type: [integer, string]
|
||
perPage:
|
||
type: [integer, string]
|
||
totalItems:
|
||
type: [integer, string]
|
||
totalPages:
|
||
type: [integer, string]
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/PocketBaseCartRecord'
|
||
PocketBaseCartBatchItem:
|
||
type: object
|
||
required: [method, url, body]
|
||
properties:
|
||
method:
|
||
type: string
|
||
description: HTTP 方法
|
||
example: PATCH|string
|
||
url:
|
||
type: string
|
||
description: PocketBase 子请求路径
|
||
example: /api/collections/tbl_cart/records/PocketBase记录主键|string
|
||
headers:
|
||
type: object
|
||
description: 子请求头
|
||
additionalProperties:
|
||
type: string
|
||
example:
|
||
Content-Type: application/json|string
|
||
body:
|
||
$ref: '#/components/schemas/PocketBaseCartUpdateRequest'
|
||
PocketBaseCartBatchRequest:
|
||
type: object
|
||
required: [requests]
|
||
properties:
|
||
requests:
|
||
type: array
|
||
description: 批量子请求列表
|
||
items:
|
||
$ref: '#/components/schemas/PocketBaseCartBatchItem'
|
||
PocketBaseBatchResponseItem:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: [integer, string]
|
||
description: 子请求响应状态码
|
||
example: 子请求状态码|integer
|
||
body:
|
||
type: object
|
||
description: 子请求响应体
|
||
additionalProperties: true
|
||
example:
|
||
字段名|string: 字段值|string
|
||
PocketBaseBatchResponse:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
description: 批处理结果列表
|
||
items:
|
||
$ref: '#/components/schemas/PocketBaseBatchResponseItem'
|
||
PocketBaseProductListExpand:
|
||
type: object
|
||
description: tbl_product_list 关联展开后的记录对象（示例字段）
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: PocketBase记录主键
|
||
example: PocketBase记录主键|string
|
||
collectionId:
|
||
type: string
|
||
description: 集合ID
|
||
example: 集合ID|string
|
||
collectionName:
|
||
type: string
|
||
description: 集合名称
|
||
example: 集合名称|string
|
||
prod_list_id:
|
||
type: string
|
||
description: 产品业务ID
|
||
example: 产品业务ID|string
|
||
prod_list_name:
|
||
type: string
|
||
description: 产品名称
|
||
example: 产品名称|string
|
||
prod_list_modelnumber:
|
||
type: string
|
||
description: 产品型号
|
||
example: 产品型号|string
|
||
prod_list_basic_price:
|
||
type: [number, integer]
|
||
description: 基础价格
|
||
example: 基础价格|number
|
||
prod_list_status:
|
||
type: string
|
||
description: 产品状态
|
||
example: 产品状态|string
|