Skip to content

♻️ refactor(realtime): 拆分会话编排职责 - #128

Merged
ZhaoXingPeng merged 1 commit into
mainfrom
refactor/realtime-session-orchestration
Sep 10, 2026
Merged

ZhaoXingPeng merged 1 commit into
mainfrom
refactor/realtime-session-orchestration

Conversation

@ZhaoXingPeng

Copy link
Copy Markdown
Owner

关联 Issue

Closes #123

做了什么

  • 将 SessionWebSocketHandler 收敛为鉴权、帧解析、命令路由和关闭通知。
  • 新增 RealtimeSessionCoordinator、RunnerLeaseManager、SessionEventDispatcher、HandoffSessionSubscriber 与 WebSocketEventSender,分离运行编排、租约、事件投送和只读 handoff 生命周期。
  • 补充 runner 事件 relay 到 handoff 的回归测试,并更新架构职责与验证文档。

实现与架构

  • 公开 WebSocket URL、token 类型、客户端命令,以及 session_started、source_sync_state、字幕、音频、纠偏、报告和错误事件保持不变。
  • 本机/Redis owner 的获取、续租、释放和失败分类封装在 RunnerLeaseManager;续租失败会停止本机 runner、释放 owner 并尽力通知当前 socket。
  • runner 事件先进入 SessionEventHub 再发送给主连接,handoff 只消费 replay/订阅,不能控制主 runner。

实验记录

实验:本地 H2/Mockito WebSocket 回归,覆盖主连接启动、第二连接拒绝、Redis lease 已占用、handoff replay/runner relay、暂停恢复、media_clock 校验、结束和断连清理。
结果:SessionWebSocketHandlerTest 13/13 通过;完整后端 mvn -B test 132 tests 通过,5 个 opt-in 外部集成按预期跳过。
结论:拆分后的协议事件与错误文案维持兼容,连接、lease、handoff 与报告收尾边界均有回归保护。本地替身不构成真实 Redis 多节点可用性、模型质量或线上 SLA 证明。

验证

cd backend && mvn -B -Dtest=SessionWebSocketHandlerTest test
结果:13 tests, 0 failures, 0 errors

cd backend && mvn -B test
结果:132 tests, 0 failures, 0 errors; 5 opt-in integration tests skipped

git diff --check
结果:通过
  • Backend tests/lint
  • Frontend tests/build(本 PR 未修改前端)
  • Desktop build(本 PR 未修改桌面端)
  • 手动验证或截图(协议与并发边界由 WebSocket 回归测试覆盖)

风险与回滚

  • 风险:后续若破坏 coordinator、lease 或 dispatcher 的关闭顺序,可能遗漏终态事件或 owner 释放。
  • 回滚方式:回退本 PR 即恢复原先单 handler 组织方式;不涉及 schema、配置、API、事件字段或数据迁移。

提交前检查

  • 已关联 Issue,或说明为何是紧急修复
  • 每个 commit 都是可理解、可验证的小变更
  • 未提交密钥、token、私钥或真实用户数据
  • 文档、前端类型和测试已同步
  • CI 失败时已在评论中解释原因和计划

@ZhaoXingPeng
ZhaoXingPeng merged commit 9111d1f into main Sep 10, 2026
3 checks passed
@ZhaoXingPeng
ZhaoXingPeng deleted the refactor/realtime-session-orchestration branch September 10, 2026 07:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

♻️ refactor(realtime): 拆分会话 WebSocket 与实时编排职责

1 participant