paths:
  cartList:
    post:
      tags: [购物车]
      summary: 查询购物车列表
      description: |
        调用自定义 hooks API 查询当前登录用户的购物车列表。
        请求头请自行携带 `Authorization: Bearer <token>`。
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartListRequest'
            example:
              keyword: 模糊搜索关键字|string
              cart_status: 购物车状态|string
              cart_number: 购物车名称或分组号|string
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartListResponse'
        '400':
          description: 参数错误
        '401':
          description: token 无效或已过期
        '415':
          description: 请求体必须为 application/json
        '500':
          description: 服务端错误
  cartDetail:
    post:
      tags: [购物车]
      summary: 查询购物车详情
      description: |
        调用自定义 hooks API 按 `cart_id` 查询单条购物车记录。
        请求头请自行携带 `Authorization: Bearer <token>`。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartDetailRequest'
            example:
              cart_id: 购物车业务ID|string
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartRecord'
        '400':
          description: 参数错误
        '401':
          description: token 无效或已过期
        '403':
          description: 无权访问该购物车记录
        '404':
          description: 未找到对应购物车记录
        '415':
          description: 请求体必须为 application/json
        '500':
          description: 服务端错误
  cartCreate:
    post:
      tags: [购物车]
      summary: 新增购物车记录
      description: |
        调用自定义 hooks API 新增购物车记录。
        服务端会基于当前 token 自动写入 `cart_owner` 并生成 `cart_id`。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartCreateRequest'
            example:
              cart_number: 可选；未传时服务端自动生成|string
              cart_product_id: tbl_product_list 的 PocketBase recordId|string
              cart_product_quantity: 产品数量|integer
              cart_status: 购物车状态|string
              cart_at_price: 加入购物车时价格|integer
              cart_remark: 备注|string
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartRecord'
        '400':
          description: 参数错误或创建失败
        '401':
          description: token 无效或已过期
        '415':
          description: 请求体必须为 application/json
        '429':
          description: 重复请求过于频繁
        '500':
          description: 服务端错误
  cartUpdate:
    post:
      tags: [购物车]
      summary: 修改购物车记录
      description: |
        调用自定义 hooks API 按 `cart_id` 更新购物车记录。
        请求头请自行携带 `Authorization: Bearer <token>`。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartUpdateRequest'
            example:
              cart_id: 购物车业务ID|string
              cart_number: 购物车名称或分组号|string
              cart_product_id: tbl_product_list 的 PocketBase recordId|string
              cart_product_quantity: 产品数量|integer
              cart_status: 购物车状态|string
              cart_at_price: 加入购物车时价格|integer
              cart_remark: 备注|string
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartRecord'
        '400':
          description: 参数错误或更新失败
        '401':
          description: token 无效或已过期
        '403':
          description: 无权访问该购物车记录
        '404':
          description: 未找到待修改记录
        '415':
          description: 请求体必须为 application/json
        '429':
          description: 重复请求过于频繁
        '500':
          description: 服务端错误
  cartDelete:
    post:
      tags: [购物车]
      summary: 删除购物车记录
      description: |
        调用自定义 hooks API 按 `cart_id` 删除购物车记录。
        当前后端实现以实际 hooks 逻辑为准。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartDeleteRequest'
            example:
              cart_id: 购物车业务ID|string
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartDeleteResponse'
        '400':
          description: 参数错误或删除失败
        '401':
          description: token 无效或已过期
        '403':
          description: 无权访问该购物车记录
        '404':
          description: 未找到待删除记录
        '415':
          description: 请求体必须为 application/json
        '429':
          description: 重复请求过于频繁
        '500':
          description: 服务端错误
