feat: 添加微信端 API 文档和字典表初始化脚本

- 新增 openapi-wx.yaml 文件，定义微信端接口文档，包括用户统计、token 刷新、微信登录和用户资料更新等接口。 - 新增 pocketbase.dictionary.js 脚本，用于初始化和校验字典表结构，确保与预期一致。
2026-03-27 19:26:25 +08:00
parent c43aae783f
commit eaf282ea24
17 changed files with 2880 additions and 128 deletions
--- a/pocket-base/spec/openapi-wx.yaml
+++ b/pocket-base/spec/openapi-wx.yaml
@@ -0,0 +1,419 @@
+openapi: 3.1.0
+info:
+  title: BAI PocketBase WeChat API
+  version: 1.0.0-wx
+  description: |
+    面向微信端的小程序接口文档。
+    本文档只包含微信登录、微信资料完善，以及微信端会共用的系统接口。
+  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: 微信登录、资料完善与 token 刷新接口
+paths:
+  /pb/api/system/users-count:
+    post:
+      operationId: postSystemUsersCount
+      security: []
+      tags:
+        - 系统
+      summary: 查询用户总数
+      description: 统计 `tbl_auth_users` 集合中的记录总数。
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UsersCountResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /pb/api/system/refresh-token:
+    post:
+      operationId: postSystemRefreshToken
+      security:
+        - bearerAuth: []
+        - {}
+      tags:
+        - 系统
+      summary: 刷新认证 token
+      description: |
+        当当前 `Authorization` 仍有效时，直接基于当前 auth 用户续签。
+        当 token 失效时，可传入 `users_wx_code` 走微信 code 重新签发。
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SystemRefreshTokenRequest'
+      responses:
+        '200':
+          description: 刷新成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RefreshTokenResponse'
+        '400':
+          description: 参数错误或微信 code 换取失败
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: token 无效，且未提供有效的 `users_wx_code`
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: 当前用户不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: 请求体不是 JSON
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: 请求过于频繁
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /pb/api/wechat/login:
+    post:
+      operationId: postWechatLogin
+      security: []
+      tags:
+        - 微信认证
+      summary: 微信登录或首次注册
+      description: |
+        使用微信 `users_wx_code` 换取微信 openid。
+        若 `tbl_auth_users` 中不存在对应用户，则自动创建新 auth 用户并返回 token。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WechatLoginRequest'
+      responses:
+        '200':
+          description: 登录或注册成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AuthSuccessResponse'
+        '400':
+          description: 参数错误或保存用户失败
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: 认证失败
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: 请求体不是 JSON
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: 请求过于频繁
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /pb/api/wechat/profile:
+    post:
+      operationId: postWechatProfile
+      security:
+        - bearerAuth: []
+      tags:
+        - 微信认证
+      summary: 更新微信用户资料
+      description: |
+        基于当前 `Authorization` 对应的 auth 用户更新昵称、手机号和头像。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WechatProfileRequest'
+      responses:
+        '200':
+          description: 更新成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WechatProfileResponse'
+        '400':
+          description: 参数错误、手机号已被占用或资料更新失败
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: token 无效或缺少 openid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: 请求体不是 JSON
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: 请求过于频繁
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+  schemas:
+    ApiResponseBase:
+      type: object
+      required:
+        - code
+        - msg
+        - data
+      properties:
+        code:
+          type: integer
+          example: 200
+        msg:
+          type: string
+          example: 操作成功
+        data:
+          type: object
+          additionalProperties: true
+    ErrorResponse:
+      type: object
+      required:
+        - code
+        - msg
+        - data
+      properties:
+        code:
+          type: integer
+          example: 400
+        msg:
+          type: string
+          example: 请求失败
+        data:
+          type: object
+          additionalProperties: true
+    CompanyInfo:
+      anyOf:
+        - type: object
+          additionalProperties: true
+        - type: 'null'
+    UserInfo:
+      type: object
+      properties:
+        pb_id:
+          type: string
+        users_convers_id:
+          type: string
+        users_id:
+          type: string
+        users_idtype:
+          type: string
+          enum:
+            - WeChat
+            - ManagePlatform
+        users_id_number:
+          type: string
+        users_type:
+          type: string
+        users_name:
+          type: string
+        users_status:
+          type:
+            - string
+            - number
+        users_rank_level:
+          type:
+            - number
+            - integer
+        users_auth_type:
+          type:
+            - number
+            - integer
+        users_phone:
+          type: string
+        users_phone_masked:
+          type: string
+        users_level:
+          type: string
+        users_picture:
+          type: string
+        openid:
+          type: string
+          description: 全平台统一身份标识
+        company_id:
+          type: string
+        users_parent_id:
+          type: string
+        users_promo_code:
+          type: string
+        usergroups_id:
+          type: string
+        company:
+          $ref: '#/components/schemas/CompanyInfo'
+        created:
+          type: string
+        updated:
+          type: string
+    WechatLoginRequest:
+      type: object
+      required:
+        - users_wx_code
+      properties:
+        users_wx_code:
+          type: string
+          description: 微信小程序登录临时凭证 code
+          example: 0a1b2c3d4e5f6g
+    WechatProfileRequest:
+      type: object
+      required:
+        - users_name
+        - users_phone_code
+        - users_picture
+      properties:
+        users_name:
+          type: string
+          example: 张三
+        users_phone_code:
+          type: string
+          example: 2b7d9f2e3c4a5b6d7e8f
+        users_picture:
+          type: string
+          example: https://example.com/avatar.png
+    SystemRefreshTokenRequest:
+      type: object
+      properties:
+        users_wx_code:
+          type:
+            - string
+            - 'null'
+          description: |
+            可选。
+            当前 token 失效时，可通过该 code 重新签发 token。
+          example: 0a1b2c3d4e5f6g
+    AuthSuccessData:
+      type: object
+      properties:
+        status:
+          type: string
+          enum:
+            - register_success
+            - login_success
+        is_info_complete:
+          type: boolean
+        user:
+          $ref: '#/components/schemas/UserInfo'
+    AuthSuccessResponse:
+      allOf:
+        - $ref: '#/components/schemas/ApiResponseBase'
+        - type: object
+          required:
+            - token
+          properties:
+            data:
+              $ref: '#/components/schemas/AuthSuccessData'
+            token:
+              type: string
+              description: PocketBase 原生 auth token
+    WechatProfileResponseData:
+      type: object
+      properties:
+        status:
+          type: string
+          enum:
+            - update_success
+        user:
+          $ref: '#/components/schemas/UserInfo'
+    WechatProfileResponse:
+      allOf:
+        - $ref: '#/components/schemas/ApiResponseBase'
+        - type: object
+          properties:
+            data:
+              $ref: '#/components/schemas/WechatProfileResponseData'
+    RefreshTokenResponse:
+      allOf:
+        - $ref: '#/components/schemas/ApiResponseBase'
+        - type: object
+          required:
+            - token
+          properties:
+            data:
+              type: object
+              additionalProperties: true
+              example: {}
+            token:
+              type: string
+              description: 新签发的 PocketBase 原生 auth token
+    UsersCountData:
+      type: object
+      properties:
+        total_users:
+          type: integer
+          example: 128
+    UsersCountResponse:
+      allOf:
+        - $ref: '#/components/schemas/ApiResponseBase'
+        - type: object
+          properties:
+            data:
+              $ref: '#/components/schemas/UsersCountData'