feat: 添加 PocketBase MiniApp 公司 API 文档和文件字段迁移脚本

- 新增 openapi-miniapp-company.yaml 文件，定义 tbl_company 的基础 CRUD 接口文档，包括查询、创建、更新和删除公司记录的详细描述和示例。 - 新增 pocketbase.file-fields-to-attachments.js 脚本，用于迁移 PocketBase 中的文件字段到文本字段，并处理 tbl_attachments 集合的公开规则。
2026-03-28 15:13:04 +08:00
parent eaf282ea24
commit 51a90260e4
50 changed files with 4250 additions and 113 deletions
--- a/pocket-base/spec/changes.2026-03-23-pocketbase-hooks-auth-hardening.md
+++ b/pocket-base/spec/changes.2026-03-23-pocketbase-hooks-auth-hardening.md
@@ -57,6 +57,28 @@
 - 已将 schema 脚本中的 `user_id` 改为非必填。
 - 其余业务字段保持非必填。

+### 4. 用户图片字段统一改为附件 ID 语义
+
+- `users_picture`
+- `users_id_pic_a`
+- `users_id_pic_b`
+- `users_title_picture`
+
+以上字段已统一改为保存 `tbl_attachments.attachments_id`，不再直接保存 PocketBase `file` 字段或外部图片 URL。
+
+查询用户信息时，hooks 会自动联查 `tbl_attachments` 并补充：
+
+- `users_picture_url`
+- `users_id_pic_a_url`
+- `users_id_pic_b_url`
+- `users_title_picture_url`
+
+说明：
+
+- `tbl_attachments` 仍由附件表保存实际文件本体；
+- 业务表仅负责保存附件 ID；
+- hooks 中原有 `ManagePlatform` 访问限制保持不变。
+
 ---

 ## 三、查询与排序修复
@@ -238,7 +260,7 @@
 	- 自动写入 `attachments_owner = 当前用户 openid`
 - `POST /pb/api/attachment/delete`
 	- 按 `attachments_id` 真删除附件
-	- 若该附件已被 `tbl_document.document_image` 或 `document_video` 中的任一附件列表引用，则拒绝删除
+	- 若该附件已被 `tbl_document.document_image`、`document_video` 或 `document_file` 中的任一附件列表引用，则拒绝删除

 说明：

@@ -258,8 +280,10 @@
 	- 额外补充：
 		- `document_image_urls`
 		- `document_video_urls`
+		- `document_file_urls`
 		- `document_image_attachments`
 		- `document_video_attachments`
+		- `document_file_attachments`
 - `POST /pb/api/document/detail`
 	- 按 `document_id` 查询单条文档
 	- 返回与附件表联动解析后的多文件流链接
@@ -267,7 +291,7 @@
 	- 新增文档
 	- `document_id` 可不传，由服务端自动生成
 	- `document_title`、`document_type` 为必填；其余字段均允许为空
-	- `document_image`、`document_video` 支持传入多个已存在的 `attachments_id`
+	- `document_image`、`document_video`、`document_file` 支持传入多个已存在的 `attachments_id`
 	- `document_type` 前端从单个字典来源中多选枚举值，最终按 `system_dict_id@dict_word_enum|...` 保存
 	- `document_keywords`、`document_product_categories`、`document_application_scenarios`、`document_hotel_type` 统一从固定字典多选并按 `|` 保存
 	- 其中 `document_product_categories` 改为从 `文档-产品关联文档` 读取，`document_application_scenarios` 改为从 `文档-筛选依据` 读取，`document_hotel_type` 改为从 `文档-适用场景` 读取
@@ -285,7 +309,7 @@

 说明：

- `document_image`、`document_video` 当前保存的是多个 `attachments_id`，底层以 `|` 分隔文本持久化，不是 PocketBase 文件字段。
+- `document_image`、`document_video`、`document_file` 当前保存的是多个 `attachments_id`，底层以 `|` 分隔文本持久化，不是 PocketBase 文件字段。
 - 文档查询时通过 `attachments_id -> tbl_attachments` 反查实际文件，并返回可直接访问的数据流链接数组。
 - `document_owner` 语义为“上传者 openid”。

@@ -337,8 +361,8 @@
 	- 返回主页
 - 文档管理页支持：
 	- 先上传附件到 `tbl_attachments`
