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

paths:
  attachmentRecords:
    get:
      operationId: getPocketBaseAttachmentRecords
      tags:
        - 附件信息
      summary: 根据 attachments_id 查询单条或多条附件信息
      description: |
        使用 PocketBase 原生 records list 接口查询 `tbl_attachments`。

        当前线上权限规则：
        - `listRule = is_delete = 0`，因此任何客户端都可直接读取未软删除附件
        - 原生 `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: ../openapi-wx.yaml#/components/schemas/PocketBaseAttachmentListResponse
              example:
                page: page|integer
                perPage: perPage|integer
                totalItems: totalItems|integer
                totalPages: 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
        "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
    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: ../openapi-wx.yaml#/components/schemas/PocketBaseAttachmentRecord
      example:
        page: page|integer
        perPage: perPage|integer
        totalItems: totalItems|integer
        totalPages: 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