XuJiacheng
ec6b59b4fa
- 在 package.json 中添加迁移脚本 `migrate:cart-active-unique-index`。 - 修改 `pocketbase.cart-order.js` 文件，更新 `cart_id` 和 `cart_product_id` 字段的必填属性，并添加唯一索引 `idx_tbl_cart_owner_product_active_unique`。 - 在 `pocketbase.ensure-cart-order-autogen-id.js` 中，调整 `cart_id` 字段的必填属性为可选，并确保 `order_id` 字段为必填。 - 在 `pocketbase.product-list.js` 中，新增 `prod_list_barcode` 字段。 - 新增 `make-openapi-standalone.cjs` 脚本，用于处理 OpenAPI 文档。 - 新增 `pocketbase.cart-active-unique-index.js` 脚本，处理购物车的唯一索引和去重逻辑。
481 lines
20 KiB
YAML
481 lines
20 KiB
YAML
openapi: 3.1.0
|
||
info:
|
||
title: BAI PocketBase Native API - Documents
|
||
version: 1.0.0
|
||
description: |
|
||
PocketBase 原生 `tbl_document` records API 文档。
|
||
本文件可单独导入使用，不依赖其他 YAML。
|
||
servers:
|
||
- url: https://bai-api.blv-oa.com
|
||
description: 生产环境
|
||
- url: http://localhost:8090
|
||
description: PocketBase 本地环境
|
||
paths:
|
||
/pb/api/collections/tbl_document/records:
|
||
get:
|
||
operationId: getPocketBaseDocumentRecords
|
||
tags:
|
||
- 文档信息
|
||
summary: 分页查询文档列表 / 按 system_dict_id 与 enum 双条件分页筛选文档
|
||
description: |
|
||
使用 PocketBase 原生 records list 接口查询 `tbl_document`。
|
||
|
||
当前线上权限规则：
|
||
- `listRule = is_delete = 0`，因此任何客户端都可直接分页查询未软删除文档
|
||
- `viewRule = is_delete = 0`，因此单条详情也只可读取未软删除文档
|
||
- `create/update/delete` 仍仅管理员或管理后台用户允许
|
||
|
||
`document_type` 的存储格式为：
|
||
- `system_dict_id@dict_word_enum|system_dict_id@dict_word_enum`
|
||
|
||
业务上这里是两个独立条件，并且查询时两个条件都要满足：
|
||
- 条件 1：包含某个 `system_dict_id`
|
||
- 条件 2：包含某个 `enum`
|
||
|
||
PocketBase 原生标准接口实际只有一个 `filter` 参数，因此应在同一个 `filter` 中写成两个 `contains` 条件，例如：
|
||
- `system_dict_id = DICT-1774599144591-hAEFQj`
|
||
- `enum = UT1`
|
||
- 最终：`document_type ~ "DICT-1774599144591-hAEFQj" && document_type ~ "@UT1"`
|
||
|
||
这条写法已经按线上真实数据验证通过。
|
||
|
||
排序说明：
|
||
- 当前线上统一按 `document_create` 排序
|
||
- 若要“最新上传的排在最前面”，请传 `sort=-document_create`
|
||
|
||
标准调用方式有两种：
|
||
1. 查询整个文档列表：
|
||
- 不传 `filter`
|
||
- 按需传 `page`、`perPage`
|
||
- 若要按最新上传倒序，传 `sort=-document_create`
|
||
2. 根据 `system_dict_id` 和 `enum` 两个业务条件分页筛选：
|
||
- 直接传 `filter=document_type ~ "<system_dict_id>" && document_type ~ "@<enum>"`
|
||
- 传 `page`、`perPage`
|
||
- 若要按最新上传倒序，传 `sort=-document_create`
|
||
|
||
注意：
|
||
- 这是 PocketBase 原生返回结构，不是 hooks 统一 `{ statusCode, errMsg, data }` 包装
|
||
- 如果需要更复杂的条件组合，可继续使用 PocketBase 原生 `filter` 语法自行扩展
|
||
parameters:
|
||
- name: filter
|
||
in: query
|
||
required: false
|
||
description: |
|
||
PocketBase 标准过滤表达式。
|
||
|
||
- 查全部列表时：不传
|
||
- 按业务条件筛选时，同时写两个 `contains` 条件
|
||
- 第二个条件建议带上 `@` 前缀，避免误命中
|
||
- 例如：`document_type ~ "DICT-1774599144591-hAEFQj" && document_type ~ "@UT1"`
|
||
schema:
|
||
type: string
|
||
example: 过滤表达式|string
|
||
- name: page
|
||
in: query
|
||
required: false
|
||
description: 页码
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
default: 1
|
||
- name: perPage
|
||
in: query
|
||
required: false
|
||
description: 每页条数
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
default: 20
|
||
- name: sort
|
||
in: query
|
||
required: false
|
||
description: |
|
||
PocketBase 原生排序表达式。
|
||
|
||
当前线上建议使用：
|
||
- `-document_create`：按最新上传倒序返回
|
||
schema:
|
||
type: string
|
||
example: 排序表达式|string
|
||
responses:
|
||
"200":
|
||
description: 查询成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: #/components/schemas/PocketBaseDocumentListResponse
|
||
example:
|
||
page: page|integer
|
||
perPage: perPage|integer
|
||
totalItems: totalItems|integer
|
||
totalPages: totalPages|integer
|
||
items:
|
||
- id: PocketBase 记录主键|string
|
||
collectionId: collectionId|string
|
||
collectionName: collectionName|string
|
||
created: 记录创建时间|string
|
||
updated: 记录更新时间|string
|
||
document_id: 文档业务 ID|string
|
||
document_create: 文档创建时间，由数据库自动生成|string
|
||
document_effect_date: 文档生效日期|string
|
||
document_expiry_date: 文档到期日期|string
|
||
document_title: 文档标题|string
|
||
document_type: 文档类型，多选时按 system_dict_id@dict_word_enum|... 保存|string
|
||
document_subtitle: 文档副标题|string
|
||
document_summary: 文档摘要|string
|
||
document_content: 正文内容，保存 Markdown|string
|
||
document_image: 图片附件 ID 集合，底层以 | 分隔|string
|
||
document_video: 视频附件 ID 集合，底层以 | 分隔|string
|
||
document_file: 文件附件 ID 集合，底层以 | 分隔|string
|
||
document_status: 文档状态，仅 有效 / 过期|string
|
||
document_owner: 上传者 openid|string
|
||
document_relation_model: 关联机型 / 模型标识|string
|
||
document_keywords: 关键词，多选后以 | 分隔|string
|
||
document_share_count: 分享次数|number
|
||
document_download_count: 下载次数|number
|
||
document_favorite_count: 收藏次数|number
|
||
document_embedding_status: 文档嵌入状态|string
|
||
document_embedding_error: 文档嵌入错误原因|string
|
||
document_embedding_lasttime: 最后一次嵌入更新时间|string
|
||
document_vector_version: 向量版本号 / 模型名称|string
|
||
document_product_categories: 产品关联文档，多选后以 | 分隔|string
|
||
document_application_scenarios: 筛选依据，多选后以 | 分隔|string
|
||
document_hotel_type: 适用场景，多选后以 | 分隔|string
|
||
document_remark: 备注|string
|
||
"400":
|
||
description: 查询参数错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: #/components/schemas/PocketBaseNativeError
|
||
example:
|
||
code: 业务状态码|integer
|
||
message: message|string
|
||
data:
|
||
业务响应数据字段|string: 业务响应数据值|string
|
||
"403":
|
||
description: 集合规则被锁定或服务端权限设置异常
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: #/components/schemas/PocketBaseNativeError
|
||
example:
|
||
code: 业务状态码|integer
|
||
message: message|string
|
||
data:
|
||
业务响应数据字段|string: 业务响应数据值|string
|
||
"500":
|
||
description: 服务端错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: #/components/schemas/PocketBaseNativeError
|
||
example:
|
||
code: 业务状态码|integer
|
||
message: message|string
|
||
data:
|
||
业务响应数据字段|string: 业务响应数据值|string
|
||
components:
|
||
schemas:
|
||
PocketBaseNativeError:
|
||
type: object
|
||
properties:
|
||
code:
|
||
type:
|
||
- integer
|
||
- string
|
||
description: 业务状态码
|
||
example: 错误状态码 | integer
|
||
message:
|
||
type: string
|
||
example: PocketBase原生错误信息 | string
|
||
data:
|
||
description: 业务响应数据
|
||
type: object
|
||
additionalProperties: true
|
||
example:
|
||
code: 业务状态码|integer
|
||
message: message|string
|
||
data:
|
||
业务响应数据字段|string: 业务响应数据值|string
|
||
PocketBaseRecordBase:
|
||
type: object
|
||
required:
|
||
- id
|
||
- collectionId
|
||
- collectionName
|
||
- created
|
||
- updated
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: PocketBase 记录主键
|
||
example: PocketBase记录主键 | string
|
||
collectionId:
|
||
type: string
|
||
example: 集合ID | string
|
||
collectionName:
|
||
type: string
|
||
example: 集合名称 | string
|
||
created:
|
||
type: string
|
||
description: 记录创建时间
|
||
example: 记录创建时间 | string
|
||
updated:
|
||
type: string
|
||
description: 记录更新时间
|
||
example: 记录更新时间 | string
|
||
example:
|
||
id: PocketBase 记录主键|string
|
||
collectionId: collectionId|string
|
||
collectionName: collectionName|string
|
||
created: 记录创建时间|string
|
||
updated: 记录更新时间|string
|
||
PocketBaseDocumentFields:
|
||
type: object
|
||
properties:
|
||
document_id:
|
||
type: string
|
||
description: 文档业务 ID
|
||
example: 文档业务ID | string
|
||
document_create:
|
||
type: string
|
||
description: 文档创建时间，由数据库自动生成
|
||
example: 文档创建时间，由数据库自动生成 | string
|
||
document_effect_date:
|
||
type: string
|
||
description: 文档生效日期
|
||
example: 文档生效日期 | string
|
||
document_expiry_date:
|
||
type: string
|
||
description: 文档到期日期
|
||
example: 文档到期日期 | string
|
||
document_title:
|
||
type: string
|
||
description: 文档标题
|
||
example: 文档标题 | string
|
||
document_type:
|
||
type: string
|
||
description: 文档类型，多选时按 system_dict_id@dict_word_enum|... 保存
|
||
example: 文档类型，按system_dict_id@dict_word_enum保存 | string
|
||
document_subtitle:
|
||
type: string
|
||
description: 文档副标题
|
||
example: 文档副标题 | string
|
||
document_summary:
|
||
type: string
|
||
description: 文档摘要
|
||
example: 文档摘要 | string
|
||
document_content:
|
||
type: string
|
||
description: 正文内容，保存 Markdown
|
||
example: 正文内容 | string
|
||
document_image:
|
||
type: string
|
||
description: 图片附件 ID 集合，底层以 | 分隔
|
||
example: 图片附件ID串，底层按|分隔 | string
|
||
document_video:
|
||
type: string
|
||
description: 视频附件 ID 集合，底层以 | 分隔
|
||
example: 视频附件ID串，底层按|分隔 | string
|
||
document_file:
|
||
type: string
|
||
description: 文件附件 ID 集合，底层以 | 分隔
|
||
example: 文件附件ID串，底层按|分隔 | string
|
||
document_status:
|
||
type: string
|
||
description: 文档状态，仅 `有效` / `过期`
|
||
example: 文档状态 | string
|
||
document_owner:
|
||
type: string
|
||
description: 上传者 openid
|
||
example: 上传者openid | string
|
||
document_relation_model:
|
||
type: string
|
||
description: 关联机型 / 模型标识
|
||
example: 关联机型标识 | string
|
||
document_keywords:
|
||
type: string
|
||
description: 关键词，多选后以 | 分隔
|
||
example: 关键词，多选按|分隔 | string
|
||
document_share_count:
|
||
type: number
|
||
description: 分享次数
|
||
example: 分享次数|number
|
||
document_download_count:
|
||
type: number
|
||
description: 下载次数
|
||
example: 下载次数|number
|
||
document_favorite_count:
|
||
type: number
|
||
description: 收藏次数
|
||
example: 收藏次数|number
|
||
document_embedding_status:
|
||
type: string
|
||
description: 文档嵌入状态
|
||
example: 文档嵌入状态 | string
|
||
document_embedding_error:
|
||
type: string
|
||
description: 文档嵌入错误原因
|
||
example: 文档嵌入错误原因 | string
|
||
document_embedding_lasttime:
|
||
type: string
|
||
description: 最后一次嵌入更新时间
|
||
example: 最后一次嵌入更新时间 | string
|
||
document_vector_version:
|
||
type: string
|
||
description: 向量版本号 / 模型名称
|
||
example: 向量版本号或模型名称 | string
|
||
document_product_categories:
|
||
type: string
|
||
description: 产品关联文档，多选后以 | 分隔
|
||
example: 产品关联文档，多选按|分隔 | string
|
||
document_application_scenarios:
|
||
type: string
|
||
description: 筛选依据，多选后以 | 分隔
|
||
example: 筛选依据，多选按|分隔 | string
|
||
document_hotel_type:
|
||
type: string
|
||
description: 适用场景，多选后以 | 分隔
|
||
example: 适用场景，多选按|分隔 | string
|
||
document_remark:
|
||
type: string
|
||
description: 备注
|
||
example: 备注 | string
|
||
example:
|
||
document_id: 文档业务 ID|string
|
||
document_create: 文档创建时间，由数据库自动生成|string
|
||
document_effect_date: 文档生效日期|string
|
||
document_expiry_date: 文档到期日期|string
|
||
document_title: 文档标题|string
|
||
document_type: 文档类型，多选时按 system_dict_id@dict_word_enum|... 保存|string
|
||
document_subtitle: 文档副标题|string
|
||
document_summary: 文档摘要|string
|
||
document_content: 正文内容，保存 Markdown|string
|
||
document_image: 图片附件 ID 集合，底层以 | 分隔|string
|
||
document_video: 视频附件 ID 集合，底层以 | 分隔|string
|
||
document_file: 文件附件 ID 集合，底层以 | 分隔|string
|
||
document_status: 文档状态，仅 有效 / 过期|string
|
||
document_owner: 上传者 openid|string
|
||
document_relation_model: 关联机型 / 模型标识|string
|
||
document_keywords: 关键词，多选后以 | 分隔|string
|
||
document_share_count: 分享次数|number
|
||
document_download_count: 下载次数|number
|
||
document_favorite_count: 收藏次数|number
|
||
document_embedding_status: 文档嵌入状态|string
|
||
document_embedding_error: 文档嵌入错误原因|string
|
||
document_embedding_lasttime: 最后一次嵌入更新时间|string
|
||
document_vector_version: 向量版本号 / 模型名称|string
|
||
document_product_categories: 产品关联文档，多选后以 | 分隔|string
|
||
document_application_scenarios: 筛选依据，多选后以 | 分隔|string
|
||
document_hotel_type: 适用场景，多选后以 | 分隔|string
|
||
document_remark: 备注|string
|
||
PocketBaseDocumentRecord:
|
||
allOf:
|
||
- $ref: #/components/schemas/PocketBaseRecordBase
|
||
- $ref: #/components/schemas/PocketBaseDocumentFields
|
||
example:
|
||
id: PocketBase 记录主键|string
|
||
collectionId: collectionId|string
|
||
collectionName: collectionName|string
|
||
created: 记录创建时间|string
|
||
updated: 记录更新时间|string
|
||
document_id: 文档业务 ID|string
|
||
document_create: 文档创建时间，由数据库自动生成|string
|
||
document_effect_date: 文档生效日期|string
|
||
document_expiry_date: 文档到期日期|string
|
||
document_title: 文档标题|string
|
||
document_type: 文档类型，多选时按 system_dict_id@dict_word_enum|... 保存|string
|
||
document_subtitle: 文档副标题|string
|
||
document_summary: 文档摘要|string
|
||
document_content: 正文内容，保存 Markdown|string
|
||
document_image: 图片附件 ID 集合，底层以 | 分隔|string
|
||
document_video: 视频附件 ID 集合，底层以 | 分隔|string
|
||
document_file: 文件附件 ID 集合，底层以 | 分隔|string
|
||
document_status: 文档状态，仅 有效 / 过期|string
|
||
document_owner: 上传者 openid|string
|
||
document_relation_model: 关联机型 / 模型标识|string
|
||
document_keywords: 关键词，多选后以 | 分隔|string
|
||
document_share_count: 分享次数|number
|
||
document_download_count: 下载次数|number
|
||
document_favorite_count: 收藏次数|number
|
||
document_embedding_status: 文档嵌入状态|string
|
||
document_embedding_error: 文档嵌入错误原因|string
|
||
document_embedding_lasttime: 最后一次嵌入更新时间|string
|
||
document_vector_version: 向量版本号 / 模型名称|string
|
||
document_product_categories: 产品关联文档，多选后以 | 分隔|string
|
||
document_application_scenarios: 筛选依据，多选后以 | 分隔|string
|
||
document_hotel_type: 适用场景，多选后以 | 分隔|string
|
||
document_remark: 备注|string
|
||
PocketBaseDocumentListResponse:
|
||
type: object
|
||
required:
|
||
- page
|
||
- perPage
|
||
- totalItems
|
||
- totalPages
|
||
- items
|
||
properties:
|
||
page:
|
||
type:
|
||
- integer
|
||
- string
|
||
example: 页码 | integer
|
||
perPage:
|
||
type:
|
||
- integer
|
||
- string
|
||
example: 每页条数 | integer
|
||
totalItems:
|
||
type:
|
||
- integer
|
||
- string
|
||
example: 总记录数 | integer
|
||
totalPages:
|
||
type:
|
||
- integer
|
||
- string
|
||
example: 总页数 | integer
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: #/components/schemas/PocketBaseDocumentRecord
|
||
example:
|
||
page: page|integer
|
||
perPage: perPage|integer
|
||
totalItems: totalItems|integer
|
||
totalPages: totalPages|integer
|
||
items:
|
||
- id: PocketBase 记录主键|string
|
||
collectionId: collectionId|string
|
||
collectionName: collectionName|string
|
||
created: 记录创建时间|string
|
||
updated: 记录更新时间|string
|
||
document_id: 文档业务 ID|string
|
||
document_create: 文档创建时间，由数据库自动生成|string
|
||
document_effect_date: 文档生效日期|string
|
||
document_expiry_date: 文档到期日期|string
|
||
document_title: 文档标题|string
|
||
document_type: 文档类型，多选时按 system_dict_id@dict_word_enum|... 保存|string
|
||
document_subtitle: 文档副标题|string
|
||
document_summary: 文档摘要|string
|
||
document_content: 正文内容，保存 Markdown|string
|
||
document_image: 图片附件 ID 集合，底层以 | 分隔|string
|
||
document_video: 视频附件 ID 集合，底层以 | 分隔|string
|
||
document_file: 文件附件 ID 集合，底层以 | 分隔|string
|
||
document_status: 文档状态，仅 有效 / 过期|string
|
||
document_owner: 上传者 openid|string
|
||
document_relation_model: 关联机型 / 模型标识|string
|
||
document_keywords: 关键词，多选后以 | 分隔|string
|
||
document_share_count: 分享次数|number
|
||
document_download_count: 下载次数|number
|
||
document_favorite_count: 收藏次数|number
|
||
document_embedding_status: 文档嵌入状态|string
|
||
document_embedding_error: 文档嵌入错误原因|string
|
||
document_embedding_lasttime: 最后一次嵌入更新时间|string
|
||
document_vector_version: 向量版本号 / 模型名称|string
|
||
document_product_categories: 产品关联文档，多选后以 | 分隔|string
|
||
document_application_scenarios: 筛选依据，多选后以 | 分隔|string
|
||
document_hotel_type: 适用场景，多选后以 | 分隔|string
|
||
document_remark: 备注|string
|