-	- 再把返回的多个 `attachments_id` 写入 `tbl_document.document_image` / `document_video`
-	- 图片和视频都支持多选上传
+	- 再把返回的多个 `attachments_id` 写入 `tbl_document.document_image` / `document_video` / `document_file`
+	- 图片、视频、文件都支持多选上传
 	- 新增文档
 	- 编辑已有文档并回显多图片、多视频
 	- 从文档中移除附件并在保存后删除对应附件记录
--- a/pocket-base/spec/openapi-manage.yaml
+++ b/pocket-base/spec/openapi-manage.yaml
@@ -130,6 +130,28 @@ components:
          type: string
        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"
@@ -190,6 +212,13 @@ components:
            users_auth_type: 0
            users_type: 注册用户
            users_picture: ''
+            users_picture_url: ''
+            users_id_pic_a: ''
+            users_id_pic_a_url: ''
+            users_id_pic_b: ''
+            users_id_pic_b_url: ''
+            users_title_picture: ''
+            users_title_picture_url: ''
            openid: app_momo
            company_id: ''
            users_parent_id: ''
@@ -221,7 +250,17 @@ components:
          example: 2b7d9f2e3c4a5b6d7e8f
        users_picture:
          type: string
-          example: https://example.com/avatar.png
+          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:
@@ -249,9 +288,19 @@ components:
          example: 12345678
        users_picture:
          type: string
-          example: https://example.com/avatar.png
+          description: "用户头像附件的 `attachments_id`"
+          example: ATT-1743123456789-abc123
        users_id_number:
          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:
          type: string
        users_type:
@@ -537,6 +586,30 @@ components:
          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"
@@ -641,6 +714,14 @@ components:
              items:
                type: string
          description: "视频附件 id 列表；支持数组或 `|` 分隔字符串"
+        document_file:
+          oneOf:
+            - type: string
+              description: "多个文件附件 id 使用 `|` 分隔"
+            - type: array
+              items:
+                type: string
+          description: "文件附件 id 列表；支持数组或 `|` 分隔字符串"
        document_relation_model:
          type: string
        document_keywords:
@@ -1144,7 +1225,7 @@ paths:
      summary: 删除附件
      description: |
        仅允许 `ManagePlatform` 用户访问。
-        按 `attachments_id` 真删除附件；若附件已被 `tbl_document.document_image` 或 `document_video` 引用，则拒绝删除。
+        按 `attachments_id` 真删除附件；若附件已被 `tbl_document.document_image`、`document_video` 或 `document_file` 引用，则拒绝删除。
      requestBody:
        required: true
        content:
@@ -1185,8 +1266,8 @@ paths:
      description: |
        仅允许 `ManagePlatform` 用户访问。
        支持按标题、摘要、关键词等字段模糊搜索，并可按 `document_status`、`document_type` 过滤。
-        返回结果会自动根据 `document_image`、`document_video` 中的多个 `attachments_id` 关联 `tbl_attachments`，
-        额外补充 `document_image_urls`、`document_video_urls` 以及对应附件对象数组。
+        返回结果会自动根据 `document_image`、`document_video`、`document_file` 中的多个 `attachments_id` 关联 `tbl_attachments`，
+        额外补充 `document_image_urls`、`document_video_urls`、`document_file_urls` 以及对应附件对象数组。
      requestBody:
        required: false
        content:
@@ -1259,7 +1340,7 @@ paths:
        仅允许 `ManagePlatform` 用户访问。
        `document_id` 可选；未传时服务端自动生成。
        `document_title`、`document_type` 为必填；其余字段均允许为空。
-        `document_image`、`document_video` 支持传入多个已存在于 `tbl_attachments` 的 `attachments_id`。
+        `document_image`、`document_video`、`document_file` 支持传入多个已存在于 `tbl_attachments` 的 `attachments_id`。
        成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `create`。
      requestBody:
        required: true
@@ -1297,7 +1378,7 @@ paths:
        仅允许 `ManagePlatform` 用户访问。
        按 `document_id` 定位现有文档并更新。
        `document_title`、`document_type` 为必填；其余字段均允许为空。
-        若传入 `document_image`、`document_video`，则支持多个 `attachments_id`，并会逐一校验是否存在。
+        若传入 `document_image`、`document_video`、`document_file`，则支持多个 `attachments_id`，并会逐一校验是否存在。
        成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `update`。
      requestBody:
        required: true