components:
  schemas:
    CartRecord:
      type: object
      properties:
        pb_id:
          type: string
          description: PocketBase记录主键id
        created:
          type: string
          description: PocketBase系统创建时间
        updated:
          type: string
          description: PocketBase系统更新时间
        cart_id:
          type: string
          description: 购物车业务ID
        cart_number:
          type: string
          description: 购物车名称或分组号
        cart_create:
          type: string
          description: 购物车项创建时间
        cart_owner:
          type: string
          description: 购物车所有者openid
        cart_product_id:
          type: string
          description: 关联产品的 PocketBase recordId
        cart_product_business_id:
          type: string
          description: 关联产品的业务 ID（即 prod_list_id），用于展示
        cart_product_quantity:
          type: [integer, number]
          description: 产品数量
        cart_status:
          type: string
          description: 购物车状态
        cart_at_price:
          type: [integer, number]
          description: 加入购物车时价格
        cart_remark:
          type: string
          description: 备注
        is_delete:
          type: [integer, number]
          description: 删除标记
        product_name:
          type: string
          description: 产品名称
        product_modelnumber:
          type: string
          description: 产品型号
        product_basic_price:
          type: [integer, number, 'null']
          description: 产品基础价格
      example:
        pb_id: PocketBase记录主键id|string
        created: PocketBase系统创建时间|string
        updated: PocketBase系统更新时间|string
        cart_id: 购物车业务ID|string
        cart_number: 购物车名称或分组号|string
        cart_create: 购物车项创建时间|string
        cart_owner: 购物车所有者openid|string
        cart_product_id: tbl_product_list 的 PocketBase recordId|string
        cart_product_business_id: 产品业务ID|string
        cart_product_quantity: 产品数量|integer
        cart_status: 购物车状态|string
        cart_at_price: 加入购物车时价格|integer
        cart_remark: 备注|string
        is_delete: 删除标记|integer
        product_name: 产品名称|string
        product_modelnumber: 产品型号|string
        product_basic_price: 产品基础价格|integer
    CartListRequest:
      type: object
      properties:
        keyword:
          type: string
          description: 模糊搜索关键字
        cart_status:
          type: string
          description: 购物车状态
        cart_number:
          type: string
          description: 购物车名称或分组号
      example:
        keyword: 模糊搜索关键字|string
        cart_status: 购物车状态|string
        cart_number: 购物车名称或分组号|string
    CartDetailRequest:
      type: object
      required: [cart_id]
      properties:
        cart_id:
          type: string
          description: 购物车业务ID
      example:
        cart_id: 购物车业务ID|string
    CartCreateRequest:
      type: object
      required: [cart_product_id, cart_product_quantity, cart_at_price]
      properties:
        cart_number:
          type: string
        cart_product_id:
          type: string
          description: tbl_product_list 的 PocketBase recordId
        cart_product_quantity:
          type: [integer, number]
        cart_status:
          type: string
        cart_at_price:
          type: [integer, number]
        cart_remark:
          type: string
      example:
        cart_number: 可选；未传时服务端自动生成|string
        cart_product_id: tbl_product_list 的 PocketBase recordId|string
        cart_product_quantity: 产品数量|integer
        cart_status: 购物车状态|string
        cart_at_price: 加入购物车时价格|integer
        cart_remark: 备注|string
    CartUpdateRequest:
      type: object
      required: [cart_id]
      properties:
        cart_id:
          type: string
        cart_number:
          type: string
        cart_product_id:
          type: string
          description: tbl_product_list 的 PocketBase recordId
        cart_product_quantity:
          type: [integer, number]
        cart_status:
          type: string
        cart_at_price:
          type: [integer, number]
        cart_remark:
          type: string
      example:
        cart_id: 购物车业务ID|string
        cart_number: 购物车名称或分组号|string
        cart_product_id: tbl_product_list 的 PocketBase recordId|string
        cart_product_quantity: 产品数量|integer
        cart_status: 购物车状态|string
        cart_at_price: 加入购物车时价格|integer
        cart_remark: 备注|string
    CartDeleteRequest:
      type: object
      required: [cart_id]
      properties:
        cart_id:
          type: string
      example:
        cart_id: 购物车业务ID|string
    CartListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartRecord'
      example:
        items:
          - pb_id: PocketBase记录主键id|string
            created: PocketBase系统创建时间|string
            updated: PocketBase系统更新时间|string
            cart_id: 购物车业务ID|string
            cart_number: 购物车名称或分组号|string
            cart_create: 购物车项创建时间|string
            cart_owner: 购物车所有者openid|string
            cart_product_id: tbl_product_list 的 PocketBase recordId|string
            cart_product_business_id: 产品业务ID|string
            cart_product_quantity: 产品数量|integer
            cart_status: 购物车状态|string
            cart_at_price: 加入购物车时价格|integer
            cart_remark: 备注|string
    CartDeleteResponse:
      type: object
      properties:
        cart_id:
          type: string
        is_delete:
          type: [integer, number]
      example:
        cart_id: 购物车业务ID|string
        is_delete: 删除标记|integer