huajishe-tts/docs/texas/02-room-delete-host-heartbeat-kick.md

问题 2：删除房间 / 房主心跳 / 房主退出自动关房 / 踢人

通用问题：所有对局（War / Mill / Holdem / DragTest）都适用，因为房间管理在 boardgame.io Lobby 层，与具体游戏无关。

现状（boardgame.io 0.50.2 的能力边界）

• Lobby REST 只有 create / join / leave / playAgain / update，没有 delete / heartbeat / kick。
• leave：最后一个玩家离开时 db.wipe(matchID) 删房间（server.js:2331）；否则仅清该玩家 name/credentials。
• 没有在线检测 / 心跳：server 不知道谁“还连着”。客户端断开 socket 不会自动 leave，房间会一直挂着。
• 房主定义：本项目约定 playerID '0'（创建者）即房主（holdem.ts 的 host() 取最低编号 seated 且有筹码者，联机下等价于 P0）。

需求拆解

1. 删除房间：房主有权删除；删除后所有客户端应被踢出 / 房间消失。
2. 房主退出自动关房：房主无 heartbeat（断开）超过 10min，房间自动解除。
3. 心跳：房主心跳周期长（10min）；为支持“自动关房”，需要一个心跳端点。
4. 踢人：房主有权把某个玩家踢出房间。

拟采用方案（在 packages/server 加自定义 koa 路由）

利用 Server() 返回的 server.app / server.db / server.auth，在 index.ts 里挂一组 /api/rooms/... 路由。 房主鉴权：请求携带 playerID=0 + credentials（与 lobby 一致），用 server.auth.authenticateCredentials 校验。

2.1 内存在线表（心跳）

// 房间 -> { pid: lastSeenEpochMs }
const presence = new Map<string, Record<string, number>>();
const HOST_TIMEOUT_MS = 10 * 60 * 1000; // 房主 10min
const PLAYER_TIMEOUT_MS = 3 * 60 * 1000;

• POST /api/rooms/:id/heartbeat：body { playerID, credentials }，鉴权后 presence[matchID][playerID] = Date.now()。 所有玩家都建议定时 ping（房主 10min 一次，普通玩家可更频繁），至少房主必须 ping。
• 定时器（server 启动时 setInterval，如每 60s）：扫描 presence， 若房主（playerID '0' 或当前 host）超时 → 执行“自动关房”（同删除逻辑）。

2.2 删除房间

POST /api/rooms/:id/delete   body: { playerID, credentials }

仅房主可删。逻辑：

const { metadata } = await server.db.fetch(matchID, { metadata: true });
// 校验 host 凭证
await server.db.wipe(matchID);
presence.delete(matchID);
// 通知所有 socket 客户端（通过 pubSub / socket.io）房间已删

客户端在 LobbyRoomList 的房间列表轮询（已有 refresh）会自然发现房间消失； 另可在 boardgame.io 的 onUpdate/自定义事件里让已挂载的 Client 监听到“房间被删”并回退到列表。

2.3 踢人

POST /api/rooms/:id/kick   body: { playerID: hostId, credentials, target: targetPid }

仅房主可踢。逻辑：

// 1) lobby metadata 清掉 target 的 name/credentials
metadata.players[target].name = undefined;
metadata.players[target].credentials = undefined;
await server.db.setMetadata(matchID, metadata);
// 2) 在游戏状态 G 里把该座位 seated=false（需发一个 game move 或走 master）
//    简化：用 master 的 dispatch 调一个 engine move `kickMove(target)`
// 3) presence 清掉 target

• 关键难点：踢人既要改 lobby metadata（让座位空出来可被别人加入），又要改游戏内 G（让被踢者从牌桌消失）。 改 G 需经 boardgame.io 的 Master dispatch（不能直接改 db 状态，否则客户端状态漂移）。 方案：在每个游戏里加一个 kick move（通用约定），server 用 Master 触发它。 为减小改动，可定义一个通用插件/约定：所有游戏实现 kick(targetPid) move， 删房间时也对所有人调用。

2.4 房主退出自动关房（合并到 2.1 定时器）

定时器发现房主超时 → 等同“删除房间”。

客户端改动（ui / web）

• LobbyRoomList：
  • 房主视角：每个房间 pill 增加“删除房间”按钮（调 delete）； 房间内当前玩家列表增加“踢”按钮（调 kick）。
  • 挂载后启动 setInterval 调 heartbeat（房主 10min；普通玩家按 PLAYER_TIMEOUT 的一半）。
• App.tsx / HoldemBoard：无需特殊处理，房间消失后列表刷新即可；可加“房间已被删除”提示。

风险与决策点

• Master dispatch 改 G：需要拿到 server 的 master 实例。boardgame.io Server() 没直接暴露 master， 但可通过 server.db + transport 重新构造，或复用 router 内部的 db。 备选（更简单）：把“座位空出 / 踢人”完全放进 lobby metadata，游戏内 playerView/move 读取 metadata？ 不行（G 拿不到 metadata）。因此必须经一个游戏内 move。 → 建议：每个游戏加 kick move（空实现也行，至少清 seated），server 用 db + 自定义 dispatch。
• 是否现在就给所有游戏加 kick move：会影响 War/Mill/DragTest。可先做 Holdem + 通用骨架，其余游戏加最小 kick。
• 房主判定：当前 host() 取“最低编号 seated 且有筹码者”，联机下创建者 = P0，但若 P0 破产/离开，host 会漂移。 建议把“房主”显式固化在 metadata（创建者 playerID），server 端以 metadata 的 createdBy 为准，engine host() 也改为读 G 里的 hostId（创建时写死）。

验证

• 房主删除 → 列表消失、其他客户端刷新后无此房间、已挂载 Client 收到“已删除”。
• 房主断网 10min（测试用短超时）→ 房间被自动 wipe。
• 房主踢人 → 被踢者 metadata 清、G 里 seated=false、座位可被重新加入。
• 非房主调 delete/kick → 403。