--- a/pocket-base/spec/openapi-miniapp-company.yaml
+++ b/pocket-base/spec/openapi-miniapp-company.yaml
@@ -0,0 +1,449 @@
+openapi: 3.1.0
+info:
+  title: PocketBase MiniApp Company API
+  version: 1.0.0
+  summary: 小程序端通过 PocketBase JS SDK 直连 tbl_company 的基础 CRUD 文档
+  description: >-
+    本文档面向小程序端直接使用 PocketBase JS SDK / REST API 访问 `tbl_company`。
+    本文档统一以 PocketBase 原生记录主键 `id` 作为唯一识别键。
+    `company_id` 保留为普通业务字段，可用于展示、筛选和业务关联，但不再作为 CRUD 的唯一键。
+  license:
+    name: Proprietary
+    identifier: LicenseRef-Proprietary
+servers:
+  - url: https://bai-api.blv-oa.com/pb
+    description: 线上 PocketBase 服务
+tags:
+  - name: Company
+    description: tbl_company 公司信息基础 CRUD
+security:
+  - pocketbaseAuth: []
+paths:
+  /api/collections/tbl_company/records:
+    get:
+      tags: [Company]
+      operationId: listCompanyRecords
+      summary: 查询公司列表
+      description: >-
+        使用 PocketBase 原生 records list/search 接口查询 `tbl_company`。
+        支持三种常见模式：
+        1. 全表查询：不传 `filter`；
+        2. 精确查询：`filter=id="q1w2e3r4t5y6u7i"`；
+        3. 模糊查询：`filter=(company_name~"华住" || company_usci~"9131" || company_entity~"张三")`。
+      parameters:
+        - $ref: '#/components/parameters/Page'
+        - $ref: '#/components/parameters/PerPage'
+        - $ref: '#/components/parameters/Sort'
+        - $ref: '#/components/parameters/Filter'
+        - $ref: '#/components/parameters/Fields'
+        - $ref: '#/components/parameters/SkipTotal'
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyListResponse'
+              examples:
+                all:
+                  summary: 全表查询
+                  value:
+                    page: 1
+                    perPage: 30
+                    totalItems: 2
+                    totalPages: 1
+                    items:
+                      - id: q1w2e3r4t5y6u7i
+                        collectionId: pbc_company_demo
+                        collectionName: tbl_company
+                        created: '2026-03-27 10:00:00.000Z'
+                        updated: '2026-03-27 10:00:00.000Z'
+                        company_id: C10001
+                        company_name: 宝镜科技
+                        company_type: 渠道商
+                        company_entity: 张三
+                        company_usci: '91310000123456789A'
+                        company_nationality: 中国
+                        company_province: 上海
+                        company_city: 上海
+                        company_postalcode: '200000'
+                        company_add: 上海市浦东新区XX路1号
+                        company_status: 有效
+                        company_level: A
+                        company_remark: ''
+                exact:
+                  summary: 按 id 精确查询
+                  value:
+                    page: 1
+                    perPage: 1
+                    totalItems: 1
+                    totalPages: 1
+                    items:
+                      - id: q1w2e3r4t5y6u7i
+                        collectionId: pbc_company_demo
+                        collectionName: tbl_company
+                        created: '2026-03-27 10:00:00.000Z'
+                        updated: '2026-03-27 10:00:00.000Z'
+                        company_id: C10001
+                        company_name: 宝镜科技
+                        company_type: 渠道商
+                        company_entity: 张三
+                        company_usci: '91310000123456789A'
+                        company_nationality: 中国
+                        company_province: 上海
+                        company_city: 上海
+                        company_postalcode: '200000'
+                        company_add: 上海市浦东新区XX路1号
+                        company_status: 有效
+                        company_level: A
+                        company_remark: ''
+        '400':
+          description: 过滤表达式或查询参数不合法
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseError'
+        '403':
+          description: 当前调用方没有 list 权限
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseError'
+    post:
+      tags: [Company]
+      operationId: createCompanyRecord
+      summary: 新增公司
+      description: >-
+        创建一条 `tbl_company` 记录。当前文档以 `id` 作为记录唯一识别键，
+        新建成功后由 PocketBase 自动生成 `id`；根据当前项目建表脚本，`company_id` 仍是必填业务字段，但不再作为 CRUD 唯一键。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CompanyCreateRequest'
+            examples:
+              default:
+                value:
+                  company_id: C10001
+                  company_name: 宝镜科技
+                  company_type: 渠道商
+                  company_entity: 张三
+                  company_usci: '91310000123456789A'
+                  company_nationality: 中国
+                  company_province: 上海
+                  company_city: 上海
+                  company_postalcode: '200000'
+                  company_add: 上海市浦东新区XX路1号
+                  company_status: 有效
+                  company_level: A
+                  company_remark: 首次创建
+      responses:
+        '200':
+          description: 创建成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyRecord'
+        '400':
+          description: 校验失败，例如字段类型不合法或违反当前集合约束
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseError'
+        '403':
+          description: 当前调用方没有 create 权限
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseError'
+        '404':
+          description: 集合不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseError'
+  /api/collections/tbl_company/records/{recordId}:
+    get:
+      tags: [Company]
+      operationId: getCompanyRecordByRecordId
+      summary: 按 PocketBase 记录 id 查询公司
+      description: >-
+        这是 PocketBase 原生单条查询接口，路径参数必须传记录主键 `id`。
+      parameters:
+        - $ref: '#/components/parameters/RecordId'
+        - $ref: '#/components/parameters/Fields'
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyRecord'
+        '403':
+          description: 当前调用方没有 view 权限
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseError'
+        '404':
+          description: 记录不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseError'
+    patch:
+      tags: [Company]
+      operationId: updateCompanyRecordByRecordId
+      summary: 按 PocketBase 记录 id 更新公司
+      description: >-
+        这是 PocketBase 原生更新接口，路径参数统一使用记录主键 `id`。
+      parameters:
+        - $ref: '#/components/parameters/RecordId'
+        - $ref: '#/components/parameters/Fields'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CompanyUpdateRequest'
+            examples:
+              default:
+                value:
+                  company_name: 宝镜科技（更新）
+                  company_status: 有效
+                  company_level: S
+                  company_remark: 已更新基础资料
+      responses:
+        '200':
+          description: 更新成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyRecord'
+        '400':
+          description: 更新参数不合法
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseError'
+        '403':
+          description: 当前调用方没有 update 权限
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseError'
+        '404':
+          description: 记录不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseError'
+    delete:
+      tags: [Company]
+      operationId: deleteCompanyRecordByRecordId
+      summary: 按 PocketBase 记录 id 删除公司
+      description: >-
+        这是 PocketBase 原生删除接口，路径参数统一使用记录主键 `id`。
+      parameters:
+        - $ref: '#/components/parameters/RecordId'
+      responses:
+        '204':
+          description: 删除成功
+        '400':
+          description: 删除失败，例如仍被必填 relation 引用
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseError'
+        '403':
+          description: 当前调用方没有 delete 权限
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseError'
+        '404':
+          description: 记录不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseError'
+components:
+  securitySchemes:
+    pocketbaseAuth:
+      type: apiKey
+      in: header
+      name: Authorization
+      description: PocketBase 认证 token。使用 JS SDK 时通常由 `pb.authStore` 自动附带。
+  parameters:
+    Page:
+      name: page
+      in: query
+      description: 页码，默认 1
+      schema:
+        type: integer
+        minimum: 1
+        default: 1
+    PerPage:
+      name: perPage
+      in: query
+      description: 每页返回条数，默认 30
+      schema:
+        type: integer
+        minimum: 1
+        default: 30
+    Sort:
+      name: sort
+      in: query
+      description: 排序字段，例如 `-created,+company_name`
+      schema:
+        type: string
+    Filter:
+      name: filter
+      in: query
+      description: >-
+        PocketBase 过滤表达式。
+        精确查询示例：`id="q1w2e3r4t5y6u7i"`；
+        模糊查询示例：`(company_name~"宝镜" || company_usci~"9131" || company_entity~"张三")`
+      schema:
+        type: string
+    Fields:
+      name: fields
+      in: query
+      description: 逗号分隔的返回字段列表，例如 `id,company_id,company_name`
+      schema:
+        type: string
+    SkipTotal:
+      name: skipTotal
+      in: query
+      description: 是否跳过 totalItems/totalPages 统计
+      schema:
+        type: boolean
+        default: false
+    RecordId:
+      name: recordId
+      in: path
+      required: true
+      description: PocketBase 记录主键 id
+      schema:
+        type: string
+  schemas:
+    CompanyBase:
+      type: object
+      properties:
+        company_id:
+          type: string
+          description: 公司业务编号字段，不再作为 CRUD 唯一键
+        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_province:
+          type: string
+          description: 省份
+        company_city:
+          type: string
+          description: 城市
+        company_postalcode:
+          type: string
+          description: 邮编
+        company_add:
+          type: string
+          description: 地址
+        company_status:
+          type: string
+          description: 公司状态
+        company_level:
+          type: string
+          description: 公司等级
+        company_remark:
+          type: string
+          description: 备注
+    CompanyCreateRequest:
+      allOf:
+        - $ref: '#/components/schemas/CompanyBase'
+        - type: object
+          required: [company_id]
+    CompanyUpdateRequest:
+      type: object
+      description: >-
+        更新时可只传需要修改的字段；记录定位统一依赖路径参数 `id`。
+      properties:
+        company_id:
+          type: string
+        company_name:
+          type: string
+        company_type:
+          type: string
+        company_entity:
+          type: string
+        company_usci:
+          type: string
+        company_nationality:
+          type: string
+        company_province:
+          type: string
+        company_city:
+          type: string
+        company_postalcode:
+          type: string
+        company_add:
+          type: string
+        company_status:
+          type: string
+        company_level:
+          type: string
+        company_remark:
+          type: string
+    CompanyRecord:
+      allOf:
+        - type: object
+          properties:
+            id:
+              type: string
+              description: PocketBase 记录主键 id
+            collectionId:
+              type: string
+            collectionName:
+              type: string
+            created:
+              type: string
+            updated:
+              type: string
+        - $ref: '#/components/schemas/CompanyBase'
+    CompanyListResponse:
+      type: object
+      properties:
+        page:
+          type: integer
+        perPage:
+          type: integer
+        totalItems:
+          type: integer
+        totalPages:
+          type: integer
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/CompanyRecord'
+    PocketBaseError:
+      type: object
+      properties:
+        status:
+          type: integer
+        message:
+          type: string
+        data:
+          type: object
+          additionalProperties: true
--- a/pocket-base/spec/openapi-wx.yaml
+++ b/pocket-base/spec/openapi-wx.yaml
@@ -297,6 +297,28 @@ components:
          type: string
        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: 全平台统一身份标识
