hyapp-server/docs/openapi/user.swagger.yaml

swagger: "2.0"
info:
  title: HY User Service API
  version: "1.0.0"
  description: |
    user-service 当前只暴露内部 gRPC + protobuf 接口，没有 HTTP JSON router。
    本文件用 OpenAPI 2.0 记录 gRPC 合约，`paths` 使用 gRPC full method 作为文档路径，不代表真实 HTTP endpoint。
host: localhost:13005
basePath: /
schemes:
  - http
consumes:
  - application/grpc+proto
produces:
  - application/grpc+proto
tags:
  - name: auth
    description: AuthService，登录注册和 token 生命周期。
  - name: users
    description: UserService，用户主状态读取。
  - name: user-identity
    description: UserIdentityService，展示短号解析和变更。
  - name: health
    description: 标准 grpc.health.v1.Health。
responses:
  GRPCError:
    description: gRPC status error；稳定业务原因放在 google.rpc.ErrorInfo.reason。
    schema:
      $ref: "#/definitions/GRPCError"
paths:
  /hyapp.user.v1.AuthService/LoginPassword:
    post:
      tags:
        - auth
      summary: 短号密码登录
      operationId: userAuthLoginPassword
      x-grpc-full-method: /hyapp.user.v1.AuthService/LoginPassword
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/LoginPasswordRequest"
      responses:
        "200":
          description: 登录成功。
          schema:
            $ref: "#/definitions/AuthResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.user.v1.AuthService/LoginThirdParty:
    post:
      tags:
        - auth
      summary: 三方登录或注册
      operationId: userAuthLoginThirdParty
      x-grpc-full-method: /hyapp.user.v1.AuthService/LoginThirdParty
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/LoginThirdPartyRequest"
      responses:
        "200":
          description: 登录或注册成功。
          schema:
            $ref: "#/definitions/AuthResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.user.v1.AuthService/SetPassword:
    post:
      tags:
        - auth
      summary: 首次设置密码
      operationId: userAuthSetPassword
      x-grpc-full-method: /hyapp.user.v1.AuthService/SetPassword
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/SetPasswordRequest"
      responses:
        "200":
          description: 密码设置完成。
          schema:
            $ref: "#/definitions/SetPasswordResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.user.v1.AuthService/RefreshToken:
    post:
      tags:
        - auth
      summary: 刷新 token
      operationId: userAuthRefreshToken
      x-grpc-full-method: /hyapp.user.v1.AuthService/RefreshToken
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/RefreshTokenRequest"
      responses:
        "200":
          description: 刷新成功。
          schema:
            $ref: "#/definitions/RefreshTokenResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.user.v1.AuthService/Logout:
    post:
      tags:
        - auth
      summary: 登出并失效 refresh session
      operationId: userAuthLogout
      x-grpc-full-method: /hyapp.user.v1.AuthService/Logout
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/LogoutRequest"
      responses:
        "200":
          description: 登出处理完成。
          schema:
            $ref: "#/definitions/LogoutResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.user.v1.UserService/GetUser:
    post:
      tags:
        - users
      summary: 查询单个用户主状态
      operationId: userGetUser
      x-grpc-full-method: /hyapp.user.v1.UserService/GetUser
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/GetUserRequest"
      responses:
        "200":
          description: 查询成功。
          schema:
            $ref: "#/definitions/GetUserResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.user.v1.UserService/BatchGetUsers:
    post:
      tags:
        - users
      summary: 批量查询用户主状态
      operationId: userBatchGetUsers
      x-grpc-full-method: /hyapp.user.v1.UserService/BatchGetUsers
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/BatchGetUsersRequest"
      responses:
        "200":
          description: 查询成功；缺失用户不填充占位对象。
          schema:
            $ref: "#/definitions/BatchGetUsersResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.user.v1.UserIdentityService/GetUserIdentity:
    post:
      tags:
        - user-identity
      summary: 按 user_id 查询当前展示短号
      operationId: userGetUserIdentity
      x-grpc-full-method: /hyapp.user.v1.UserIdentityService/GetUserIdentity
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/GetUserIdentityRequest"
      responses:
        "200":
          description: 查询成功。
          schema:
            $ref: "#/definitions/GetUserIdentityResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.user.v1.UserIdentityService/ResolveDisplayUserID:
    post:
      tags:
        - user-identity
      summary: 通过当前展示短号解析用户
      operationId: userResolveDisplayUserID
      x-grpc-full-method: /hyapp.user.v1.UserIdentityService/ResolveDisplayUserID
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/ResolveDisplayUserIDRequest"
      responses:
        "200":
          description: 解析成功。
          schema:
            $ref: "#/definitions/ResolveDisplayUserIDResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.user.v1.UserIdentityService/ChangeDisplayUserID:
    post:
      tags:
        - user-identity
      summary: 修改默认展示短号
      operationId: userChangeDisplayUserID
      x-grpc-full-method: /hyapp.user.v1.UserIdentityService/ChangeDisplayUserID
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/ChangeDisplayUserIDRequest"
      responses:
        "200":
          description: 修改成功。
          schema:
            $ref: "#/definitions/ChangeDisplayUserIDResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.user.v1.UserIdentityService/ApplyPrettyDisplayUserID:
    post:
      tags:
        - user-identity
      summary: 申请临时靓号
      operationId: userApplyPrettyDisplayUserID
      x-grpc-full-method: /hyapp.user.v1.UserIdentityService/ApplyPrettyDisplayUserID
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/ApplyPrettyDisplayUserIDRequest"
      responses:
        "200":
          description: 申请成功。
          schema:
            $ref: "#/definitions/ApplyPrettyDisplayUserIDResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.user.v1.UserIdentityService/ExpirePrettyDisplayUserID:
    post:
      tags:
        - user-identity
      summary: 主动触发靓号过期恢复
      operationId: userExpirePrettyDisplayUserID
      x-grpc-full-method: /hyapp.user.v1.UserIdentityService/ExpirePrettyDisplayUserID
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/ExpirePrettyDisplayUserIDRequest"
      responses:
        "200":
          description: 恢复成功。
          schema:
            $ref: "#/definitions/ExpirePrettyDisplayUserIDResponse"
        default:
          $ref: "#/responses/GRPCError"
  /grpc.health.v1.Health/Check:
    post:
      tags:
        - health
      summary: 标准 gRPC health check
      operationId: userHealthCheck
      x-grpc-full-method: /grpc.health.v1.Health/Check
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/HealthCheckRequest"
      responses:
        "200":
          description: 返回 SERVING 或 NOT_SERVING；未知 service 返回 gRPC NotFound。
          schema:
            $ref: "#/definitions/HealthCheckResponse"
        default:
          $ref: "#/responses/GRPCError"
  /grpc.health.v1.Health/Watch:
    post:
      tags:
        - health
      summary: 标准 gRPC health watch
      operationId: userHealthWatch
      x-grpc-full-method: /grpc.health.v1.Health/Watch
      x-server-streaming: true
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/HealthCheckRequest"
      responses:
        "200":
          description: 服务端流式推送健康状态变化。
          schema:
            $ref: "#/definitions/HealthCheckResponse"
        default:
          $ref: "#/responses/GRPCError"
