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

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