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

openapi: 3.1.0
info:
  title: BAI PocketBase Manage API
  description: |
    基于 PocketBase `bai_api_pb_hooks` 的对外接口文档，可直接导入 Postman。
    当前 `tbl_auth_users.openid` 已被定义为全平台统一身份锚点：
    - 微信用户：`openid = 微信 openid`
    - 平台用户：`openid = 服务端生成的 GUID`
    请在 Apifox 环境中统一设置全局 Header：`Authorization: Bearer {{token}}`。
  version: 1.0.0-manage
  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: "面向平台用户的认证接口；平台用户会生成 GUID 并写入统一 `openid` 字段。"
  - name: 字典管理
    description: "字典读接口公开；字典写接口面向 ManagePlatform 用户。"
  - name: 附件管理
    description: "面向 ManagePlatform 用户的附件上传、查询与删除接口。"
  - name: 文档管理
    description: "面向 ManagePlatform 用户的文档新增、查询、修改、删除接口；查询时会自动返回关联附件的 PocketBase 文件流链接。"
  - name: 文档历史
    description: "面向 ManagePlatform 用户的文档操作历史查询接口。"
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ApiResponse:
      type: object
      required: [code, msg, data]
      properties:
        code:
          type: integer
          description: "业务状态码"
          example: 200
        msg:
          type: string
          description: "业务提示信息"
          example: 操作成功
        data:
          description: "业务响应数据"
          type: object
          additionalProperties: true
    HealthData:
      type: object
      properties:
        status:
          type: string
          example: healthy
        version:
          type: string
          description: "当前已部署 hooks 版本号，用于确认发布是否生效"
          example: 2026.03.26-health-probe.1
        timestamp:
          type: string
          format: date-time
    UsersCountData:
      type: object
      properties:
        total_users:
          type: integer
          description: "tbl_auth_users 表中的用户总数"
          example: 128
    HelloWorldData:
      type: object
      properties:
        message:
          type: string
          example: Hello, World!
        timestamp:
          type: string
          format: date-time
        status:
          type: string
          example: success
        build_time:
          type:
            - string
            - 'null'
          format: date-time
    CompanyInfo:
      anyOf:
        - type: object
          description: 用户所属公司信息；当用户尚未绑定公司时返回 `null`
          properties:
            pb_id:
              type: string
              description: PocketBase 记录主键 id
            company_id:
              type: string
              description: 公司业务 id，由数据库自动生成
            company_name:
              type: string
              description: 公司名称
            company_type:
              type: string
              description: 公司类型
            company_entity:
              type: string
              description: 公司法人
            company_usci:
              type: string
              description: 统一社会信用代码
            company_nationality:
              type: string
              description: 国家名称
            company_nationality_code:
              type: string
              description: 国家编码
            company_province:
              type: string
              description: 省份名称
            company_province_code:
              type: string
              description: 省份编码
            company_city:
              type: string
              description: 城市名称
            company_city_code:
              type: string
              description: 城市编码
            company_district:
              type: string
              description: 区/县名称
            company_district_code:
              type: string
              description: 区/县编码
            company_postalcode:
              type: string
              description: 邮政编码
            company_add:
              type: string
              description: 公司地址
            company_status:
              type: string
              description: 公司状态
            company_level:
              type: string
              description: 公司等级
            company_owner_openid:
              type: string
              description: 公司所有者 openid
            company_remark:
              type: string
              description: 备注
            created:
              type: string
              description: 记录创建时间
            updated:
              type: string
              description: 记录更新时间
          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'
    UserInfo:
      type: object
      description: |
        统一用户视图。
        其中 `openid` 为全平台统一身份标识：微信用户使用微信 openid，平台用户使用服务端生成 GUID。
      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_status:
          description: "用户状态"
          type: string
        users_rank_level:
          description: "用户星级数值"
          type: [number, string]
        users_auth_type:
          description: "账户类型"
          type: [number, string]
        users_type:
          description: "用户类型"
          anyOf:
            - type: string
              enum: [游客, 注册用户]
            - type: string
        users_name:
          description: "用户姓名 / 昵称"
          type: 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: "全平台统一身份标识；微信用户为微信 openid，平台用户为服务端生成的 GUID"
        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
    PocketBaseAuthResponse:
      type: object
      description: |
        项目统一认证响应。
        所有对外接口统一返回 `code`、`msg`、`data`，认证成功时额外返回顶层 `token`。
      properties:
        code:
          type: integer
          description: "业务状态码"
          example: 200
        msg:
          type: string
          description: "业务提示信息"
          example: 登录成功
        data:
          description: "业务响应数据"
          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'
        token:
          type: string
          description: "PocketBase 原生 auth token；仅认证类接口在成功时额外返回"
      example:
        code: 200
        msg: 登录成功
        data:
          status: 登录或注册状态 | string
          is_info_complete: 资料是否完整 | boolean
          user:
            pb_id: PocketBase记录主键id | string
            users_id: 用户业务ID | string
            users_idtype: 用户身份来源类型 | string
            users_name: 用户姓名或昵称 | string
            users_phone: 手机号 | string
            users_phone_masked: 手机号脱敏值 | string
            users_status: 用户状态 | string
            users_rank_level: 用户星级数值 | number
            users_auth_type: 账户类型 | number
            users_type: 用户类型 | 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
    WechatLoginRequest:
      type: object
      required: [users_wx_code]
      description: "微信小程序登录/注册请求体。"
      properties:
        users_wx_code:
          type: string
          description: "微信小程序登录临时凭证 code"
          example: 0a1b2c3d4e5f6g
    WechatProfileRequest:
      type: object
      description: "微信用户资料完善请求体。"
      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_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`"
    WechatProfileResponseData:
      type: object
      properties:
        status:
          type: string
          enum: [update_success]
        user:
          $ref: '#/components/schemas/UserInfo'
    PlatformRegisterRequest:
      type: object
      required: [users_name, users_phone, password, passwordConfirm, users_picture]
      description: "平台用户注册请求体；注册成功后将生成 GUID 并写入统一 `openid` 字段。"
      properties:
        users_name:
          type: string
          description: "用户姓名 / 昵称"
          example: 张三
        users_phone:
          type: string
          description: "手机号"
          example: 13800138000
        password:
          type: string
          description: "PocketBase 认证密码"
          example: 12345678
        passwordConfirm:
          type: string
          example: 12345678
        users_picture:
          type: string
          description: "用户头像附件的 `attachments_id`"
          example: ATT-1743123456789-abc123
        users_id_number:
          description: "证件号"
          type: string
        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`"
        users_level:
          description: "用户等级文本"
          type: string
        users_tag:
          description: "用户标签"
          type: string
        users_type:
          description: "用户类型"
          type: string
        company_id:
          description: "所属公司业务 ID"
          type: string
        users_parent_id:
          description: "上级用户业务 ID"
          type: string
        users_promo_code:
          description: "推广码"
          type: string
        usergroups_id:
          description: "用户组 / 角色 ID"
          type: string
    PlatformLoginRequest:
      type: object
      required: [login_account, password]
      description: "平台用户登录请求体；前端使用邮箱或手机号 + 密码提交，服务端内部转换为 PocketBase 原生 password auth。"
      properties:
        login_account:
          type: string
          description: "支持邮箱或手机号"
          example: admin@example.com
        password:
          type: string
          description: "PocketBase 认证密码"
          example: 12345678
    SystemRefreshTokenRequest:
      type: object
      description: |
        系统刷新 token 请求体。
        `users_wx_code` 允许为空。
        当 `Authorization` 对应 token 有效时，可不传或传空；
        当 token 失效时，需提供 `users_wx_code` 走微信 code 重新签发流程。
      properties:
        users_wx_code:
          type:
            - string
            - 'null'
          description: "微信小程序登录临时凭证 code"
          example: 0a1b2c3d4e5f6g
    RefreshTokenData:
      type: object
      properties: {}
    DictionaryItem:
      type: object
      required: [enum, description, sortOrder]
      properties:
        enum:
          type: string
          example: enabled
        description:
          type: string
          example: 启用
        image:
          type: string
          description: "对应图片附件的 `attachments_id`，允许为空"
          example: ATT-1743037200000-abc123
        imageUrl:
          type: string
          description: "根据 `image -> tbl_attachments` 自动解析出的图片文件流链接"
        imageAttachment:
          anyOf:
            - $ref: '#/components/schemas/AttachmentRecord'
            - type: 'null'
        sortOrder:
          type: [integer, string]
          example: 1
      example:
        enum: 枚举值 | string
        description: 枚举描述 | string
        image: 图片附件ID | string
        imageUrl: 图片文件流链接 | string
        imageAttachment:
          attachments_id: 附件业务ID | string
          attachments_filename: 原始文件名 | string
        sortOrder: 排序值 | integer
    DictionaryRecord:
      type: object
      properties:
        pb_id:
          description: "PocketBase 记录主键 id"
          type: string
        system_dict_id:
          description: "字典业务 ID"
          type: string
        dict_name:
          description: "字典名称，当前按全局唯一维护"
          type: string
        dict_word_is_enabled:
          description: "字典是否启用"
          type: [boolean, string]
        dict_word_parent_id:
          description: "父级字典业务 ID"
          type: string
        dict_word_remark:
          description: "备注"
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/DictionaryItem'
        created:
          description: "记录创建时间"
          type: string
        updated:
          description: "记录更新时间"
          type: string
      example:
        pb_id: PocketBase记录主键id | string
        system_dict_id: 字典业务ID | string
        dict_name: 字典名称 | string
        dict_word_is_enabled: 字典是否启用 | boolean
        dict_word_parent_id: 父级字典业务ID | string
        dict_word_remark: 备注 | string
        items:
          - enum: UT1
            description: 枚举描述 | string
            image: 图片附件ID | string
            imageUrl: 图片文件流链接 | string
            sortOrder: 排序值 | integer
        created: 记录创建时间 | string
        updated: 记录更新时间 | string
    DictionaryListRequest:
      type: object
      properties:
        keyword:
          type: string
          description: "对 `dict_name` 的模糊搜索关键字"
          example: 状态
    DictionaryDetailRequest:
      type: object
      required: [dict_name]
      properties:
        dict_name:
          type: string
          description: "字典名称，当前按全局唯一维护"
          example: 用户状态
    DictionaryMutationRequest:
      type: object
      required: [dict_name, items]
      properties:
        original_dict_name:
          type: string
          description: "更新时用于定位原始记录；新增时可不传"
          example: 用户状态
        dict_name:
          type: string
          description: "字典名称，当前按全局唯一维护"
          example: 用户状态
        dict_word_is_enabled:
          type: boolean
          description: "字典是否启用"
          example: true
        dict_word_parent_id:
          type: string
          description: "父级字典业务 ID"
          example: ''
        dict_word_remark:
          type: string
          description: "备注"
          example: 系统状态字典
        items:
          type: array
          minItems: 1
          description: "每项会分别序列化写入 `dict_word_enum`、`dict_word_description`、`dict_word_image`、`dict_word_sort_order`"
          items:
            $ref: '#/components/schemas/DictionaryItem'
    DictionaryDeleteRequest:
      type: object
      required: [dict_name]
      properties:
        dict_name:
          type: string
          description: "字典名称，当前按全局唯一维护"
          example: 用户状态
    AttachmentRecord:
      type: object
      properties:
        pb_id:
          description: "PocketBase 记录主键 id"
          type: string
        attachments_id:
          description: "附件业务 ID"
          type: string
        attachments_link:
          type: string
          description: "PocketBase 实际存储的文件名"
        attachments_url:
          type: string
          description: "附件文件流访问链接"
        attachments_download_url:
          type: string
          description: "附件下载链接"
        attachments_filename:
          description: "原始文件名"
          type: string
        attachments_filetype:
          description: "文件类型 / MIME"
          type: string
        attachments_size:
          description: "文件大小"
          type: [number, string]
        attachments_owner:
          description: "上传者业务标识"
          type: string
        attachments_md5:
          description: "文件 MD5"
          type: string
        attachments_ocr:
          description: "OCR 识别结果"
          type: string
        attachments_status:
          description: "附件状态"
          type: string
        attachments_remark:
          description: "备注"
          type: string
        created:
          description: "记录创建时间"
          type: string
        updated:
          description: "记录更新时间"
          type: string
      example:
        pb_id: PocketBase记录主键id | string
        attachments_id: 附件业务ID | string
        attachments_link: PocketBase实际存储文件名 | string
        attachments_url: 附件文件流访问链接 | string
        attachments_download_url: 附件下载链接 | 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
        created: 记录创建时间 | string
        updated: 记录更新时间 | string
    AttachmentListRequest:
      type: object
      properties:
        keyword:
          type: string
          description: "对 `attachments_id`、`attachments_filename` 的模糊搜索关键字"
          example: 手册
        status:
          type: string
          description: "按附件状态过滤"
          example: active
    AttachmentDetailRequest:
      type: object
      required: [attachments_id]
      properties:
        attachments_id:
          type: string
          description: "附件业务 ID"
          example: ATT-1743037200000-abc123
    AttachmentUploadRequest:
      type: object
      required: [attachments_link]
      properties:
        attachments_link:
          type: string
          format: binary
          description: "要上传到 `tbl_attachments` 的单个文件"
        attachments_filename:
          type: string
          description: "原始文件名；不传时可由前端直接使用文件名"
        attachments_filetype:
          type: string
          description: "文件 MIME 类型"
        attachments_size:
          type: number
          description: "文件大小"
        attachments_md5:
          description: "文件 MD5"
          type: string
        attachments_ocr:
          description: "OCR 识别结果"
          type: string
        attachments_status:
          type: string
          description: "附件状态"
          example: active
        attachments_remark:
          description: "备注"
          type: string
    DocumentRecord:
      type: object
      properties:
        pb_id:
          description: "PocketBase 记录主键 id"
          type: string
        document_id:
          description: "文档业务 ID"
          type: string
        document_create:
          type: string
          description: "文档创建时间，由数据库自动生成"
        document_effect_date:
          description: "文档生效日期"
          type: string
        document_expiry_date:
          description: "文档到期日期"
          type: string
        document_type:
          type: string
          description: "多选时按 `system_dict_id@dict_word_enum|...` 保存"
        document_title:
          description: "文档标题"
          type: string
        document_subtitle:
          description: "文档副标题"
          type: string
        document_summary:
          description: "文档摘要"
          type: string
        document_content:
          description: "正文内容，保存 Markdown"
          type: string
        document_image:
          type: string
          description: "关联多个 `attachments_id`，底层使用 `|` 分隔保存"
        document_image_ids:
          type: array
          description: "`document_image` 解析后的附件 id 列表"
          items:
            type: string
        document_image_urls:
          type: array
          description: "根据 `document_image -> tbl_attachments` 自动解析出的图片文件流链接列表"
          items:
            type: string
        document_image_url:
          type: string
          description: "兼容字段，返回第一张图片的文件流链接"
        document_image_attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentRecord'
        document_image_attachment:
          anyOf:
            - $ref: '#/components/schemas/AttachmentRecord'
            - type: 'null'
        document_video:
          type: string
          description: "关联多个 `attachments_id`，底层使用 `|` 分隔保存"
        document_video_ids:
          type: array
          description: "`document_video` 解析后的附件 id 列表"
          items:
            type: string
        document_video_urls:
          type: array
          description: "根据 `document_video -> tbl_attachments` 自动解析出的视频文件流链接列表"
          items:
            type: string
        document_video_url:
          type: string
          description: "兼容字段，返回第一个视频的文件流链接"
        document_video_attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentRecord'
        document_video_attachment:
          anyOf:
            - $ref: '#/components/schemas/AttachmentRecord'
            - type: 'null'
        document_file:
          type: string
          description: "关联多个 `attachments_id`，底层使用 `|` 分隔保存"
        document_file_ids:
          type: array
          description: "`document_file` 解析后的附件 id 列表"
          items:
            type: string
        document_file_urls:
          type: array
          description: "根据 `document_file -> tbl_attachments` 自动解析出的文件流链接列表"
          items:
            type: string
        document_file_url:
          type: string
          description: "兼容字段，返回第一个文件的文件流链接"
        document_file_attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentRecord'
        document_file_attachment:
          anyOf:
            - $ref: '#/components/schemas/AttachmentRecord'
            - type: 'null'
        document_owner:
          type: string
          description: "上传者 openid"
        document_relation_model:
          description: "关联机型 / 模型标识"
          type: string
        document_keywords:
          type: string
          description: "固定字典多选字段，使用 `|` 分隔"
        document_share_count:
          description: "分享次数"
          type: [number, string]
        document_download_count:
          description: "下载次数"
          type: [number, string]
        document_favorite_count:
          description: "收藏次数"
          type: [number, string]
        document_status:
          type: string
          description: "文档状态，仅允许 `有效` 或 `过期`，由系统根据生效日期和到期日期自动计算；当两者都为空时默认 `有效`"
        document_embedding_status:
          description: "文档嵌入状态"
          type: string
        document_embedding_error:
          description: "文档嵌入错误原因"
          type: string
        document_embedding_lasttime:
          description: "最后一次嵌入更新时间"
          type: string
        document_vector_version:
          description: "向量版本号 / 模型名称"
          type: string
        document_product_categories:
          type: string
          description: "固定字典多选字段，使用 `|` 分隔"
        document_application_scenarios:
          type: string
          description: "固定字典多选字段，使用 `|` 分隔"
        document_hotel_type:
          type: string
          description: "固定字典多选字段，使用 `|` 分隔"
        document_remark:
          description: "备注"
          type: string
        created:
          description: "记录创建时间"
          type: string
        updated:
          description: "记录更新时间"
          type: string
      example:
        pb_id: PocketBase记录主键id | string
        document_id: 文档业务ID | string
        document_create: 文档创建时间，由数据库自动生成 | string
        document_effect_date: 文档生效日期 | string
        document_expiry_date: 文档到期日期 | string
        document_type: 文档类型，按system_dict_id@dict_word_enum保存 | string
        document_title: 文档标题 | string
        document_subtitle: 文档副标题 | string
        document_summary: 文档摘要 | string
        document_content: 正文内容Markdown | string
        document_image: 图片附件ID列表，使用竖线分隔 | string
        document_image_ids:
          - 图片附件ID | string
        document_image_urls:
          - 图片文件流链接 | string
        document_image_url: 第一张图片文件流链接 | string
        document_video: 视频附件ID列表，使用竖线分隔 | string
        document_video_ids:
          - 视频附件ID | string
        document_video_urls:
          - 视频文件流链接 | string
        document_video_url: 第一个视频文件流链接 | string
        document_file: 文件附件ID列表，使用竖线分隔 | string
        document_file_ids:
          - 文件附件ID | string
        document_file_urls:
          - 文件流链接 | string
        document_file_url: 第一个文件流链接 | 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_status: 文档状态 | string
        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
        created: 记录创建时间 | string
        updated: 记录更新时间 | string
    DocumentListRequest:
      type: object
      properties:
        keyword:
          type: string
          description: "对 `document_id`、`document_title`、`document_subtitle`、`document_summary`、`document_keywords` 的模糊搜索关键字"
          example: 安装
        status:
          type: string
          example: active
        document_type:
          type: string
          description: "支持按存储值过滤；多选时格式为 `system_dict_id@dict_word_enum|...`"
          example: 说明书
    DocumentDetailRequest:
      type: object
      required: [document_id]
      properties:
        document_id:
          type: string
          description: "文档业务 ID"
          example: DOC-1743037200000-abc123
    DocumentMutationRequest:
      type: object
      required: [document_title, document_type]
      properties:
        document_id:
          type: string
          description: "创建时可不传，由服务端自动生成；更新时必填"
          example: DOC-1743037200000-abc123
        document_effect_date:
          type: string
          description: "支持 `YYYY-MM-DD` 或 PocketBase 可识别日期时间字符串"
          example: 2026-03-27
        document_expiry_date:
          type: string
          description: "支持 `YYYY-MM-DD` 或 PocketBase 可识别日期时间字符串"
          example: 2027-03-27
        document_type:
          type: string
          description: "必填；前端显示为字典项描述，存库时按 `system_dict_id@dict_word_enum|...` 保存"
        document_title:
          description: "文档标题"
          type: string
        document_subtitle:
          description: "文档副标题"
          type: string
        document_summary:
          description: "文档摘要"
          type: string
        document_content:
          description: "正文内容，保存 Markdown"
          type: string
        document_image:
          oneOf:
            - type: string
              description: "多个图片附件 id 使用 `|` 分隔"
            - type: array
              items:
                type: string
          description: "图片附件 id 列表；支持数组或 `|` 分隔字符串"
        document_video:
          oneOf:
            - type: string
              description: "多个视频附件 id 使用 `|` 分隔"
            - type: array
              items:
                type: string
          description: "视频附件 id 列表；支持数组或 `|` 分隔字符串"
        document_file:
          oneOf:
            - type: string
              description: "多个文件附件 id 使用 `|` 分隔"
            - type: array
              items:
                type: string
          description: "文件附件 id 列表；支持数组或 `|` 分隔字符串"
        document_relation_model:
          description: "关联机型 / 模型标识"
          type: string
        document_keywords:
          type: string
          description: "从 `文档-关键词` 字典多选后使用 `|` 分隔保存"
        document_share_count:
          description: "分享次数"
          type: number
        document_download_count:
          description: "下载次数"
          type: number
        document_favorite_count:
          description: "收藏次数"
          type: number
        document_status:
          type: string
          description: "文档状态，仅允许 `有效` 或 `过期`，由系统根据生效日期和到期日期自动计算；当两者都为空时默认 `有效`"
        document_embedding_status:
          description: "文档嵌入状态"
          type: string
        document_embedding_error:
          description: "文档嵌入错误原因"
          type: string
        document_embedding_lasttime:
          description: "最后一次嵌入更新时间"
          type: string
        document_vector_version:
          description: "向量版本号 / 模型名称"
          type: string
        document_product_categories:
          type: string
          description: "从 `文档-产品关联文档` 字典多选后使用 `|` 分隔保存"
        document_application_scenarios:
          type: string
          description: "从 `文档-筛选依据` 字典多选后使用 `|` 分隔保存"
        document_hotel_type:
          type: string
          description: "从 `文档-适用场景` 字典多选后使用 `|` 分隔保存"
        document_remark:
          description: "备注"
          type: string
    DocumentDeleteRequest:
      type: object
      required: [document_id]
      properties:
        document_id:
          type: string
          description: "文档业务 ID"
          example: DOC-1743037200000-abc123
    DocumentHistoryRecord:
      type: object
      properties:
        pb_id:
          description: "PocketBase 记录主键 id"
          type: string
        doh_id:
          description: "文档操作历史业务 ID"
          type: string
        doh_document_id:
          description: "关联文档业务 ID"
          type: string
        doh_operation_type:
          description: "操作类型"
          type: string
        doh_user_id:
          description: "操作人业务 ID"
          type: string
        doh_current_count:
          description: "本次操作对应次数"
          type: [number, string]
        doh_remark:
          description: "备注"
          type: string
        created:
          description: "记录创建时间"
          type: string
        updated:
          description: "记录更新时间"
          type: string
      example:
        pb_id: PocketBase记录主键id | string
        doh_id: 文档操作历史业务ID | string
        doh_document_id: 关联文档业务ID | string
        doh_operation_type: 操作类型 | string
        doh_user_id: 操作人业务ID | string
        doh_current_count: 本次操作对应次数 | number
        doh_remark: 备注 | string
        created: 记录创建时间 | string
        updated: 记录更新时间 | string
    DocumentHistoryListRequest:
      type: object
      properties:
        document_id:
          type: string
          description: "可选；传入时仅查询指定文档的操作历史"
          example: DOC-1743037200000-abc123
