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-query
    description: RoomQueryService，不改变 Room Cell 状态的读模型查询。
  - 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 群组存在后再提交房间状态；同一个 actor 只能作为 owner 创建一个房间，重复创建返回 Conflict。
          schema:
            $ref: "#/definitions/CreateRoomResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomCommandService/UpdateRoomProfile:
    post:
      tags:
        - room-command
      summary: 修改房间资料和座位数
      operationId: roomUpdateRoomProfile
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/UpdateRoomProfile
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/UpdateRoomProfileRequest"
      responses:
        "200":
          description: 修改成功；资料、座位数、snapshot、command log 和 outbox 已经通过 Room Cell 提交。
          schema:
            $ref: "#/definitions/UpdateRoomProfileResponse"
        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/ConfirmMicPublishing:
    post:
      tags:
        - room-command
      summary: 确认 RTC 音频发布成功
      operationId: roomConfirmMicPublishing
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/ConfirmMicPublishing
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/ConfirmMicPublishingRequest"
      responses:
        "200":
          description: 当前 mic_session 确认成功；旧 session、旧 room_version 或旧 event_time 会被安全忽略。
          schema:
            $ref: "#/definitions/ConfirmMicPublishingResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomCommandService/SetMicSeatLock:
    post:
      tags:
        - room-command
      summary: 锁定或解锁麦位
      operationId: roomSetMicSeatLock
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/SetMicSeatLock
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/SetMicSeatLockRequest"
      responses:
        "200":
          description: 锁麦状态修改成功。
          schema:
            $ref: "#/definitions/SetMicSeatLockResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomCommandService/SetChatEnabled:
    post:
      tags:
        - room-command
      summary: 开启或关闭公屏
      operationId: roomSetChatEnabled
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/SetChatEnabled
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/SetChatEnabledRequest"
      responses:
        "200":
          description: 公屏开关修改成功；结果会影响 CheckSpeakPermission。
          schema:
            $ref: "#/definitions/SetChatEnabledResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomCommandService/SetRoomAdmin:
    post:
      tags:
        - room-command
      summary: 添加或移除房间管理员
      operationId: roomSetRoomAdmin
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/SetRoomAdmin
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/SetRoomAdminRequest"
      responses:
        "200":
          description: 管理员集合修改成功。
          schema:
            $ref: "#/definitions/SetRoomAdminResponse"
        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/UnbanUser:
    post:
      tags:
        - room-command
      summary: 解除房间 ban
      operationId: roomUnbanUser
      x-grpc-full-method: /hyapp.room.v1.RoomCommandService/UnbanUser
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/UnbanUserRequest"
      responses:
        "200":
          description: 解封成功；不会自动恢复 presence、麦位或管理员身份。
          schema:
            $ref: "#/definitions/UnbanUserResponse"
        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"
  /hyapp.room.v1.RoomQueryService/GetCurrentRoom:
    post:
      tags:
        - room-query
      summary: 查询用户当前可恢复房间
      operationId: roomGetCurrentRoom
      description: 启动、回前台和网络恢复时使用；只读 room_user_presence 投影并用 Room Cell 快照二次校验，不会隐式 JoinRoom 或刷新 presence。
      x-grpc-full-method: /hyapp.room.v1.RoomQueryService/GetCurrentRoom
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/GetCurrentRoomRequest"
      responses:
        "200":
          description: 返回是否存在可恢复房间，以及是否需要重新入 IM 群和重新签 RTC token。
          schema:
            $ref: "#/definitions/GetCurrentRoomResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomQueryService/GetRoomSnapshot:
    post:
      tags:
        - room-query
      summary: 查询房间完整快照
      operationId: roomGetRoomSnapshot
      description: 房间页主动同步使用；只读 Room Cell/snapshot，不刷新 presence，不隐式 JoinRoom，viewer 必须仍在该房间。
      x-grpc-full-method: /hyapp.room.v1.RoomQueryService/GetRoomSnapshot
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/GetRoomSnapshotRequest"
      responses:
        "200":
          description: 返回当前完整房间快照。
          schema:
            $ref: "#/definitions/GetRoomSnapshotResponse"
        default:
          $ref: "#/responses/GRPCError"
  /hyapp.room.v1.RoomQueryService/ListRoomBannedUsers:
    post:
      tags:
        - room-query
      summary: 查询房间黑名单列表
      operationId: roomListRoomBannedUsers
      description: 读取 Room Cell 当前仍有效的 ban 状态；viewer 必须是当前房间 owner/admin。
      x-grpc-full-method: /hyapp.room.v1.RoomQueryService/ListRoomBannedUsers
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/ListRoomBannedUsersRequest"
      responses:
        "200":
          description: 返回当前仍有效的房间黑名单。
          schema:
            $ref: "#/definitions/ListRoomBannedUsersResponse"
        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
    required:
      - request_id
      - command_id
      - actor_user_id
      - room_id
    properties:
      request_id:
        type: string
        description: 后端生成的链路追踪 ID，不参与幂等。
      command_id:
        type: string
        description: 客户端按用户写动作生成的幂等命令 ID，同一动作重试必须复用。
      actor_user_id:
        type: integer
        format: int64
      room_id:
        type: string
        pattern: "^[A-Za-z0-9_-]{1,48}$"
        maxLength: 48
        description: 命令所属房间 ID；CreateRoom 时必须同时满足腾讯 IM GroupID 和 RTC strRoomId 限制。
      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
      publish_state:
        type: string
        enum:
          - pending_publish
          - publishing
          - idle
        description: pending_publish 表示业务占麦成功但 RTC 尚未确认发流；publishing 表示已确认发布音频；空麦可为空或 idle。
      mic_session_id:
        type: string
        description: 单次上麦发流会话 ID；客户端确认和 RTC webhook 必须原样带回。
      publish_deadline_ms:
        type: integer
        format: int64
        description: pending_publish 必须完成确认的截止时间；超时会自动下麦。
      mic_session_room_version:
        type: integer
        format: int64
        description: 创建当前 mic_session 的房间版本，用于丢弃旧版本 RTC 事件。
      last_publish_event_time_ms:
        type: integer
        format: int64
        description: 当前麦位已接受的最新发布事件时间。
  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
      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
      ban_states:
        type: array
        description: 房间 ban 的时间边界；expires_at_ms 为 0 表示永久。
        items:
          $ref: "#/definitions/RoomBanState"
      mute_user_ids:
        type: array
        items:
          type: integer
          format: int64
      gift_rank:
        type: array
        items:
          $ref: "#/definitions/RankItem"
      room_ext:
        type: object
        description: 扩展字段集合；创建房间展示资料固定使用 `title`、`cover_url`、`description`。
        additionalProperties:
          type: string
      heat:
        type: integer
        format: int64
      version:
        type: integer
        format: int64
  RoomBanState:
    type: object
    properties:
      user_id:
        type: integer
        format: int64
      actor_user_id:
        type: integer
        format: int64
      created_at_ms:
        type: integer
        format: int64
      expires_at_ms:
        type: integer
        format: int64
        description: 0 表示永久；非 0 表示该 UTC 毫秒后可重新进房。
  CreateRoomRequest:
    type: object
    description: 同一个 `meta.actor_user_id` 只能作为 owner 创建一个房间；owner/host 不接受外部字段自报。
    required:
      - meta
      - mode
      - room_name
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      seat_count:
        type: integer
        format: int32
        minimum: 0
        description: 麦位数量；0 或省略时使用后台默认值，正数必须命中后台启用座位数。
      mode:
        type: string
        minLength: 1
        description: 房间模式，不能为空；当前 room-service 保存并通过快照透出。
      room_name:
        type: string
        minLength: 1
        maxLength: 128
        description: 房间展示名称，room-service 写入 `RoomSnapshot.room_ext["title"]`。
      room_avatar:
        type: string
        maxLength: 512
        description: 房间头像；为空时写入默认系统头像 `hyapp://room/default-avatar`。
      room_description:
        type: string
        maxLength: 512
        description: 房间简介；写入 `RoomSnapshot.room_ext["description"]`，不参与房间状态决策。
  CreateRoomResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      room:
        $ref: "#/definitions/RoomSnapshot"
  UpdateRoomProfileRequest:
    type: object
    required:
      - meta
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      room_name:
        type: string
        maxLength: 128
        description: proto3 optional；传入时更新 RoomExt title。
      room_avatar:
        type: string
        maxLength: 512
        description: proto3 optional；传空字符串时恢复系统默认头像。
      room_description:
        type: string
        maxLength: 512
        description: proto3 optional；允许传空字符串清空简介。
      seat_count:
        type: integer
        format: int32
        enum:
          - 10
          - 15
          - 20
          - 25
          - 30
        description: proto3 optional；必须是后台启用座位数，缩容要求被删除麦位空闲且未锁。
  UpdateRoomProfileResponse:
    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"
      mic_session_id:
        type: string
      publish_deadline_ms:
        type: integer
        format: int64
  MicDownRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      target_user_id:
        type: integer
        format: int64
      reason:
        type: string
        description: 主动下麦可为空；系统自动下麦会使用 publish_timeout 等稳定原因。
  MicDownResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      seat_no:
        type: integer
        format: int32
      room:
        $ref: "#/definitions/RoomSnapshot"
  ConfirmMicPublishingRequest:
    type: object
    required:
      - meta
      - mic_session_id
      - room_version
      - event_time_ms
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      target_user_id:
        type: integer
        format: int64
        description: 为空时默认确认 actor_user_id；RTC webhook 编排可显式指定目标用户。
      mic_session_id:
        type: string
      room_version:
        type: integer
        format: int64
        description: 客户端传 MicUp 返回或快照中的 room_version；旧版本事件不会覆盖新会话。
      event_time_ms:
        type: integer
        format: int64
        description: 客户端 SDK 或 RTC webhook 事件发生时间；只接受当前会话更新的事件。
      source:
        type: string
        description: 例如 client 或 rtc_webhook。
  ConfirmMicPublishingResponse:
    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"
  SetMicSeatLockRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      seat_no:
        type: integer
        format: int32
      locked:
        type: boolean
  SetMicSeatLockResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      room:
        $ref: "#/definitions/RoomSnapshot"
  SetChatEnabledRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      enabled:
        type: boolean
  SetChatEnabledResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      room:
        $ref: "#/definitions/RoomSnapshot"
  SetRoomAdminRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      target_user_id:
        type: integer
        format: int64
      enabled:
        type: boolean
  SetRoomAdminResponse:
    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
      duration_ms:
        type: integer
        format: int64
        description: 0 表示永久禁止进房；大于 0 表示从服务端当前 UTC 时间起禁止进房的毫秒时长。
  KickUserResponse:
    type: object
    properties:
      result:
        $ref: "#/definitions/CommandResult"
      room:
        $ref: "#/definitions/RoomSnapshot"
  UnbanUserRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      target_user_id:
        type: integer
        format: int64
  UnbanUserResponse:
    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
  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
      request_id:
        type: string
        description: 外部守卫调用的追踪 ID；不作为幂等键。
  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
  GetCurrentRoomRequest:
    type: object
    required:
      - meta
      - user_id
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      user_id:
        type: integer
        format: int64
        description: 由 gateway 从 token user_id 注入，客户端不能自报。
  GetCurrentRoomResponse:
    type: object
    properties:
      has_current_room:
        type: boolean
      room_id:
        type: string
      room_version:
        type: integer
        format: int64
      role:
        type: string
        description: 用户在房间快照中的角色。
      mic_session_id:
        type: string
        description: 用户当前在麦时返回；客户端确认发流必须带回该 session。
      publish_state:
        type: string
        enum:
          - pending_publish
          - publishing
          - idle
      need_join_im_group:
        type: boolean
        description: true 表示客户端应重新确保加入腾讯云 IM 群。
      need_rtc_token:
        type: boolean
        description: true 表示用户处于 pending_publish/publishing，需要重新获取 RTC token。
      server_time_ms:
        type: integer
        format: int64
  GetRoomSnapshotRequest:
    type: object
    required:
      - meta
      - room_id
      - viewer_user_id
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      room_id:
        type: string
        pattern: "^[A-Za-z0-9_-]{1,48}$"
        maxLength: 48
      viewer_user_id:
        type: integer
        format: int64
        description: 由 gateway 从 token user_id 注入，客户端不能自报。
  GetRoomSnapshotResponse:
    type: object
    properties:
      room:
        $ref: "#/definitions/RoomSnapshot"
      server_time_ms:
        type: integer
        format: int64
  RoomBannedUser:
    type: object
    properties:
      user_id:
        type: integer
        format: int64
      actor_user_id:
        type: integer
        format: int64
      created_at_ms:
        type: integer
        format: int64
      unban_at_ms:
        type: integer
        format: int64
        description: 0 表示永久；非 0 表示自动解封 UTC 毫秒。
      remaining_ms:
        type: integer
        format: int64
      permanent:
        type: boolean
  ListRoomBannedUsersRequest:
    type: object
    properties:
      meta:
        $ref: "#/definitions/RequestMeta"
      room_id:
        type: string
      viewer_user_id:
        type: integer
        format: int64
        description: 由 gateway 从 token user_id 注入，客户端不能自报。
      page:
        type: integer
        format: int32
      page_size:
        type: integer
        format: int32
  ListRoomBannedUsersResponse:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: "#/definitions/RoomBannedUser"
      total:
        type: integer
        format: int64
      page:
        type: integer
        format: int32
      page_size:
        type: integer
        format: int32
      server_time_ms:
        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_mic_seat_locked
          - room_chat_enabled_changed
          - room_admin_changed
          - room_user_muted
          - room_user_kicked
          - room_user_unbanned
          - 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