feat: 添加购物车与订单管理页面及相关API支持

- 新增购物车与订单管理页面，包含用户列表、购物车详情和订单记录展示功能。 - 实现用户搜索、刷新、重置和退出登录功能。 - 新增购物车和订单数据表结构初始化脚本，包含字段、索引及权限规则设置。 - 实现数据表的创建与更新逻辑，并进行结构校验。
2026-04-03 10:50:31 +08:00
parent c8a1f72bde
commit 91fcdcd65a
28 changed files with 3279 additions and 171 deletions
--- a/pocket-base/spec/openapi-wx.yaml
+++ b/pocket-base/spec/openapi-wx.yaml
@@ -4,7 +4,13 @@ info:
  version: 1.0.0-wx
  description: |
    面向微信端的小程序接口文档。
-    本文档只包含微信登录、微信资料完善，以及微信端会共用的系统接口。
+    本文档包含微信登录、微信资料完善，以及微信小程序侧会直接调用的业务接口。
+
+    微信小程序调用适配说明：
+    - 除 `/pb/api/wechat/login` 外，其余购物车 / 订单接口都需要在请求头中携带 `Authorization: Bearer <token>`
+    - `token` 取自 `/pb/api/wechat/login` 成功返回的认证 token
+    - 小程序端应统一使用 HTTPS + JSON 请求体，不依赖 Cookie / Session
+    - 购物车与订单接口的 owner 字段由服务端根据当前 token 自动绑定到 `tbl_auth_users.openid`
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
@@ -26,9 +32,15 @@ tags:
    description: 通过 PocketBase 原生 records API 访问 `tbl_product_list`
  - name: 文档信息
    description: 通过 PocketBase 原生 records API 访问 `tbl_document`
+  - name: 购物车
+    description: 微信小程序侧购物车 CRUD 接口
+  - name: 订单
+    description: 微信小程序侧订单 CRUD 接口
+security: []
 paths:
  /pb/api/system/users-count:
    post:
+      security: []
      operationId: postSystemUsersCount
      tags:
        - 系统
@@ -55,6 +67,9 @@ paths:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/system/refresh-token:
    post:
+      security:
+        - BearerAuth: []
+        - {}
      operationId: postSystemRefreshToken
      tags:
        - 系统
@@ -113,6 +128,7 @@ paths:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/wechat/login:
    post:
+      security: []
      operationId: postWechatLogin
      tags:
        - 微信认证
@@ -165,6 +181,8 @@ paths:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/wechat/profile:
    post:
+      security:
+        - BearerAuth: []
      operationId: postWechatProfile
      tags:
        - 微信认证
