openapi: 3.1.0
info:
  title: BAI Management API
  description: BAI 管理系统后端 API 文档
  version: 1.0.0
servers:
  - url: https://bai-api.blv-oa.com
    description: BAI-api生产环境
  - url: http://localhost:3000
    description: BAI-api本地开发环境
tags:
  - name: 系统
    description: 基础健康检查接口
  - name: 微信小程序用户
    description: 微信小程序注册、登录与鉴权接口
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ApiResponse:
      type: object
      required: [code, msg, data]
      properties:
        code:
          type: integer
          description: 业务状态码
          example: 200
        msg:
          type: string
          description: 响应消息
          example: 操作成功
        data:
          type: object
          description: 响应数据
          additionalProperties: true
    HealthData:
      type: object
      properties:
        status:
          type: string
          example: healthy
        timestamp:
          type: string
          format: date-time
    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
          description: 最近一次构建时间；开发模式下若未执行构建则可能为空
          format: date-time
    WechatProfileRequest:
      type: object
      required: [users_name, users_phone_code, users_picture]
      properties:
        users_name:
          type: string
          description: 用户姓名
          example: 张三
        users_phone_code:
          type: string
          description: 微信手机号获取凭证 code，由后端换取真实手机号后写入 users_phone
          example: 2b7d9f2e3c4a5b6d7e8f
        users_picture:
          type: string
          description: 用户头像 URL
          example: https://example.com/avatar.png
    WechatAuthRequest:
      type: object
      required: [users_wx_code]
      properties:
        users_wx_code:
          type: string
          description: 微信小程序登录临时凭证 code
          example: 0a1b2c3d4e5f6g
    CompanyInfo:
      type: object
      properties:
        company_id:
          type: string
          example: C10001
        company_name:
          type: string
          example: 示例科技有限公司
        company_type:
          type: string
          example: 科技服务
        company_entity:
          type: string
          example: 李四
        company_usci:
          type: string
          example: 91330100XXXXXXXXXX
        company_nationality:
          type: string
          example: 中国
        company_province:
          type: string
          example: 浙江省
        company_city:
          type: string
          example: 杭州市
        company_postalcode:
          type: string
          example: "310000"
        company_add:
          type: string
          example: 某某大道 100 号
        company_status:
          type: string
          example: 正常
        company_level:
          type: string
          example: A
        company_remark:
          type: string
          example: 重点合作客户
    UserInfo:
      type: object
      properties:
        users_id:
          type: string
          example: U202603190001
        users_type:
          type: string
          description: |
            用户类型。
            - `游客`：仅完成微信新号注册，尚未首次完整补充 `users_name`、`users_phone`、`users_picture`
            - `注册用户`：用户曾从“三项资料均为空”首次补充为“三项资料均完整”
          enum: [游客, 注册用户]
          example: 游客
        users_name:
          type: string
          example: 张三
        users_phone:
          type: string
          example: "13800138000"
        users_phone_masked:
          type: string
          example: "138****8000"
        users_picture:
          type: string
          example: https://example.com/avatar.png
        users_wx_openid:
          type: string
          example: oAbCdEfGh123456789
        company_id:
          type: string
          example: C10001
        company:
          $ref: '#/components/schemas/CompanyInfo'
        pb_id:
          type: string
          description: PocketBase 记录 id
          example: abc123xyz
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
    WechatProfileResponseData:
      type: object
      properties:
        status:
          type: string
          description: 信息编辑状态
          enum: [update_success, update_failed]
        user:
          $ref: '#/components/schemas/UserInfo'
    WechatAuthResponseData:
      type: object
      properties:
        status:
          type: string
          description: 登录/注册结果状态
          enum: [register_success, login_success]
        is_info_complete:
          type: boolean
          description: 用户资料是否已完善
          example: true
        token:
          type: string
          description: JWT 令牌
        user:
          $ref: '#/components/schemas/UserInfo'
paths:
  /api/test-helloworld:
    post:
      tags: [系统]
      summary: Test endpoint
      description: Returns a hello world message and build time
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/HelloWorldData'
  /api/health:
    post:
      tags: [系统]
      summary: 健康检查
      description: 检查服务是否正常运行
      responses:
        '200':
          description: 服务状态正常
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/HealthData'
  /api/wechat/login:
    post:
      tags: [微信小程序用户]
      summary: 微信小程序登录/注册合一
      description: |
        使用微信小程序临时登录凭证换取 openid。
        若用户不存在，则自动创建新账号并返回完整用户信息；若已存在，则直接登录并返回完整用户信息。
        登录/注册合一接口不处理手机号获取。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - users_wx_code
              properties:
                users_wx_code:
                  type: string
                  description: 微信小程序登录临时凭证 code
                  example: 0a1b2c3d4e5f6g
      responses:
        '200':
          description: 登录或注册成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/WechatAuthResponseData'
        '400':
          description: 参数错误
        '415':
          description: 请求体格式错误，仅支持 application/json
        '429':
          description: 重复提交过于频繁
        '500':
          description: 服务端异常
  /api/wechat/profile:
    post:
      tags: [微信小程序用户]
      summary: 微信小程序用户信息编辑
      description: |
        从请求头 `users_wx_openid` 定位用户，不再从 body 中传 `users_wx_code`。
        body 中传入 `users_name`、`users_phone_code`、`users_picture`。
        后端会通过微信 `users_phone_code` 调用官方接口换取真实手机号，再写入 `users_phone`。
        `users_name`、`users_phone_code`、`users_picture` 均为必填项。
        当且仅当用户原先这三项资料全部为空，且本次首次完整补充三项资料时，系统自动将 `users_type` 从 `游客` 更新为 `注册用户`。
        后续资料修改不会再影响已确定的 `users_type`。
        返回更新后的完整用户信息，其中手机号等敏感字段需脱敏处理。
      parameters:
        - in: header
          name: users_wx_openid
          required: true
          schema:
            type: string
          description: 微信用户唯一标识，用于数据库查询
        - in: header
          name: Authorization
          required: true
          schema:
            type: string
          description: 标准 JWT 认证头，格式为 `Bearer <token>`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - users_name
                - users_phone_code
                - users_picture
              properties:
                users_name:
                  type: string
                  description: 用户姓名
                  example: 张三
                users_phone_code:
                  type: string
                  description: 微信手机号获取凭证 code
                  example: 2b7d9f2e3c4a5b6d7e8f
                users_picture:
                  type: string
                  description: 用户头像 URL
                  example: https://example.com/avatar.png
      responses:
        '200':
          description: 信息更新成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/WechatProfileResponseData'
        '400':
          description: 参数错误
        '401':
          description: 请求头缺少 users_wx_openid 或 Authorization，或令牌无效
        '415':
          description: 请求体格式错误，仅支持 application/json
        '404':
          description: 用户不存在
        '500':
          description: 服务端异常
  /api/wechat/refresh-token:
    post:
      tags: [微信小程序用户]
      summary: 微信小程序刷新 token
      description: |
        小程序通过请求头中的 `users_wx_openid` 定位用户，并返回新的 JWT token。
        本接口无 body 参数，请求方法固定为 POST。
        本接口不要求旧 `Authorization`，仅依赖 `users_wx_openid` 识别用户并签发新 token。
      parameters:
        - in: header
          name: users_wx_openid
          required: true
          schema:
            type: string
          description: 微信用户唯一标识，用于数据库查询
      responses:
        '200':
          description: 刷新成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          token:
                            type: string
                            description: 新的 JWT 令牌
        '404':
          description: 未注册用户
        '401':
          description: 请求头缺少 users_wx_openid
        '500':
          description: 服务端异常