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

openapi: 3.1.0
info:
  title: BAI PocketBase WeChat API
  version: 1.0.0-wx
  description: |
    面向微信端的小程序接口文档。
    本文档包含微信登录、微信资料完善，以及微信小程序侧会直接调用的业务接口。

    微信小程序调用适配说明：
    - 除 `/pb/api/wechat/login` 外，其余购物车 / 订单接口都需要在请求头中携带 `Authorization: Bearer <token>`
    - `token` 取自 `/pb/api/wechat/login` 成功返回的认证 token
    - 小程序端应统一使用 HTTPS + JSON 请求体，不依赖 Cookie / Session
    - 购物车与订单接口的 owner 字段由服务端根据当前 token 自动绑定到 `tbl_auth_users.openid`
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://bai-api.blv-oa.com
    description: 生产环境
  - url: http://localhost:8090
    description: PocketBase 本地环境
tags:
  - name: 系统
    description: 微信端共用系统接口
  - name: 微信认证
    description: 微信登录、资料完善与 token 刷新接口
  - name: 企业信息
    description: 通过 PocketBase 原生 records API 访问 `tbl_company`
  - name: 附件信息
    description: 通过 PocketBase 原生 records API 访问 `tbl_attachments`
  - name: 产品信息
    description: 通过 PocketBase 原生 records API 访问 `tbl_product_list`
  - name: 文档信息
    description: 通过 PocketBase 原生 records API 访问 `tbl_document`
  - name: 购物车
    description: 微信小程序侧购物车 CRUD 接口
  - name: 订单
    description: 微信小程序侧订单 CRUD 接口
