hyapp-server/api/proto/room/v1/room.proto

syntax = "proto3";

package hyapp.room.v1;

option go_package = "hyapp/api/proto/room/v1;roomv1";

// RequestMeta 固定承载所有命令的调用元信息。
// room-service 用它串起幂等、追踪、路由和业务操作者身份。
message RequestMeta {
  string request_id = 1;
  string command_id = 2;
  int64 actor_user_id = 3;
  // room_id 是命令路由、持久化和腾讯 IM/RTC 映射共同依赖的必填字段。
  // CreateRoom 时必须满足 ^[A-Za-z0-9_-]{1,48}$。
  string room_id = 4;
  string gateway_node_id = 5;
  string session_id = 6;
  int64 sent_at_ms = 7;
}

// CommandResult 统一返回命令是否真正落地，以及落地后的房间版本。
message CommandResult {
  bool applied = 1;
  int64 room_version = 2;
  int64 server_time_ms = 3;
}

// RoomUser 只表达 room-service 需要保存的房间内轻量用户态。
message RoomUser {
  int64 user_id = 1;
  string role = 2;
  int64 joined_at_ms = 3;
  int64 last_seen_at_ms = 4;
}

// SeatState 表达单个麦位当前占用关系。
message SeatState {
  int32 seat_no = 1;
  int64 user_id = 2;
  bool locked = 3;
}

// RankItem 表达房间内本地礼物榜项目。
message RankItem {
  int64 user_id = 1;
  int64 score = 2;
  int64 gift_value = 3;
  int64 updated_at_ms = 4;
}

// RoomSnapshot 把 room-service 对外需要暴露的房间投影集中返回。
message RoomSnapshot {
  string room_id = 1;
  int64 owner_user_id = 2;
  int64 host_user_id = 3;
  string mode = 4;
  string status = 5;
  bool chat_enabled = 6;
  repeated SeatState mic_seats = 7;
  repeated RoomUser online_users = 8;
  repeated int64 admin_user_ids = 9;
  repeated int64 ban_user_ids = 10;
  repeated int64 mute_user_ids = 11;
  repeated RankItem gift_rank = 12;
  map<string, string> room_ext = 13;
  int64 heat = 14;
  int64 version = 15;
}

// CreateRoomRequest 创建一个新的房间执行单元。
// 必填语义：meta.room_id、meta.command_id、meta.actor_user_id、seat_count 和 mode。
// owner_user_id/host_user_id 是内部兼容字段，外部 gateway 创建路径不接收客户端自报值。
message CreateRoomRequest {
  RequestMeta meta = 1;
  int64 owner_user_id = 2;
  int64 host_user_id = 3;
  // seat_count 必须大于 0；没有麦位的语音房不进入 Room Cell。
  int32 seat_count = 4;
  // mode 必须非空；当前只作为房间状态字段保存和透出。
  string mode = 5;
}

// CreateRoomResponse 返回新建后的房间快照。
message CreateRoomResponse {
  CommandResult result = 1;
  RoomSnapshot room = 2;
}

// JoinRoomRequest 把用户 presence 接入房间业务态。
message JoinRoomRequest {
  RequestMeta meta = 1;
  string role = 2;
}

// JoinRoomResponse 返回加入后的房间快照。
message JoinRoomResponse {
  CommandResult result = 1;
  RoomUser user = 2;
  RoomSnapshot room = 3;
}

// LeaveRoomRequest 把用户从房间 presence 移出。
message LeaveRoomRequest {
  RequestMeta meta = 1;
}

// LeaveRoomResponse 返回离房后的房间快照。
message LeaveRoomResponse {
  CommandResult result = 1;
  RoomSnapshot room = 2;
}

// MicUpRequest 申请把用户放到指定麦位。
message MicUpRequest {
  RequestMeta meta = 1;
  int32 seat_no = 2;
}

// MicUpResponse 返回最新房间快照与目标麦位。
message MicUpResponse {
  CommandResult result = 1;
  int32 seat_no = 2;
  RoomSnapshot room = 3;
}

