Web_BAI_Manage_ApiServer/pocket-base/spec/openapi-wx/cart.yaml

paths:
  cartRecords:
    get:
      tags: [购物车]
      summary: 查询购物车记录列表
      description: |
        使用 PocketBase 原生 records list 接口查询 `tbl_cart`。
        如需鉴权，请自行在请求头中携带 `Authorization: Bearer <token>`。
      parameters:
        - name: filter
          in: query
          required: false
          schema:
            type: string
          description: PocketBase 原生过滤表达式
          example: cart_id="购物车业务ID|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: -cart_create
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseCartListResponse'
        '400':
          description: 查询参数错误
        '401':
          description: token 无效或已过期
        '403':
          description: 无权访问
        '500':
          description: 服务端错误
    post:
      tags: [购物车]
      summary: 创建购物车记录
      description: |
        使用 PocketBase 原生 records create 接口向 `tbl_cart` 新增记录。
        如集合规则要求 `cart_owner` 与当前用户一致，请客户端显式提交。
      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: tbl_product_list 的 PocketBase recordId|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: 参数错误或违反集合规则
        '401':
          description: token 无效或已过期
        '403':
          description: 无权访问
        '500':
          description: 服务端错误
  cartRecordById:
    patch:
      tags: [购物车]
      summary: 更新购物车记录
      description: |
        使用 PocketBase 原生 records update 接口更新 `tbl_cart`。
        路径参数使用 PocketBase 原生 `recordId`。
      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: tbl_product_list 的 PocketBase recordId|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: 参数错误
        '401':
          description: token 无效或已过期
        '404':
          description: 记录不存在
        '500':
          description: 服务端错误
    delete:
      tags: [购物车]
      summary: 删除购物车记录
      description: |
        使用 PocketBase 原生 records delete 接口删除 `tbl_cart`。
        路径参数使用 PocketBase 原生 `recordId`。
      parameters:
        - name: recordId
          in: path
          required: true
          schema:
            type: string
          example: PocketBase记录主键|string
      responses:
        '204':
          description: 删除成功
        '401':
          description: token 无效或已过期
        '404':
          description: 记录不存在
        '500':
          description: 服务端错误
        "400":
          description: 参数错误
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "401":
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "403":
          description: 无权访问该购物车记录
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "404":
          description: 未找到对应购物车记录
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "415":
          description: 请求体必须为 application/json
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "500":
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
  cartCreate:
    post:
      operationId: postCartCreate
      tags:
        - 购物车
      summary: 新增购物车记录
      description: |
        调用自定义 hooks API 新增一条购物车记录。

        创建规则：
        - 服务端自动根据当前 token 写入 `cart_owner`
        - 服务端自动生成 `cart_id`
        - 若未传 `cart_number`，服务端会自动生成展示编号
        - `cart_product_id` 为必填；当前 hooks 与库结构保持一致，必须传 `tbl_product_list` 的 `recordId`
        - `cart_product_quantity`、`cart_at_price` 为必填

        目标软删除契约：
        - 新建记录应默认为 `is_delete = 0`
        - 当前仓库导出响应中尚未显式返回 `is_delete` 字段
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ../openapi-wx.yaml#/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: ../openapi-wx.yaml#/components/schemas/CartRecord
              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: 关联产品的 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: 软删除标记；目标契约字段，当前 hooks 响应可能尚未显式透出|integer
                product_name: 产品名称（服务端联动补充）|string
                product_modelnumber: 产品型号（服务端联动补充）|string
                product_basic_price: 产品基础价格（服务端联动补充）|integer
        "400":
          description: 参数错误、产品不存在或创建失败
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "401":
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "415":
          description: 请求体必须为 application/json
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "429":
          description: 重复请求过于频繁
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "500":
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
  cartUpdate:
    post:
      operationId: postCartUpdate
      tags:
        - 购物车
      summary: 修改购物车记录
      description: |
        调用自定义 hooks API 按 `cart_id` 更新购物车记录。

        更新规则：
        - 仅允许修改当前 `Authorization` 对应用户自己的购物车记录
        - `cart_id` 为必填，用于精确定位目标记录
        - 其余字段均为可选增量更新
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ../openapi-wx.yaml#/components/schemas/CartUpdateRequest
            example:
              cart_id: 购物车业务 ID|string
              cart_number: cart_number|string
              cart_product_id: tbl_product_list 的 PocketBase recordId|string
              cart_product_quantity: cart_product_quantity|integer
              cart_status: cart_status|string
              cart_at_price: cart_at_price|integer
              cart_remark: cart_remark|string
      responses:
        "200":
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/CartRecord
              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: 关联产品的 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: 软删除标记；目标契约字段，当前 hooks 响应可能尚未显式透出|integer
                product_name: 产品名称（服务端联动补充）|string
                product_modelnumber: 产品型号（服务端联动补充）|string
                product_basic_price: 产品基础价格（服务端联动补充）|integer
        "400":
          description: 参数错误、产品不存在或更新失败
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "401":
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "403":
          description: 无权访问该购物车记录
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "404":
          description: 未找到待修改的购物车记录
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "415":
          description: 请求体必须为 application/json
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "429":
          description: 重复请求过于频繁
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "500":
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
  cartDelete:
    post:
      operationId: postCartDelete
      tags:
        - 购物车
      summary: 软删除购物车记录
      description: |
        目标契约：按 `cart_id` 软删除购物车记录，将 `is_delete` 标记为 `1`，而不是物理删除。

        当前仓库实现差异：
        - 当前 `cartOrderService.deleteCart()` 仍直接调用 `$app.delete(record)` 做物理删除
        - 因此当前后端实现与本软删除契约不一致
        - 若要严格按本文档执行，需先同步调整后端服务实现，并在列表/详情接口中补充 `is_delete = 0` 过滤
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ../openapi-wx.yaml#/components/schemas/CartDeleteRequest
            example:
              cart_id: 购物车业务 ID|string
      responses:
        "200":
          description: 删除成功
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/CartDeleteResponse
              example:
                cart_id: 购物车业务 ID|string
                is_delete: 目标软删除标记值；当前实现可能仍返回物理删除结果|integer
        "400":
          description: 参数错误或删除失败
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "401":
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "403":
          description: 无权访问该购物车记录
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "404":
          description: 未找到待删除的购物车记录
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "415":
          description: 请求体必须为 application/json
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "429":
          description: 重复请求过于频繁
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "500":
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
  cartRecords:
    get:
      operationId: getPocketBaseCartRecords
      tags:
        - 购物车
      summary: 查询当前用户购物车列表或按业务 ID 精确查询
      description: |
        使用 PocketBase 原生 records list 接口查询 `tbl_cart`。

        当前线上权限规则：
        - `listRule = @request.auth.id != "" && cart_owner = @request.auth.openid && is_delete = 0`
        - 因此调用方只能读到 `cart_owner` 等于自己 `openid` 且未软删除的记录

        标准调用方式：
        1. 查询当前登录用户全部购物车：
           - 不传 `filter`
           - 可选传 `sort=-cart_create`
        2. 按业务 ID 精确查单条：
           - `filter=cart_id="CART-..."`
           - `perPage=1`
           - `page=1`

        注意：
        - 这是 PocketBase 原生返回结构，不是 hooks 统一包装
        - 即使不传 `filter`，返回结果也会继续受 `listRule` 限制
      security:
        - BearerAuth: []
      parameters:
        - name: filter
          in: query
          required: false
          description: |
            PocketBase 标准过滤表达式。

            - 查当前用户全部购物车时：不传
            - 按 `cart_id` 精确查单条时：`cart_id="CART-1770000000000-abc123"`
          schema:
            type: string
          example: cart_id="CART-1770000000000-abc123"
        - 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
          description: PocketBase 原生排序表达式，推荐 `-cart_create`
          schema:
            type: string
          example: -cart_create
      responses:
        "200":
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCartListResponse
              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
                    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
        "400":
          description: 查询参数错误或不满足 listRule
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "401":
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "403":
          description: 集合规则被锁定或服务端权限设置异常
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "500":
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
    post:
      operationId: postPocketBaseCartRecord
      tags:
        - 购物车
      summary: 创建购物车记录
      description: |
        使用 PocketBase 原生 records create 接口向 `tbl_cart` 新增记录。

        当前线上权限规则：
        - `createRule = @request.body.cart_owner != ""`
        - 因此客户端创建时必须显式提交非空 `cart_owner`
        - `cart_product_id` 当前为 relation 字段，必须传 `tbl_product_list` 的 PocketBase `recordId`

        这意味着：
        - 不能依赖服务端自动补 owner
        - 不能省略 `cart_owner`
        - 不满足规则时 PocketBase 会直接返回 `400`
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCartCreateRequest
            example:
              cart_id: cart_id|string
              cart_number: cart_number|string
              cart_owner: 必须显式提交非空 owner|string
              cart_product_id: tbl_product_list 的 PocketBase recordId|string
              cart_product_quantity: cart_product_quantity|integer，可为空
              cart_status: cart_status|string，可为空
              cart_at_price: cart_at_price|number，可为空
              cart_remark: cart_remark|string
      responses:
        "200":
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCartRecord
              example:
                id: PocketBase 记录主键|string
                collectionId: collectionId|string
                collectionName: collectionName|string
                created: 记录创建时间|string
                updated: 记录更新时间|string
                cart_id: 购物车业务 ID|string
                cart_number: 购物车名称或分组号|string
                cart_create: 购物车项创建时间，由数据库自动生成|string
                cart_owner: 购物车所有者 openid|string
                cart_product_id: 关联产品的 PocketBase recordId|string
                cart_product_quantity: 产品数量|integer
                cart_status: 购物车状态|string
                cart_at_price: 加入购物车时价格|number
                cart_remark: 备注|string
        "400":
          description: 参数错误、违反字段约束或不满足 createRule
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "401":
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "403":
          description: 集合规则被锁定或服务端权限设置异常
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "500":
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
  cartRecordById:
    patch:
      operationId: patchPocketBaseCartRecordByRecordId
      tags:
        - 购物车
      summary: 更新购物车记录
      description: |
        使用 PocketBase 原生 records update 接口更新 `tbl_cart`。

        标准调用流程：
        1. 先通过 `GET /pb/api/collections/tbl_cart/records?filter=cart_id="..."&perPage=1&page=1` 找到原生 `recordId`
        2. 再调用当前 `PATCH /pb/api/collections/tbl_cart/records/{recordId}`

        当前线上权限规则：
        - `updateRule = @request.auth.id != "" && cart_owner = @request.auth.openid`
        - 调用方只能修改自己的购物车记录
      security:
        - BearerAuth: []
      parameters:
        - name: recordId
          in: path
          required: true
          schema:
            type: string
          example: l2r3nq7rqhuob0h
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCartUpdateRequest
            example:
              cart_number: cart_number|string
              cart_owner: 若提交，必须仍等于当前 token 对应 openid|string
              cart_product_id: cart_product_id|string
              cart_product_quantity: cart_product_quantity|integer
              cart_status: cart_status|string
              cart_at_price: cart_at_price|number
              cart_remark: cart_remark|string
      responses:
        "200":
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCartRecord
              example:
                id: PocketBase 记录主键|string
                collectionId: collectionId|string
                collectionName: collectionName|string
                created: 记录创建时间|string
                updated: 记录更新时间|string
                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
        "400":
          description: 参数错误或违反字段约束
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "401":
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "404":
          description: 记录不存在或不满足 updateRule
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "500":
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
    delete:
      operationId: deletePocketBaseCartRecordByRecordId
      tags:
        - 购物车
      summary: 删除购物车记录
      description: |
        使用 PocketBase 原生 records delete 接口删除 `tbl_cart`。

        当前线上权限规则：
        - `deleteRule = @request.auth.id != "" && cart_owner = @request.auth.openid`
        - 调用方只能删除自己的购物车记录
      security:
        - BearerAuth: []
      parameters:
        - name: recordId
          in: path
          required: true
          schema:
            type: string
          example: l2r3nq7rqhuob0h
      responses:
        "204":
          description: 删除成功
        "401":
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "404":
          description: 记录不存在或不满足 deleteRule
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "500":
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
components:
  schemas:
    PocketBaseNativeError:
      type: object
      properties:
        code:
          type:
            - integer
            - string
          description: PocketBase错误码
          example: 错误状态码 | integer
        message:
          type: string
          description: PocketBase错误信息
          example: PocketBase原生错误信息 | string
        data:
          description: PocketBase错误数据
          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
    PocketBaseCartFields:
      type: object
      properties:
        cart_id:
          type: string
          description: 购物车业务 ID
          example: CART-1770000000000-abc123
        cart_number:
          type: string
          description: 购物车名称或分组号
          example: wx-user-20260403153000
        cart_create:
          type: string
          description: 购物车项创建时间，由数据库自动生成
          example: 2026-04-03 15:30:00.000Z
        cart_owner:
          type: string
          description: 购物车所有者 openid
          example: wx-openid-user-001
        cart_product_id:
          type: string
          description: 关联产品的 PocketBase recordId
          example: pbc_product_record_id|string
        cart_product_business_id:
          type: string
          description: 关联产品的业务 ID（prod_list_id），用于展示
          example: PROD-1770000000000-abcd12
        cart_product_quantity:
          type:
            - integer
            - number
          description: 产品数量
          example: 2
        cart_status:
          type: string
          description: 购物车状态
          example: 有效
        cart_at_price:
          type:
            - number
            - integer
          description: 加入购物车时价格
          example: 1999
        cart_remark:
          type: string
          description: 备注
          example: 小程序加入购物车示例
      example:
        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: 加入购物车时价格|number
        cart_remark: 备注|string
    PocketBaseCartRecord:
      allOf:
        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseRecordBase
        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCartFields
      example:
        id: PocketBase 记录主键|string
        collectionId: collectionId|string
        collectionName: collectionName|string
        created: 记录创建时间|string
        updated: 记录更新时间|string
        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
    PocketBaseCartCreateRequest:
      type: object
      required:
        - cart_owner
        - cart_product_id
      properties:
        cart_id:
          type: string
        cart_number:
          type: string
        cart_owner:
          type: string
          description: 必须显式提交非空 owner
        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:
            - number
            - integer
        cart_remark:
          type: string
      example:
        cart_owner: 必须显式提交非空 owner|string
        cart_product_id: tbl_product_list 的 PocketBase recordId|string
        cart_product_quantity: cart_product_quantity|integer，可为空
        cart_status: cart_status|string，可为空
        cart_at_price: cart_at_price|number，可为空
        cart_remark: cart_remark|string
    PocketBaseCartUpdateRequest:
      type: object
      properties:
        cart_number:
          type: string
        cart_owner:
          type: string
          description: 若提交，必须仍为非空 owner
        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:
            - number
            - integer
        cart_remark:
          type: string
      example:
        cart_number: cart_number|string
        cart_owner: 若提交，必须仍为非空 owner|string
        cart_product_id: tbl_product_list 的 PocketBase recordId|string
        cart_product_quantity: cart_product_quantity|integer
        cart_status: cart_status|string
        cart_at_price: cart_at_price|number
        cart_remark: cart_remark|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: ../openapi-wx.yaml#/components/schemas/PocketBaseCartRecord
      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
            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