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

paths:
  cartList:
    post:
      operationId: postCartList
      tags:
        - 购物车
      summary: 按索引字段模糊查询购物车列表
      description: |
        调用自定义 hooks API 查询当前登录用户的购物车列表。

        查询规则：
        - 仅允许查询当前 `Authorization` 对应用户自己的购物车记录
        - 支持通过 `keyword` 对多个索引相关字段做统一模糊搜索，当前实现覆盖：
          - `cart_id`
          - `cart_number`
          - `cart_product_id`
          - `product_name`
        - 支持按 `cart_status` 精确过滤
        - 支持按 `cart_number` 精确过滤

        目标软删除契约：
        - 目标行为应仅返回 `is_delete = 0` 的记录
        - 当前仓库实现尚未显式追加 `is_delete = 0` 过滤，请以实际后端代码为准
      security:
        - BearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: ../openapi-wx.yaml#/components/schemas/CartListRequest
            example:
              keyword: 对 cart_id、cart_number、cart_product_id 等索引相关字段的统一模糊搜索关键字|string
              cart_status: 购物车状态精确过滤|string
              cart_number: 购物车名称或分组号精确过滤|string
      responses:
        "200":
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/CartListResponse
              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: 产品业务 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
        "500":
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
              example:
                statusCode: 业务状态码|integer
                errMsg: 业务提示信息|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
  cartDetail:
    post:
      operationId: postCartDetail
      tags:
        - 购物车
      summary: 按 cart_id 精确查询购物车详情
      description: |
        调用自定义 hooks API 按 `cart_id` 查询单条购物车记录。

        查询规则：
        - 仅允许访问当前 `Authorization` 对应用户自己的购物车记录
        - 查询键为业务 ID `cart_id`，不是 PocketBase 原生 `recordId`

        目标软删除契约：
        - 目标行为应仅允许查询 `is_delete = 0` 的记录
        - 当前仓库实现尚未显式追加 `is_delete = 0` 过滤，请以实际后端代码为准
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ../openapi-wx.yaml#/components/schemas/CartDetailRequest
            example:
              cart_id: 购物车业务 ID|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: 产品业务 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
        "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`、`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: 产品业务 ID|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: 产品业务 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: cart_product_id|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: 产品业务 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.auth.id != "" && @request.body.cart_owner = @request.auth.openid`
        - 因此客户端创建时必须显式提交 `cart_owner`，并且值必须等于当前 token 对应的 `openid`

        这意味着：
        - 不能依赖服务端自动补 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: 必须显式提交，且值必须等于当前 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: 参数错误、违反字段约束或不满足 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:
    ApiResponseBase:
      type: object
      required:
        - statusCode
        - errMsg
        - data
      properties:
        statusCode:
          type:
            - integer
            - string
          description: 业务状态码
          example: 业务状态码 | integer
        errMsg:
          type: string
          description: 业务提示信息
          example: 业务提示信息 | string
        data:
          description: 业务响应数据
          type: object
          additionalProperties: true
      example:
        statusCode: 业务状态码|integer
        errMsg: 业务提示信息|string
        data:
          业务响应数据字段|string: 业务响应数据值|string
    ErrorResponse:
      type: object
      required:
        - statusCode
        - errMsg
        - data
      properties:
        statusCode:
          type:
            - integer
            - string
          description: 业务状态码
          example: 业务状态码 | integer
        errMsg:
          type: string
          description: 业务提示信息
          example: 失败原因提示 | string
        data:
          description: 业务响应数据
          type: object
          additionalProperties: true
      example:
        statusCode: 业务状态码|integer
        errMsg: 业务提示信息|string
        data:
          业务响应数据字段|string: 业务响应数据值|string
    HookRecordBase:
      type: object
      properties:
        pb_id:
          type: string
          description: PocketBase 记录主键 id
          example: l2r3nq7rqhuob0h
        created:
          type: string
          description: PocketBase 系统创建时间
          example: 2026-04-03 15:30:00.000Z
        updated:
          type: string
          description: PocketBase 系统更新时间
          example: 2026-04-03 15:35:00.000Z
      example:
        pb_id: PocketBase 记录主键 id|string
        created: PocketBase 系统创建时间|string
        updated: PocketBase 系统更新时间|string
    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
    CartRecord:
      allOf:
        - $ref: ../openapi-wx.yaml#/components/schemas/HookRecordBase
        - 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: 产品业务 ID
              example: PROD-1770000000000-abcd12
            cart_product_quantity:
              type:
                - integer
                - number
              description: 产品数量
              example: 2
            cart_status:
              type: string
              description: 购物车状态
              example: 有效
            cart_at_price:
              type:
                - integer
                - number
              description: 加入购物车时价格
              example: 1999
            cart_remark:
              type: string
              description: 备注
              example: 小程序加入购物车示例
            is_delete:
              type:
                - integer
                - number
              description: 软删除标记；目标契约字段，当前 hooks 响应可能尚未显式透出
              example: 0
            product_name:
              type: string
              description: 产品名称（服务端联动补充）
              example: BAI 智能主机
            product_modelnumber:
              type: string
              description: 产品型号（服务端联动补充）
              example: BAI-HOST-01
            product_basic_price:
              type:
                - integer
                - number
                - "null"
              description: 产品基础价格（服务端联动补充）
              example: 1999
      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: 产品业务 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
    CartListRequest:
      type: object
      properties:
        keyword:
          type: string
          description: 对 `cart_id`、`cart_number`、`cart_product_id` 等索引相关字段的统一模糊搜索关键字
          example: CART-1770
        cart_status:
          type: string
          description: 购物车状态精确过滤
          example: 有效
        cart_number:
          type: string
          description: 购物车名称或分组号精确过滤
          example: wx-user-20260403153000
      example:
        keyword: 对 cart_id、cart_number、cart_product_id 等索引相关字段的统一模糊搜索关键字|string
        cart_status: 购物车状态精确过滤|string
        cart_number: 购物车名称或分组号精确过滤|string
    CartDetailRequest:
      type: object
      required:
        - cart_id
      properties:
        cart_id:
          type: string
          description: 购物车业务 ID
          example: CART-1770000000000-abc123
      example:
        cart_id: 购物车业务 ID|string
    CartCreateRequest:
      type: object
      required:
        - cart_product_id
        - cart_product_quantity
        - cart_at_price
      properties:
        cart_number:
          type: string
          description: 可选；未传时服务端自动生成
        cart_product_id:
          type: string
          description: 产品业务 ID
          example: PROD-1770000000000-abcd12
        cart_product_quantity:
          type:
            - integer
            - number
          description: 产品数量，需为正整数
          example: 2
        cart_status:
          type: string
          description: 可选；未传时默认 `有效`
          example: 有效
        cart_at_price:
          type:
            - integer
            - number
          description: 加入购物车时价格
          example: 1999
        cart_remark:
          type: string
          description: 备注
          example: 小程序加入购物车示例
      example:
        cart_number: 可选；未传时服务端自动生成|string
        cart_product_id: 产品业务 ID|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
          description: 购物车业务 ID
          example: CART-1770000000000-abc123
        cart_number:
          type: string
        cart_product_id:
          type: string
        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: cart_number|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|integer
        cart_remark: cart_remark|string
    CartDeleteRequest:
      type: object
      required:
        - cart_id
      properties:
        cart_id:
          type: string
          description: 购物车业务 ID
          example: CART-1770000000000-abc123
      example:
        cart_id: 购物车业务 ID|string
    CartListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: ../openapi-wx.yaml#/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: 产品业务 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
    CartDeleteResponse:
      type: object
      properties:
        cart_id:
          type: string
          description: 购物车业务 ID
          example: CART-1770000000000-abc123
        is_delete:
          type:
            - integer
            - number
          description: 目标软删除标记值；当前实现可能仍返回物理删除结果
          example: 1
      example:
        cart_id: 购物车业务 ID|string
        is_delete: 目标软删除标记值；当前实现可能仍返回物理删除结果|integer
    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: 产品业务 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: 产品业务 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_id
        - cart_number
        - cart_owner
        - cart_product_id
        - cart_product_quantity
        - cart_status
        - cart_at_price
      properties:
        cart_id:
          type: string
        cart_number:
          type: string
        cart_owner:
          type: string
          description: 必须显式提交，且值必须等于当前 token 对应 openid
        cart_product_id:
          type: string
        cart_product_quantity:
          type:
            - integer
            - number
        cart_status:
          type: string
        cart_at_price:
          type:
            - number
            - integer
        cart_remark:
          type: string
      example:
        cart_id: cart_id|string
        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
    PocketBaseCartUpdateRequest:
      type: object
      properties:
        cart_number:
          type: string
        cart_owner:
          type: string
          description: 若提交，必须仍等于当前 token 对应 openid
        cart_product_id:
          type: string
        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: 若提交，必须仍等于当前 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
    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