security: []
paths:
  /pb/api/system/users-count:
    post:
      security: []
      operationId: postSystemUsersCount
      tags:
        - 系统
      summary: 查询用户总数
      description: 统计 `tbl_auth_users` 集合中的记录总数。
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersCountResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/system/refresh-token:
    post:
      security:
        - BearerAuth: []
        - {}
      operationId: postSystemRefreshToken
      tags:
        - 系统
      summary: 刷新认证 token
      description: |
        当当前 `Authorization` 仍有效时，直接基于当前 auth 用户续签。
        当 token 失效时，可传入 `users_wx_code` 走微信 code 重新签发。
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SystemRefreshTokenRequest'
      responses:
        '200':
          description: 刷新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshTokenResponse'
        '400':
          description: 参数错误或微信 code 换取失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: token 无效，且未提供有效的 `users_wx_code`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 当前用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: 请求体不是 JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 请求过于频繁
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/wechat/login:
    post:
      security: []
      operationId: postWechatLogin
      tags:
        - 微信认证
      summary: 微信登录或首次注册
      description: |
        使用微信 `users_wx_code` 换取微信 openid。
        若 `tbl_auth_users` 中不存在对应用户，则自动创建新 auth 用户并返回 token。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WechatLoginRequest'
      responses:
        '200':
          description: 登录或注册成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthSuccessResponse'
        '400':
          description: 参数错误或保存用户失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 认证失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: 请求体不是 JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 请求过于频繁
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/wechat/profile:
    post:
      security:
        - BearerAuth: []
      operationId: postWechatProfile
      tags:
        - 微信认证
      summary: 更新微信用户资料
      description: |
        基于当前 `Authorization` 对应的 auth 用户按“非空字段增量更新”资料。

        更新规则：
        - 所有字段都不是必填
        - 如果传了 `users_phone_code`，服务端优先调用微信接口换取真实手机号并写入 `users_phone`
        - 如果没传 `users_phone_code`，但传了 `users_phone`，则直接将该手机号写入数据库
        - 如果上传了 `users_picture`、`users_id_pic_a`、`users_id_pic_b`、`users_title_picture`，会按附件 ID 进行关联校验并更新
        - 若当前用户类型为 `游客`，且本次未显式传 `users_type`，服务端会自动升级为 `注册用户`
        - 如果某个字段未传或传空，则不会清空数据库中的已有值
        - 只有请求体里非空的字段才会更新到数据库
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WechatProfileRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WechatProfileResponse'
        '400':
          description: 参数错误、手机号已被占用、附件 ID 无效、微信手机号换取失败或资料更新失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: token 无效或缺少 openid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: 请求体不是 JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 请求过于频繁
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/collections/tbl_company/records:
    post:
      operationId: postPocketBaseCompanyRecord
      tags:
        - 企业信息
      summary: 创建公司
      description: |
        使用 PocketBase 原生 records create 接口向 `tbl_company` 新增一行记录。

        当前线上权限规则：
        - `createRule = ""`，因此任何客户端都可直接创建
        - 其他原生操作中，`update/delete/view` 仅管理员或管理后台用户允许

        注意：
        - 这是 PocketBase 原生返回结构，不是 hooks 统一 `{ statusCode, errMsg, data }` 包装
        - `company_id` 由数据库自动生成，客户端创建时不需要传
        - `company_id` 仍带唯一索引，可用于后续按业务 id 查询
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PocketBaseCompanyCreateRequest'
            examples:
              default:
                value:
                  company_name: 微信侧测试企业
                  company_type: 渠道商
                  company_entity: 张三
                  company_usci: '91310000123456789A'
                  company_nationality: 中国
                  company_nationality_code: CN
                  company_province: 上海
                  company_province_code: '310000'
                  company_city: 上海
                  company_city_code: '310100'
                  company_district: 浦东新区
                  company_district_code: '310115'
                  company_postalcode: '200000'
                  company_add: 上海市浦东新区XX路1号
                  company_status: 有效
                  company_level: A
                  company_owner_openid: wx-openid-owner-001
                  company_remark: 小程序公开创建示例
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseCompanyRecord'
        '400':
          description: 参数错误或违反当前集合约束
          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'
    get:
      operationId: getPocketBaseCompanyRecords
      tags:
        - 企业信息
      summary: 查询整个 tbl_company 列表 / 根据 company_id 查询对应公司信息
      description: |
        使用 PocketBase 原生 records list 接口查询 `tbl_company`。

        当前线上权限规则：
        - `listRule = ""`，因此当前整个列表查询与条件查询都公开可读
        - `createRule = ""`，因此创建也公开可调用
        - `view/update/delete` 仅管理员或管理后台用户允许

        标准调用方式有两种：
        1. 根据 `company_id` 查询对应公司信息：
           - `filter=company_id="WX-COMPANY-10001"`
           - `perPage=1`
           - `page=1`
        2. 查询整个 `tbl_company` 列表：
           - 不传 `filter`
           - 按需传 `page`、`perPage`

        注意：
        - 这是 PocketBase 原生返回结构，不是 hooks 统一 `{ statusCode, errMsg, data }` 包装
        - PocketBase 原生标准接口里，“按 `company_id` 查询单条”和“查询整个列表”共用同一个 `GET /records` 路径，因此文档以同一个 GET operation 展示两种调用模式
      parameters:
        - name: filter
          in: query
          required: false
          description: |
            PocketBase 标准过滤表达式。

            - 根据 `company_id` 查询单条时：`company_id="WX-COMPANY-10001"`
            - 查询整个列表时：不传该参数
          schema:
            type: string
          example: company_id="WX-COMPANY-10001"
        - name: page
          in: query
          required: false
          description: 页码
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          required: false
          description: 每页条数；按 `company_id` 单查时建议固定为 `1`
          schema:
            type: integer
            minimum: 1
            default: 20
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseCompanyListResponse'
              examples:
                byCompanyId:
                  value:
                    page: 页码 | integer
                    perPage: 每页条数 | integer
                    totalItems: 总记录数 | integer
                    totalPages: 总页数 | integer
                    items:
                      - id: PocketBase记录主键 | string
                        collectionId: 集合ID | string
                        collectionName: 集合名称 | string
                        created: 记录创建时间 | string
                        updated: 记录更新时间 | string
                        company_id: 公司业务id，由数据库自动生成 | string
                        company_name: 公司名称 | string
                        company_type: 公司类型 | string
                        company_entity: 公司法人 | string
                        company_usci: 统一社会信用代码 | string
                        company_nationality: 国家名称 | string
                        company_nationality_code: 国家编码 | string
                        company_province: 省份名称 | string
                        company_province_code: 省份编码 | string
                        company_city: 城市名称 | string
                        company_city_code: 城市编码 | string
                        company_district: 区县名称 | string
                        company_district_code: 区县编码 | string
                        company_postalcode: 邮政编码 | string
                        company_add: 公司地址 | string
                        company_status: 公司状态 | string
                        company_level: 公司等级 | string
                        company_owner_openid: 公司所有者openid | string
                        company_remark: 备注 | string
                listAll:
                  value:
                    page: 页码 | integer
                    perPage: 每页条数 | integer
                    totalItems: 总记录数 | integer
                    totalPages: 总页数 | integer
                    items:
                      - id: PocketBase记录主键 | string
                        collectionId: 集合ID | string
                        collectionName: 集合名称 | string
                        created: 记录创建时间 | string
                        updated: 记录更新时间 | string
                        company_id: 公司业务id，由数据库自动生成 | string
                        company_name: 公司名称 | string
                        company_type: 公司类型 | string
                        company_entity: 公司法人 | string
                        company_usci: 统一社会信用代码 | string
                        company_nationality: 国家名称 | string
                        company_nationality_code: 国家编码 | string
                        company_province: 省份名称 | string
                        company_province_code: 省份编码 | string
                        company_city: 城市名称 | string
                        company_city_code: 城市编码 | string
                        company_district: 区县名称 | string
                        company_district_code: 区县编码 | string
                        company_postalcode: 邮政编码 | string
                        company_add: 公司地址 | string
                        company_status: 公司状态 | string
                        company_level: 公司等级 | string
                        company_owner_openid: 公司所有者openid | string
                        company_remark: 备注 | string
                notFoundByCompanyId:
                  value:
                    page: 页码 | integer
                    perPage: 每页条数 | integer
                    totalItems: 总记录数 | integer
                    totalPages: 总页数 | integer
                    items: []
        '400':
          description: 查询参数错误
          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_company/records/{recordId}:
    patch:
      operationId: patchPocketBaseCompanyRecordByRecordId
      tags:
        - 企业信息
      summary: 通过 company_id 定位后修改公司信息
      description: |
        这是 PocketBase 原生标准更新接口，实际写入路径参数仍然必须使用记录主键 `recordId`。

        如果前端手里只有 `company_id`，标准调用流程是：
        1. 先调用 `GET /pb/api/collections/tbl_company/records?filter=company_id="..."&perPage=1&page=1`
        2. 从返回结果 `items[0].id` 中取出 PocketBase 原生记录主键
        3. 再调用当前 `PATCH /pb/api/collections/tbl_company/records/{recordId}` 完成更新

        当前线上权限规则：
        - `updateRule` 仅管理员或管理后台用户允许
        - 普通公开调用不能直接更新
      parameters:
        - name: recordId
          in: path
          required: true
          description: 通过 `company_id` 查询结果拿到的 PocketBase 记录主键 `id`
          schema:
            type: string
          example: l2r3nq7rqhuob0h
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PocketBaseCompanyUpdateRequest'
            examples:
              default:
                value:
                  company_name: 微信侧测试企业（更新）
                  company_status: 有效
                  company_level: S
                  company_owner_openid: wx-openid-owner-001
                  company_district: 徐汇区
                  company_district_code: '310104'
                  company_remark: 通过 company_id 先定位再修改
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseCompanyRecord'
        '400':
          description: 参数错误或违反集合约束
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
        '403':
          description: 当前调用方没有 update 权限
          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'
  /pb/api/collections/tbl_attachments/records:
    get:
      operationId: getPocketBaseAttachmentRecords
      tags:
        - 附件信息
      summary: 根据 attachments_id 查询单条或多条附件信息
      description: |
        使用 PocketBase 原生 records list 接口查询 `tbl_attachments`。

        当前线上权限规则：
        - `listRule = ""`，因此任何客户端都可直接读取
        - 原生 `create/update/delete` 仍仅管理员或管理后台用户允许

        标准调用方式有两种：
        1. 按 `attachments_id` 查询单条：
           - `filter=attachments_id="ATT-1774599142438-8n1UcU"`
           - `perPage=1`
           - `page=1`
        2. 按多个 `attachments_id` 批量查询：
           - 使用 `||` 组合多个等值条件
           - 例如：`filter=attachments_id="ATT-1774599142438-8n1UcU" || attachments_id="ATT-1774599143999-7pQkLm"`
           - 传 `perPage` 为预期返回条数，`page=1`

        注意：
        - 这是 PocketBase 原生返回结构，不是 hooks 统一 `{ statusCode, errMsg, data }` 包装
        - `attachments_link` 返回的是 PocketBase 文件字段值，不是完整下载地址
        - 若需文件流地址，可按 PocketBase 标准文件路径自行拼接：`/pb/api/files/{collectionId}/{recordId}/{attachments_link}`
      parameters:
        - name: filter
          in: query
          required: false
          description: |
            PocketBase 标准过滤表达式。

            - 按 `attachments_id` 精确查询单条：`attachments_id="ATT-1774599142438-8n1UcU"`
            - 按多个 `attachments_id` 批量查询：`attachments_id="ATT-1774599142438-8n1UcU" || attachments_id="ATT-1774599143999-7pQkLm"`
            - 不传该参数时，返回分页列表
          schema:
            type: string
          example: attachments_id="ATT-1774599142438-8n1UcU"
        - name: page
          in: query
          required: false
          description: 页码
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          required: false
          description: 每页条数；单查建议为 `1`，批量查询建议设置为预期条数
          schema:
            type: integer
            minimum: 1
            default: 20
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseAttachmentListResponse'
              examples:
                byAttachmentsId:
                  value:
                    page: 页码 | integer
                    perPage: 每页条数 | integer
                    totalItems: 总记录数 | integer
                    totalPages: 总页数 | integer
                    items:
                      - id: PocketBase记录主键 | string
                        collectionId: 集合ID | string
                        collectionName: 集合名称 | string
                        attachments_id: 附件业务ID | string
                        attachments_link: PocketBase文件字段值，可拼接文件流地址 | string
                        attachments_filename: 原始文件名 | string
                        attachments_filetype: 文件类型或MIME | string
                        attachments_size: 文件大小 | number
                        attachments_owner: 上传者业务标识 | string
                        attachments_md5: 文件MD5 | string
                        attachments_ocr: OCR识别结果 | string
                        attachments_status: 附件状态 | string
                        attachments_remark: 备注 | string
                byAttachmentsIds:
                  value:
                    page: 页码 | integer
                    perPage: 每页条数 | integer
                    totalItems: 总记录数 | integer
                    totalPages: 总页数 | integer
                    items:
                      - id: PocketBase记录主键 | string
                        collectionId: 集合ID | string
                        collectionName: 集合名称 | string
                        attachments_id: ATT-1774599142438-8n1UcU
                        attachments_link: PocketBase文件字段值，可拼接文件流地址 | string
                        attachments_filename: 原始文件名 | string
                        attachments_filetype: 文件类型或MIME | string
                        attachments_size: 文件大小 | number
                        attachments_owner: 上传者业务标识 | string
                        attachments_md5: 文件MD5 | string
                        attachments_ocr: OCR识别结果 | string
                        attachments_status: 附件状态 | string
                        attachments_remark: 备注 | string
                      - id: PocketBase记录主键 | string
                        collectionId: 集合ID | string
                        collectionName: 集合名称 | string
                        attachments_id: ATT-1774599143999-7pQkLm
                        attachments_link: PocketBase文件字段值，可拼接文件流地址 | string
                        attachments_filename: 原始文件名 | string
                        attachments_filetype: 文件类型或MIME | string
                        attachments_size: 文件大小 | number
                        attachments_owner: 上传者业务标识 | string
                        attachments_md5: 文件MD5 | string
                        attachments_ocr: OCR识别结果 | string
                        attachments_status: 附件状态 | string
                        attachments_remark: 备注 | string
        '400':
          description: 查询参数错误
          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_product_list/records:
    get:
      operationId: getPocketBaseProductListRecords
      tags:
        - 产品信息
      summary: 根据产品分类精确筛选并按分类排序值升序返回产品列表
      description: |
        使用 PocketBase 原生 records list 接口查询 `tbl_product_list`。

        当前接口约定：
        - 条件：按 `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: '#/components/schemas/PocketBaseProductListListResponse'
              examples:
                byCategoryAscSort:
                  value:
                    page: <页码>|<integer>
                    perPage: <每页条数>|<integer>
                    totalItems: <总记录数>|<integer>
                    totalPages: <总页数>|<integer>
                    items:
                      - id: <PocketBase记录主键>|<string>
                        collectionId: <集合ID>|<string>
                        collectionName: <集合名称>|<string>
                        created: <记录创建时间>|<string>
                        updated: <记录更新时间>|<string>
                        prod_list_id: <产品列表业务ID>|<string>
                        prod_list_name: <产品名称>|<string>
                        prod_list_modelnumber: <产品型号>|<string>
                        prod_list_icon: <产品图标附件ID>|<string>
                        prod_list_description: <产品说明>|<string>
                        prod_list_feature: <产品特色>|<string>
                        prod_list_parameters:
                          - name: <属性名>|<string>
                            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_remark: <备注>|<string>
        '400':
          description: 查询参数错误
          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_document/records:
    get:
      operationId: getPocketBaseDocumentRecords
      tags:
        - 文档信息
      summary: 分页查询文档列表 / 按 system_dict_id 与 enum 双条件分页筛选文档
      description: |
        使用 PocketBase 原生 records list 接口查询 `tbl_document`。

        当前线上权限规则：
        - `listRule = ""`，因此任何客户端都可直接分页查询
        - `viewRule = ""`，因此单条详情也可公开读取
        - `create/update/delete` 仍仅管理员或管理后台用户允许

        `document_type` 的存储格式为：
        - `system_dict_id@dict_word_enum|system_dict_id@dict_word_enum`

        业务上这里是两个独立条件，并且查询时两个条件都要满足：
        - 条件 1：包含某个 `system_dict_id`
        - 条件 2：包含某个 `enum`

        PocketBase 原生标准接口实际只有一个 `filter` 参数，因此应在同一个 `filter` 中写成两个 `contains` 条件，例如：
        - `system_dict_id = DICT-1774599144591-hAEFQj`
        - `enum = UT1`
        - 最终：`document_type ~ "DICT-1774599144591-hAEFQj" && document_type ~ "@UT1"`

        这条写法已经按线上真实数据验证通过。

        排序说明：
        - 当前线上统一按 `document_create` 排序
        - 若要“最新上传的排在最前面”，请传 `sort=-document_create`

        标准调用方式有两种：
        1. 查询整个文档列表：
           - 不传 `filter`
           - 按需传 `page`、`perPage`
           - 若要按最新上传倒序，传 `sort=-document_create`
        2. 根据 `system_dict_id` 和 `enum` 两个业务条件分页筛选：
           - 直接传 `filter=document_type ~ "<system_dict_id>" && document_type ~ "@<enum>"`
           - 传 `page`、`perPage`
           - 若要按最新上传倒序，传 `sort=-document_create`

        注意：
        - 这是 PocketBase 原生返回结构，不是 hooks 统一 `{ statusCode, errMsg, data }` 包装
        - 如果需要更复杂的条件组合，可继续使用 PocketBase 原生 `filter` 语法自行扩展
      parameters:
        - name: filter
          in: query
          required: false
          description: |
            PocketBase 标准过滤表达式。

            - 查全部列表时：不传
            - 按业务条件筛选时，同时写两个 `contains` 条件
            - 第二个条件建议带上 `@` 前缀，避免误命中
            - 例如：`document_type ~ "DICT-1774599144591-hAEFQj" && document_type ~ "@UT1"`
          schema:
            type: string
          example: document_type ~ "DICT-1774599144591-hAEFQj" && document_type ~ "@UT1"
        - 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 原生排序表达式。

            当前线上建议使用：
            - `-document_create`：按最新上传倒序返回
          schema:
            type: string
          example: -document_create
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseDocumentListResponse'
              examples:
                listAll:
                  value:
                    page: 页码 | integer
                    perPage: 每页条数 | integer
                    totalItems: 总记录数 | integer
                    totalPages: 总页数 | integer
                    items:
                      - id: PocketBase记录主键 | string
                        collectionId: 集合ID | string
                        collectionName: 集合名称 | string
                        created: 记录创建时间 | string
                        updated: 记录更新时间 | string
                        document_id: 文档业务ID | string
                        document_create: 文档创建时间，由数据库自动生成 | string
                        document_effect_date: 文档生效日期 | string
                        document_expiry_date: 文档到期日期 | string
                        document_title: 文档标题 | string
                        document_type: 文档类型，按system_dict_id@dict_word_enum保存 | string
                        document_subtitle: 文档副标题 | string
                        document_summary: 文档摘要 | string
                        document_content: 正文内容 | string
                        document_image: 图片附件ID串，底层按|分隔 | string
                        document_video: 视频附件ID串，底层按|分隔 | string
                        document_file: 文件附件ID串，底层按|分隔 | string
                        document_status: 文档状态 | string
                        document_owner: 上传者openid | string
                        document_relation_model: 关联机型标识 | string
                        document_keywords: 关键词，多选按|分隔 | string
                        document_share_count: 分享次数 | number
                        document_download_count: 下载次数 | number
                        document_favorite_count: 收藏次数 | number
                        document_embedding_status: 文档嵌入状态 | string
                        document_embedding_error: 文档嵌入错误原因 | string
                        document_embedding_lasttime: 最后一次嵌入更新时间 | string
                        document_vector_version: 向量版本号或模型名称 | string
                        document_product_categories: 产品关联文档，多选按|分隔 | string
                        document_application_scenarios: 筛选依据，多选按|分隔 | string
                        document_hotel_type: 适用场景，多选按|分隔 | string
                        document_remark: 备注 | string
                filterByTypeToken:
                  value:
                    page: 页码 | integer
                    perPage: 每页条数 | integer
                    totalItems: 总记录数 | integer
                    totalPages: 总页数 | integer
                    items:
                      - id: PocketBase记录主键 | string
                        collectionId: 集合ID | string
                        collectionName: 集合名称 | string
                        created: 记录创建时间 | string
                        updated: 记录更新时间 | string
                        document_id: 文档业务ID | string
                        document_create: 文档创建时间，由数据库自动生成 | string
                        document_effect_date: 文档生效日期 | string
                        document_expiry_date: 文档到期日期 | string
                        document_title: 文档标题 | string
                        document_type: 文档类型，按system_dict_id@dict_word_enum保存 | string
                        document_subtitle: 文档副标题 | string
                        document_summary: 文档摘要 | string
                        document_content: 正文内容 | string
                        document_image: 图片附件ID串，底层按|分隔 | string
                        document_video: 视频附件ID串，底层按|分隔 | string
                        document_file: 文件附件ID串，底层按|分隔 | string
                        document_status: 文档状态 | string
                        document_owner: 上传者openid | string
                        document_relation_model: 关联机型标识 | string
                        document_keywords: 关键词，多选按|分隔 | string
                        document_share_count: 分享次数 | number
                        document_download_count: 下载次数 | number
                        document_favorite_count: 收藏次数 | number
                        document_embedding_status: 文档嵌入状态 | string
                        document_embedding_error: 文档嵌入错误原因 | string
                        document_embedding_lasttime: 最后一次嵌入更新时间 | string
                        document_vector_version: 向量版本号或模型名称 | string
                        document_product_categories: 产品关联文档，多选按|分隔 | string
                        document_application_scenarios: 筛选依据，多选按|分隔 | string
                        document_hotel_type: 适用场景，多选按|分隔 | string
                        document_remark: 备注 | string
                      - id: ofy47wp9mmm0aub
                        collectionId: pbc_3636602973
                        collectionName: tbl_document
                        created: '2026-03-28 07:20:00.000Z'
                        updated: '2026-03-28 07:20:00.000Z'
                        document_id: DOC-1774680568340-TeUSQn
                        document_create: '2026-03-28 08:22:48.000Z'
                        document_effect_date: ''
                        document_expiry_date: ''
                        document_title: 易从碳达人节能系统,为酒店每天每间房省二元,以智能推动酒店ESG双碳落地!上海酒店用品展我们在E7A01等您!!
                        document_type: DICT-1774599144591-hAEFQj@UT1
                        document_subtitle: ''
                        document_summary: ''
                        document_content: ''
                        document_image: ATT-1774680568287-zuhJWN
                        document_video: ''
                        document_file: ''
                        document_status: 有效
                        document_owner: su13106859882
                        document_relation_model: ''
                        document_keywords: ''
                        document_share_count: 0
                        document_download_count: 0
                        document_favorite_count: 0
                        document_embedding_status: ''
                        document_embedding_error: ''
                        document_embedding_lasttime: ''
                        document_vector_version: ''
                        document_product_categories: ''
                        document_application_scenarios: ''
                        document_hotel_type: ''
                        document_remark: ''
        '400':
          description: 查询参数错误
          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/cart/list:
    post:
      operationId: postCartList
      tags:
        - 购物车
      summary: 查询当前登录用户的购物车列表
      description: |
        返回当前 `Authorization` 对应 openid 名下的购物车记录。
        小程序端不需要传 `cart_owner`，服务端会自动基于 token 过滤。
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartListRequest'
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartListResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权访问目标数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: 请求体不是 JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/cart/detail:
    post:
      operationId: postCartDetail
      tags:
        - 购物车
      summary: 查询当前登录用户的购物车详情
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartDetailRequest'
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartDetailResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权访问目标数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 购物车记录不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: 请求体不是 JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/cart/create:
    post:
      operationId: postCartCreate
      tags:
        - 购物车
      summary: 创建购物车记录
      description: |
        `cart_owner`、`cart_create` 由服务端自动处理。
        小程序端只需要提交商品、数量、价格和可选备注。
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartCreateRequest'
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartMutationResponse'
        '400':
          description: 请求参数错误或产品不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: 请求体不是 JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 请求过于频繁
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/cart/update:
    post:
      operationId: postCartUpdate
      tags:
        - 购物车
      summary: 更新购物车记录
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartUpdateRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartMutationResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权访问目标数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 购物车记录不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: 请求体不是 JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 请求过于频繁
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/cart/delete:
    post:
      operationId: postCartDelete
      tags:
        - 购物车
      summary: 删除购物车记录
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartDeleteRequest'
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartDeleteResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权访问目标数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 购物车记录不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: 请求体不是 JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 请求过于频繁
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/order/list:
    post:
      operationId: postOrderList
      tags:
        - 订单
      summary: 查询当前登录用户的订单列表
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderListRequest'
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权访问目标数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: 请求体不是 JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/order/detail:
    post:
      operationId: postOrderDetail
      tags:
        - 订单
      summary: 查询当前登录用户的订单详情
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderDetailRequest'
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetailResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权访问目标数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 订单记录不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: 请求体不是 JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/order/create:
    post:
      operationId: postOrderCreate
      tags:
        - 订单
      summary: 创建订单
      description: |
        `order_owner`、`order_create` 由服务端自动处理。
        小程序端需要提交订单来源、来源 ID、订单快照和订单金额。
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreateRequest'
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderMutationResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: 请求体不是 JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 请求过于频繁
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/order/update:
    post:
      operationId: postOrderUpdate
      tags:
        - 订单
      summary: 更新订单
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdateRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderMutationResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权访问目标数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 订单记录不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: 请求体不是 JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 请求过于频繁
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pb/api/order/delete:
    post:
      operationId: postOrderDelete
      tags:
        - 订单
      summary: 删除订单
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderDeleteRequest'
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDeleteResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: token 缺失、无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权访问目标数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 订单记录不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: 请求体不是 JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 请求过于频繁
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  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:
          任意业务字段: 业务响应数据 | object
    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:
          任意错误字段: 错误附加信息 | object
    CartRecord:
      type: object
      required:
        - cart_id
        - cart_number
        - cart_create
        - cart_owner
        - cart_product_id
        - cart_product_quantity
        - cart_status
        - cart_at_price
      properties:
        pb_id:
          type: string
        cart_id:
          type: string
        cart_number:
          type: string
        cart_create:
          type: string
          description: 购物车项创建时间
        cart_owner:
          type: string
          description: 当前登录用户 openid
        cart_product_id:
          type: string
        cart_product_quantity:
          type: integer
        cart_status:
          type: string
        cart_at_price:
          type: number
        cart_remark:
          type: string
        product_name:
          type: string
        product_modelnumber:
          type: string
        product_basic_price:
          type:
            - number
            - 'null'
        created:
          type: string
        updated:
          type: string
    CartListRequest:
      type: object
      properties:
        keyword:
          type: string
          description: 按购物车编号、商品 ID、商品名称模糊搜索
        cart_status:
          type: string
        cart_number:
          type: string
    CartDetailRequest:
      type: object
      required:
        - cart_id
      properties:
        cart_id:
          type: string
    CartCreateRequest:
      type: object
      required:
        - cart_product_id
        - cart_product_quantity
        - cart_at_price
      properties:
        cart_number:
          type: string
        cart_product_id:
          type: string
        cart_product_quantity:
          type: integer
        cart_status:
          type: string
        cart_at_price:
          type: number
        cart_remark:
          type: string
    CartUpdateRequest:
      type: object
      required:
        - cart_id
      properties:
        cart_id:
          type: string
        cart_number:
          type: string
        cart_product_id:
          type: string
        cart_product_quantity:
          type: integer
        cart_status:
          type: string
        cart_at_price:
          type: number
        cart_remark:
          type: string
    CartDeleteRequest:
      type: object
      required:
        - cart_id
      properties:
        cart_id:
          type: string
    CartListResponse:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartRecord'
    CartDetailResponse:
      $ref: '#/components/schemas/CartRecord'
    CartMutationResponse:
      $ref: '#/components/schemas/CartRecord'
    CartDeleteResponse:
      type: object
      required:
        - cart_id
      properties:
        cart_id:
          type: string
    OrderRecord:
      type: object
      required:
        - order_id
        - order_number
        - order_create
        - order_owner
        - order_source
        - order_status
        - order_source_id
        - order_snap
        - order_amount
      properties:
        pb_id:
          type: string
        order_id:
          type: string
        order_number:
          type: string
        order_create:
          type: string
          description: 订单创建时间
        order_owner:
          type: string
          description: 当前登录用户 openid
        order_source:
          type: string
        order_status:
          type: string
        order_source_id:
          type: string
        order_snap:
          description: 下单快照
          oneOf:
            - type: object
              additionalProperties: true
            - type: array
              items:
                type: object
                additionalProperties: true
        order_amount:
          type: number
        order_remark:
          type: string
        created:
          type: string
        updated:
          type: string
    OrderListRequest:
      type: object
      properties:
        keyword:
          type: string
          description: 按订单编号、订单 ID、来源 ID 模糊搜索
        order_status:
          type: string
        order_source:
          type: string
    OrderDetailRequest:
      type: object
      required:
        - order_id
      properties:
        order_id:
          type: string
    OrderCreateRequest:
      type: object
      required:
        - order_source
        - order_source_id
        - order_snap
        - order_amount
      properties:
        order_number:
          type: string
        order_source:
          type: string
        order_status:
          type: string
        order_source_id:
          type: string
        order_snap:
          oneOf:
            - type: object
              additionalProperties: true
            - type: array
              items:
                type: object
                additionalProperties: true
        order_amount:
          type: number
        order_remark:
          type: string
    OrderUpdateRequest:
      type: object
      required:
        - order_id
      properties:
        order_id:
          type: string
        order_number:
          type: string
        order_source:
          type: string
        order_status:
          type: string
        order_source_id:
          type: string
        order_snap:
          oneOf:
            - type: object
              additionalProperties: true
            - type: array
              items:
                type: object
                additionalProperties: true
        order_amount:
          type: number
        order_remark:
          type: string
    OrderDeleteRequest:
      type: object
      required:
        - order_id
      properties:
        order_id:
          type: string
    OrderListResponse:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderRecord'
    OrderDetailResponse:
      $ref: '#/components/schemas/OrderRecord'
    OrderMutationResponse:
      $ref: '#/components/schemas/OrderRecord'
    OrderDeleteResponse:
      type: object
      required:
        - order_id
      properties:
        order_id:
          type: string
    CompanyInfo:
      anyOf:
        - type: object
          description: 用户所属公司信息；当用户尚未绑定公司时返回 `null`
          properties:
            pb_id:
              type: string
              description: PocketBase 记录主键 id
              example: PocketBase记录主键id | string
            company_id:
              type: string
              description: 公司业务 id，由数据库自动生成
              example: 公司业务id，由数据库自动生成 | string
            company_name:
              type: string
              description: 公司名称
              example: 公司名称 | string
            company_type:
              type: string
              description: 公司类型
              example: 公司类型 | string
            company_entity:
              type: string
              description: 公司法人
              example: 公司法人 | string
            company_usci:
              type: string
              description: 统一社会信用代码
              example: 统一社会信用代码 | string
            company_nationality:
              type: string
              description: 国家名称
              example: 国家名称 | string
            company_nationality_code:
              type: string
              description: 国家编码
              example: 国家编码 | string
            company_province:
              type: string
              description: 省份名称
              example: 省份名称 | string
            company_province_code:
              type: string
              description: 省份编码
              example: 省份编码 | string
            company_city:
              type: string
              description: 城市名称
              example: 城市名称 | string
            company_city_code:
              type: string
              description: 城市编码
              example: 城市编码 | string
            company_district:
              type: string
              description: 区/县名称
              example: 区县名称 | string
            company_district_code:
              type: string
              description: 区/县编码
              example: 区县编码 | string
            company_postalcode:
              type: string
              description: 邮政编码
              example: 邮政编码 | string
            company_add:
              type: string
              description: 公司地址
              example: 公司地址 | string
            company_status:
              type: string
              description: 公司状态
              example: 公司状态 | string
            company_level:
              type: string
              description: 公司等级
              example: 公司等级 | string
            company_owner_openid:
              type: string
              description: 公司所有者 openid
              example: 公司所有者openid | string
            company_remark:
              type: string
              description: 备注
              example: 备注 | string
            created:
              type: string
              description: 记录创建时间
              example: 记录创建时间 | string
            updated:
              type: string
              description: 记录更新时间
              example: 记录更新时间 | string
          example:
            pb_id: PocketBase记录主键id | string
            company_id: 公司业务id，由数据库自动生成 | string
            company_name: 公司名称 | string
            company_type: 公司类型 | string
            company_entity: 公司法人 | string
            company_usci: 统一社会信用代码 | string
            company_nationality: 国家名称 | string
            company_nationality_code: 国家编码 | string
            company_province: 省份名称 | string
            company_province_code: 省份编码 | string
            company_city: 城市名称 | string
            company_city_code: 城市编码 | string
            company_district: 区县名称 | string
            company_district_code: 区县编码 | string
            company_postalcode: 邮政编码 | string
            company_add: 公司地址 | string
            company_status: 公司状态 | string
            company_level: 公司等级 | string
            company_owner_openid: 公司所有者openid | string
            company_remark: 备注 | string
            created: 记录创建时间 | string
            updated: 记录更新时间 | string
        - type: 'null'
    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: 集合ID | string
        collectionName: 集合名称 | string
        created: 记录创建时间 | string
        updated: 记录更新时间 | string
    PocketBaseCompanyFields:
      type: object
      properties:
        company_id:
          type: string
          description: 公司业务 id，由数据库自动生成
          example: 公司业务id，由数据库自动生成 | string
        company_name:
          type: string
          description: 公司名称
          example: 公司名称 | string
        company_type:
          type: string
          description: 公司类型
          example: 公司类型 | string
        company_entity:
          type: string
          description: 公司法人
          example: 公司法人 | string
        company_usci:
          type: string
          description: 统一社会信用代码
          example: 统一社会信用代码 | string
        company_nationality:
          type: string
          description: 国家名称
          example: 国家名称 | string
        company_nationality_code:
          type: string
          description: 国家编码
          example: 国家编码 | string
        company_province:
          type: string
          description: 省份名称
          example: 省份名称 | string
        company_province_code:
          type: string
          description: 省份编码
          example: 省份编码 | string
        company_city:
          type: string
          description: 城市名称
          example: 城市名称 | string
        company_city_code:
          type: string
          description: 城市编码
          example: 城市编码 | string
        company_district:
          type: string
          description: 区/县名称
          example: 区县名称 | string
        company_district_code:
          type: string
          description: 区/县编码
          example: 区县编码 | string
        company_postalcode:
          type: string
          description: 邮政编码
          example: 邮政编码 | string
        company_add:
          type: string
          description: 公司地址
          example: 公司地址 | string
        company_status:
          type: string
          description: 公司状态
          example: 公司状态 | string
        company_level:
          type: string
          description: 公司等级
          example: 公司等级 | string
        company_owner_openid:
          type: string
          description: 公司所有者 openid
          example: 公司所有者openid | string
        company_remark:
          type: string
          description: 备注
          example: 备注 | string
    PocketBaseCompanyRecord:
      allOf:
        - $ref: '#/components/schemas/PocketBaseRecordBase'
        - $ref: '#/components/schemas/PocketBaseCompanyFields'
      example:
        id: PocketBase记录主键 | string
        collectionId: 集合ID | string
        collectionName: 集合名称 | string
        created: 记录创建时间 | string
        updated: 记录更新时间 | string
        company_id: 公司业务id，由数据库自动生成 | string
        company_name: 公司名称 | string
        company_type: 公司类型 | string
        company_entity: 公司法人 | string
        company_usci: 统一社会信用代码 | string
        company_nationality: 国家名称 | string
        company_nationality_code: 国家编码 | string
        company_province: 省份名称 | string
        company_province_code: 省份编码 | string
        company_city: 城市名称 | string
        company_city_code: 城市编码 | string
        company_district: 区县名称 | string
        company_district_code: 区县编码 | string
        company_postalcode: 邮政编码 | string
        company_add: 公司地址 | string
        company_status: 公司状态 | string
        company_level: 公司等级 | string
        company_owner_openid: 公司所有者openid | string
        company_remark: 备注 | string
    PocketBaseCompanyCreateRequest:
      type: object
      properties:
        company_name:
          description: "公司名称"
          type: string
        company_type:
          description: "公司类型"
          type: string
        company_entity:
          description: "公司法人"
          type: string
        company_usci:
          description: "统一社会信用代码"
          type: string
        company_nationality:
          description: "国家名称"
          type: string
        company_nationality_code:
          description: "国家编码"
          type: string
        company_province:
          description: "省份名称"
          type: string
        company_province_code:
          description: "省份编码"
          type: string
        company_city:
          description: "城市名称"
          type: string
        company_city_code:
          description: "城市编码"
          type: string
        company_district:
          description: "区 / 县名称"
          type: string
        company_district_code:
          description: "区 / 县编码"
          type: string
        company_postalcode:
          description: "邮编"
          type: string
        company_add:
          description: "地址"
          type: string
        company_status:
          description: "公司状态"
          type: string
        company_level:
          description: "公司等级"
          type: string
        company_owner_openid:
          description: "公司所有者 openid"
          type: string
        company_remark:
          description: "备注"
          type: string
      additionalProperties: false
    PocketBaseCompanyUpdateRequest:
      type: object
      properties:
        company_id:
          description: "所属公司业务 ID"
          type: string
        company_name:
          description: "公司名称"
          type: string
        company_type:
          description: "公司类型"
          type: string
        company_entity:
          description: "公司法人"
          type: string
        company_usci:
          description: "统一社会信用代码"
          type: string
        company_nationality:
          description: "国家名称"
          type: string
        company_nationality_code:
          description: "国家编码"
          type: string
        company_province:
          description: "省份名称"
          type: string
        company_province_code:
          description: "省份编码"
          type: string
        company_city:
          description: "城市名称"
          type: string
        company_city_code:
          description: "城市编码"
          type: string
        company_district:
          description: "区 / 县名称"
          type: string
        company_district_code:
          description: "区 / 县编码"
          type: string
        company_postalcode:
          description: "邮编"
          type: string
        company_add:
          description: "地址"
          type: string
        company_status:
          description: "公司状态"
          type: string
        company_level:
          description: "公司等级"
          type: string
        company_owner_openid:
          description: "公司所有者 openid"
          type: string
        company_remark:
          description: "备注"
          type: string
      additionalProperties: false
    PocketBaseCompanyListResponse:
      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: '#/components/schemas/PocketBaseCompanyRecord'
      example:
        page: 页码 | integer
        perPage: 每页条数 | integer
        totalItems: 总记录数 | integer
        totalPages: 总页数 | integer
        items:
          - id: PocketBase记录主键 | string
            collectionId: 集合ID | string
            collectionName: 集合名称 | string
            created: 记录创建时间 | string
            updated: 记录更新时间 | string
            company_id: 公司业务id，由数据库自动生成 | string
            company_name: 公司名称 | string
            company_type: 公司类型 | string
            company_entity: 公司法人 | string
            company_usci: 统一社会信用代码 | string
            company_nationality: 国家名称 | string
            company_nationality_code: 国家编码 | string
            company_province: 省份名称 | string
            company_province_code: 省份编码 | string
            company_city: 城市名称 | string
            company_city_code: 城市编码 | string
            company_district: 区县名称 | string
            company_district_code: 区县编码 | string
            company_postalcode: 邮政编码 | string
            company_add: 公司地址 | string
            company_status: 公司状态 | string
            company_level: 公司等级 | string
            company_owner_openid: 公司所有者openid | string
            company_remark: 备注 | string
    PocketBaseAttachmentRecord:
      type: object
      properties:
        id:
          type: string
          description: PocketBase 记录主键
          example: PocketBase记录主键 | string
        collectionId:
          type: string
          description: 集合ID
          example: 集合ID | string
        collectionName:
          type: string
          description: 集合名称
          example: 集合名称 | string
        attachments_id:
          type: string
          description: 附件业务 ID
          example: 附件业务ID | string
        attachments_link:
          type: string
          description: PocketBase 文件字段值，可按标准文件路径拼接文件流地址
          example: PocketBase文件字段值，可拼接文件流地址 | string
        attachments_filename:
          type: string
          description: 原始文件名
          example: 原始文件名 | string
        attachments_filetype:
          type: string
          description: 文件类型 / MIME
          example: 文件类型或MIME | string
        attachments_size:
          type:
            - number
            - integer
            - string
          description: 文件大小
          example: 文件大小 | number
        attachments_owner:
          type: string
          description: 上传者业务标识
          example: 上传者业务标识 | string
        attachments_md5:
          type: string
          description: 文件 MD5
          example: 文件MD5 | string
        attachments_ocr:
          type: string
          description: OCR 识别结果
          example: OCR识别结果 | string
        attachments_status:
          type: string
          description: 附件状态
          example: 附件状态 | string
        attachments_remark:
          type: string
          description: 备注
          example: 备注 | string
      example:
        id: PocketBase记录主键 | string
        collectionId: 集合ID | string
        collectionName: 集合名称 | string
        attachments_id: 附件业务ID | string
        attachments_link: PocketBase文件字段值，可拼接文件流地址 | string
        attachments_filename: 原始文件名 | string
        attachments_filetype: 文件类型或MIME | string
        attachments_size: 文件大小 | number
        attachments_owner: 上传者业务标识 | string
        attachments_md5: 文件MD5 | string
        attachments_ocr: OCR识别结果 | string
        attachments_status: 附件状态 | string
        attachments_remark: 备注 | string
    PocketBaseAttachmentListResponse:
      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: '#/components/schemas/PocketBaseAttachmentRecord'
      example:
        page: 页码 | integer
        perPage: 每页条数 | integer
        totalItems: 总记录数 | integer
        totalPages: 总页数 | integer
        items:
          - id: PocketBase记录主键 | string
            collectionId: 集合ID | string
            collectionName: 集合名称 | string
            attachments_id: 附件业务ID | string
            attachments_link: PocketBase文件字段值，可拼接文件流地址 | string
            attachments_filename: 原始文件名 | string
            attachments_filetype: 文件类型或MIME | string
            attachments_size: 文件大小 | number
            attachments_owner: 上传者业务标识 | string
            attachments_md5: 文件MD5 | string
            attachments_ocr: OCR识别结果 | string
            attachments_status: 附件状态 | string
            attachments_remark: 备注 | 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: <排序值>|<number>
        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: <基础价格>|<number>
        prod_list_remark:
          type: string
          description: 备注
          example: <备注>|<string>
    PocketBaseProductListRecord:
      allOf:
        - $ref: '#/components/schemas/PocketBaseRecordBase'
        - $ref: '#/components/schemas/PocketBaseProductListFields'
      example:
        id: <PocketBase记录主键>|<string>
        collectionId: <集合ID>|<string>
        collectionName: <集合名称>|<string>
        created: <记录创建时间>|<string>
        updated: <记录更新时间>|<string>
        prod_list_id: <产品列表业务ID>|<string>
        prod_list_name: <产品名称>|<string>
        prod_list_modelnumber: <产品型号>|<string>
        prod_list_icon: <产品图标附件ID>|<string>
        prod_list_description: <产品说明>|<string>
        prod_list_feature: <产品特色>|<string>
        prod_list_parameters:
          - name: <属性名>|<string>
            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_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: '#/components/schemas/PocketBaseProductListRecord'
      example:
        page: <页码>|<integer>
        perPage: <每页条数>|<integer>
        totalItems: <总记录数>|<integer>
        totalPages: <总页数>|<integer>
        items:
          - id: <PocketBase记录主键>|<string>
            collectionId: <集合ID>|<string>
            collectionName: <集合名称>|<string>
            created: <记录创建时间>|<string>
            updated: <记录更新时间>|<string>
            prod_list_id: <产品列表业务ID>|<string>
            prod_list_name: <产品名称>|<string>
            prod_list_modelnumber: <产品型号>|<string>
            prod_list_icon: <产品图标附件ID>|<string>
            prod_list_description: <产品说明>|<string>
            prod_list_feature: <产品特色>|<string>
            prod_list_parameters:
              - name: <属性名>|<string>
                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_remark: <备注>|<string>
    PocketBaseDocumentFields:
      type: object
      properties:
        document_id:
          type: string
          description: "文档业务 ID"
          example: 文档业务ID | string
        document_create:
          type: string
          description: "文档创建时间，由数据库自动生成"
          example: 文档创建时间，由数据库自动生成 | string
        document_effect_date:
          type: string
          description: "文档生效日期"
          example: 文档生效日期 | string
        document_expiry_date:
          type: string
          description: "文档到期日期"
          example: 文档到期日期 | string
        document_title:
          type: string
          description: "文档标题"
          example: 文档标题 | string
        document_type:
          type: string
          description: "文档类型，多选时按 system_dict_id@dict_word_enum|... 保存"
          example: 文档类型，按system_dict_id@dict_word_enum保存 | string
        document_subtitle:
          type: string
          description: "文档副标题"
          example: 文档副标题 | string
        document_summary:
          type: string
          description: "文档摘要"
          example: 文档摘要 | string
        document_content:
          type: string
          description: "正文内容，保存 Markdown"
          example: 正文内容 | string
        document_image:
          type: string
          description: "图片附件 ID 集合，底层以 | 分隔"
          example: 图片附件ID串，底层按|分隔 | string
        document_video:
          type: string
          description: "视频附件 ID 集合，底层以 | 分隔"
          example: 视频附件ID串，底层按|分隔 | string
        document_file:
          type: string
          description: "文件附件 ID 集合，底层以 | 分隔"
          example: 文件附件ID串，底层按|分隔 | string
        document_status:
          type: string
          description: "文档状态，仅 `有效` / `过期`"
          example: 文档状态 | string
        document_owner:
          type: string
          description: "上传者 openid"
          example: 上传者openid | string
        document_relation_model:
          type: string
          description: "关联机型 / 模型标识"
          example: 关联机型标识 | string
        document_keywords:
          type: string
          description: "关键词，多选后以 | 分隔"
          example: 关键词，多选按|分隔 | string
        document_share_count:
          type: number
          description: "分享次数"
          example: 分享次数 | number
        document_download_count:
          type: number
          description: "下载次数"
          example: 下载次数 | number
        document_favorite_count:
          type: number
          description: "收藏次数"
          example: 收藏次数 | number
        document_embedding_status:
          type: string
          description: "文档嵌入状态"
          example: 文档嵌入状态 | string
        document_embedding_error:
          type: string
          description: "文档嵌入错误原因"
          example: 文档嵌入错误原因 | string
        document_embedding_lasttime:
          type: string
          description: "最后一次嵌入更新时间"
          example: 最后一次嵌入更新时间 | string
        document_vector_version:
          type: string
          description: "向量版本号 / 模型名称"
          example: 向量版本号或模型名称 | string
        document_product_categories:
          type: string
          description: "产品关联文档，多选后以 | 分隔"
          example: 产品关联文档，多选按|分隔 | string
        document_application_scenarios:
          type: string
          description: "筛选依据，多选后以 | 分隔"
          example: 筛选依据，多选按|分隔 | string
        document_hotel_type:
          type: string
          description: "适用场景，多选后以 | 分隔"
          example: 适用场景，多选按|分隔 | string
        document_remark:
          type: string
          description: "备注"
          example: 备注 | string
    PocketBaseDocumentRecord:
      allOf:
        - $ref: '#/components/schemas/PocketBaseRecordBase'
        - $ref: '#/components/schemas/PocketBaseDocumentFields'
      example:
        id: PocketBase记录主键 | string
        collectionId: 集合ID | string
        collectionName: 集合名称 | string
        created: 记录创建时间 | string
        updated: 记录更新时间 | string
        document_id: 文档业务ID | string
        document_create: 文档创建时间，由数据库自动生成 | string
        document_effect_date: 文档生效日期 | string
        document_expiry_date: 文档到期日期 | string
        document_title: 文档标题 | string
        document_type: 文档类型，按system_dict_id@dict_word_enum保存 | string
        document_subtitle: 文档副标题 | string
        document_summary: 文档摘要 | string
        document_content: 正文内容 | string
        document_image: 图片附件ID串，底层按|分隔 | string
        document_video: 视频附件ID串，底层按|分隔 | string
        document_file: 文件附件ID串，底层按|分隔 | string
        document_status: 文档状态 | string
        document_owner: 上传者openid | string
        document_relation_model: 关联机型标识 | string
        document_keywords: 关键词，多选按|分隔 | string
        document_share_count: 分享次数 | number
        document_download_count: 下载次数 | number
        document_favorite_count: 收藏次数 | number
        document_embedding_status: 文档嵌入状态 | string
        document_embedding_error: 文档嵌入错误原因 | string
        document_embedding_lasttime: 最后一次嵌入更新时间 | string
        document_vector_version: 向量版本号或模型名称 | string
        document_product_categories: 产品关联文档，多选按|分隔 | string
        document_application_scenarios: 筛选依据，多选按|分隔 | string
        document_hotel_type: 适用场景，多选按|分隔 | string
        document_remark: 备注 | string
    PocketBaseDocumentListResponse:
      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: '#/components/schemas/PocketBaseDocumentRecord'
      example:
        page: 页码 | integer
        perPage: 每页条数 | integer
        totalItems: 总记录数 | integer
        totalPages: 总页数 | integer
        items:
          - id: PocketBase记录主键 | string
            collectionId: 集合ID | string
            collectionName: 集合名称 | string
            created: 记录创建时间 | string
            updated: 记录更新时间 | string
            document_id: 文档业务ID | string
            document_create: 文档创建时间，由数据库自动生成 | string
            document_effect_date: 文档生效日期 | string
            document_expiry_date: 文档到期日期 | string
            document_title: 文档标题 | string
            document_type: 文档类型，按system_dict_id@dict_word_enum保存 | string
            document_subtitle: 文档副标题 | string
            document_summary: 文档摘要 | string
            document_content: 正文内容 | string
            document_image: 图片附件ID串，底层按|分隔 | string
            document_video: 视频附件ID串，底层按|分隔 | string
            document_file: 文件附件ID串，底层按|分隔 | string
            document_status: 文档状态 | string
            document_owner: 上传者openid | string
            document_relation_model: 关联机型标识 | string
            document_keywords: 关键词，多选按|分隔 | string
            document_share_count: 分享次数 | number
            document_download_count: 下载次数 | number
            document_favorite_count: 收藏次数 | number
            document_embedding_status: 文档嵌入状态 | string
            document_embedding_error: 文档嵌入错误原因 | string
            document_embedding_lasttime: 最后一次嵌入更新时间 | string
            document_vector_version: 向量版本号或模型名称 | string
            document_product_categories: 产品关联文档，多选按|分隔 | string
            document_application_scenarios: 筛选依据，多选按|分隔 | string
            document_hotel_type: 适用场景，多选按|分隔 | string
            document_remark: 备注 | 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: PocketBase原生错误信息 | string
        data:
          任意错误字段: 原生错误附加信息 | object
    UserInfo:
      type: object
      properties:
        pb_id:
          description: "PocketBase 记录主键 id"
          type: string
        users_convers_id:
          description: "会话侧用户 ID"
          type: string
        users_id:
          description: "用户业务 ID"
          type: string
        users_idtype:
          description: "身份来源类型或证件类型"
          anyOf:
            - type: string
              enum:
                - WeChat
                - ManagePlatform
            - type: string
        users_id_number:
          description: "证件号"
          type: string
        users_type:
          description: "用户类型"
          anyOf:
            - type: string
              enum:
                - 游客
                - 注册用户
            - type: string
        users_name:
          description: "用户姓名 / 昵称"
          type: string
        users_status:
          description: "用户状态"
          type:
            - string
            - number
        users_rank_level:
          description: "用户星级数值"
          type:
            - number
            - integer
            - string
        users_auth_type:
          description: "账户类型"
          type:
            - number
            - integer
            - string
        users_phone:
          description: "手机号"
          type: string
        users_phone_masked:
          type: string
        users_level:
          type: string
          description: 用户等级
        users_tag:
          type: string
          description: 用户标签
        users_picture:
          type: string
          description: 用户头像附件的 `attachments_id`
        users_picture_url:
          type: string
          description: 根据 `users_picture -> tbl_attachments` 自动解析出的头像文件流链接
        users_id_pic_a:
          type: string
          description: 证件正面附件的 `attachments_id`
        users_id_pic_a_url:
          type: string
          description: 根据 `users_id_pic_a -> tbl_attachments` 自动解析出的文件流链接
        users_id_pic_b:
          type: string
          description: 证件反面附件的 `attachments_id`
        users_id_pic_b_url:
          type: string
          description: 根据 `users_id_pic_b -> tbl_attachments` 自动解析出的文件流链接
        users_title_picture:
          type: string
          description: 资质附件的 `attachments_id`
        users_title_picture_url:
          type: string
          description: 根据 `users_title_picture -> tbl_attachments` 自动解析出的文件流链接
        openid:
          type: string
          description: 全平台统一身份标识
        company_id:
          type: string
          description: 公司业务 id，存储 `tbl_company.company_id`
        users_parent_id:
          type: string
          description: 上级用户业务 id
        users_promo_code:
          type: string
          description: 推广码
        usergroups_id:
          type: string
          description: 用户组业务 id
        company:
          $ref: '#/components/schemas/CompanyInfo'
        created:
          type: string
          description: 用户创建时间
        updated:
          type: string
          description: 用户更新时间
      example:
        pb_id: PocketBase记录主键id | string
        users_convers_id: 会话侧用户ID | string
        users_id: 用户业务ID | string
        users_idtype: 用户身份来源类型 | string
        users_id_number: 证件号 | string
        users_type: 用户类型 | string
        users_name: 用户姓名或昵称 | string
        users_status: 用户状态 | string
        users_rank_level: 用户星级数值 | number
        users_auth_type: 账户类型 | number
        users_phone: 手机号 | string
        users_phone_masked: 手机号脱敏值 | string
        users_level: 用户等级 | string
        users_tag: 用户标签 | string
        users_picture: 用户头像附件ID | string
        users_picture_url: 用户头像文件流链接 | string
        users_id_pic_a: 证件正面附件ID | string
        users_id_pic_a_url: 证件正面文件流链接 | string
        users_id_pic_b: 证件反面附件ID | string
        users_id_pic_b_url: 证件反面文件流链接 | string
        users_title_picture: 资质附件ID | string
        users_title_picture_url: 资质附件文件流链接 | string
        openid: 全平台统一身份标识 | string
        company_id: 公司业务id | string
        users_parent_id: 上级用户业务id | string
        users_promo_code: 推广码 | string
        usergroups_id: 用户组业务id | string
        company:
          pb_id: PocketBase记录主键id | string
          company_id: 公司业务id，由数据库自动生成 | string
          company_name: 公司名称 | string
          company_type: 公司类型 | string
          company_entity: 公司法人 | string
          company_usci: 统一社会信用代码 | string
          company_nationality: 国家名称 | string
          company_nationality_code: 国家编码 | string
          company_province: 省份名称 | string
          company_province_code: 省份编码 | string
          company_city: 城市名称 | string
          company_city_code: 城市编码 | string
          company_district: 区县名称 | string
          company_district_code: 区县编码 | string
          company_postalcode: 邮政编码 | string
          company_add: 公司地址 | string
          company_status: 公司状态 | string
          company_level: 公司等级 | string
          company_owner_openid: 公司所有者openid | string
          company_remark: 备注 | string
          created: 记录创建时间 | string
          updated: 记录更新时间 | string
        created: 用户创建时间 | string
        updated: 用户更新时间 | string
    WechatLoginRequest:
      type: object
      required:
        - users_wx_code
      properties:
        users_wx_code:
          type: string
          description: 微信小程序登录临时凭证 code
          example: 0a1b2c3d4e5f6g
    WechatProfileRequest:
      type: object
      properties:
        users_name:
          type: string
          description: "用户姓名 / 昵称"
          example: 张三
        users_phone_code:
          type: string
          description: 可选。若传入，服务端优先通过微信接口换取真实手机号并写入数据库
          example: 2b7d9f2e3c4a5b6d7e8f
        users_phone:
          type: string
          description: 可选。未传 `users_phone_code` 时，可直接写入手机号
          example: '13800138000'
        users_type:
          type: string
          description: 可选。用户类型；仅在传入非空值时更新
          example: 服务商
        company_id:
          type: string
          description: 可选。公司业务 id；仅在传入非空值时更新
          example: WX-COMPANY-10001
        users_tag:
          type: string
          description: 可选。用户标签；非空时才更新
          example: 核心客户
        users_picture:
          type: string
          description: 可选。用户头像附件的 `attachments_id`
          example: ATT-1743123456789-abc123
        users_id_pic_a:
          type: string
          description: 可选。证件正面附件的 `attachments_id`
        users_id_pic_b:
          type: string
          description: 可选。证件反面附件的 `attachments_id`
        users_title_picture:
          type: string
          description: 可选。资质附件的 `attachments_id`
    SystemRefreshTokenRequest:
      type: object
      properties:
        users_wx_code:
          type:
            - string
            - 'null'
          description: |
            可选。
            当前 token 失效时，可通过该 code 重新签发 token。
          example: 0a1b2c3d4e5f6g
    AuthSuccessData:
      type: object
      properties:
        status:
          anyOf:
            - type: string
              enum:
                - register_success
                - login_success
            - type: string
        is_info_complete:
          type:
            - boolean
            - string
        user:
          $ref: '#/components/schemas/UserInfo'
    AuthSuccessResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponseBase'
        - type: object
          required:
            - token
          properties:
            data:
              description: "业务响应数据"
              $ref: '#/components/schemas/AuthSuccessData'
            token:
              type: string
              description: PocketBase 原生 auth token
      example:
        statusCode: 业务状态码 | integer
        errMsg: 业务提示信息 | string
        data:
          status: 登录或注册状态 | string
          is_info_complete: 资料是否完整 | boolean
          user:
            pb_id: PocketBase记录主键id | string
            users_convers_id: 会话侧用户ID | string
            users_id: 用户业务ID | string
            users_idtype: 用户身份来源类型 | string
            users_id_number: 证件号 | string
            users_type: 用户类型 | string
            users_name: 用户姓名或昵称 | string
            users_status: 用户状态 | string
            users_rank_level: 用户星级数值 | number
            users_auth_type: 账户类型 | number
            users_phone: 手机号 | string
            users_phone_masked: 手机号脱敏值 | string
            users_level: 用户等级 | string
            users_tag: 用户标签 | string
            users_picture: 用户头像附件ID | string
            users_picture_url: 用户头像文件流链接 | string
            users_id_pic_a: 证件正面附件ID | string
            users_id_pic_a_url: 证件正面文件流链接 | string
            users_id_pic_b: 证件反面附件ID | string
            users_id_pic_b_url: 证件反面文件流链接 | string
            users_title_picture: 资质附件ID | string
            users_title_picture_url: 资质附件文件流链接 | string
            openid: 全平台统一身份标识 | string
            company_id: 公司业务id | string
            users_parent_id: 上级用户业务id | string
            users_promo_code: 推广码 | string
            usergroups_id: 用户组业务id | string
            company:
              pb_id: PocketBase记录主键id | string
              company_id: 公司业务id，由数据库自动生成 | string
              company_name: 公司名称 | string
              company_type: 公司类型 | string
              company_entity: 公司法人 | string
              company_usci: 统一社会信用代码 | string
              company_nationality: 国家名称 | string
              company_nationality_code: 国家编码 | string
              company_province: 省份名称 | string
              company_province_code: 省份编码 | string
              company_city: 城市名称 | string
              company_city_code: 城市编码 | string
              company_district: 区县名称 | string
              company_district_code: 区县编码 | string
              company_postalcode: 邮政编码 | string
              company_add: 公司地址 | string
              company_status: 公司状态 | string
              company_level: 公司等级 | string
              company_owner_openid: 公司所有者openid | string
              company_remark: 备注 | string
              created: 记录创建时间 | string
              updated: 记录更新时间 | string
            created: 用户创建时间 | string
            updated: 用户更新时间 | string
        token: PocketBase原生认证token | string
    WechatProfileResponseData:
      type: object
      properties:
        status:
          anyOf:
            - type: string
              enum:
                - update_success
            - type: string
        user:
          $ref: '#/components/schemas/UserInfo'
    WechatProfileResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponseBase'
        - type: object
          properties:
            data:
              description: "业务响应数据"
              $ref: '#/components/schemas/WechatProfileResponseData'
      example:
        statusCode: 业务状态码 | integer
        errMsg: 业务提示信息 | string
        data:
          status: 资料更新状态 | string
          user:
            pb_id: PocketBase记录主键id | string
            users_convers_id: 会话侧用户ID | string
            users_id: 用户业务ID | string
            users_idtype: 用户身份来源类型 | string
            users_id_number: 证件号 | string
            users_type: 用户类型 | string
            users_name: 用户姓名或昵称 | string
            users_status: 用户状态 | string
            users_rank_level: 用户星级数值 | number
            users_auth_type: 账户类型 | number
            users_phone: 手机号 | string
            users_phone_masked: 手机号脱敏值 | string
            users_level: 用户等级 | string
            users_tag: 用户标签 | string
            users_picture: 用户头像附件ID | string
            users_picture_url: 用户头像文件流链接 | string
            users_id_pic_a: 证件正面附件ID | string
            users_id_pic_a_url: 证件正面文件流链接 | string
            users_id_pic_b: 证件反面附件ID | string
            users_id_pic_b_url: 证件反面文件流链接 | string
            users_title_picture: 资质附件ID | string
            users_title_picture_url: 资质附件文件流链接 | string
            openid: 全平台统一身份标识 | string
            company_id: 公司业务id | string
            users_parent_id: 上级用户业务id | string
            users_promo_code: 推广码 | string
            usergroups_id: 用户组业务id | string
            company:
              pb_id: PocketBase记录主键id | string
              company_id: 公司业务id，由数据库自动生成 | string
              company_name: 公司名称 | string
              company_type: 公司类型 | string
              company_entity: 公司法人 | string
              company_usci: 统一社会信用代码 | string
              company_nationality: 国家名称 | string
              company_nationality_code: 国家编码 | string
              company_province: 省份名称 | string
              company_province_code: 省份编码 | string
              company_city: 城市名称 | string
              company_city_code: 城市编码 | string
              company_district: 区县名称 | string
              company_district_code: 区县编码 | string
              company_postalcode: 邮政编码 | string
              company_add: 公司地址 | string
              company_status: 公司状态 | string
              company_level: 公司等级 | string
              company_owner_openid: 公司所有者openid | string
              company_remark: 备注 | string
              created: 记录创建时间 | string
              updated: 记录更新时间 | string
            created: 用户创建时间 | string
            updated: 用户更新时间 | string
    RefreshTokenResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponseBase'
        - type: object
          required:
            - token
          properties:
            data:
              type: object
              additionalProperties: true
              description: "业务响应数据"
              example: {}
            token:
              type: string
              description: 新签发的 PocketBase 原生 auth token
      example:
        statusCode: 业务状态码 | integer
        errMsg: 刷新成功 | string
        data: {}
        token: 新签发的PocketBase原生auth token | string
    UsersCountData:
      type: object
      properties:
        total_users:
          type:
            - integer
            - string
          example: 用户总数 | integer
    UsersCountResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponseBase'
        - type: object
          properties:
            data:
              description: "业务响应数据"
              $ref: '#/components/schemas/UsersCountData'
      example:
        statusCode: 业务状态码 | integer
        errMsg: 业务提示信息 | string
        data:
          total_users: 用户总数 | integer