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
          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: 全平台统一身份标识
        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
          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:
        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'