swagger: "2.0"
info:
  title: HY Room Service API
  version: "1.0.0"
  description: |
    room-service 当前只暴露内部 gRPC + protobuf 接口，没有 HTTP JSON router。
    本文件用 OpenAPI 2.0 记录 gRPC 合约，`paths` 使用 gRPC full method 作为文档路径，不代表真实 HTTP endpoint。
    腾讯云 IM 房间系统消息是 room-service 的外发消息契约，记录在 definitions 中。
host: localhost:13001
basePath: /
schemes:
  - http
consumes:
  - application/grpc+proto
produces:
  - application/grpc+proto
tags:
  - name: room-command
    description: RoomCommandService，改变房间状态的命令接口。
  - name: room-guard
    description: RoomGuardService，腾讯云 IM 入群和发言前的同步守卫。
  - name: health
    description: 标准 grpc.health.v1.Health。
responses:
  GRPCError:
    description: gRPC status error；稳定业务原因放在 google.rpc.ErrorInfo.reason。
    schema:
      $ref: "#/definitions/GRPCError"
paths:
  /hyapp.room.v1.RoomCommandService/CreateRoom:
    post:
      tags:
        - room-command
      summary: 创建房间
      operationId: roomCreateRoom
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/CreateRoom
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/CreateRoomRequest"
      responses:
        "200":
          description: 创建成功；CreateRoom 会确保腾讯云 IM 群组存在后再提交房间状态。
          schema:
            $ref: "#/definitions/CreateRoomResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomCommandService/JoinRoom:
    post:
      tags:
        - room-command
      summary: 加入房间业务 presence
      operationId: roomJoinRoom
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/JoinRoom
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/JoinRoomRequest"
      responses:
        "200":
          description: 加入成功；只维护 room-service presence，不创建腾讯云 IM 连接。
          schema:
            $ref: "#/definitions/JoinRoomResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomCommandService/LeaveRoom:
    post:
      tags:
        - room-command
      summary: 离开房间业务 presence
      operationId: roomLeaveRoom
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/LeaveRoom
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/LeaveRoomRequest"
      responses:
        "200":
          description: 离房成功；若用户在麦上会释放麦位。
          schema:
            $ref: "#/definitions/LeaveRoomResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomCommandService/MicUp:
    post:
      tags:
        - room-command
      summary: 上麦
      operationId: roomMicUp
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/MicUp
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/MicUpRequest"
      responses:
        "200":
          description: 上麦成功。
          schema:
            $ref: "#/definitions/MicUpResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomCommandService/MicDown:
    post:
      tags:
        - room-command
      summary: 下麦
      operationId: roomMicDown
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/MicDown
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/MicDownRequest"
      responses:
        "200":
          description: 下麦成功。
          schema:
            $ref: "#/definitions/MicDownResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomCommandService/ChangeMicSeat:
    post:
      tags:
        - room-command
      summary: 调整麦位
      operationId: roomChangeMicSeat
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/ChangeMicSeat
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/ChangeMicSeatRequest"
      responses:
        "200":
          description: 调整成功。
          schema:
            $ref: "#/definitions/ChangeMicSeatResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomCommandService/MuteUser:
    post:
      tags:
        - room-command
      summary: 设置房间内禁言
      operationId: roomMuteUser
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/MuteUser
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/MuteUserRequest"
      responses:
        "200":
          description: 禁言状态修改成功；结果会影响 CheckSpeakPermission。
          schema:
            $ref: "#/definitions/MuteUserResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomCommandService/KickUser:
    post:
      tags:
        - room-command
      summary: 踢出房间用户
      operationId: roomKickUser
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/KickUser
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/KickUserRequest"
      responses:
        "200":
          description: 踢人成功；结果会影响 VerifyRoomPresence 和 CheckSpeakPermission。
          schema:
            $ref: "#/definitions/KickUserResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomCommandService/SendGift:
    post:
      tags:
        - room-command
      summary: 发送礼物
      operationId: roomSendGift
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/SendGift
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/SendGiftRequest"
      responses:
        "200":
          description: 扣费成功并落入房间状态。
          schema:
            $ref: "#/definitions/SendGiftResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomGuardService/CheckSpeakPermission:
    post:
      tags:
        - room-guard
      summary: 发言前守卫
      operationId: roomCheckSpeakPermission
      x-grpc-full-method: /hyapp.room.v1.RoomGuardService/CheckSpeakPermission
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/CheckSpeakPermissionRequest"
      responses:
        "200":
          description: 返回是否允许用户在房间发言。
          schema:
            $ref: "#/definitions/CheckSpeakPermissionResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomGuardService/VerifyRoomPresence:
    post:
      tags:
        - room-guard
      summary: 入群前 presence 守卫
      operationId: roomVerifyRoomPresence
      x-grpc-full-method: /hyapp.room.v1.RoomGuardService/VerifyRoomPresence
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/VerifyRoomPresenceRequest"
      responses:
        "200":
          description: 返回用户业务上是否仍在房间内。
          schema:
            $ref: "#/definitions/VerifyRoomPresenceResponse"
        default:
          $ref: "#/responses/GRPCError"
  /grpc.health.v1.Health/Check:
    post:
      tags:
        - health
      summary: 标准 gRPC health check
      operationId: roomHealthCheck
      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: roomHealthWatch
      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
      command_id:
        type: string
      actor_user_id:
        type: integer
        format: int64
      room_id:
        type: string
      gateway_node_id:
        type: string
      session_id:
        type: string
      sent_at_ms:
        type: integer
        format: int64
  CommandResult:
    type: object
    properties:
      applied:
        type: boolean
      room_version:
        type: integer
        format: int64
      server_time_ms:
        type: integer
        format: int64
  RoomUser:
    type: object
    properties:
      user_id:
        type: integer
        format: int64
      role:
        type: string
      joined_at_ms:
        type: integer
        format: int64
      last_seen_at_ms:
        type: integer
        format: int64
  SeatState:
    type: object
    properties:
      seat_no:
        type: integer
        format: int32
      user_id:
        type: integer
        format: int64
      locked:
        type: boolean
  RankItem:
    type: object
    properties:
      user_id:
        type: integer
        format: int64
      score:
        type: integer
        format: int64
      gift_value:
        type: integer
        format: int64
      updated_at_ms:
        type: integer
        format: int64
  RoomSnapshot:
    type: object
    properties:
      room_id:
        type: string
      owner_user_id:
        type: integer
        format: int64
      host_user_id:
        type: integer
        format: int64
      mode:
        type: string
      status:
        type: string
      chat_enabled:
        type: boolean
      mic_seats:
        type: array
        items:
          $ref: "#/definitions/SeatState"
      online_users:
        type: array
        items:
          $ref: "#/definitions/RoomUser"
      admin_user_ids:
        type: array
        items:
          type: integer
          format: int64
      ban_user_ids:
        type: array
        items:
          type: integer
          format: int64
      mute_user_ids:
        type: array
        items:
          type: integer
          format: int64
      gift_rank:
        type: array
        items:
          $ref: "#/definitions/RankItem"
      room_ext:
        type: object
        additionalProperties:
          type: string
      heat:
        type: integer
        format: int64
      version:
        type: integer
        format: int64
  CreateRoomRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      owner_user_id:
        type: integer
        format: int64
      host_user_id:
        type: integer
        format: int64
      seat_count:
        type: integer
        format: int32
      mode:
        type: string
  CreateRoomResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      room:
        $ref: "#/definitions/RoomSnapshot"
  JoinRoomRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      role:
        type: string
  JoinRoomResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      user:
        $ref: "#/definitions/RoomUser"
      room:
        $ref: "#/definitions/RoomSnapshot"
  LeaveRoomRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
  LeaveRoomResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      room:
        $ref: "#/definitions/RoomSnapshot"
  MicUpRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      seat_no:
        type: integer
        format: int32
  MicUpResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      seat_no:
        type: integer
        format: int32
      room:
        $ref: "#/definitions/RoomSnapshot"
  MicDownRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      target_user_id:
        type: integer
        format: int64
  MicDownResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      seat_no:
        type: integer
        format: int32
      room:
        $ref: "#/definitions/RoomSnapshot"
  ChangeMicSeatRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      target_user_id:
        type: integer
        format: int64
      seat_no:
        type: integer
        format: int32
  ChangeMicSeatResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      room:
        $ref: "#/definitions/RoomSnapshot"
  MuteUserRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      target_user_id:
        type: integer
        format: int64
      muted:
        type: boolean
  MuteUserResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      room:
        $ref: "#/definitions/RoomSnapshot"
  KickUserRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      target_user_id:
        type: integer
        format: int64
  KickUserResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      room:
        $ref: "#/definitions/RoomSnapshot"
  SendGiftRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      target_user_id:
        type: integer
        format: int64
      gift_id:
        type: string
      gift_count:
        type: integer
        format: int32
      gift_unit_value:
        type: integer
        format: int64
  SendGiftResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      billing_receipt_id:
        type: string
      room_heat:
        type: integer
        format: int64
      gift_rank:
        type: array
        items:
          $ref: "#/definitions/RankItem"
      room:
        $ref: "#/definitions/RoomSnapshot"
  CheckSpeakPermissionRequest:
    type: object
    properties:
      room_id:
        type: string
      user_id:
        type: integer
        format: int64
  CheckSpeakPermissionResponse:
    type: object
    properties:
      allowed:
        type: boolean
      reason:
        type: string
        enum:
          - room_not_found
          - not_in_room
          - user_banned
          - user_muted
          - chat_disabled
      room_version:
        type: integer
        format: int64
  VerifyRoomPresenceRequest:
    type: object
    properties:
      room_id:
        type: string
      user_id:
        type: integer
        format: int64
      session_id:
        type: string
  VerifyRoomPresenceResponse:
    type: object
    properties:
      present:
        type: boolean
      reason:
        type: string
        enum:
          - room_not_found
          - not_in_room
          - user_banned
      room_version:
        type: integer
        format: int64
  RoomSystemMessage:
    type: object
    properties:
      event_id:
        type: string
      room_id:
        type: string
      event_type:
        type: string
        enum:
          - room_created
          - room_user_joined
          - room_user_left
          - room_mic_changed
          - room_user_muted
          - room_user_kicked
          - room_gift_sent
          - room_heat_changed
          - room_rank_changed
      actor_user_id:
        type: integer
        format: int64
      target_user_id:
        type: integer
        format: int64
      seat_no:
        type: integer
        format: int32
      gift_value:
        type: integer
        format: int64
      room_heat:
        type: integer
        format: int64
      room_version:
        type: integer
        format: int64
      text:
        type: string
      attributes:
        type: object
        additionalProperties:
          type: string
    description: room-service 发送到腾讯云 IM 的 `TIMCustomElem.Data` 和 `CloudCustomData` 稳定载荷。
  TencentTIMCustomElem:
    type: object
    properties:
      MsgType:
        type: string
        enum:
          - TIMCustomElem
      MsgContent:
        type: object
        properties:
          Data:
            $ref: "#/definitions/RoomSystemMessage"
          Desc:
            type: string
            description: 与 `RoomSystemMessage.event_type` 一致。
          Ext:
            type: string
            enum:
              - room_system_message
          Sound:
            type: string
    description: 腾讯云 IM 群系统消息元素结构。
  HealthCheckRequest:
    type: object
    properties:
      service:
        type: string
        description: 空字符串或 `room-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
      message:
        type: string
      error_info_domain:
        type: string
        enum:
          - hyapp