实现游戏大厅与房间模块：玩法插件化、匹配与房间生命周期管理

internal/dto/ws.go

@@ -0,0 +1,91 @@
+package dto // 包名声明：与 user.go 同属 dto 包，集中放置对外数据结构
+
+import "encoding/json" // 标准库：玩法动作的自定义参数保持原始 JSON，由玩法插件自行解析
+
+// ===== 大厅上行 =====
+
+// WSHallMatchRequest 是 hall.match 的上行体：请求进入匹配队列。
+type WSHallMatchRequest struct {
+	GameID string `json:"game_id"` // 要玩的游戏 ID，必须是已注册的玩法
+}
+
+// WSHallCancelRequest 是 hall.cancel 的上行体：取消当前排队。
+type WSHallCancelRequest struct {
+	GameID string `json:"game_id"` // 要取消的游戏 ID；空表示取消该用户全部排队
+}
+
+// ===== 房间上行 =====
+
+// WSRoomJoinRequest 是 room.join 的上行体：按房间 ID 加入。
+type WSRoomJoinRequest struct {
+	RoomID string `json:"room_id"` // 房间 ID
+}
+
+// WSRoomReadyRequest 是 room.ready 的上行体：切换准备状态。
+type WSRoomReadyRequest struct {
+	Ready bool `json:"ready"` // true=准备，false=取消准备
+}
+
+// WSRoomActionRequest 是 room.action 的上行体：一次玩法动作，透传给玩法插件。
+type WSRoomActionRequest struct {
+	Action  string          `json:"action"`            // 动作名，由玩法约定（如 "place"）
+	Payload json.RawMessage `json:"payload,omitempty"` // 动作参数：原样透传，网关与房间都不解析
+}
+
+// WSRoomLeaveRequest 是 room.leave 的上行体：主动离开房间。
+type WSRoomLeaveRequest struct{}
+
+// WSRoomReconnectRequest 是 room.reconnect 的上行体：断线后回到原房间。
+type WSRoomReconnectRequest struct {
+	RoomID string `json:"room_id"` // 断线前所在房间 ID
+}
+
+// ===== 大厅下行 =====
+
+// WSHallMatchedPayload 是 hall.matched 的下行体：告知匹配成功与房间信息。
+type WSHallMatchedPayload struct {
+	RoomID string  `json:"room_id"` // 新建房间 ID
+	GameID string  `json:"game_id"` // 游戏 ID
+	Seats  int     `json:"seats"`   // 总座位数（2=双人，>2=多人）
+	Users  []int64 `json:"users"`   // 同局用户 ID，顺序即座位顺序
+}
+
+// WSHallCancelledPayload 是 hall.cancelled 的下行体：告知排队已取消。
+type WSHallCancelledPayload struct {
+	GameID string `json:"game_id"` // 被取消的游戏 ID
+	Reason string `json:"reason"`  // 取消原因：user（主动）/ timeout（排队超时）
+}
+
+// ===== 房间下行 =====
+
+// WSRoomStatePayload 是 room.state 的下行体：房间全量快照。
+type WSRoomStatePayload struct {
+	RoomID string  `json:"room_id"` // 房间 ID
+	GameID string  `json:"game_id"` // 游戏 ID
+	Status string  `json:"status"`  // 状态：waiting/ready/playing/paused/finished/closed
+	Seats  []int64 `json:"seats"`   // 座位顺序（0 表示空位）
+	Ready  []int64 `json:"ready"`   // 已准备的用户 ID
+	State  any     `json:"state"`   // 玩法对该用户可见的状态（Game.Snapshot 生成，可做信息隐藏）
+}
+
+// WSRoomEventPayload 是 room.event 的下行体：玩法产生的增量事件。
+type WSRoomEventPayload struct {
+	RoomID  string `json:"room_id"` // 房间 ID
+	Event   string `json:"event"`   // 事件名，由玩法约定
+	Payload any    `json:"payload"` // 事件内容
+}
+
+// WSRoomFinishedPayload 是 room.finished 的下行体：对局结束与结算。
+type WSRoomFinishedPayload struct {
+	RoomID string        `json:"room_id"` // 房间 ID
+	GameID string        `json:"game_id"` // 游戏 ID
+	Winner int64         `json:"winner"`  // 获胜用户 ID，0 表示平局
+	Scores map[int64]int `json:"scores"`  // 各用户得分，可为空
+	Reason string        `json:"reason"`  // 结束原因：normal/opponent_leave/timeout
+}
+
+// WSRoomClosedPayload 是 room.closed 的下行体：房间已关闭。
+type WSRoomClosedPayload struct {
+	RoomID string `json:"room_id"` // 房间 ID
+	Reason string `json:"reason"`  // 关闭原因：dissolved/idle/finished
+}