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

paths:
  documentRecords:
    get:
      operationId: getPocketBaseDocumentRecords
      tags:
        - 文档信息
      summary: 分页查询文档列表 / 按 system_dict_id 与 enum 双条件分页筛选文档
      description: |
        使用 PocketBase 原生 records list 接口查询 `tbl_document`。

        当前线上权限规则：
        - `listRule = is_delete = 0`，因此任何客户端都可直接分页查询未软删除文档
        - `viewRule = is_delete = 0`，因此单条详情也只可读取未软删除文档
        - `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: ../openapi-wx.yaml#/components/schemas/PocketBaseDocumentListResponse
              example:
                page: page|integer
                perPage: perPage|integer
                totalItems: totalItems|integer
                totalPages: totalPages|integer
                items:
                  - id: PocketBase 记录主键|string
                    collectionId: collectionId|string
                    collectionName: collectionName|string
                    created: 记录创建时间|string
                    updated: 记录更新时间|string
                    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: 正文内容，保存 Markdown|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
        "400":
          description: 查询参数错误
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "403":
          description: 集合规则被锁定或服务端权限设置异常
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
        "500":
          description: 服务端错误
          content:
            application/json:
              schema:
                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
              example:
                code: 业务状态码|integer
                message: message|string
                data:
                  业务响应数据字段|string: 业务响应数据值|string
components:
  schemas:
    PocketBaseNativeError:
      type: object
      properties:
        code:
          type:
            - integer
            - string
          description: 业务状态码
          example: 错误状态码 | integer
        message:
          type: string
          example: PocketBase原生错误信息 | string
        data:
          description: 业务响应数据
          type: object
          additionalProperties: true
      example:
        code: 业务状态码|integer
        message: message|string
        data:
          业务响应数据字段|string: 业务响应数据值|string
    PocketBaseRecordBase:
      type: object
      required:
        - id
        - collectionId
        - collectionName
        - created
        - updated
      properties:
        id:
          type: string
          description: PocketBase 记录主键
          example: PocketBase记录主键 | string
        collectionId:
          type: string
          example: 集合ID | string
        collectionName:
          type: string
          example: 集合名称 | string
        created:
          type: string
          description: 记录创建时间
          example: 记录创建时间 | string
        updated:
          type: string
          description: 记录更新时间
          example: 记录更新时间 | string
      example:
        id: PocketBase 记录主键|string
        collectionId: collectionId|string
        collectionName: collectionName|string
        created: 记录创建时间|string
        updated: 记录更新时间|string
    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: 0
        document_download_count:
          type: number
          description: 下载次数
          example: 0
        document_favorite_count:
          type: number
          description: 收藏次数
          example: 0
        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
      example:
        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: 正文内容，保存 Markdown|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
    PocketBaseDocumentRecord:
      allOf:
        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseRecordBase
        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseDocumentFields
      example:
        id: PocketBase 记录主键|string
        collectionId: collectionId|string
        collectionName: 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: 正文内容，保存 Markdown|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: ../openapi-wx.yaml#/components/schemas/PocketBaseDocumentRecord
      example:
        page: page|integer
        perPage: perPage|integer
        totalItems: totalItems|integer
        totalPages: totalPages|integer
        items:
          - id: PocketBase 记录主键|string
            collectionId: collectionId|string
            collectionName: collectionName|string
            created: 记录创建时间|string
            updated: 记录更新时间|string
            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: 正文内容，保存 Markdown|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