definitions:
  RequestMeta:
    type: object
    properties:
      request_id:
        type: string
      caller:
        type: string
      gateway_node_id:
        type: string
      sent_at_ms:
        type: integer
        format: int64
      device_id:
        type: string
      client_ip:
        type: string
      user_agent:
        type: string
  AuthToken:
    type: object
    properties:
      user_id:
        type: integer
        format: int64
      session_id:
        type: string
      access_token:
        type: string
      refresh_token:
        type: string
      expires_in_sec:
        type: integer
        format: int64
      token_type:
        type: string
      display_user_id:
        type: string
      default_display_user_id:
        type: string
      display_user_id_kind:
        type: string
      display_user_id_expires_at_ms:
        type: integer
        format: int64
  LoginPasswordRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      display_user_id:
        type: string
      password:
        type: string
  LoginThirdPartyRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      provider:
        type: string
      credential:
        type: string
  AuthResponse:
    type: object
    properties:
      token:
        $ref: "#/definitions/AuthToken"
      is_new_user:
        type: boolean
  SetPasswordRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      user_id:
        type: integer
        format: int64
      password:
        type: string
  SetPasswordResponse:
    type: object
    properties:
      password_set:
        type: boolean
  RefreshTokenRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      refresh_token:
        type: string
  RefreshTokenResponse:
    type: object
    properties:
      token:
        $ref: "#/definitions/AuthToken"
  LogoutRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      session_id:
        type: string
      refresh_token:
        type: string
  LogoutResponse:
    type: object
    properties:
      revoked:
        type: boolean
  User:
    type: object
    properties:
      user_id:
        type: integer
        format: int64
      status:
        type: integer
        format: int32
        enum:
          - 0
          - 1
          - 2
          - 3
        x-enum-names:
          - USER_STATUS_UNSPECIFIED
          - USER_STATUS_ACTIVE
          - USER_STATUS_DISABLED
          - USER_STATUS_BANNED
      created_at_ms:
        type: integer
        format: int64
      updated_at_ms:
        type: integer
        format: int64
      display_user_id:
        type: string
      default_display_user_id:
        type: string
      display_user_id_kind:
        type: string
      display_user_id_expires_at_ms:
        type: integer
        format: int64
  GetUserRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      user_id:
        type: integer
        format: int64
  GetUserResponse:
    type: object
    properties:
      user:
        $ref: "#/definitions/User"
  BatchGetUsersRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      user_ids:
        type: array
        items:
          type: integer
          format: int64
  BatchGetUsersResponse:
    type: object
    properties:
      users:
        type: object
        additionalProperties:
          $ref: "#/definitions/User"
  UserIdentity:
    type: object
    properties:
      user_id:
        type: integer
        format: int64
      display_user_id:
        type: string
      status:
        type: string
      default_display_user_id:
        type: string
      display_user_id_kind:
        type: string
      display_user_id_expires_at_ms:
        type: integer
        format: int64
  GetUserIdentityRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      user_id:
        type: integer
        format: int64
  GetUserIdentityResponse:
    type: object
    properties:
      identity:
        $ref: "#/definitions/UserIdentity"
  ResolveDisplayUserIDRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      display_user_id:
        type: string
  ResolveDisplayUserIDResponse:
    type: object
    properties:
      identity:
        $ref: "#/definitions/UserIdentity"
  ChangeDisplayUserIDRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      user_id:
        type: integer
        format: int64
      new_display_user_id:
        type: string
      reason:
        type: string
      operator_user_id:
        type: integer
        format: int64
  ChangeDisplayUserIDResponse:
    type: object
    properties:
      identity:
        $ref: "#/definitions/UserIdentity"
  ApplyPrettyDisplayUserIDRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      user_id:
        type: integer
        format: int64
      pretty_display_user_id:
        type: string
      lease_duration_ms:
        type: integer
        format: int64
      payment_receipt_id:
        type: string
  ApplyPrettyDisplayUserIDResponse:
    type: object
    properties:
      identity:
        $ref: "#/definitions/UserIdentity"
      lease_id:
        type: string
  ExpirePrettyDisplayUserIDRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      user_id:
        type: integer
        format: int64
      lease_id:
        type: string
  ExpirePrettyDisplayUserIDResponse:
    type: object
    properties:
      identity:
        $ref: "#/definitions/UserIdentity"
  HealthCheckRequest:
    type: object
    properties:
      service:
        type: string
        description: 空字符串或 `user-service`。
  HealthCheckResponse:
    type: object
    properties:
      status:
        type: integer
        format: int32
        enum:
          - 0
          - 1
          - 2
          - 3
        x-enum-names:
          - UNKNOWN
          - SERVING
          - NOT_SERVING
          - SERVICE_UNKNOWN
  GRPCError:
    type: object
    properties:
      grpc_code:
        type: string
        enum:
          - InvalidArgument
          - NotFound
          - FailedPrecondition
          - Unauthenticated
          - PermissionDenied
          - Unavailable
          - AlreadyExists
          - Internal
          - Aborted
      reason:
        type: string
        enum:
          - INVALID_ARGUMENT
          - NOT_FOUND
          - CONFLICT
          - UNAUTHORIZED
          - PERMISSION_DENIED
          - UNAVAILABLE
          - INTERNAL_ERROR
          - AUTH_FAILED
          - PASSWORD_ALREADY_SET
          - USER_DISABLED
          - SESSION_EXPIRED
          - SESSION_REVOKED
          - DISPLAY_USER_ID_INVALID
          - DISPLAY_USER_ID_EXISTS
          - DISPLAY_USER_ID_COOLDOWN
          - DISPLAY_USER_ID_NOT_FOUND
          - DISPLAY_USER_ID_ALLOCATE_FAILED
          - DISPLAY_USER_ID_PRETTY_NOT_AVAILABLE
          - DISPLAY_USER_ID_PRETTY_ACTIVE
          - DISPLAY_USER_ID_LEASE_EXPIRED
          - DISPLAY_USER_ID_PAYMENT_REQUIRED
      message:
        type: string
      error_info_domain:
        type: string
        enum:
          - hyapp