@@ -984,7 +1002,591 @@ paths:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
+  /pb/api/cart/list:
+    post:
+      operationId: postCartList
+      tags:
+        - 购物车
+      summary: 查询当前登录用户的购物车列表
+      description: |
+        返回当前 `Authorization` 对应 openid 名下的购物车记录。
+        小程序端不需要传 `cart_owner`，服务端会自动基于 token 过滤。
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CartListRequest'
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CartListResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: token 缺失、无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '403':
+          description: 无权访问目标数据
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: 请求体不是 JSON
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /pb/api/cart/detail:
+    post:
+      operationId: postCartDetail
+      tags:
+        - 购物车
+      summary: 查询当前登录用户的购物车详情
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CartDetailRequest'
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CartDetailResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: token 缺失、无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '403':
+          description: 无权访问目标数据
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: 购物车记录不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: 请求体不是 JSON
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /pb/api/cart/create:
+    post:
+      operationId: postCartCreate
+      tags:
+        - 购物车
+      summary: 创建购物车记录
+      description: |
+        `cart_owner`、`cart_create` 由服务端自动处理。
+        小程序端只需要提交商品、数量、价格和可选备注。
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CartCreateRequest'
+      responses:
+        '200':
+          description: 创建成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CartMutationResponse'
+        '400':
+          description: 请求参数错误或产品不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: token 缺失、无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: 请求体不是 JSON
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: 请求过于频繁
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /pb/api/cart/update:
+    post:
+      operationId: postCartUpdate
+      tags:
+        - 购物车
+      summary: 更新购物车记录
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CartUpdateRequest'
+      responses:
+        '200':
+          description: 更新成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CartMutationResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: token 缺失、无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '403':
+          description: 无权访问目标数据
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: 购物车记录不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: 请求体不是 JSON
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: 请求过于频繁
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /pb/api/cart/delete:
+    post:
+      operationId: postCartDelete
+      tags:
+        - 购物车
+      summary: 删除购物车记录
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CartDeleteRequest'
+      responses:
+        '200':
+          description: 删除成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CartDeleteResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: token 缺失、无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '403':
+          description: 无权访问目标数据
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: 购物车记录不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: 请求体不是 JSON
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: 请求过于频繁
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /pb/api/order/list:
+    post:
+      operationId: postOrderList
+      tags:
+        - 订单
+      summary: 查询当前登录用户的订单列表
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OrderListRequest'
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OrderListResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: token 缺失、无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '403':
+          description: 无权访问目标数据
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: 请求体不是 JSON
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /pb/api/order/detail:
+    post:
+      operationId: postOrderDetail
+      tags:
+        - 订单
+      summary: 查询当前登录用户的订单详情
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OrderDetailRequest'
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OrderDetailResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: token 缺失、无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '403':
+          description: 无权访问目标数据
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: 订单记录不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: 请求体不是 JSON
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /pb/api/order/create:
+    post:
+      operationId: postOrderCreate
+      tags:
+        - 订单
+      summary: 创建订单
+      description: |
+        `order_owner`、`order_create` 由服务端自动处理。
+        小程序端需要提交订单来源、来源 ID、订单快照和订单金额。
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OrderCreateRequest'
+      responses:
+        '200':
+          description: 创建成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OrderMutationResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: token 缺失、无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: 请求体不是 JSON
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: 请求过于频繁
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /pb/api/order/update:
+    post:
+      operationId: postOrderUpdate
+      tags:
+        - 订单
+      summary: 更新订单
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OrderUpdateRequest'
+      responses:
+        '200':
+          description: 更新成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OrderMutationResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: token 缺失、无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '403':
+          description: 无权访问目标数据
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: 订单记录不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: 请求体不是 JSON
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: 请求过于频繁
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /pb/api/order/delete:
+    post:
+      operationId: postOrderDelete
+      tags:
+        - 订单
+      summary: 删除订单
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OrderDeleteRequest'
+      responses:
+        '200':
+          description: 删除成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OrderDeleteResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: token 缺失、无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '403':
+          description: 无权访问目标数据
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: 订单记录不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: 请求体不是 JSON
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: 请求过于频繁
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
 components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
  schemas:
    ApiResponseBase:
      type: object
@@ -1038,6 +1640,281 @@ components:
        errMsg: 失败原因提示 | string
        data:
          任意错误字段: 错误附加信息 | object
