openapi: 3.1.0
info:
  title: BAI PocketBase Native API - Cart
  version: 1.0.0
  description: |
    PocketBase 原生 `tbl_cart` records API 文档。
    本文件可单独导入使用，不依赖其他 YAML。
servers:
  - url: https://bai-api.blv-oa.com
    description: 生产环境
  - url: http://localhost:8090
    description: PocketBase 本地环境
tags:
  - name: 购物车
    description: PocketBase 原生购物车记录接口
paths:
  /pb/api/collections/tbl_cart/records:
    get:
      operationId: getPocketBaseCartRecords
      tags: [购物车]
      summary: 查询购物车记录列表
      description: |
        使用 PocketBase 原生 records list 接口查询 `tbl_cart`。

        说明：
        - `cart_product_id` 是 relation 字段，默认仅返回关联记录 id。
        - 如需同时返回 `tbl_product_list` 详情，请传 `expand=cart_product_id`。
      parameters:
        - name: filter
          in: query
          required: false
          schema:
            type: string
          description: PocketBase 原生过滤表达式
          example: 过滤表达式|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: 排序表达式|string
        - name: expand
          in: query
          required: false
          schema:
            type: string
          description: 关系字段展开；传 `cart_product_id` 时返回 `expand.cart_product_id`
          example: 关联展开字段|string
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseCartListResponse'
        '400':
          description: 查询参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
        '401':
          description: token 无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
        '403':
          description: 无权访问
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
    post:
      operationId: postPocketBaseCartRecord
      tags: [购物车]
      summary: 创建购物车记录
      description: |
        使用 PocketBase 原生 records create 接口向 `tbl_cart` 新增记录。
      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: 产品业务ID|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: 参数错误或违反集合规则
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
        '401':
          description: token 无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
        '403':
          description: 无权访问
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
  /pb/api/collections/tbl_cart/records/{recordId}:
    patch:
      operationId: patchPocketBaseCartRecordByRecordId
      tags: [购物车]
      summary: 更新购物车记录
      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: 产品业务ID|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: 参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
        '401':
          description: token 无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
        '404':
          description: 记录不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
    delete:
      operationId: deletePocketBaseCartRecordByRecordId
      tags: [购物车]
      summary: 删除购物车记录
      parameters:
        - name: recordId
          in: path
          required: true
          schema:
            type: string
          example: PocketBase记录主键|string
      responses:
        '204':
          description: 删除成功
        '401':
          description: token 无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
        '404':
          description: 记录不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
components:
  schemas:
    PocketBaseNativeError:
      type: object
      properties:
        code:
          type: [integer, string]
          description: PocketBase错误码
        message:
          type: string
          description: PocketBase错误信息
        data:
          type: object
          additionalProperties: true
          description: PocketBase错误数据
      example:
        code: 错误状态码|integer
        message: PocketBase原生错误信息|string
        data:
          字段名|string: 字段值|string
    PocketBaseRecordBase:
      type: object
      required: [id, collectionId, collectionName, created, updated]
      properties:
        id:
          type: string
          description: PocketBase记录主键
        collectionId:
          type: string
          description: 集合ID
        collectionName:
          type: string
          description: 集合名称
        created:
          type: string
          description: 记录创建时间
        updated:
          type: string
          description: 记录更新时间
      example:
        id: PocketBase记录主键|string
        collectionId: 集合ID|string
        collectionName: 集合名称|string
        created: 记录创建时间|string
        updated: 记录更新时间|string
    PocketBaseCartFields:
      type: object
      properties:
        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: 产品业务ID
        cart_product_quantity:
          type: [integer, number]
          description: 产品数量
        cart_status:
          type: string
          description: 购物车状态
        cart_at_price:
          type: [number, integer]
          description: 加入购物车时价格
        cart_remark:
          type: string
          description: 备注
      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: '#/components/schemas/PocketBaseRecordBase'
        - $ref: '#/components/schemas/PocketBaseCartFields'
        - type: object
          properties:
            expand:
              type: object
              description: 关系字段展开结果（需请求参数 `expand=cart_product_id`）
              properties:
                cart_product_id:
                  $ref: '#/components/schemas/PocketBaseProductListExpand'
    PocketBaseCartCreateRequest:
      type: object
      required: [cart_owner]
      properties:
        cart_id:
          type: string
          example: 购物车业务ID|string
        cart_number:
          type: string
          example: 购物车名称或分组号|string
        cart_owner:
          type: string
          example: 购物车所有者openid|string
        cart_product_id:
          type: string
          example: 产品业务ID|string
        cart_product_quantity:
          type: [integer, number]
          example: 产品数量|integer
        cart_status:
          type: string
          example: 购物车状态|string
        cart_at_price:
          type: [number, integer]
          example: 加入购物车时价格|number
        cart_remark:
          type: string
          example: 备注|string
    PocketBaseCartUpdateRequest:
      type: object
      properties:
        cart_number:
          type: string
          example: 购物车名称或分组号|string
        cart_owner:
          type: string
          example: 购物车所有者openid|string
        cart_product_id:
          type: string
          example: 产品业务ID|string
        cart_product_quantity:
          type: [integer, number]
          example: 产品数量|integer
        cart_status:
          type: string
          example: 购物车状态|string
        cart_at_price:
          type: [number, integer]
          example: 加入购物车时价格|number
        cart_remark:
          type: string
          example: 备注|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: '#/components/schemas/PocketBaseCartRecord'
    PocketBaseProductListExpand:
      type: object
      description: tbl_product_list 关联展开后的记录对象（示例字段）
      properties:
        id:
          type: string
          description: PocketBase记录主键
          example: PocketBase记录主键|string
        collectionId:
          type: string
          description: 集合ID
          example: 集合ID|string
        collectionName:
          type: string
          description: 集合名称
          example: 集合名称|string
        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_basic_price:
          type: [number, integer]
          description: 基础价格
          example: 基础价格|number
        prod_list_status:
          type: string
          description: 产品状态
          example: 产品状态|string