@@ -338,7 +360,17 @@ components:
          example: 2b7d9f2e3c4a5b6d7e8f
        users_picture:
          type: string
-          example: https://example.com/avatar.png
+          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:
--- a/pocket-base/spec/openapi.yaml
+++ b/pocket-base/spec/openapi.yaml
@@ -120,6 +120,28 @@ components:
          type: string
        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
@@ -180,6 +202,13 @@ components:
            users_auth_type: 0
            users_type: 注册用户
            users_picture: ''
+            users_picture_url: ''
+            users_id_pic_a: ''
+            users_id_pic_a_url: ''
+            users_id_pic_b: ''
+            users_id_pic_b_url: ''
+            users_title_picture: ''
+            users_title_picture_url: ''
            openid: app_momo
            company_id: ''
            users_parent_id: ''
@@ -211,7 +240,17 @@ components:
          example: 2b7d9f2e3c4a5b6d7e8f
        users_picture:
          type: string
-          example: https://example.com/avatar.png
+          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:
@@ -239,9 +278,19 @@ components:
          example: 12345678
        users_picture:
          type: string
-          example: https://example.com/avatar.png
+          description: 用户头像附件的 `attachments_id`
+          example: ATT-1743123456789-abc123
        users_id_number:
          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:
          type: string
        users_type:
