feat(phase2e-2): 落地会议生命周期状态机 + Router 幂等双层防御(Task 8)

核心交付:
- 新建 MeetingLifecycleService(6 钩子 + sync.Map 本地 timer + Redis key 双保险 + RescheduleFromRedis)
- 新建 MeetingCleanupTask(启动重建 timer + 每 N 秒扫 host_grace/empty_ttl 兜底 + 4h stale active 回收)
- MediaOrchestrator 新增 ResolveRouterID;HTTPMediaOrchestrator.CreateRouter 入口 sync.Map 幂等防御
- 业务层 JoinRoom 移除 CreateRouter 调用改走 CancelEmptyTTL + ResolveRouterID;LeaveRoom 空房分支改调 OnAllMembersLeft 不再立即销毁
- MeetingSignalService 新增 OnWSDisconnect 实现 ws.MeetingDisconnectHook;OnRoomJoin 追加 host 重连钩子
- ws.handler 定义 MeetingDisconnectHook 接口 + SetMeetingDisconnectHook,解耦 ws→meeting 反向依赖
- config 新增 MeetingConfig{HostGrace=120, EmptyRoomTTL=300, CleanupInterval=30, StaleRoomHours=4}

关键设计决策:
- Redis key TTL = 业务时长 + max(CleanupIntervalSeconds*2, 30s) buffer:避免本地 timer 与
  Redis 自动过期同步到期导致 DEL 返回 0 被误判为"已被其他路径处理"而跳过业务逻辑
- Router 幂等双层防御(决策 q2_router_dedup=a2_both):业务层不重复调 + HTTP 层 sync.Map 命中直接返回
- 普通成员 WS 断开仅清 media 资源不动 participant 表(决策 q1_nonhost_disconnect=a1_keep_current)

E2E 验证:docs/verify/meeting_t8_verify.mjs PASS=20 FAIL=0,覆盖 5 场景:
- S1 host 宽限期过期自动转让(meeting.host.changed + DB host_id 更新)
- S2 宽限期内重连保留身份
- S3 empty_ttl 期内新成员加入复活房间
- S4 empty_ttl 过期 → 房间 Ended + 新 join 被拒
- S5 CreateRoom +1 Router / JoinRoom 不再创建新 Router(通过 media-server /internal/info stats.routers 断言)

media-server:/internal/info 响应追加 stats.routers + routers[] 供 E2E 断言 Router 幂等

文档同步:
- docs/progress/CURRENT_STATUS.md 头部 + 新增 Task 8 交付条目
- docs/plans/2026-04-21-phase2e-2-implementation.plan.md Task 8 标记完成 + 实际产出/决策/验证
- docs/api/frontend/meeting.md 补充 host.changed.auto_reason / room.ended.reason=system_error / 空房 TTL 复活语义 + Task 8 验证记录
- docs/architecture/system-architecture.md meeting 模块职责补充"会议生命周期状态机"
- .cursor/rules/project-context.mdc 追加 Task 8 条目并更新 Phase 2e-2 进度(Task 0-8 )

Made-with: Cursor
This commit is contained in:
bujinyuan
2026-04-21 18:21:04 +08:00
parent 55d6352c6a
commit 3b83c79036
23 changed files with 1344 additions and 48 deletions

View File

@@ -35,6 +35,15 @@ type NotifyConnectHook interface {
PushUnreadTotalOnConnect(ctx context.Context, userID int64)
}
// MeetingDisconnectHook 会议 WS 断线钩子接口Phase 2e-2 Task 8
// 由 meeting.service.MeetingSignalService 隐式实现
// 触发时机:用户最后一条 WS 连接被移除(最终下线)
// 职责:清理该用户在会议中的媒体资源;若为 host 则启动 host 宽限期
// 抽象为接口避免 ws 包反向依赖 meeting 包引发循环引用
type MeetingDisconnectHook interface {
OnWSDisconnect(ctx context.Context, userID int64)
}
var upgrader = websocket.Upgrader{
ReadBufferSize: 1024,
WriteBufferSize: 1024,
@@ -45,13 +54,14 @@ var upgrader = websocket.Upgrader{
// Handler WebSocket 连接处理器
type Handler struct {
hub *ws.Hub
pubsub *ws.PubSub
jwtCfg *config.JWTConfig
onlineService *OnlineService
tokenValidator TokenValidator
offlinePusher OfflineMessagePusher
notifyConnectHook NotifyConnectHook
hub *ws.Hub
pubsub *ws.PubSub
jwtCfg *config.JWTConfig
onlineService *OnlineService
tokenValidator TokenValidator
offlinePusher OfflineMessagePusher
notifyConnectHook NotifyConnectHook
meetingDisconnectHook MeetingDisconnectHook // Task 8 注入
}
// NewHandler 创建 WebSocket Handler 实例
@@ -75,6 +85,12 @@ func (h *Handler) SetNotifyConnectHook(hook NotifyConnectHook) {
h.notifyConnectHook = hook
}
// SetMeetingDisconnectHook 设置会议 WS 断线钩子(由 meeting 模块在初始化时注入)
// Phase 2e-2 Task 8WS 最终下线时触发 host 宽限期 / 媒体资源清理
func (h *Handler) SetMeetingDisconnectHook(hook MeetingDisconnectHook) {
h.meetingDisconnectHook = hook
}
// Upgrade 处理 WebSocket 升级请求
// GET /ws?token=xxx → JWT 认证 → 升级连接 → 注册 Hub → 订阅 Redis 频道
func (h *Handler) Upgrade(c *gin.Context) {
@@ -120,6 +136,11 @@ func (h *Handler) Upgrade(c *gin.Context) {
}
h.pubsub.Unsubscribe(userID)
h.onlineService.UserOffline(context.Background(), userID)
// Task 8通知会议模块处理 host 宽限期 / 媒体资源清理
// 钩子为可选(测试或 meeting 模块未加载场景安全跳过)
if h.meetingDisconnectHook != nil {
go h.meetingDisconnectHook.OnWSDisconnect(context.Background(), userID)
}
})
h.hub.Register(client)
h.pubsub.Subscribe(claims.UserID)