Web_BAI_Manage_ApiServer/pocket-base/spec/openapi.yaml

openapi: 3.1.0
info:
  title: BAI PocketBase Hooks 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
servers:
  - url: https://bai-api.blv-oa.com/pb
    description: 生产环境
  - url: http://localhost:8090
    description: PocketBase 本地环境
tags:
  - name: 系统
    description: 基础检查接口
  - name: 微信认证
    description: 面向微信用户的认证接口；认证成功后仍统一使用全平台 `openid` 与 PocketBase 原生 token。
  - name: 平台认证
    description: 面向平台用户的认证接口；平台用户会生成 GUID 并写入统一 `openid` 字段。
  - name: 字典管理
    description: 面向 ManagePlatform 用户的系统字典维护接口。
components:
  schemas:
    ApiResponse:
      type: object
      required: [code, msg, data]
      properties:
        code:
          type: integer
          example: 200
        msg:
          type: string
          example: 操作成功
        data:
          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
          nullable: true
          format: date-time
    CompanyInfo:
      type: object
      nullable: true
      additionalProperties: true
    UserInfo:
      type: object
      description: |
        统一用户视图。
        其中 `openid` 为全平台统一身份标识：微信用户使用微信 openid，平台用户使用服务端生成 GUID。
      properties:
        pb_id:
          type: string
        users_convers_id:
          type: string
        users_id:
          type: string
        users_idtype:
          type: string
          description: 用户身份来源类型
          enum: [WeChat, ManagePlatform]
        users_id_number:
          type: string
        users_status:
          type: string
        users_rank_level:
          type: number
        users_auth_type:
          type: number
        users_type:
          type: string
          enum: [游客, 注册用户]
        users_name:
          type: string
        users_phone:
          type: string
        users_phone_masked:
          type: string
        users_level:
          type: string
        users_picture:
          type: string
        openid:
          type: string
          description: 全平台统一身份标识；微信用户为微信 openid，平台用户为服务端生成的 GUID
        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
    PocketBaseAuthResponse:
      type: object
      description: |
        项目统一认证响应。
        所有对外接口统一返回 `code`、`msg`、`data`，认证成功时额外返回顶层 `token`。
      properties:
        code:
          type: integer
          example: 200
        msg:
          type: string
          example: 登录成功
        data:
          type: object
          properties:
            status:
              type: string
              enum: [register_success, login_success]
            is_info_complete:
              type: boolean
            user:
              $ref: '#/components/schemas/UserInfo'
        token:
          type: string
          description: PocketBase 原生 auth token；仅认证类接口在成功时额外返回
      example:
        code: 200
        msg: 登录成功
        data:
          status: login_success
          is_info_complete: true
          user:
            pb_id: vtukf6agem2xbcv
            users_id: U202603260001
            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...
    WechatLoginRequest:
      type: object
      required: [users_wx_code]
      description: 微信小程序登录/注册请求体。
      properties:
        users_wx_code:
          type: string
          description: 微信小程序登录临时凭证 code
          example: 0a1b2c3d4e5f6g
    WechatProfileRequest:
      type: object
      required: [users_name, users_phone_code, users_picture]
      description: 微信用户资料完善请求体。
      properties:
        users_name:
          type: string
          example: 张三
        users_phone_code:
          type: string
          example: 2b7d9f2e3c4a5b6d7e8f
        users_picture:
          type: string
          example: https://example.com/avatar.png
    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
          example: 张三
        users_phone:
          type: string
          example: 13800138000
        password:
          type: string
          example: 12345678
        passwordConfirm:
          type: string
          example: 12345678
        users_picture:
          type: string
          example: https://example.com/avatar.png
        users_id_number:
          type: string
        users_level:
          type: string
        users_type:
          type: string
        company_id:
          type: string
        users_parent_id:
          type: string
        users_promo_code:
          type: string
        usergroups_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
          example: 12345678
    SystemRefreshTokenRequest:
      type: object
      description: |
        系统刷新 token 请求体。
        `users_wx_code` 允许为空。
        当 `Authorization` 对应 token 有效时，可不传或传空；
        当 token 失效时，需提供 `users_wx_code` 走微信 code 重新签发流程。
      properties:
        users_wx_code:
          type: string
          nullable: true
          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: 启用
        sortOrder:
          type: integer
          example: 1
    DictionaryRecord:
      type: object
      properties:
        pb_id:
          type: string
        system_dict_id:
          type: string
        dict_name:
          type: string
        dict_word_is_enabled:
          type: boolean
        dict_word_parent_id:
          type: string
        dict_word_remark:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/DictionaryItem'
        created:
          type: string
        updated:
          type: string
    DictionaryListRequest:
      type: object
      properties:
        keyword:
          type: string
          description: 对 `dict_name` 的模糊搜索关键字
          example: 状态
    DictionaryDetailRequest:
      type: object
      required: [dict_name]
      properties:
        dict_name:
          type: string
          example: 用户状态
    DictionaryMutationRequest:
      type: object
      required: [dict_name, items]
      properties:
        original_dict_name:
          type: string
          description: 更新时用于定位原始记录；新增时可不传
          example: 用户状态
        dict_name:
          type: string
          example: 用户状态
        dict_word_is_enabled:
          type: boolean
          example: true
        dict_word_parent_id:
          type: string
          example: ''
        dict_word_remark:
          type: string
          example: 系统状态字典
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/DictionaryItem'
    DictionaryDeleteRequest:
      type: object
      required: [dict_name]
      properties:
        dict_name:
          type: string
          example: 用户状态