@@ -480,52 +529,76 @@ components:
          type: string
        document_image:
          type: string
-          description: 关联多个 `attachments_id`，底层使用 `|` 分隔保存
+          description: "关联多个 `attachments_id`，底层使用 `|` 分隔保存"
        document_image_ids:
          type: array
-          description: `document_image` 解析后的附件 id 列表
+          description: "`document_image` 解析后的附件 id 列表"
          items:
            type: string
        document_image_urls:
          type: array
-          description: 根据 `document_image -> tbl_attachments` 自动解析出的图片文件流链接列表
+          description: "根据 `document_image -> tbl_attachments` 自动解析出的图片文件流链接列表"
          items:
            type: string
        document_image_url:
          type: string
-          description: 兼容字段，返回第一张图片的文件流链接
+          description: "兼容字段，返回第一张图片的文件流链接"
        document_image_attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentRecord'
        document_image_attachment:
-          allOf:
+          anyOf:
            - $ref: '#/components/schemas/AttachmentRecord'
-          nullable: true
+            - type: 'null'
        document_video:
          type: string
-          description: 关联多个 `attachments_id`，底层使用 `|` 分隔保存
+          description: "关联多个 `attachments_id`，底层使用 `|` 分隔保存"
        document_video_ids:
          type: array
-          description: `document_video` 解析后的附件 id 列表
+          description: "`document_video` 解析后的附件 id 列表"
          items:
            type: string
        document_video_urls:
          type: array
