quick-share/docs/02-房间管理（创建-加入-退出）.md

02 - 房间管理（创建 / 加入 / 退出）

功能目标

• 创建房间：自动生成 6 位数字房间号 roomCode。
• 加入房间：输入房间号加入；服务端维护在线用户列表。
• 退出房间：主动退出或断线退出；房间空则销毁或等待过期。

前端（Vue）

• 页面/组件
  • HomeView.vue：创建房间、加入房间（输入 roomCode）。
  • RoomView.vue：展示房间信息与离开操作入口。
  • RoomPanel.vue：显示房间号、在线用户、退出按钮、快捷操作（清空/导出等）。
• 交互细节
  • 加入房间前校验 roomCode 为 6 位数字。
  • join/leave 成功后，在消息区插入系统提示（“xxx加入/离开”）。

后端（Spring Boot）

• 核心服务：RoomService
  • createRoom()：生成 roomCode 并创建房间。
  • joinRoom(roomCode, sessionId, userName)：绑定用户到房间。
  • leaveRoom(roomCode, sessionId)：移除用户；若空房间则移除。
  • （可选）expireRoom()：定时清理过期房间（按 transfer.room-expire-hours）。
• 消息入口（STOMP）
  • /app/room/{roomCode}/join：加入房间
  • /app/room/{roomCode}/leave：离开房间

协议与数据

• JoinRequest
  • userName：用户昵称（前端生成或用户输入）
• 系统消息（SYSTEM）
  • payload.event：USER_JOIN | USER_LEAVE | ERROR
  • payload.message：提示文本
  • payload.userList：在线用户列表（数组）

边界与注意点

• 房间是否需要“先创建后加入”：文档示例允许 computeIfAbsent，即加入时若不存在会自动创建（实现上需确定产品规则）。
• 断线离开：建议监听会话断开事件，同步触发离房逻辑并广播 USER_LEAVE。
• 防暴力猜测：限制 join 尝试频率（可选增强）。