paths:
  /api/system/test-helloworld:
    post:
      tags: [系统]
      summary: HelloWorld 测试接口
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/HelloWorldData'
  /api/system/health:
    post:
      tags: [系统]
      summary: 健康检查
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/HealthData'
  /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:
                        $ref: '#/components/schemas/UsersCountData'
  /api/system/refresh-token:
    post:
      tags: [系统]
      summary: 刷新系统认证 token
      description: |
        当前实现支持两种刷新路径：
        1) 若 `Authorization` 对应 token 仍有效：直接按当前 auth record 续签（不调用微信接口）。
        2) 若 token 已过期：仅在 body 提供 `users_wx_code` 时才走微信 code 重新签发。
        返回体仅包含新的 `token`，不返回完整登录用户信息。
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SystemRefreshTokenRequest'
      responses:
        '200':
          description: 刷新成功（返回精简 token）
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      token:
                        type: string
                        description: 新签发的 PocketBase 原生 auth token
              example:
                code: 200
                msg: 刷新成功
                data: {}
                token: eyJhbGciOi...
        '400':
          description: 参数错误或微信侧身份换取失败
        '401':
          description: token 无效/已过期，且未提供 users_wx_code
        '404':
          description: 用户不存在
        '415':
          description: 请求体必须为 application/json
        '429':
          description: 重复请求过于频繁
  /api/wechat/login:
    post:
      tags: [微信认证]
      summary: 微信登录/注册合一
      description: |
        使用微信 code 换取微信侧 openid，并写入统一身份字段 `tbl_auth_users.openid`。
        若 `tbl_auth_users` 中不存在对应用户则自动创建 auth record，随后返回 PocketBase 原生 auth token。
        首次注册创建时会写入 `users_idtype = WeChat`。
        返回的 `token` 可直接用于 PocketBase SDK 与当前 hooks 接口调用。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WechatLoginRequest'
      responses:
        '200':
          description: 登录或注册成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PocketBaseAuthResponse'
        '400':
          description: 参数错误或微信侧身份换取失败
        '401':
          description: PocketBase 原生认证失败
        '415':
          description: 请求体必须为 application/json
        '429':
          description: 重复请求过于频繁
        '500':
          description: 保存 auth 用户失败或服务端内部错误
  /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: 重复请求过于频繁
  /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: 重复请求过于频繁
  /api/wechat/profile:
    post:
      tags: [微信认证]
      summary: 更新微信用户资料
      description: |
        基于当前 `Authorization` 对应 auth record 中的统一 `openid` 定位当前微信用户。
        当前接口仍用于微信资料完善场景。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WechatProfileRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/WechatProfileResponseData'
        '401':
          description: token 无效或当前 auth record 缺少统一身份字段 openid
        '400':
          description: 参数错误、手机号已被注册或资料更新失败
  /api/dictionary/list:
    post:
      tags: [字典管理]
      summary: 查询字典列表
      description: |
        仅允许 `ManagePlatform` 用户访问。
        支持按 `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:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              $ref: '#/components/schemas/DictionaryRecord'
        '401':
          description: token 无效或已过期
        '403':
          description: 非 ManagePlatform 用户无权访问
        '415':
          description: 请求体必须为 application/json
  /api/dictionary/detail:
    post:
      tags: [字典管理]
      summary: 查询指定字典
      description: |
        仅允许 `ManagePlatform` 用户访问。
        按唯一键 `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:
                        $ref: '#/components/schemas/DictionaryRecord'
        '400':
          description: 参数错误
        '401':
          description: token 无效或已过期
        '403':
          description: 非 ManagePlatform 用户无权访问
        '404':
          description: 未找到对应字典
        '415':
          description: 请求体必须为 application/json
  /api/dictionary/create:
    post:
      tags: [字典管理]
      summary: 新增字典
      description: |
        仅允许 `ManagePlatform` 用户访问。
        `system_dict_id` 由服务端自动生成；`dict_name` 必须唯一；
        `items` 会分别序列化写入 `dict_word_enum`、`dict_word_description`、`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:
                        $ref: '#/components/schemas/DictionaryRecord'
        '400':
          description: 参数错误或 dict_name 已存在
        '401':
          description: token 无效或已过期
        '403':
          description: 非 ManagePlatform 用户无权访问
        '415':
          description: 请求体必须为 application/json
        '429':
          description: 重复请求过于频繁
  /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:
                        $ref: '#/components/schemas/DictionaryRecord'
        '400':
          description: 参数错误或 dict_name 冲突
        '401':
          description: token 无效或已过期
        '403':
          description: 非 ManagePlatform 用户无权访问
        '404':
          description: 未找到待修改字典
        '415':
          description: 请求体必须为 application/json
        '429':
          description: 重复请求过于频繁
  /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:
                        type: object
                        properties:
                          dict_name:
                            type: string
        '400':
          description: 参数错误或删除失败
        '401':
          description: token 无效或已过期
        '403':
          description: 非 ManagePlatform 用户无权访问
        '404':
          description: 未找到待删除字典
        '415':
          description: 请求体必须为 application/json
        '429':
          description: 重复请求过于频繁