paths:
  productRecords:
    get:
      operationId: getPocketBaseProductListRecords
      tags:
        - 产品信息
      summary: 根据产品分类精确筛选并按分类排序值升序返回产品列表
      description: |
        使用 PocketBase 原生 records list 接口查询 `tbl_product_list`。

        当前接口约定：
        - 默认仅返回 `is_delete = 0` 的未软删除产品
        - 条件：按 `prod_list_category` 精确匹配筛选
        - 排序：按 `prod_list_sort` 从小到大排序

        标准调用参数建议：
        - `filter=prod_list_category="<产品分类>"`
        - `sort=prod_list_sort`

        注意：
        - 这是 PocketBase 原生返回结构，不是 hooks 统一 `{ statusCode, errMsg, data }` 包装
        - 若不传 `sort`，将由 PocketBase 默认排序策略决定返回顺序
      parameters:
        - name: filter
          in: query
          required: true
          description: |
            PocketBase 标准过滤表达式，当前要求按产品分类精确值筛选。

            推荐写法：`prod_list_category="<产品分类>"`
          schema:
            type: string
          example: prod_list_category="<产品分类>"
        - name: page
          in: query
          required: false
          description: 页码
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          required: false
          description: 每页条数
          schema:
            type: integer
            minimum: 1
            default: 20
        - name: sort
          in: query
          required: false
          description: |
            PocketBase 原生排序表达式。

            当前要求使用：
            - `prod_list_sort`：按分类排序值从小到大
          schema:
            type: string
          example: prod_list_sort
      responses:
        "200":
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseProductListListResponse
              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
                    prod_list_id: 产品列表业务 ID，唯一标识|string
                    prod_list_name: 产品名称|string
                    prod_list_modelnumber: 产品型号|string
                    prod_list_icon: 产品图标附件 ID，保存 tbl_attachments.attachments_id|string
                    prod_list_description: 产品说明|string
                    prod_list_feature: 产品特色|string
                    prod_list_parameters:
                      - name: name|string
                        value: value|string
                    prod_list_plantype: 产品方案|string
                    prod_list_category: 产品分类（必填，单选）|string
                    prod_list_sort: 排序值（同分类内按升序）|number
                    prod_list_comm_type: 通讯类型|string
                    prod_list_series: 产品系列|string
                    prod_list_power_supply: 供电方式|string
                    prod_list_tags: 产品标签（辅助检索，以 | 聚合）|string
                    prod_list_status: 产品状态（有效 / 过期 / 主推等）|string
                    prod_list_basic_price: 基础价格|number
                    prod_list_vip_price:
                      - viplevel: viplevel|string
                        price: price|number
                    prod_list_remark: 备注|string
        "400":
          description: 查询参数错误
          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
