Appearance
第十三章 实时数据更新机制
13.1 通信方式
13.1.1 主要方式：WebSocket 长连接
系统采用 WebSocket 长连接作为主要通信方式，用于接收服务端主动推送的数据变更。
| 特性 | 说明 |
|---|---|
| 协议 | WebSocket (wss://) |
| 连接时机 | 页面加载完成后自动建立 |
| 心跳间隔 | 30 秒 |
| 超时判定 | 连续 3 次心跳无响应（90秒） |
13.1.2 备用方式：定时轮询
当 WebSocket 连接不可用时，系统自动降级为定时轮询模式。
| 特性 | 说明 |
|---|---|
| 协议 | HTTPS |
| 触发条件 | WebSocket 连接失败或断开超过最大重连次数 |
| 界面提示 | 显示横幅「实时连接不可用，已切换为轮询模式」 |
13.2 订阅主题
系统根据当前页面状态订阅不同的数据推送主题（默认刷新频率为5秒，系统级写死，修改需发版）：
| 主题 | 推送内容 | 触发条件 |
|---|---|---|
| score_update | 比分变化 | 任一赛事进球 |
| phase_update | 阶段变化 | 赛事进程变更（如上半场→中场休息） |
| status_update | 状态变化 | 赛事状态、上架状态、盘口状态变更 |
| new_fixture | 新赛事 | 数据源下发新赛事 |
| alert | 告警触发 | 满足告警条件 |
| bet_update | 投注变化 | 投注额、赔付额、单边比例变化 |
订阅策略
不同 Tab 订阅不同主题，减少不必要的数据传输：
| 页签 | 订阅主题 |
|---|---|
| 滚球 | 全部主题 |
| 即将 | status_update, new_fixture, alert |
| 赛前 | status_update, new_fixture |
| 全部 | 全部主题 |
13.3 更新频率
| 当前页签 | WebSocket 推送 | 降级轮询间隔 | 说明 |
|---|---|---|---|
| 滚球 | 实时 | 3 秒 | 滚球数据变化频繁，需最高优先级 |
| 即将 | 实时 | 10 秒 | 关注开赛状态变化 |
| 赛前 | 实时 | 30 秒 | 数据变化较少 |
| 全部 | 实时 | 15 秒 | 综合间隔 |
13.4 数据更新处理
13.4.1 比分更新
| 处理步骤 | 说明 |
|---|---|
| 更新单元格 | 更新对应行的比分显示 |
| 视觉反馈 | 比分单元格黄色高亮闪烁 2 秒 |
| 更新时间戳 | 更新「更新于 N 秒前」显示 |
13.4.2 阶段更新
| 处理步骤 | 说明 |
|---|---|
| 更新标签 | 更新对应行的阶段标签（如「上半场 45'」→「中场休息」） |
| 筛选检查 | 检查是否仍符合当前筛选条件 |
| 延迟移除 | 不符合条件时延迟 5 秒后移除，期间显示灰色背景 |
说明：延迟移除是为了避免阶段频繁切换时列表抖动（如补时结束瞬间）。
13.4.3 新赛事
| 处理步骤 | 说明 |
|---|---|
| 筛选检查 | 检查是否符合当前筛选条件 |
| 插入列表 | 符合条件时按排序规则插入到适当位置 |
| 视觉反馈 | 新行绿色高亮闪烁 1 秒 |
| 消息通知 | 若通知开关开启，显示「新赛事待上架」通知 |
13.4.4 告警产生
| 处理步骤 | 说明 |
|---|---|
| 更新告警列 | 更新对应行的告警标签 |
| 置顶检查 | 若为需置顶告警，将赛事移入置顶区 |
| 消息通知 | 若通知开关开启，显示对应类型的 Toast 通知 |
| 声音提醒 | 若声音开关开启，播放提示音 |
告警置顶规则（与9.11.5保持一致）：
| 置顶优先级 | 告警类型 | 说明 |
|---|---|---|
| 1 | 最紧急（MOST_URGENT） | 待上架且滚球 |
| 2 | 紧急（URGENT） | 待上架且≤10分钟内开赛 |
| 3 | 单边超限、大额投注 | 风险告警 |
| 4 | 延期超时（150%+） | 延期时长超阈值150% |
| 不置顶 | 其他告警 | 仅显示告警标签，不触发置顶 |
13.5 本地数据缓存
13.5.1 缓存策略
| 场景 | 处理方式 |
|---|---|
| 页签切换 | 优先使用本地缓存快速渲染，同时后台请求最新数据 |
| 缓存有效期 | 30 秒，超过有效期仍可使用但触发后台刷新 |
| 手动刷新 | 强制请求最新数据，不使用缓存 |
13.5.2 缓存数据结构
| 缓存键 | 缓存内容 | 过期时间 |
|---|---|---|
| fixture_list_{tab}_ | 赛事列表数据 | 30 秒 |
| fixture_count | 各状态赛事数量（用于 Tab 角标） | 10 秒 |
| user_preferences | 用户偏好设置（每页条数、列宽等） | 永久 |
缓存与WebSocket的关系
缓存是降级备用方案，WebSocket是主方案：
- 正常情况：统计数据（Tab角标数字）通过WebSocket实时推送（4.2.2），缓存仅用于页面首次加载时的快速渲染
- 降级情况：WebSocket断开后，使用缓存数据 + 定时轮询（13.1.2）
- fixture_count缓存10秒：确保降级模式下Tab角标也能定期更新，而非依赖WebSocket推送
13.6 断线重连机制
13.6.1 重连策略
| 参数 | 值 | 说明 |
|---|---|---|
| 初始重连间隔 | 1 秒 | 首次断线后等待时间 |
| 最大重连间隔 | 30 秒 | 间隔时间上限 |
| 间隔增长方式 | 指数退避 | 每次失败后间隔翻倍（1s → 2s → 4s → 8s → 16s → 30s） |
| 最大重连次数 | 5 次 | 超过后停止自动重连，需用户手动触发 |
13.6.2 重连过程界面反馈
| 阶段 | 界面反馈 |
|---|---|
| 断线检测 | 表格上方显示橙色横幅「网络连接已断开」 |
| 自动重连中 | 横幅显示「正在重新连接...」+ 旋转图标 |
| 重连成功 | 横幅消失，显示 Toast「连接已恢复」 |
| 重连失败（未超限） | 横幅显示「连接失败，N 秒后重试」 |
| 重连失败（超限） | 横幅显示「连接失败」+「手动重试」按钮 |
13.6.3 重连后数据同步
| 操作 | 说明 |
|---|---|
| 判断断线时长 | 断线 ≤ 5 分钟用增量同步，大于 5 分钟用全量刷新 |
| 增量同步 | 请求断线期间的变更数据，按时间顺序应用 |
| 全量刷新 | 重新请求当前筛选条件下的完整数据 |
| 差异提示 | 如有重要变化（如新告警），显示 Toast 通知 |
13.7 数据一致性保障
13.7.1 版本号机制
每条数据携带版本号（version），用于处理数据冲突：
| 场景 | 处理方式 |
|---|---|
| 收到旧版本数据 | 丢弃，保留本地新版本 |
| 收到新版本数据 | 更新本地数据 |
| 版本号相同 | 保留本地数据 |
13.7.2 乐观锁
用户执行操作（上架、下架等）时采用乐观锁机制：
| 步骤 | 说明 |
|---|---|
| 读取版本号 | 操作前读取当前数据版本号 |
| 提交操作 | 提交时携带版本号 |
| 服务端校验 | 服务端比对版本号是否一致 |
| 冲突处理 | 版本号不一致时返回错误，提示「数据已被其他用户修改，请刷新后重试」 |
13.8 性能优化
13.8.1 数据压缩
| 方向 | 压缩方式 |
|---|---|
| 下行数据 | gzip 压缩 |
| 增量更新 | 仅传输变化字段（Delta 模式） |
13.8.2 节流与防抖
| 场景 | 策略 | 参数 | 说明 |
|---|---|---|---|
| 高频数据更新 | 节流 | 100ms 内合并 | 避免频繁 DOM 操作 |
| 用户筛选操作 | 防抖 | 300ms | 等用户操作完成后再请求 |
| 搜索输入 | 防抖 | 300ms | 等用户输入完成后再搜索 |
13.9 通知系统
13.9.1 通知类型
系统提供两种通知方式，用户可独立控制开关：
| 通知类型 | 说明 | 默认状态 | 控制位置 |
|---|---|---|---|
| 页内通知 | 页面内 Toast 提示 | 开启 | 筛选区「通知」开关 |
| 声音提醒 | 播放提示音 | 关盘 | 筛选区「声音」开关 |
13.9.2 通知触发条件
告警类型（枚举）详见第9章9.11节「告警类型枚举」，各告警类型的通知策略与触发级别在该章节统一定义，本章仅引用不重复定义。
非告警事件的通知策略：
| 事件类型 | 是否触发页内通知 | 是否触发声音 |
|---|---|---|
| 新赛事待上架 | 是 | 否 |
| 比分更新 | 否（仅高亮） | 否 |
| 其他状态变更 | 否（仅高亮） | 否 |
时间边界术语说明
本章「≤10分钟」是紧急告警阈值，与9.2.3定义的「即将状态」（≤30分钟）不同：
- 即将状态（比赛进程）：≤30分钟，赛事阶段分类，开赛前30分钟内的赛事归类为「即将」Tab
- 紧急阈值（置顶/一键锁盘）：≤10分钟，告警触发条件，开赛前10分钟内触发紧急通知和置顶
两者是不同维度的概念，10分钟阈值可在联赛管理配置中调整（参考16.5.0）。
13.9.3 桌面通知（P2 功能，一期不实现）
桌面通知使用浏览器 Notification API，可在用户切换到其他标签页时仍能收到提醒。一期预留开关位置，功能暂不实现。
修订记录
| 版本 | 日期 | 修订内容 |
|---|---|---|
| v1.0 | 2026-01-15 | 初稿 |
| v1.1 | 2026-01-21 | 【9.11对齐】1) 13.4.4节告警置顶规则与9.11.5对齐，补充完整置顶优先级；2) 13.9.2节通知触发条件覆盖全部11种告警类型； |