feat: 更新用户类型逻辑，优化微信用户资料更新接口；移除不必要的安全配置，简化 API 文档

2026-03-30 12:04:02 +08:00
parent 50c09d855b
commit 6f7efbc799
5 changed files with 63 additions and 54 deletions
--- a/pocket-base/bai_api_pb_hooks/bai_api_shared/services/userService.js
+++ b/pocket-base/bai_api_pb_hooks/bai_api_shared/services/userService.js
@@ -439,7 +439,7 @@ function registerPlatformUser(payload) {
        record.set('users_phone', payload.users_phone)
        record.set('users_id_number', payload.users_id_number || '')
        record.set('users_level', payload.users_level || '')
-        record.set('users_type', payload.users_type || REGISTERED_USER_TYPE)
+        record.set('users_type', payload.users_type || GUEST_USER_TYPE)
        record.set('users_tag', payload.users_tag || '')
        record.set('company_id', payload.company_id || '')
        record.set('users_parent_id', payload.users_parent_id || '')
@@ -572,6 +572,8 @@ function updateWechatUserProfile(usersWxOpenid, payload) {
            throw createAppError(404, '未找到待编辑的用户')
        }

+        const currentUserTypeBefore = currentUser.getString('users_type') || GUEST_USER_TYPE
+
        let usersPhone = ''
        if (payload.users_phone_code) {
            usersPhone = wechatService.getWxPhoneNumber(payload.users_phone_code)
@@ -596,8 +598,13 @@ function updateWechatUserProfile(usersWxOpenid, payload) {
        if (usersPhone) {
            currentUser.set('users_phone', usersPhone)
        }
+        let hasExplicitUserType = false
        if (typeof payload.users_type !== 'undefined' && payload.users_type) {
-            currentUser.set('users_type', payload.users_type)
+            const requestedUserType = String(payload.users_type || '').trim()
+            if (requestedUserType) {
+                currentUser.set('users_type', requestedUserType)
+                hasExplicitUserType = true
+            }
        }
        if (typeof payload.company_id !== 'undefined' && payload.company_id) {
            currentUser.set('company_id', payload.company_id)
@@ -607,9 +614,8 @@ function updateWechatUserProfile(usersWxOpenid, payload) {
        }
        applyUserAttachmentFields(currentUser, payload)

-        const shouldPromote = ((currentUser.getString('users_type') || GUEST_USER_TYPE) === GUEST_USER_TYPE)
-            && typeof payload.users_type === 'undefined'
-            && isInfoComplete(currentUser)
+        const shouldPromote = (currentUserTypeBefore === GUEST_USER_TYPE)
+            && !hasExplicitUserType
        if (shouldPromote) {
            currentUser.set('users_type', REGISTERED_USER_TYPE)
        }
--- a/pocket-base/spec/openapi-manage.yaml
+++ b/pocket-base/spec/openapi-manage.yaml
@@ -29,14 +29,7 @@ tags:
    description: "面向 ManagePlatform 用户的文档新增、查询、修改、删除接口；查询时会自动返回关联附件的 PocketBase 文件流链接。"
  - name: 文档历史
    description: "面向 ManagePlatform 用户的文档操作历史查询接口。"
-security:
-  - bearerAuth: []
 components:
-  securitySchemes:
-    bearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
  schemas:
    ApiResponse:
      type: object
@@ -1325,7 +1318,6 @@ paths:
    post:
      tags: [字典管理]
      summary: 查询字典列表
-      security: []
      description: |
        公开读接口，无需 token。
        支持按 `dict_name` 模糊搜索，返回字典全量信息，并将三个聚合字段组装为 `items`。
@@ -1354,7 +1346,6 @@ paths:
    post:
      tags: [字典管理]
      summary: 查询指定字典
-      security: []
      description: |
        公开读接口，无需 token。
        按唯一键 `dict_name` 查询单条字典，并返回组装后的 `items`。
--- a/pocket-base/spec/openapi-miniapp-company.yaml
+++ b/pocket-base/spec/openapi-miniapp-company.yaml
@@ -18,8 +18,6 @@ servers:
 tags:
  - name: Company
    description: tbl_company 公司信息基础 CRUD
-security:
-  - pocketbaseAuth: []
 paths:
  /api/collections/tbl_company/records:
    get:
@@ -293,12 +291,6 @@ paths:
              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
--- a/pocket-base/spec/openapi-wx.yaml
+++ b/pocket-base/spec/openapi-wx.yaml
@@ -28,7 +28,6 @@ paths:
  /pb/api/system/users-count:
    post:
      operationId: postSystemUsersCount
-      security: []
      tags:
        - 系统
      summary: 查询用户总数
@@ -55,9 +54,6 @@ paths:
  /pb/api/system/refresh-token:
    post:
      operationId: postSystemRefreshToken
-      security:
-        - bearerAuth: []
-        - {}
      tags:
        - 系统
      summary: 刷新认证 token
@@ -116,7 +112,6 @@ paths:
  /pb/api/wechat/login:
    post:
      operationId: postWechatLogin
-      security: []
      tags:
        - 微信认证
      summary: 微信登录或首次注册
@@ -169,8 +164,6 @@ paths:
  /pb/api/wechat/profile:
    post:
      operationId: postWechatProfile
-      security:
-        - bearerAuth: []
      tags:
        - 微信认证
      summary: 更新微信用户资料
@@ -181,6 +174,8 @@ paths:
        - 所有字段都不是必填
        - 如果传了 `users_phone_code`，服务端优先调用微信接口换取真实手机号并写入 `users_phone`
        - 如果没传 `users_phone_code`，但传了 `users_phone`，则直接将该手机号写入数据库
+        - 如果上传了 `users_picture`、`users_id_pic_a`、`users_id_pic_b`、`users_title_picture`，会按附件 ID 进行关联校验并更新
+        - 若当前用户类型为 `游客`，且本次未显式传 `users_type`，服务端会自动升级为 `注册用户`
        - 如果某个字段未传或传空，则不会清空数据库中的已有值
        - 只有请求体里非空的字段才会更新到数据库
      requestBody:
@@ -197,7 +192,7 @@ paths:
              schema:
                $ref: '#/components/schemas/WechatProfileResponse'
        '400':
-          description: 参数错误、手机号已被占用、微信手机号换取失败或资料更新失败
+          description: 参数错误、手机号已被占用、附件 ID 无效、微信手机号换取失败或资料更新失败
          content:
            application/json:
              schema:
@@ -229,7 +224,6 @@ paths:
  /pb/api/collections/tbl_company/records:
    post:
      operationId: postPocketBaseCompanyRecord
-      security: []
      tags:
        - 企业信息
      summary: 创建公司
@@ -298,7 +292,6 @@ paths:
                $ref: '#/components/schemas/PocketBaseNativeError'
    get:
      operationId: getPocketBaseCompanyRecords
-      security: []
      tags:
        - 企业信息
      summary: 查询整个 tbl_company 列表 / 根据 company_id 查询对应公司信息
@@ -448,8 +441,6 @@ paths:
  /pb/api/collections/tbl_company/records/{recordId}:
    patch:
      operationId: patchPocketBaseCompanyRecordByRecordId
-      security:
-        - bearerAuth: []
      tags:
        - 企业信息
      summary: 通过 company_id 定位后修改公司信息
@@ -522,10 +513,9 @@ paths:
  /pb/api/collections/tbl_attachments/records:
    get:
      operationId: getPocketBaseAttachmentRecords
-      security: []
      tags:
        - 附件信息
-      summary: 根据 attachments_id 查询附件信息
+      summary: 根据 attachments_id 查询单条或多条附件信息
      description: |
        使用 PocketBase 原生 records list 接口查询 `tbl_attachments`。

@@ -533,10 +523,15 @@ paths:
        - `listRule = ""`，因此任何客户端都可直接读取
        - 原生 `create/update/delete` 仍仅管理员或管理后台用户允许

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

        注意：
        - 这是 PocketBase 原生返回结构，不是 hooks 统一 `{ statusCode, errMsg, data }` 包装
@@ -545,12 +540,13 @@ paths:
      parameters:
        - name: filter
          in: query
-          required: true
+          required: false
          description: |
            PocketBase 标准过滤表达式。

-            按 `attachments_id` 精确查询时固定写法为：
-            - `attachments_id="ATT-1774599142438-8n1UcU"`
+            - 按 `attachments_id` 精确查询单条：`attachments_id="ATT-1774599142438-8n1UcU"`
+            - 按多个 `attachments_id` 批量查询：`attachments_id="ATT-1774599142438-8n1UcU" || attachments_id="ATT-1774599143999-7pQkLm"`
+            - 不传该参数时，返回分页列表
          schema:
            type: string
          example: attachments_id="ATT-1774599142438-8n1UcU"
@@ -565,11 +561,11 @@ paths:
        - name: perPage
          in: query
          required: false
-          description: 每页条数；按 `attachments_id` 单查时建议固定为 `1`
+          description: 每页条数；单查建议为 `1`，批量查询建议设置为预期条数
          schema:
            type: integer
            minimum: 1
-            default: 1
+            default: 20
      responses:
        '200':
          description: 查询成功
@@ -598,6 +594,39 @@ paths:
                        attachments_ocr: OCR识别结果 | string
                        attachments_status: 附件状态 | string
                        attachments_remark: 备注 | string
+                byAttachmentsIds:
+                  value:
+                    page: 页码 | integer
+                    perPage: 每页条数 | integer
+                    totalItems: 总记录数 | integer
+                    totalPages: 总页数 | integer
+                    items:
+                      - id: PocketBase记录主键 | string
+                        collectionId: 集合ID | string
+                        collectionName: 集合名称 | string
+                        attachments_id: ATT-1774599142438-8n1UcU
+                        attachments_link: PocketBase文件字段值，可拼接文件流地址 | string
+                        attachments_filename: 原始文件名 | string
+                        attachments_filetype: 文件类型或MIME | string
+                        attachments_size: 文件大小 | number
+                        attachments_owner: 上传者业务标识 | string
+                        attachments_md5: 文件MD5 | string
+                        attachments_ocr: OCR识别结果 | string
+                        attachments_status: 附件状态 | string
+                        attachments_remark: 备注 | string
+                      - id: PocketBase记录主键 | string
+                        collectionId: 集合ID | string
+                        collectionName: 集合名称 | string
+                        attachments_id: ATT-1774599143999-7pQkLm
+                        attachments_link: PocketBase文件字段值，可拼接文件流地址 | string
+                        attachments_filename: 原始文件名 | string
+                        attachments_filetype: 文件类型或MIME | string
+                        attachments_size: 文件大小 | number
+                        attachments_owner: 上传者业务标识 | string
+                        attachments_md5: 文件MD5 | string
+                        attachments_ocr: OCR识别结果 | string
+                        attachments_status: 附件状态 | string
+                        attachments_remark: 备注 | string
        '400':
          description: 查询参数错误
          content:
@@ -619,7 +648,6 @@ paths:
  /pb/api/collections/tbl_document/records:
    get:
      operationId: getPocketBaseDocumentRecords
-      security: []
      tags:
        - 文档信息
      summary: 分页查询文档列表 / 按 system_dict_id 与 enum 双条件分页筛选文档
@@ -777,11 +805,6 @@ paths:
              schema:
                $ref: '#/components/schemas/PocketBaseNativeError'
 components:
-  securitySchemes:
-    bearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
  schemas:
    ApiResponseBase:
      type: object
--- a/pocket-base/spec/openapi.yaml
+++ b/pocket-base/spec/openapi.yaml
@@ -13,7 +13,6 @@ servers:
    description: 生产环境
  - url: http://localhost:8090
    description: PocketBase 本地环境
-security: []
 tags:
  - name: 系统
    description: 基础检查接口
@@ -1398,7 +1397,6 @@ paths:
    post:
      tags: [字典管理]
      summary: 查询字典列表
-      security: []
      description: |
        公开读接口，无需 token。
        支持按 `dict_name` 模糊搜索，返回字典全量信息，并将三个聚合字段组装为 `items`。
@@ -1427,7 +1425,6 @@ paths:
    post:
      tags: [字典管理]
      summary: 查询指定字典
-      security: []
      description: |
        公开读接口，无需 token。
        按唯一键 `dict_name` 查询单条字典，并返回组装后的 `items`。