components:
  schemas:
    PocketBaseNativeError:
      type: object
      properties:
        code:
          type:
            - integer
            - string
          description: 业务状态码
          example: 错误状态码 | integer
        message:
          type: string
          example: PocketBase原生错误信息 | string
        data:
          description: 业务响应数据
          type: object
          additionalProperties: true
      example:
        code: 业务状态码|integer
        message: message|string
        data:
          业务响应数据字段|string: 业务响应数据值|string
    PocketBaseRecordBase:
      type: object
      required:
        - id
        - collectionId
        - collectionName
        - created
        - updated
      properties:
        id:
          type: string
          description: PocketBase 记录主键
          example: PocketBase记录主键 | string
        collectionId:
          type: string
          example: 集合ID | string
        collectionName:
          type: string
          example: 集合名称 | string
        created:
          type: string
          description: 记录创建时间
          example: 记录创建时间 | string
        updated:
          type: string
          description: 记录更新时间
          example: 记录更新时间 | string
      example:
        id: PocketBase 记录主键|string
        collectionId: collectionId|string
        collectionName: collectionName|string
        created: 记录创建时间|string
        updated: 记录更新时间|string
    PocketBaseProductListFields:
      type: object
      properties:
        prod_list_id:
          type: string
          description: 产品列表业务 ID，唯一标识
          example: <产品列表业务ID>|<string>
        prod_list_name:
          type: string
          description: 产品名称
          example: <产品名称>|<string>
        prod_list_modelnumber:
          type: string
          description: 产品型号
          example: <产品型号>|<string>
        prod_list_icon:
          type: string
          description: 产品图标附件 ID，保存 `tbl_attachments.attachments_id`
          example: <产品图标附件ID>|<string>
        prod_list_description:
          type: string
          description: 产品说明
          example: <产品说明>|<string>
        prod_list_feature:
          type: string
          description: 产品特色
          example: <产品特色>|<string>
        prod_list_parameters:
          type: array
          description: 产品参数数组，每项包含 name/value
          items:
            type: object
            properties:
              name:
                type: string
                example: <属性名>|<string>
              value:
                type: string
                example: <属性值>|<string>
          example:
            - name: <属性名>|<string>
              value: <属性值>|<string>
        prod_list_plantype:
          type: string
          description: 产品方案
          example: <产品方案>|<string>
        prod_list_category:
          type: string
          description: 产品分类（必填，单选）
          example: <产品分类>|<string>
        prod_list_sort:
          type:
            - number
            - integer
          description: 排序值（同分类内按升序）
          example: 10
        prod_list_comm_type:
          type: string
          description: 通讯类型
          example: <通讯类型>|<string>
        prod_list_series:
          type: string
          description: 产品系列
          example: <产品系列>|<string>
        prod_list_power_supply:
          type: string
          description: 供电方式
          example: <供电方式>|<string>
        prod_list_tags:
          type: string
          description: 产品标签（辅助检索，以 `|` 聚合）
          example: <产品标签>|<string>
        prod_list_status:
          type: string
          description: 产品状态（有效 / 过期 / 主推等）
          example: <产品状态>|<string>
        prod_list_basic_price:
          type:
            - number
            - integer
          description: 基础价格
          example: 1999
        prod_list_vip_price:
          type: array
          description: 会员价数组，每项包含会员等级枚举值与价格
          items:
            type: object
            properties:
              viplevel:
                type: string
                example: <会员等级枚举值>|<string>
              price:
                type:
                  - number
                  - integer
                example: 1899
          example:
            - viplevel: VIP1
              price: 1899
        prod_list_remark:
          type: string
          description: 备注
          example: <备注>|<string>
      example:
        prod_list_id: 产品列表业务 ID，唯一标识|string
        prod_list_name: 产品名称|string
        prod_list_modelnumber: 产品型号|string
        prod_list_icon: 产品图标附件 ID，保存 tbl_attachments.attachments_id|string
        prod_list_description: 产品说明|string
        prod_list_feature: 产品特色|string
        prod_list_parameters:
          - name: name|string
            value: value|string
        prod_list_plantype: 产品方案|string
        prod_list_category: 产品分类（必填，单选）|string
        prod_list_sort: 排序值（同分类内按升序）|number
        prod_list_comm_type: 通讯类型|string
        prod_list_series: 产品系列|string
        prod_list_power_supply: 供电方式|string
        prod_list_tags: 产品标签（辅助检索，以 | 聚合）|string
        prod_list_status: 产品状态（有效 / 过期 / 主推等）|string
        prod_list_basic_price: 基础价格|number
        prod_list_vip_price:
          - viplevel: viplevel|string
            price: price|number
        prod_list_remark: 备注|string
    PocketBaseProductListRecord:
      allOf:
        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseRecordBase
        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseProductListFields
      example:
        id: PocketBase 记录主键|string
        collectionId: collectionId|string
        collectionName: collectionName|string
        created: 记录创建时间|string
        updated: 记录更新时间|string
        prod_list_id: 产品列表业务 ID，唯一标识|string
        prod_list_name: 产品名称|string
        prod_list_modelnumber: 产品型号|string
        prod_list_icon: 产品图标附件 ID，保存 tbl_attachments.attachments_id|string
        prod_list_description: 产品说明|string
        prod_list_feature: 产品特色|string
        prod_list_parameters:
          - name: name|string
            value: value|string
        prod_list_plantype: 产品方案|string
        prod_list_category: 产品分类（必填，单选）|string
        prod_list_sort: 排序值（同分类内按升序）|number
        prod_list_comm_type: 通讯类型|string
        prod_list_series: 产品系列|string
        prod_list_power_supply: 供电方式|string
        prod_list_tags: 产品标签（辅助检索，以 | 聚合）|string
        prod_list_status: 产品状态（有效 / 过期 / 主推等）|string
        prod_list_basic_price: 基础价格|number
        prod_list_vip_price:
          - viplevel: viplevel|string
            price: price|number
        prod_list_remark: 备注|string
    PocketBaseProductListListResponse:
      type: object
      required:
        - page
        - perPage
        - totalItems
        - totalPages
        - items
      properties:
        page:
          type:
            - integer
            - string
          example: <页码>|<integer>
        perPage:
          type:
            - integer
            - string
          example: <每页条数>|<integer>
        totalItems:
          type:
            - integer
            - string
          example: <总记录数>|<integer>
        totalPages:
          type:
            - integer
            - string
          example: <总页数>|<integer>
        items:
          type: array
          items:
            $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseProductListRecord
      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
            prod_list_id: 产品列表业务 ID，唯一标识|string
            prod_list_name: 产品名称|string
            prod_list_modelnumber: 产品型号|string
            prod_list_icon: 产品图标附件 ID，保存 tbl_attachments.attachments_id|string
            prod_list_description: 产品说明|string
            prod_list_feature: 产品特色|string
            prod_list_parameters:
              - name: name|string
                value: value|string
            prod_list_plantype: 产品方案|string
            prod_list_category: 产品分类（必填，单选）|string
            prod_list_sort: 排序值（同分类内按升序）|number
            prod_list_comm_type: 通讯类型|string
            prod_list_series: 产品系列|string
            prod_list_power_supply: 供电方式|string
            prod_list_tags: 产品标签（辅助检索，以 | 聚合）|string
            prod_list_status: 产品状态（有效 / 过期 / 主推等）|string
            prod_list_basic_price: 基础价格|number
            prod_list_vip_price:
              - viplevel: viplevel|string
                price: price|number
            prod_list_remark: 备注|string