// MicDownRequest 把用户从当前麦位移下。
message MicDownRequest {
  RequestMeta meta = 1;
  int64 target_user_id = 2;
}

// MicDownResponse 返回最新房间快照与目标麦位。
message MicDownResponse {
  CommandResult result = 1;
  int32 seat_no = 2;
  RoomSnapshot room = 3;
}

// ChangeMicSeatRequest 直接调整指定用户所在麦位。
message ChangeMicSeatRequest {
  RequestMeta meta = 1;
  int64 target_user_id = 2;
  int32 seat_no = 3;
}

// ChangeMicSeatResponse 返回变更后的房间快照。
message ChangeMicSeatResponse {
  CommandResult result = 1;
  RoomSnapshot room = 2;
}

// MuteUserRequest 修改房间内禁言态。
message MuteUserRequest {
  RequestMeta meta = 1;
  int64 target_user_id = 2;
  bool muted = 3;
}

// MuteUserResponse 返回最新房间快照。
message MuteUserResponse {
  CommandResult result = 1;
  RoomSnapshot room = 2;
}

// KickUserRequest 把指定用户踢出房间。
message KickUserRequest {
  RequestMeta meta = 1;
  int64 target_user_id = 2;
}

// KickUserResponse 返回最新房间快照。
message KickUserResponse {
  CommandResult result = 1;
  RoomSnapshot room = 2;
}

// SendGiftRequest 是首版房间内最重要的变现命令。
message SendGiftRequest {
  RequestMeta meta = 1;
  int64 target_user_id = 2;
  string gift_id = 3;
  int32 gift_count = 4;
  int64 gift_unit_value = 5;
}

// SendGiftResponse 返回扣费成功并落到房间后的状态结果。
message SendGiftResponse {
  CommandResult result = 1;
  string billing_receipt_id = 2;
  int64 room_heat = 3;
  repeated RankItem gift_rank = 4;
  RoomSnapshot room = 5;
}

// CheckSpeakPermissionRequest 让腾讯云 IM 发言回调或 gateway 在公屏前同步问房间业务态。
message CheckSpeakPermissionRequest {
  string room_id = 1;
  int64 user_id = 2;
}

// CheckSpeakPermissionResponse 返回当前用户是否允许发言。
message CheckSpeakPermissionResponse {
  bool allowed = 1;
  string reason = 2;
  int64 room_version = 3;
}

// VerifyRoomPresenceRequest 让外部 IM 入口在进群前确认用户业务上仍在房间内。
message VerifyRoomPresenceRequest {
  string room_id = 1;
  int64 user_id = 2;
  string session_id = 3;
  string request_id = 4;
}

// VerifyRoomPresenceResponse 返回用户是否仍然属于该房间。
message VerifyRoomPresenceResponse {
  bool present = 1;
  string reason = 2;
  int64 room_version = 3;
}

// RoomCommandService 承载所有会改变房间状态的命令。
service RoomCommandService {
  rpc CreateRoom(CreateRoomRequest) returns (CreateRoomResponse);
  rpc JoinRoom(JoinRoomRequest) returns (JoinRoomResponse);
  rpc LeaveRoom(LeaveRoomRequest) returns (LeaveRoomResponse);
  rpc MicUp(MicUpRequest) returns (MicUpResponse);
  rpc MicDown(MicDownRequest) returns (MicDownResponse);
  rpc ChangeMicSeat(ChangeMicSeatRequest) returns (ChangeMicSeatResponse);
  rpc MuteUser(MuteUserRequest) returns (MuteUserResponse);
  rpc KickUser(KickUserRequest) returns (KickUserResponse);
  rpc SendGift(SendGiftRequest) returns (SendGiftResponse);
}

// RoomGuardService 提供给腾讯云 IM 回调或 gateway 做实时守卫查询。
service RoomGuardService {
  rpc CheckSpeakPermission(CheckSpeakPermissionRequest) returns (CheckSpeakPermissionResponse);
  rpc VerifyRoomPresence(VerifyRoomPresenceRequest) returns (VerifyRoomPresenceResponse);
}