+    CartRecord:
+      type: object
+      required:
+        - cart_id
+        - cart_number
+        - cart_create
+        - cart_owner
+        - cart_product_id
+        - cart_product_quantity
+        - cart_status
+        - cart_at_price
+      properties:
+        pb_id:
+          type: string
+        cart_id:
+          type: string
+        cart_number:
+          type: string
+        cart_create:
+          type: string
+          description: 购物车项创建时间
+        cart_owner:
+          type: string
+          description: 当前登录用户 openid
+        cart_product_id:
+          type: string
+        cart_product_quantity:
+          type: integer
+        cart_status:
+          type: string
+        cart_at_price:
+          type: number
+        cart_remark:
+          type: string
+        product_name:
+          type: string
+        product_modelnumber:
+          type: string
+        product_basic_price:
+          type:
+            - number
+            - 'null'
+        created:
+          type: string
+        updated:
+          type: string
+    CartListRequest:
+      type: object
+      properties:
+        keyword:
+          type: string
+          description: 按购物车编号、商品 ID、商品名称模糊搜索
+        cart_status:
+          type: string
+        cart_number:
+          type: string
+    CartDetailRequest:
+      type: object
+      required:
+        - cart_id
+      properties:
+        cart_id:
+          type: string
+    CartCreateRequest:
+      type: object
+      required:
+        - cart_product_id
+        - cart_product_quantity
+        - cart_at_price
+      properties:
+        cart_number:
+          type: string
+        cart_product_id:
+          type: string
+        cart_product_quantity:
+          type: integer
+        cart_status:
+          type: string
+        cart_at_price:
+          type: number
+        cart_remark:
+          type: string
+    CartUpdateRequest:
+      type: object
+      required:
+        - cart_id
+      properties:
+        cart_id:
+          type: string
+        cart_number:
+          type: string
+        cart_product_id:
+          type: string
+        cart_product_quantity:
+          type: integer
+        cart_status:
+          type: string
+        cart_at_price:
+          type: number
+        cart_remark:
+          type: string
+    CartDeleteRequest:
+      type: object
+      required:
+        - cart_id
+      properties:
+        cart_id:
+          type: string
+    CartListResponse:
+      type: object
+      required:
+        - items
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/CartRecord'
+    CartDetailResponse:
+      $ref: '#/components/schemas/CartRecord'
+    CartMutationResponse:
+      $ref: '#/components/schemas/CartRecord'
+    CartDeleteResponse:
+      type: object
+      required:
+        - cart_id
+      properties:
+        cart_id:
+          type: string
+    OrderRecord:
+      type: object
+      required:
+        - order_id
+        - order_number
+        - order_create
+        - order_owner
+        - order_source
+        - order_status
+        - order_source_id
+        - order_snap
+        - order_amount
+      properties:
+        pb_id:
+          type: string
+        order_id:
+          type: string
+        order_number:
+          type: string
+        order_create:
+          type: string
+          description: 订单创建时间
+        order_owner:
+          type: string
+          description: 当前登录用户 openid
+        order_source:
+          type: string
+        order_status:
+          type: string
+        order_source_id:
+          type: string
+        order_snap:
+          description: 下单快照
+          oneOf:
+            - type: object
+              additionalProperties: true
+            - type: array
+              items:
+                type: object
+                additionalProperties: true
+        order_amount:
+          type: number
+        order_remark:
+          type: string
+        created:
+          type: string
+        updated:
+          type: string
+    OrderListRequest:
+      type: object
+      properties:
+        keyword:
+          type: string
+          description: 按订单编号、订单 ID、来源 ID 模糊搜索
+        order_status:
+          type: string
+        order_source:
+          type: string
+    OrderDetailRequest:
+      type: object
+      required:
+        - order_id
+      properties:
+        order_id:
+          type: 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:
+          oneOf:
+            - type: object
+              additionalProperties: true
+            - type: array
+              items:
+                type: object
+                additionalProperties: true
+        order_amount:
+          type: number
+        order_remark:
+          type: 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:
+          oneOf:
+            - type: object
+              additionalProperties: true
+            - type: array
+              items:
+                type: object
+                additionalProperties: true
+        order_amount:
+          type: number
+        order_remark:
+          type: string
+    OrderDeleteRequest:
+      type: object
+      required:
+        - order_id
+      properties:
+        order_id:
+          type: string
+    OrderListResponse:
+      type: object
+      required:
+        - items
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/OrderRecord'
+    OrderDetailResponse:
+      $ref: '#/components/schemas/OrderRecord'
+    OrderMutationResponse:
+      $ref: '#/components/schemas/OrderRecord'
+    OrderDeleteResponse:
+      type: object
+      required:
+        - order_id
+      properties:
+        order_id:
+          type: string
    CompanyInfo:
      anyOf:
        - type: object
@@ -2449,4 +3326,3 @@ components:
        errMsg: 业务提示信息 | string
        data:
          total_users: 用户总数 | integer
-