# Room Cell State Machines 本文档定义 `room-service` 在微服务多机部署下必须遵守的 Room Cell 状态机。Room Cell 的目标是让同一个房间在同一时间只有一个执行节点提交状态，并且在节点重启、发布、RTC 回调延迟和 outbox 重试时不丢状态、不双写、不重复扣费。 ## Room Room 是房间生命周期的主状态。只有 `active` 房间允许进房、麦位、管理和送礼命令。 ```mermaid stateDiagram-v2 [*] --> creating creating --> active: CreateRoom 持久化成功 active --> closing: CloseRoom 开始收尾 closing --> closed: command log/outbox/meta 提交 active --> closed: CloseRoom 当前实现一次提交完成 closed --> [*] ``` 状态语义： | State | Meaning | | ---------- | ------------------------------------------ | | `creating` | 正在创建房间外部依赖，不对客户端开放 | | `active` | 可进房、可管理、可上麦、可送礼 | | `closing` | 正在关闭，不再接收新业务命令 | | `closed` | 已关闭，`JoinRoom` 和 guard 查询都必须拒绝 | `CloseRoom` 必须作为 Room Cell 命令提交，不能只从后台直接更新 `rooms.status`。关闭房间时必须清空业务 presence、释放麦位、写 command log、写 `RoomClosed` outbox、更新 `rooms` 和 `room_list_entries` 状态。 ## Presence Presence 是 room-service 自己维护的业务进房状态，不等同于腾讯云 IM 或 RTC 的真实连接。 ```mermaid stateDiagram-v2 [*] --> absent absent --> present: JoinRoom present --> present: JoinRoom 重试或 RoomHeartbeat 刷新 last_seen_at_ms present --> left: LeaveRoom present --> stale_left: stale worker 超时清理 present --> kicked: KickUser present --> closed_left: CloseRoom left --> present: JoinRoom stale_left --> present: JoinRoom kicked --> present: UnbanUser 后重新 JoinRoom closed_left --> [*] ``` 规则： - `RoomHeartbeat` 只能刷新已有 presence，不能创建 presence。 - `LeaveRoom` 要同步释放用户占用的麦位。 - RTC `room_exited` 只释放当前麦位，不清理业务 presence；用户可能仍停留在房间页等待重连。 - `KickUser` 写入 ban 集合，用户必须先 `UnbanUser` 才能重新 `JoinRoom`。 ## Mic Mic 是麦位和 RTC 发流确认状态。业务上麦不等于已经在 RTC 发流。 ```mermaid stateDiagram-v2 [*] --> idle idle --> locked: SetMicSeatLock(true) locked --> idle: SetMicSeatLock(false) idle --> pending_publish: MicUp pending_publish --> publishing: ConfirmMicPublishing 或 RTC audio_started pending_publish --> idle: publish_timeout 或 MicDown 或 LeaveRoom publishing --> idle: MicDown 或 RTC audio_stopped 或 LeaveRoom publishing --> pending_publish: ChangeMicSeat 保留 mic_session pending_publish --> pending_publish: ChangeMicSeat 保留 mic_session ``` 规则： - `mic_session_id` 是单次上麦会话 ID，旧会话的确认、停止和超时任务不能清掉新会话。 - `mic_session_room_version` 和 `last_publish_event_time_ms` 用于丢弃旧 RTC 事件。 - `pending_publish` 超过 `publish_deadline_ms` 后由 worker 自动下麦。 - `LeaveRoom` 与 RTC `room_exited` 并发时以业务 presence 的 `last_seen_at_ms` 和当前 `mic_session_id` 为准；旧的 RTC 退房事件不能释放用户重进房后的新麦位会话。 - `CloseRoom` 必须释放全部麦位，但保留麦位编号和锁定结构。 ## Lease Lease 是多机部署下的房间执行权。Redis 只保存热路由，不是恢复来源；MySQL snapshot + command log 才是恢复来源。 ```mermaid stateDiagram-v2 [*] --> unowned unowned --> owned_by_node: EnsureOwner owned_by_node --> owned_by_node: 同节点续约并生成新 lease_token owned_by_node --> expired: TTL 到期 expired --> owned_by_other_node: 新节点 EnsureOwner owned_by_node --> fenced_out: 提交前 VerifyOwner 失败 fenced_out --> [*] ``` 规则： - Redis runtime route key 统一使用 `app_code + "\0" + room_id`，包括默认 App；不能再使用裸 `room_id` 作为兼容 key。 - `room:node:{node_id}` 保存当前 room-service 实例的 `advertise_addr`，只用于 owner 转发；它不是服务发现的全局配置中心。 - gateway 可以连接 room-service 内网负载均衡；命中非 owner 节点时，gRPC 边界必须按 Redis owner route 转发到当前 owner 实例。 - `advertise_addr` 必须是实例私网地址，不能是 room-service 内网 CLB 地址，否则转发会命中任意节点并触发递归保护。 - 命令开始前通过 `EnsureOwner` 获得执行权。 - 命令真正写 command log/outbox 前必须用 `lease_token` 再做一次 `VerifyOwner`。 - 如果提交前 lease 已经过期或 token 已变化，旧节点必须返回 `UNAVAILABLE`，不能写房间状态。 - `room_command_log` 保存 `owner_node_id` 和 `lease_token`，用于排查谁在什么 lease 下提交了命令。 - stale presence worker 和 mic publish timeout worker 只能扫描本节点已加载 Cell；清理前必须确认当前 Redis lease 仍属于本节点，并在读完快照后再次用相同 `lease_token` 校验，最后由命令提交链路再做 fencing。 - 节点进入 draining 后不能再接收新的 Room Cell 命令，也不能恢复或创建新的 Cell；gRPC drain 完成后应主动释放本节点已加载房间的 owner lease，降低滚动发布等待 TTL 的窗口。 ## Outbox Outbox 是房间事件对外投递状态机。它允许重复投递，但多 worker 不应该同时抢同一批。 ```mermaid stateDiagram-v2 [*] --> pending pending --> delivering: ClaimPendingOutbox retryable --> delivering: ClaimPendingOutbox delivering --> delivered: 投递成功并确认 delivering --> retryable: 投递失败或状态未知 delivering --> failed: 明确不可重试 retryable --> failed: 超过策略上限或人工判定 ``` 规则： - `ClaimPendingOutbox` 必须把事件从 `pending/retryable` 原子改成 `delivering`，并写入 `worker_id` 和 `lock_until_ms`。 - 其他 worker 不能抢到未过期的 `delivering` 事件。 - 投递成功后才能标记 `delivered`。 - 投递失败必须保留 envelope 和 last_error，转入 `retryable` 等待下一轮抢占。 - outbox 事件必须带 `app_code`，消费者按 App 隔离幂等。