paths:
  /pb/api/system/test-helloworld:
    post:
      tags: [系统]
      summary: HelloWorld 测试接口
      responses:
        '200':
          description: "成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        $ref: '#/components/schemas/HelloWorldData'
  /pb/api/system/health:
    post:
      tags: [系统]
      summary: 健康检查
      responses:
        '200':
          description: "成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        $ref: '#/components/schemas/HealthData'
  /pb/api/system/users-count:
    post:
      tags: [系统]
      summary: 查询用户总数
      description: "统计 `tbl_auth_users` 集合中的记录总数，并返回一个数值。"
      responses:
        '200':
          description: "成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        $ref: '#/components/schemas/UsersCountData'
  /pb/api/platform/register:
    post:
      tags: [平台认证]
      summary: 平台用户注册
      description: |
        创建平台用户 auth record。
        服务端会自动生成 GUID 并写入统一身份字段 `openid`，同时写入 `users_idtype = ManagePlatform`。
        前端以 `users_phone + password/passwordConfirm` 注册，但服务端仍会创建 PocketBase 原生 auth 用户。
        注册成功后直接返回 PocketBase 原生 auth token。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformRegisterRequest'
      responses:
        '200':
          description: "注册成功"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseAuthResponse'
        '400':
          description: "参数错误或手机号已存在"
        '500':
          description: "GUID 生成失败、auth identity 缺失或保存用户失败"
        '415':
          description: "请求体必须为 application/json"
        '429':
          description: "重复请求过于频繁"
  /pb/api/platform/login:
    post:
      tags: [平台认证]
      summary: 平台用户登录
      description: |
        前端使用平台注册时保存的 `邮箱或手机号 + password` 登录。
        仅允许 `users_idtype = ManagePlatform` 的用户通过该接口登录。
        服务端会根据 `login_account` 自动判断邮箱或手机号，并定位平台用户，再使用该用户的 PocketBase 原生 identity（当前为 `email`）执行原生 password auth。
        登录成功后直接返回 PocketBase 原生 auth token。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformLoginRequest'
            example:
              login_account: 13509214696
              password: Momo123456
      responses:
        '200':
          description: "登录成功"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseAuthResponse'
              example:
                code: 200
                msg: 登录成功
                data:
                  status: login_success
                  is_info_complete: false
                  user:
                    pb_id: vtukf6agem2xbcv
                    users_id: ''
                    users_idtype: ManagePlatform
                    users_name: momo
                    users_phone: '13509214696'
                    users_phone_masked: '135****4696'
                    users_status: ''
                    users_rank_level: 0
                    users_auth_type: 0
                    users_type: ''
                    users_picture: ''
                    openid: app_momo
                    company_id: ''
                    users_parent_id: ''
                    users_promo_code: ''
                    usergroups_id: ''
                    company: null
                    created: ''
                    updated: ''
                token: eyJhbGciOi...
        '400':
          description: "参数错误、密码错误或用户类型不匹配"
        '404':
          description: "平台用户不存在"
        '500':
          description: "平台用户缺少原生登录 identity 或服务端内部错误"
        '415':
          description: "请求体必须为 application/json"
        '429':
          description: "重复请求过于频繁"
  /pb/api/dictionary/list:
    post:
      tags: [字典管理]
      summary: 查询字典列表
      security: []
      description: |
        公开读接口，无需 token。
        支持按 `dict_name` 模糊搜索，返回字典全量信息，并将三个聚合字段组装为 `items`。
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DictionaryListRequest'
      responses:
        '200':
          description: "查询成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              $ref: '#/components/schemas/DictionaryRecord'
        '415':
          description: "请求体必须为 application/json"
  /pb/api/dictionary/detail:
    post:
      tags: [字典管理]
      summary: 查询指定字典
      security: []
      description: |
        公开读接口，无需 token。
        按唯一键 `dict_name` 查询单条字典，并返回组装后的 `items`。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DictionaryDetailRequest'
      responses:
        '200':
          description: "查询成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        $ref: '#/components/schemas/DictionaryRecord'
        '400':
          description: "参数错误"
        '404':
          description: "未找到对应字典"
        '415':
          description: "请求体必须为 application/json"
  /pb/api/dictionary/create:
    post:
      tags: [字典管理]
      summary: 新增字典
      description: |
        仅允许 `ManagePlatform` 用户访问。
        `system_dict_id` 由服务端自动生成；`dict_name` 必须唯一；
        `items` 会分别序列化写入 `dict_word_enum`、`dict_word_description`、`dict_word_image`、`dict_word_sort_order` 四个字段。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DictionaryMutationRequest'
      responses:
        '200':
          description: "新增成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        $ref: '#/components/schemas/DictionaryRecord'
        '400':
          description: "参数错误或 dict_name 已存在"
        '401':
          description: "token 无效或已过期"
        '403':
          description: "非 ManagePlatform 用户无权访问"
        '415':
          description: "请求体必须为 application/json"
        '429':
          description: "重复请求过于频繁"
  /pb/api/dictionary/update:
    post:
      tags: [字典管理]
      summary: 修改字典
      description: |
        仅允许 `ManagePlatform` 用户访问。
        根据 `original_dict_name`（未传时回退为 `dict_name`）定位原记录并更新。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DictionaryMutationRequest'
      responses:
        '200':
          description: "修改成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        $ref: '#/components/schemas/DictionaryRecord'
        '400':
          description: "参数错误或 dict_name 冲突"
        '401':
          description: "token 无效或已过期"
        '403':
          description: "非 ManagePlatform 用户无权访问"
        '404':
          description: "未找到待修改字典"
        '415':
          description: "请求体必须为 application/json"
        '429':
          description: "重复请求过于频繁"
  /pb/api/dictionary/delete:
    post:
      tags: [字典管理]
      summary: 删除字典
      description: |
        仅允许 `ManagePlatform` 用户访问。
        按 `dict_name` 真删除对应记录。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DictionaryDeleteRequest'
      responses:
        '200':
          description: "删除成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        type: object
                        properties:
                          dict_name:
                            description: "字典名称，当前按全局唯一维护"
                            type: string
        '400':
          description: "参数错误或删除失败"
        '401':
          description: "token 无效或已过期"
        '403':
          description: "非 ManagePlatform 用户无权访问"
        '404':
          description: "未找到待删除字典"
        '415':
          description: "请求体必须为 application/json"
        '429':
          description: "重复请求过于频繁"
  /pb/api/attachment/list:
    post:
      tags: [附件管理]
      summary: 查询附件列表
      description: |
        仅允许 `ManagePlatform` 用户访问。
        支持按 `attachments_id`、`attachments_filename` 模糊搜索，并可按 `attachments_status` 过滤。
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachmentListRequest'
      responses:
        '200':
          description: "查询成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              $ref: '#/components/schemas/AttachmentRecord'
        '401':
          description: "token 无效或已过期"
        '403':
          description: "非 ManagePlatform 用户无权访问"
        '415':
          description: "请求体必须为 application/json"
  /pb/api/attachment/detail:
    post:
      tags: [附件管理]
      summary: 查询附件详情
      description: |
        仅允许 `ManagePlatform` 用户访问。
        按 `attachments_id` 查询单条附件，并返回 PocketBase 文件流链接与下载链接。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachmentDetailRequest'
      responses:
        '200':
          description: "查询成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        $ref: '#/components/schemas/AttachmentRecord'
        '400':
          description: "参数错误"
        '401':
          description: "token 无效或已过期"
        '403':
          description: "非 ManagePlatform 用户无权访问"
        '404':
          description: "未找到对应附件"
        '415':
          description: "请求体必须为 application/json"
  /pb/api/attachment/upload:
    post:
      tags: [附件管理]
      summary: 上传附件
      description: |
        仅允许 `ManagePlatform` 用户访问。
        使用 `multipart/form-data` 上传单个文件到 `tbl_attachments`，服务端会自动生成 `attachments_id`，
        并返回可直接访问的 PocketBase 文件流链接。
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AttachmentUploadRequest'
      responses:
        '200':
          description: "上传成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        $ref: '#/components/schemas/AttachmentRecord'
        '400':
          description: "参数错误、缺少文件或附件保存失败"
        '401':
          description: "token 无效或已过期"
        '403':
          description: "非 ManagePlatform 用户无权访问"
  /pb/api/attachment/delete:
    post:
      tags: [附件管理]
      summary: 删除附件
      description: |
        仅允许 `ManagePlatform` 用户访问。
        按 `attachments_id` 真删除附件；若附件已被 `tbl_document.document_image`、`document_video` 或 `document_file` 引用，则拒绝删除。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachmentDetailRequest'
      responses:
        '200':
          description: "删除成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        type: object
                        properties:
                          attachments_id:
                            description: "附件业务 ID"
                            type: string
        '400':
          description: "参数错误、附件已被文档引用或删除失败"
        '401':
          description: "token 无效或已过期"
        '403':
          description: "非 ManagePlatform 用户无权访问"
        '404':
          description: "未找到待删除附件"
        '415':
          description: "请求体必须为 application/json"
        '429':
          description: "重复请求过于频繁"
  /pb/api/document/list:
    post:
      tags: [文档管理]
      summary: 查询文档列表
      description: |
        仅允许 `ManagePlatform` 用户访问。
        支持按标题、摘要、关键词等字段模糊搜索，并可按 `document_status`、`document_type` 过滤。
        返回结果会自动根据 `document_image`、`document_video`、`document_file` 中的多个 `attachments_id` 关联 `tbl_attachments`，
        额外补充 `document_image_urls`、`document_video_urls`、`document_file_urls` 以及对应附件对象数组。
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentListRequest'
      responses:
        '200':
          description: "查询成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              $ref: '#/components/schemas/DocumentRecord'
        '401':
          description: "token 无效或已过期"
        '403':
          description: "非 ManagePlatform 用户无权访问"
        '415':
          description: "请求体必须为 application/json"
  /pb/api/document/detail:
    post:
      tags: [文档管理]
      summary: 查询文档详情
      description: |
        仅允许 `ManagePlatform` 用户访问。
        按 `document_id` 查询单条文档，并返回与附件表联动解析后的多文件流链接。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentDetailRequest'
      responses:
        '200':
          description: "查询成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        $ref: '#/components/schemas/DocumentRecord'
        '400':
          description: "参数错误"
        '401':
          description: "token 无效或已过期"
        '403':
          description: "非 ManagePlatform 用户无权访问"
        '404':
          description: "未找到对应文档"
        '415':
          description: "请求体必须为 application/json"
  /pb/api/document/create:
    post:
      tags: [文档管理]
      summary: 新增文档
      description: |
        仅允许 `ManagePlatform` 用户访问。
        `document_id` 可选；未传时服务端自动生成。
        `document_title`、`document_type` 为必填；其余字段均允许为空。
        `document_image`、`document_video`、`document_file` 支持传入多个已存在于 `tbl_attachments` 的 `attachments_id`。
        成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `create`。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentMutationRequest'
      responses:
        '200':
          description: "新增成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        $ref: '#/components/schemas/DocumentRecord'
        '400':
          description: "参数错误、附件不存在或文档创建失败"
        '401':
          description: "token 无效或已过期"
        '403':
          description: "非 ManagePlatform 用户无权访问"
        '415':
          description: "请求体必须为 application/json"
        '429':
          description: "重复请求过于频繁"
  /pb/api/document/update:
    post:
      tags: [文档管理]
      summary: 修改文档
      description: |
        仅允许 `ManagePlatform` 用户访问。
        按 `document_id` 定位现有文档并更新。
        `document_title`、`document_type` 为必填；其余字段均允许为空。
        若传入 `document_image`、`document_video`、`document_file`，则支持多个 `attachments_id`，并会逐一校验是否存在。
        成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `update`。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentMutationRequest'
      responses:
        '200':
          description: "修改成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        $ref: '#/components/schemas/DocumentRecord'
        '400':
          description: "参数错误、附件不存在或修改失败"
        '401':
          description: "token 无效或已过期"
        '403':
          description: "非 ManagePlatform 用户无权访问"
        '404':
          description: "未找到待修改文档"
        '415':
          description: "请求体必须为 application/json"
        '429':
          description: "重复请求过于频繁"
  /pb/api/document/delete:
    post:
      tags: [文档管理]
      summary: 删除文档
      description: |
        仅允许 `ManagePlatform` 用户访问。
        按 `document_id` 真删除文档，并在删除前同步写入一条 `tbl_document_operation_history`，操作类型为 `delete`。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentDeleteRequest'
      responses:
        '200':
          description: "删除成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        type: object
                        properties:
                          document_id:
                            description: "文档业务 ID"
                            type: string
        '400':
          description: "参数错误或删除失败"
        '401':
          description: "token 无效或已过期"
        '403':
          description: "非 ManagePlatform 用户无权访问"
        '404':
          description: "未找到待删除文档"
        '415':
          description: "请求体必须为 application/json"
        '429':
          description: "重复请求过于频繁"
  /pb/api/document-history/list:
    post:
      tags: [文档历史]
      summary: 查询文档操作历史
      description: |
        仅允许 `ManagePlatform` 用户访问。
        若 body 传入 `document_id`，则仅查询该文档的历史；否则返回全部文档操作历史，按创建时间倒序排列。
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentHistoryListRequest'
      responses:
        '200':
          description: "查询成功"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        description: "业务响应数据"
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              $ref: '#/components/schemas/DocumentHistoryRecord'
        '401':
          description: "token 无效或已过期"
        '403':
          description: "非 ManagePlatform 用户无权访问"
        '415':
          description: "请求体必须为 application/json"