-          description: 根据 `document_video -> tbl_attachments` 自动解析出的视频文件流链接列表
+          description: "根据 `document_video -> tbl_attachments` 自动解析出的视频文件流链接列表"
          items:
            type: string
        document_video_url:
          type: string
-          description: 兼容字段，返回第一个视频的文件流链接
+          description: "兼容字段，返回第一个视频的文件流链接"
        document_video_attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentRecord'
        document_video_attachment:
-          allOf:
+          anyOf:
            - $ref: '#/components/schemas/AttachmentRecord'
-          nullable: true
+            - 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
@@ -630,6 +703,14 @@ components:
              items:
                type: string
          description: 视频附件 id 列表；支持数组或 `|` 分隔字符串
+        document_file:
+          oneOf:
+            - type: string
+              description: 多个文件附件 id 使用 `|` 分隔
+            - type: array
+              items:
+                type: string
+          description: 文件附件 id 列表；支持数组或 `|` 分隔字符串
        document_relation_model:
          type: string
        document_keywords:
@@ -1237,7 +1318,7 @@ paths:
      summary: 删除附件
      description: |
        仅允许 `ManagePlatform` 用户访问。
-        按 `attachments_id` 真删除附件；若附件已被 `tbl_document.document_image` 或 `document_video` 引用，则拒绝删除。
+        按 `attachments_id` 真删除附件；若附件已被 `tbl_document.document_image`、`document_video` 或 `document_file` 引用，则拒绝删除。
      requestBody:
        required: true
        content:
@@ -1278,8 +1359,8 @@ paths:
      description: |
        仅允许 `ManagePlatform` 用户访问。
        支持按标题、摘要、关键词等字段模糊搜索，并可按 `document_status`、`document_type` 过滤。
-        返回结果会自动根据 `document_image`、`document_video` 中的多个 `attachments_id` 关联 `tbl_attachments`，
-        额外补充 `document_image_urls`、`document_video_urls` 以及对应附件对象数组。
+        返回结果会自动根据 `document_image`、`document_video`、`document_file` 中的多个 `attachments_id` 关联 `tbl_attachments`，
+        额外补充 `document_image_urls`、`document_video_urls`、`document_file_urls` 以及对应附件对象数组。
      requestBody:
        required: false
        content:
@@ -1352,7 +1433,7 @@ paths:
        仅允许 `ManagePlatform` 用户访问。
        `document_id` 可选；未传时服务端自动生成。
        `document_title`、`document_type` 为必填；其余字段均允许为空。
-        `document_image`、`document_video` 支持传入多个已存在于 `tbl_attachments` 的 `attachments_id`。
+        `document_image`、`document_video`、`document_file` 支持传入多个已存在于 `tbl_attachments` 的 `attachments_id`。
        成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `create`。
      requestBody:
        required: true
@@ -1390,7 +1471,7 @@ paths:
        仅允许 `ManagePlatform` 用户访问。
        按 `document_id` 定位现有文档并更新。
        `document_title`、`document_type` 为必填；其余字段均允许为空。
-        若传入 `document_image`、`document_video`，则支持多个 `attachments_id`，并会逐一校验是否存在。
+        若传入 `document_image`、`document_video`、`document_file`，则支持多个 `attachments_id`，并会逐一校验是否存在。
        成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `update`。
      requestBody:
        required: true