fix(p2): 按审查清单修 103 条「建议修」+ 奖牌榜改名 + 两个守卫（dev_0.2.0）

## 奖牌榜改名（主人要求）
「团体奖牌榜」→「单位奖牌榜」，界面 / 大屏渲染页 / 导出件（工作表名与
下载文件名 `单位奖牌明细.xlsx`）/ 用户文档 全部统一；`DISPLAY_PAGES` 是
大屏控制页与大屏页的共同来源，改一处两边同时生效。旧名保留为别名，
老链接与老配置（`display.pages`）照常有效。真 Chromium 验证：14 个管理端
路由 + 7 个基础数据分区 0 报错，大屏页标题已是「单位奖牌榜」。

## P2 清单（123 条，103 条标「建议修」）
按 A/B/C/D 分组、以「文件所有权互斥」分 10 个代理并行推进，另有独立复核
代理逐条核对：61 条声称已修 / 55 条证实 / 4 条部分 / 0 条不成立 / 0 垃圾。

主要交付（按风险从高到低）：
- 写入侧校验：update 路径补必填与 TrimSpace、模板 rules 重复 rank、
  「小项不存在」的四种回答、`defaultProfileId` 外键、decodeJSON 的 8MB
  上限与 413（A01–A06、D02、D03 批量上限 500）
- 危险操作：一键恢复加互斥（第二个请求当场 409）、恢复超时不再说
  「未执行」、`ConfirmDialog` pending 时锁死 ESC/遮罩/关闭
- 认证：改密与撤会话进同一事务、滑动续期写库失败不再假装成功、
  CSRF Cookie 丢失自动补发、密码长度按字符（原按字节）、
  反代 403 只在可信代理透传原 Host 时采信 `X-Forwarded-Host`（全等比较）、
  过期会话定期清理、登出补审计、登录限流可配
- 数据可见性：导出「已发布未结算」行改为 `名次 — / 积分 — / 状态未结算`、
  单位积分明细成绩列与其它导出件逐字一致、空单位也打合计行、
  基础数据包命中「已彻底删除的单位」整行跳过并报界面路径、
  报名导入换单位给明确提示、勾选报名有冲突不再假报成功
- 导入/导出：赛事包上限 512MB（**它是唯一带字体/图片的包**，字体上限
  20MB）而 multipart 内存档位独立钉在 16MB、工作簿表名尾随空格、
  导出件路由与文件名契约补全
- 前端：一次写请求只生成一个 requestId（幂等缓存此前从未命中）、
  基础数据包补 `X-Request-Id`、示例数据模式禁写扩到撤销发布/存草稿、
  访客 401 不再是裸错误、模板 `{{else if}}` 不再静默吞内容
- Console：按设计退出（切赛事/恢复）不再判成崩溃、旧数据目录读不出来
  会记日志、渲染层日志按上限截断、`service.js` 补 17 例测试

## 测试
服务端用例 610 → 674（13 包全绿，新增老库跨九条迁移升级、panic 形状、
429 落 interceptions、三态对照、avg_mode 分母、会话失效、请求体上限等）
前端 449 → 531（vue-tsc + build 通过）；Console 28 → 54（19 个文件）。
另修复一条会让整包挂死 600s 的用例（测试主协程堵在 client.Do，defer
轮不到执行 → 改为可取消 + 探针超时，改坏也 7.5s 快速失败）。

## 两个新守卫（防止再出现「组件 setup 抛异常」这类盲区）
- `web/scripts/check-declaration-order.mjs` 已进测试命令：沿 watch/
  watchEffect 的 const 依赖链查 TDZ（正是「运动员页整块空白」的根因）
- `web/scripts/smoke-admin.mjs`（`pnpm smoke`）：真 Chromium 点遍 14 个
  管理端路由 + 7 个基础数据分区 + 大屏页，任何 console 错误即失败

## 文档
- `docs/升级说明.md` 新增 dev_0.2.0 一节（三件升级必知：改名、审计前缀
  与历史记录、密码口径；现场变化；赛事包上限；反代与 CSRF）
- 使用手册 / 常见问题 / 部署指南 / 上线检查清单按实现同步

server/internal/realtime/changes.go

@@ -4,11 +4,32 @@ import (
 	"context"
 	"database/sql"
 	"encoding/json"
+	"errors"
 	"fmt"
 
 	"git.yeij.top/AskaEth/Scoreboard/server/internal/dto"
 )
 
+// errDBClosed 是 database/sql 在连接池已关闭时返回的错误。
+//
+// 标准库里这个错误是**未导出**的（database/sql 的 errDBClosed），拿不到变量，只能按原文认。
+// httpapi 包里有一份同口径的实现（那一份也导不出来，实时层又依赖不了 httpapi——会成环），
+// 两份必须保持同一套语义：库已关闭 = 恢复/重启动作的中间状态，不是故障。
+var errDBClosed = errors.New("sql: database is closed")
+
+// dbClosed 判定错误是否只是「库已经被关掉」。
+//
+// 只认原文完全相等的那一层（含被 %w 包过的），不按子串匹配：别的读库失败（锁超时、
+// SQL 写错、库损坏）都得继续按 WARN/ERROR 报出来，不能被这条静默规则顺手吞掉。
+func dbClosed(err error) bool {
+	for e := err; e != nil; e = errors.Unwrap(e) {
+		if e.Error() == errDBClosed.Error() {
+			return true
+		}
+	}
+	return false
+}
+
 // currentVersion 返回服务端版本号，即 change_log 的最大 id；空表为 0。
 // NewHub 允许 db 为 nil（降级/测试），此时退回内存版本，避免空指针 panic。
 func (h *Hub) currentVersion(ctx context.Context) (int64, error) {
@@ -26,12 +47,18 @@ func (h *Hub) currentVersion(ctx context.Context) (int64, error) {
 }
 
 // currentVersionCached 在数据库不可用时退回内存里的版本，保证心跳与广播不会因一次查询失败而中断。
+// 「库已关闭」（恢复/重启窗口）只记 Debug：那不是故障，而且它每个心跳周期都会发生一次，
+// 记 WARN 会让现场日志刷成一片红。
 func (h *Hub) currentVersionCached(ctx context.Context) int64 {
 	if h.db == nil {
 		return h.Version()
 	}
 	v, err := h.currentVersion(ctx)
 	if err != nil {
+		if dbClosed(err) {
+			h.log.Debug("读取版本号：库已关闭（恢复/重启中），沿用内存版本", "version", h.Version())
+			return h.Version()
+		}
 		h.log.Warn("读取版本号失败，沿用内存版本", "err", err, "version", h.Version())
 		return h.Version()
 	}

server/internal/realtime/client.go

@@ -51,10 +51,13 @@ type client struct {
 	// 丢了就可能让那块屏一直停在旧数据上，直到下一条变更到来。
 	snapshotPending atomic.Bool
 	slow            atomic.Bool
+	// lastSeen 是最近一次真正收到对端帧的时间（unix 纳秒），含普通数据帧与 ping 的 pong。
+	// 「这条连接还活着吗」只认它：服务端自己发过什么、写过几次 socket 都不算证据。
+	lastSeen atomic.Int64
 }
 
 func newClient(h *Hub, conn *websocket.Conn, remoteAddr string, id wsIdentity) *client {
-	return &client{
+	c := &client{
 		hub:           h,
 		conn:          conn,
 		remoteAddr:    remoteAddr,
@@ -65,9 +68,36 @@ func newClient(h *Hub, conn *websocket.Conn, remoteAddr string, id wsIdentity) *
 		sessionID:     id.SessionID,
 		settingsAdmin: id.SettingsAdmin,
 	}
+	// 建立连接本身就是一次「听到对端」：不初始化的话，存活探测会把刚连上的
+	// 大屏当成已经静默很久，第一条 ping 立刻发出去。
+	c.markSeen(time.Now())
+	return c
 }
 
-// stop 只负责让两条 goroutine 退出；真正的关闭动作由 serve 统一执行，
+// markSeen 记下「刚刚听到了对端」。
+func (c *client) markSeen(now time.Time) { c.lastSeen.Store(now.UnixNano()) }
+
+// lastSeenAt 返回最近一次听到对端的时间。
+func (c *client) lastSeenAt() time.Time { return time.Unix(0, c.lastSeen.Load()) }
+
+// instanceIDValue 读实例 id；调用方拿到的是快照值，不持有锁。
+func (c *client) instanceIDValue() string {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.instanceID
+}
+
+// isDone 判断本连接是否已经进入关闭流程。
+func (c *client) isDone() bool {
+	select {
+	case <-c.done:
+		return true
+	default:
+		return false
+	}
+}
+
+// stop 只负责让读写与存活探测三条 goroutine 退出；真正的关闭动作由 serve 统一执行，
 // 避免在持有广播锁时做可能阻塞的关闭握手。
 func (c *client) stop(code websocket.StatusCode, reason string) {
 	c.closeOnce.Do(func() {
@@ -135,12 +165,21 @@ func (c *client) sendRaw(msg []byte) bool {
 	}
 }
 
-// readLoop 解析 C→S 消息；首条消息受 helloTimeout 限制，防止空连接占用资源。
+// readLoop 解析 C→S 消息；握手必须在 helloTimeout 内完成，否则断开，
+// 防止「连上就不说话」的空连接一直占着 goroutine 与 fd。
 // 读写都在独立 goroutine 里跑，HTTP 中间件的 recover 覆盖不到，必须各自兜底。
 func (c *client) readLoop(ctx context.Context) {
 	defer c.stop(websocket.StatusNormalClosure, "")
 	defer c.guardLoop("读")
 
+	// 握手 deadline 在进入循环时算一次，整个「未握手」阶段共用它。
+	//
+	// 以前是每轮 Read 都新建一个 WithTimeout：只要对端在超时前随便发一帧（哪怕是个
+	// 客户端不认识的事件），计时就被重置，未握手的连接可以无限期挂着——
+	// 现场用脚本反复重连就能堆出一堆永不释放的连接。绝对 deadline 让「打开连接却不
+	// hello」在固定时间后必然被断开；已握手的连接不受它限制。
+	helloDeadline := time.Now().Add(c.hub.helloTimeout())
+
 	for {
 		c.mu.Lock()
 		greeted := c.greeted
@@ -149,7 +188,7 @@ func (c *client) readLoop(ctx context.Context) {
 		readCtx := ctx
 		var cancel context.CancelFunc
 		if !greeted {
-			readCtx, cancel = context.WithTimeout(ctx, c.hub.helloTimeout())
+			readCtx, cancel = context.WithDeadline(ctx, helloDeadline)
 		}
 		_, data, err := c.conn.Read(readCtx)
 		if cancel != nil {
@@ -158,10 +197,84 @@ func (c *client) readLoop(ctx context.Context) {
 		if err != nil {
 			return
 		}
+		// 收到任何一帧都是「对端还活着」的证据，与它是不是合法事件无关。
+		c.markSeen(time.Now())
 		c.handleMessage(ctx, data)
 	}
 }
 
+// livenessLoop 定期求证对端还在不在：静默（没有任何 C→S 帧）超过一个探测周期就发一次
+// WebSocket ping 并等 pong，连续 maxProbeFailures 次等不到就断开这条连接。
+//
+// 为什么必须单独探：大屏在数据没变时只收不发（hello 只在连接与翻页时发、ack 只在应用
+// 变更时发），所以「没有上行帧」不等于掉线，不能当判据；而 TCP 层面「连接对象还在」
+// 什么也证明不了——拔网线、断电、机器休眠都不会让服务端立刻收到错误，内核缓冲会让写
+// 一直“成功”，注册表里的「在线」就会永远挂着那块已经不在的屏。
+// ping/pong 是唯一的真实往返，且由浏览器在网络层自动应答，不需要前端改代码。
+func (c *client) livenessLoop(ctx context.Context) {
+	defer c.guardLoop("存活探测")
+
+	failures := 0
+	for {
+		interval := c.hub.livenessIntervalValue()
+		if interval <= 0 {
+			// <= 0 表示关闭探测，只给「单独验证某个判定口径」的用例用：
+			// 生产路径上 NewHub 一定给了默认值，不会走到这里。
+			return
+		}
+		timer := time.NewTimer(interval)
+		select {
+		case <-ctx.Done():
+			timer.Stop()
+			return
+		case <-c.done:
+			timer.Stop()
+			return
+		case <-timer.C:
+		}
+
+		if time.Since(c.lastSeenAt()) < interval {
+			// 静默期内收到过真实上行帧：这条连接有人，不必多问一句。
+			failures = 0
+			continue
+		}
+		if c.probePeer(ctx) {
+			failures = 0
+			continue
+		}
+		if ctx.Err() != nil || c.isDone() {
+			return
+		}
+		failures++
+		if failures < maxProbeFailures {
+			// 一次不回应可能只是对端正忙（例如正在收一份大快照，写锁被占住），
+			// 再给一个周期；连续失败才说明这条连接上已经没有人了。
+			continue
+		}
+		c.hub.log.Info("实时连接长时间无响应（未回 pong），按掉线断开",
+			"remote", c.remoteAddr, "instance", c.instanceIDValue(),
+			"silent", time.Since(c.lastSeenAt()).Truncate(time.Second).String())
+		c.stop(unresponsiveCloseCode, "连接无响应")
+		return
+	}
+}
+
+// probePeer 发一次 ping 并等 pong；返回 true 表示对端应答了。
+func (c *client) probePeer(ctx context.Context) bool {
+	pingCtx, cancel := context.WithTimeout(ctx, c.hub.pongTimeoutValue())
+	defer cancel()
+
+	if err := c.conn.Ping(pingCtx); err != nil {
+		c.hub.log.Debug("存活探测未收到 pong", "remote", c.remoteAddr, "err", err)
+		return false
+	}
+	now := time.Now()
+	c.markSeen(now)
+	// 这次往返是真实的客户端应答，注册表的「最后活跃」也该跟着走。
+	c.hub.touchInstance(c, now)
+	return true
+}
+
 func (c *client) handleMessage(ctx context.Context, data []byte) {
 	var env envelope
 	if err := json.Unmarshal(data, &env); err != nil {

server/internal/realtime/hub.go

@@ -17,7 +17,10 @@ import (
 	"git.yeij.top/AskaEth/Scoreboard/server/internal/middleware"
 )
 
-// 默认参数；现场可通过 Set* 调整。
+// 默认参数。
+//
+// 注意：Set* 目前只有测试在调用——现场调优要求先把它们接到 config.yaml / main.go 上，
+// 那是本包之外的决定，所以不要照着 Set* 的存在去宣称「现场可调」。
 const (
 	defaultHeartbeatInterval = 10 * time.Second
 	defaultMaxCatchup        = 500
@@ -26,6 +29,19 @@ const (
 	defaultWriteTimeout      = 10 * time.Second
 	defaultCloseTimeout      = 2 * time.Second
 	defaultSendBuffer        = 64
+	// defaultLivenessInterval 是「一点客户端帧都没收到」的静默期上限：超过它就发一次
+	// WebSocket ping 求证对端还在不在（见 client.livenessLoop）。
+	//
+	// 不能把「静默」直接当掉线：大屏在数据没变时本来就不上行。取 15s，配合
+	// maxProbeFailures = 2 与 defaultPongTimeout = 5s，真正掉线的屏最迟
+	// 2 × (15s + 5s) = 40s 内被判定并断开；稳态下每块屏每分钟只多发 4 个 ping 帧。
+	defaultLivenessInterval = 15 * time.Second
+	// defaultPongTimeout 是等一次 pong 的超时。ping 帧本身要走写锁，正常浏览器在
+	// 网络层立刻应答，5s 已经宽裕。
+	defaultPongTimeout = 5 * time.Second
+	// maxProbeFailures 是连续多少次探测失败才断开：单次失败可能只是对端在忙
+	// （正在收一份大快照，写锁被占住），连续失败才说明连接上没有人了。
+	maxProbeFailures = 2
 	// defaultSnapshotMinInterval 是同一连接两次「整库快照」之间的最小间隔。
 	//
 	// 取 2.5s，比客户端自己的 3s 冷却（web/src/shared/realtime.ts 的 resyncCooldownMs）短半秒：
@@ -43,6 +59,10 @@ const (
 // 不能用 1008：前端把所有 1008 当「登录失效」并永久停止重连，慢客户端被踢后大屏会冻结。
 const slowCloseCode = websocket.StatusCode(4000)
 
+// unresponsiveCloseCode 是踢掉「不回 pong」的连接时使用的关闭码。同样避开 1008：
+// 那块屏只是掉线了，重连回来就能补上数据，不该被引导去重新登录。
+const unresponsiveCloseCode = websocket.StatusCode(4001)
+
 // Hub 是实时同步中心：维护房间、连接、大屏实例注册表与版本号。
 //
 // 版本号等于 change_log 的最大 id；写入方提交事务后调用 Broadcast 推送变更，
@@ -76,6 +96,11 @@ type Hub struct {
 	allowedOrigins    []string
 	// snapshotMinInterval 是同一连接两次整库快照之间的最小间隔；<=0 表示不限流。
 	snapshotMinInterval time.Duration
+	// livenessInterval 是「一点客户端帧都没收到」的静默期上限；pongTimeout 是等一次
+	// pong 的超时。两者只影响存活探测（见 client.livenessLoop），默认值见常量区注释；
+	// livenessInterval <= 0 表示关闭探测（只有测试会这么设）。
+	livenessInterval time.Duration
+	pongTimeout      time.Duration
 	// sessionChecker 复查长连接背后的会话是否还有效；未注入时只在握手时校验一次。
 	sessionChecker SessionChecker
 }
@@ -108,6 +133,8 @@ func NewHub(db *sql.DB, log *slog.Logger) *Hub {
 		helloTO:             defaultHelloTimeout,
 		writeTO:             defaultWriteTimeout,
 		snapshotMinInterval: defaultSnapshotMinInterval,
+		livenessInterval:    defaultLivenessInterval,
+		pongTimeout:         defaultPongTimeout,
 	}
 	if db != nil {
 		if v, err := h.currentVersion(context.Background()); err == nil {
@@ -159,7 +186,11 @@ func (h *Hub) setVersion(v int64) {
 	h.mu.Unlock()
 }
 
-// SetHeartbeatInterval 调整心跳间隔并立即生效；用于现场调优与测试。
+// SetHeartbeatInterval 调整心跳间隔并立即生效。
+//
+// 唯一调用方是测试（把心跳调快，好在毫秒级跑完「会话撤销即断开」这类用例）；
+// 生产路径用的是 defaultHeartbeatInterval。要做成现场可调，得先在 main.go 里
+// 从 config.yaml 读出来再调这里——本包不读配置，也没有别的消费方。
 func (h *Hub) SetHeartbeatInterval(d time.Duration) {
 	if d <= 0 {
 		return
@@ -174,7 +205,7 @@ func (h *Hub) SetHeartbeatInterval(d time.Duration) {
 	}
 }
 
-// SetMaxCatchup 设置增量补发的条数上限；超过就回落全量快照。
+// SetMaxCatchup 设置增量补发的条数上限；超过就回落全量快照。同样只有测试在调用。
 func (h *Hub) SetMaxCatchup(n int) {
 	if n <= 0 {
 		return
@@ -184,7 +215,7 @@ func (h *Hub) SetMaxCatchup(n int) {
 	h.mu.Unlock()
 }
 
-// SetSlowLag 设置「慢客户端」的版本落后阈值；<=0 表示不判定。
+// SetSlowLag 设置「慢客户端」的版本落后阈值；<=0 表示不判定。同样只有测试在调用。
 func (h *Hub) SetSlowLag(n int64) {
 	h.mu.Lock()
 	h.slowLag = n
@@ -261,6 +292,18 @@ func (h *Hub) writeTimeout() time.Duration {
 	return h.writeTO
 }
 
+func (h *Hub) livenessIntervalValue() time.Duration {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+	return h.livenessInterval
+}
+
+func (h *Hub) pongTimeoutValue() time.Duration {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+	return h.pongTimeout
+}
+
 func (h *Hub) allowedOriginsValue() []string {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
@@ -336,9 +379,11 @@ func (h *Hub) serve(conn *websocket.Conn, remoteAddr string, id wsIdentity) {
 	defer cancel()
 
 	var loops sync.WaitGroup
-	loops.Add(2)
+	loops.Add(3)
 	go func() { defer loops.Done(); c.readLoop(ctx) }()
 	go func() { defer loops.Done(); c.writeLoop(ctx) }()
+	// 存活探测：服务端「连接对象还在」不等于对端还在，注册表的在线判定靠这条循环求证。
+	go func() { defer loops.Done(); c.livenessLoop(ctx) }()
 
 	<-c.done
 	// 先做关闭握手，再取消读上下文：coder/websocket 在读上下文被取消时会直接
@@ -487,6 +532,15 @@ func (h *Hub) sendInitial(ctx context.Context, c *client, lastVersion *int64) {
 
 	cur, err := h.currentVersion(ctx)
 	if err != nil {
+		if dbClosed(err) {
+			// 恢复/重启窗口（库已经被关掉、文件还没换完）里的新连接不能踢：
+			// 现场看到的是「每块屏刚连上就被 1011 打回、日志一屏 ERROR」，像恢复把系统
+			// 搞坏了。与 httpapi/realtime.go 的降级口径一致——这类错误只记 Debug，
+			// 连接留着（心跳照发，客户端看门狗不会误判），等库回来后的下一次
+			// resync / 重连自然就能拿到数据。
+			h.log.Debug("跳过首包：库已关闭（恢复/重启中）", "remote", c.remoteAddr, "err", err)
+			return
+		}
 		h.log.Error("读取版本号失败，无法下发首包", "err", err)
 		c.stop(websocket.StatusInternalError, "版本号不可用")
 		return
@@ -584,6 +638,13 @@ func (h *Hub) flushPendingSnapshot(ctx context.Context, c *client) bool {
 func (h *Hub) sendSnapshotLocked(ctx context.Context, c *client) {
 	snap, err := h.Snapshot(ctx)
 	if err != nil {
+		if dbClosed(err) {
+			// 同 sendInitial：恢复窗口里「快照读不出来」不是故障，是停机动作的一部分。
+			// 这里既不能记 ERROR，也不能拿 1011 把大屏踢回去重连（那正是现场
+			// 「恢复把系统搞坏了」的观感来源）；连接留着，心跳继续。
+			h.log.Debug("跳过整库快照：库已关闭（恢复/重启中）", "remote", c.remoteAddr, "err", err)
+			return
+		}
 		h.log.Error("构建快照失败", "err", err)
 		c.stop(websocket.StatusInternalError, "快照不可用")
 		return
@@ -604,6 +665,10 @@ func (h *Hub) sendSnapshotLocked(ctx context.Context, c *client) {
 func (h *Hub) Broadcast(changes []Change) { h.fanout("", changes) }
 
 // BroadcastTo 把变更推给指定房间（如 RoomAdmin、AdminRoom(uid)）。
+//
+// 同样只有测试在调用：生产的推送要么是 Broadcast（所有已握手连接），要么是
+// SendCommandTo（大屏指令）。保留它是为了让「房间」这层语义有可用的出口，
+// 删掉或接到生产调用方都要连 devdocs/05 §1 一起改（审查清单 C36）。
 func (h *Hub) BroadcastTo(room string, changes []Change) { h.fanout(room, changes) }
 
 // fanout 在 sendMu 下按版本去重后下发：已经发过的版本不再重复投递。
@@ -701,10 +766,18 @@ func (h *Hub) SendCommandToInstances(targets []string, cmd DisplayCommand) (int,
 		return h.onlineDisplayCount(), nil
 	}
 
+	// 归一化只做一次，并且**匹配与写注册表共用同一个值**：管理端从表格里带过来的 id
+	// 常有多余空白（粘贴/换行），以前匹配用 TrimSpace、写「当前页」用原值，
+	// 结果是指令真的发到了那块屏，注册表里的当前页却停在旧值上，
+	// 管理端下一次轮询又把界面上刚切过去的页显示回来。
 	wanted := make(map[string]bool, len(targets))
+	normalized := make([]string, 0, len(targets))
 	for _, id := range targets {
 		if id = strings.TrimSpace(id); id != "" {
-			wanted[id] = true
+			if !wanted[id] {
+				wanted[id] = true
+				normalized = append(normalized, id)
+			}
 		}
 	}
 
@@ -723,7 +796,7 @@ func (h *Hub) SendCommandToInstances(targets []string, cmd DisplayCommand) (int,
 	h.sendMu.Unlock()
 
 	if cmd.Action == CmdGoto {
-		h.setInstancePage(pageFromPayload(cmd.Payload), targets)
+		h.setInstancePage(pageFromPayload(cmd.Payload), normalized)
 	}
 	return len(matched), nil
 }
@@ -819,7 +892,10 @@ func (h *Hub) beat() {
 			continue
 		}
 		c.sendEvent(EventHeartbeat, data)
-		h.touchInstance(c, now)
+		// 只同步 ack / 慢标记，**不刷 lastHeartbeat**：注册表里的「在线」与「最后活跃」
+		// 必须来自对端。服务端每 10s 自己给自己盖一个时间戳，会让拔了网线的屏一直
+		// 显示在线、指令发过去还报「命中 N 块屏」。真正的存活求证在 livenessLoop。
+		h.syncInstance(c)
 		h.checkSlow(c, version)
 
 		if c.snapshotPending.Load() {

server/internal/realtime/hub_test.go

@@ -1,6 +1,7 @@
 package realtime
 
 import (
+	"bytes"
 	"context"
 	"database/sql"
 	"encoding/json"
@@ -13,6 +14,7 @@ import (
 	"path/filepath"
 	"reflect"
 	"strings"
+	"sync"
 	"sync/atomic"
 	"testing"
 	"time"
@@ -50,9 +52,17 @@ func newTestEnvAs(t *testing.T, u *auth.User) *testEnv {
 // *auth.Session：会话复查（撤销即断开）要按会话 id 判定，测试必须能给出这一条。
 func newTestEnvAsSession(t *testing.T, u *auth.User, sessionID string) *testEnv {
 	t.Helper()
+	return newTestEnvFull(t, u, sessionID, io.Discard)
+}
+
+// newTestEnvFull 与 newTestEnvAsSession 相同，但把实时层的日志写进调用方给的 writer，
+// 且放行 Debug：需要断言「这条路径不该刷 WARN/ERROR」的用例（如恢复窗口降级）用它。
+// 其余用例传 io.Discard，行为与以前一致。
+func newTestEnvFull(t *testing.T, u *auth.User, sessionID string, logw io.Writer) *testEnv {
+	t.Helper()
 
 	db := newTestDB(t)
-	h := NewHub(db, slog.New(slog.NewTextHandler(io.Discard, &slog.HandlerOptions{Level: slog.LevelError})))
+	h := NewHub(db, slog.New(slog.NewTextHandler(logw, &slog.HandlerOptions{Level: slog.LevelDebug})))
 	handler := h.Handler()
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		ctx := middleware.WithUser(r.Context(), u)
@@ -934,6 +944,40 @@ func TestSendCommandTargetsMixedOnlineOffline(t *testing.T) {
 	}
 }
 
+// targets 里带空白（管理端从表格/粘贴里带过来的 id）时，匹配与「当前页」写入必须用
+// 同一个归一化后的值：以前匹配走 TrimSpace、写注册表用原值，结果是指令真的发到了那块屏，
+// 注册表里的当前页却停在旧值上，管理端下一次轮询又把界面上刚切过去的页显示回来。
+func TestSendCommandTargetsTrimsWhitespaceForPageRegistry(t *testing.T) {
+	env := newTestEnv(t)
+	a := env.dial(t, &helloPayload{Role: RoleDisplay, InstanceID: "screen-a", Page: "standings"})
+	b := env.dial(t, &helloPayload{Role: RoleDisplay, InstanceID: "screen-b", Page: "standings"})
+	a.recvEvent(EventSnapshot)
+	b.recvEvent(EventSnapshot)
+
+	cmd, err := NewDisplayCommand(CmdGoto, map[string]string{"page": "medals"})
+	if err != nil {
+		t.Fatalf("构造 goto: %v", err)
+	}
+	matched, err := env.hub.SendCommandToInstances([]string{"  screen-a \n"}, cmd)
+	if err != nil {
+		t.Fatalf("定向下发: %v", err)
+	}
+	if matched != 1 {
+		t.Fatalf("带空白的 id 应命中 1 个实例，得到 %d", matched)
+	}
+	if got := decode[DisplayCommand](t, a.recvEvent(EventDisplayCommand)); got.Action != CmdGoto {
+		t.Fatalf("被点名的实例应收到 goto，得到 %s", got.Action)
+	}
+
+	insts := env.hub.Instances()
+	if got := instancePage(insts, "screen-a"); got != "medals" {
+		t.Fatalf("被点名实例的当前页应更新为 medals，得到 %q", got)
+	}
+	if got := instancePage(insts, "screen-b"); got != "standings" {
+		t.Fatalf("未被点名实例的当前页不该变，得到 %q", got)
+	}
+}
+
 // 非法 action 走定向通道要报错，不能静默丢掉。
 func TestSendCommandTargetsRejectsUnknownAction(t *testing.T) {
 	env := newTestEnv(t)
@@ -1399,3 +1443,237 @@ func TestPendingSnapshotFlushIsPerConnection(t *testing.T) {
 	a.noSnapshotWithin(300 * time.Millisecond)
 	b.noSnapshotWithin(300 * time.Millisecond)
 }
+
+// ---------- 在线判定 / 握手期限 / 恢复窗口降级 ----------
+
+// syncBuffer 是带锁的日志缓冲：日志由实时层的多条 goroutine 写、用例在主 goroutine 读。
+type syncBuffer struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+func (b *syncBuffer) Write(p []byte) (int, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.Write(p)
+}
+
+func (b *syncBuffer) String() string {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.String()
+}
+
+// tune 直接改内部参数：这些值只影响超时，用例需要的是毫秒级跑完，
+// 而 Set* 那一族是留给现场调优的（且本包不该再为测试多开一个导出 API）。
+func (e *testEnv) tune(fn func(h *Hub)) {
+	e.hub.mu.Lock()
+	defer e.hub.mu.Unlock()
+	fn(e.hub)
+}
+
+// waitForWithin 与 waitFor 相同，只是等待窗口由调用方给：有的用例要等一次完整的
+// 服务端关闭握手（serve 里最多 2s）。
+func waitForWithin(t *testing.T, what string, d time.Duration, cond func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(d)
+	for time.Now().Before(deadline) {
+		if cond() {
+			return
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	t.Fatalf("等待条件超时: %s", what)
+}
+
+func instanceOnline(insts []Instance, id string) bool {
+	for _, st := range insts {
+		if st.ID == id {
+			return st.Online
+		}
+	}
+	return false
+}
+
+// trySend 发送一帧并在失败时返回错误：用例要靠它判断「服务端已经关掉这条连接」
+// （普通 send 会直接 Fatal，那条路径在这里是预期结果而不是失败）。
+func (c *wsClient) trySend(event string, data any) error {
+	msg, err := encode(event, data)
+	if err != nil {
+		return err
+	}
+	ctx, cancel := context.WithTimeout(c.ctx, 2*time.Second)
+	defer cancel()
+	return c.conn.Write(ctx, websocket.MessageText, msg)
+}
+
+// muteConn 是一条「连上就不再读」的客户端：它的 TCP 连接还在，但永远不会回应 pong——
+// 这正是拔网线 / 断电 / 机器休眠之后，服务端那一侧看到的样子。
+type muteConn struct {
+	t    *testing.T
+	ctx  context.Context
+	conn *websocket.Conn
+}
+
+func dialMute(t *testing.T, env *testEnv, hello helloPayload) *muteConn {
+	t.Helper()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	conn, _, err := websocket.Dial(ctx, "ws"+strings.TrimPrefix(env.srv.URL, "http")+"/ws", nil)
+	if err != nil {
+		cancel()
+		t.Fatalf("连接 /ws: %v", err)
+	}
+	t.Cleanup(func() {
+		_ = conn.CloseNow()
+		cancel()
+	})
+
+	c := &muteConn{t: t, ctx: ctx, conn: conn}
+	if err := c.send(EventHello, hello); err != nil {
+		t.Fatalf("发送 hello: %v", err)
+	}
+	return c
+}
+
+func (c *muteConn) send(event string, data any) error {
+	msg, err := encode(event, data)
+	if err != nil {
+		return err
+	}
+	ctx, cancel := context.WithTimeout(c.ctx, 5*time.Second)
+	defer cancel()
+	return c.conn.Write(ctx, websocket.MessageText, msg)
+}
+
+// 「在线」必须反映真的还活着：连接对象还在、但对端已经不应答的屏不能一直算命中。
+// 判据是真实的 ping/pong 往返，不是服务端自己刷的时间戳。
+func TestInstanceGoesOfflineWhenPeerStopsAnswering(t *testing.T) {
+	env := newTestEnv(t)
+	env.tune(func(h *Hub) {
+		h.livenessInterval = 80 * time.Millisecond
+		h.pongTimeout = 60 * time.Millisecond
+	})
+
+	// 失联的屏：握手正常，之后一个字节都不回。
+	dialMute(t, env, helloPayload{Role: RoleDisplay, InstanceID: "mute-1", Page: "standings"})
+	waitFor(t, "失联实例登记在线", func() bool {
+		insts := env.hub.Instances()
+		return len(insts) == 1 && insts[0].Online
+	})
+
+	// 正常的大屏同时挂着：它一直在收（于是自动回 pong），绝不能被误判成离线。
+	alive := env.dial(t, &helloPayload{Role: RoleDisplay, InstanceID: "alive-1", Page: "standings"})
+	alive.recvEvent(EventSnapshot)
+
+	waitForWithin(t, "失联实例被判离线", 5*time.Second, func() bool {
+		return !instanceOnline(env.hub.Instances(), "mute-1")
+	})
+	if !instanceOnline(env.hub.Instances(), "alive-1") {
+		t.Fatal("正常应答的实例不该被判离线")
+	}
+
+	cmd, err := NewDisplayCommand(CmdReload, nil)
+	if err != nil {
+		t.Fatalf("构造 reload: %v", err)
+	}
+	if matched, err := env.hub.SendCommandToInstances([]string{"mute-1"}, cmd); err != nil || matched != 0 {
+		t.Fatalf("失联实例不该再计入命中，得到 %d err=%v", matched, err)
+	}
+	// 在线的屏不受影响：它的连接与服务端之间一切照旧。
+	if ev, _, ok := alive.recvWithin(200 * time.Millisecond); ok {
+		t.Fatalf("正常实例不该收到额外消息，得到 %q", ev)
+	}
+}
+
+// 握手超时是**绝对** deadline：以前每轮 Read 都重开一个 helloTimeout 窗口，
+// 没握手的连接只要在窗口内随便发一帧就能无限期挂着（脚本重连能堆出一片空连接）。
+func TestHelloDeadlineIsAbsolute(t *testing.T) {
+	env := newTestEnv(t)
+	env.tune(func(h *Hub) { h.helloTO = 300 * time.Millisecond })
+
+	// 不 hello，只反复喂合法但无关的帧（ack）。
+	c := env.dial(t, nil)
+
+	closed := false
+	deadline := time.Now().Add(1500 * time.Millisecond)
+	for time.Now().Before(deadline) && !closed {
+		select {
+		case msg, ok := <-c.msgs:
+			if !ok || msg.err != nil {
+				closed = true
+			}
+		case <-time.After(60 * time.Millisecond):
+			// 写失败说明服务端已经关了这条连接，同样算「已断开」。
+			closed = c.trySend(EventAck, ackPayload{}) != nil
+		}
+	}
+	if !closed {
+		t.Fatal("未握手的连接必须在绝对 deadline（300ms）后被断开，而不是每收一帧就重置计时")
+	}
+}
+
+// 心跳循环不能替客户端盖「最后活跃」的章：一块不发任何上行帧的大屏，它的
+// LastHeartbeat 必须停在真实收到帧的那一刻，否则注册表里的「在线/最后活跃」
+// 全是服务端自己说的，拔了网线的屏也会显示成刚刚活跃（这正是 A24 的根因）。
+func TestHeartbeatDoesNotRefreshActivityByItself(t *testing.T) {
+	env := newTestEnv(t)
+	env.hub.SetHeartbeatInterval(30 * time.Millisecond)
+	// 关掉存活探测：这条用例只验证「时间戳的口径」，探测本身另有用例。
+	env.tune(func(h *Hub) { h.livenessInterval = 0 })
+
+	c := env.dial(t, &helloPayload{Role: RoleDisplay, InstanceID: "d1"})
+	c.recvEvent(EventSnapshot)
+
+	insts := env.hub.Instances()
+	if len(insts) != 1 {
+		t.Fatalf("实例数应为 1，得到 %d", len(insts))
+	}
+	before := insts[0].LastHeartbeat
+
+	// 连收 5 个心跳，期间客户端一个上行帧都不发（它只读）。
+	for i := 0; i < 5; i++ {
+		c.recvEvent(EventHeartbeat)
+	}
+	if got := env.hub.Instances()[0].LastHeartbeat; !got.Equal(before) {
+		t.Fatalf("服务端自己发心跳不能把「最后活跃」往前推：%v → %v", before, got)
+	}
+}
+
+// 恢复窗口（库已经关掉、文件还没换完）里实时层必须安静下来：不刷 WARN/ERROR，
+// 也不拿 1011 把刚连上或正在重连的屏踢回去——现场会把那读成「恢复把系统搞坏了」。
+// 降级口径与 httpapi/realtime.go 的 dbClosed 一致：只记 Debug，连接留着、心跳照发。
+func TestRecoveryWindowDegradesQuietly(t *testing.T) {
+	logs := &syncBuffer{}
+	env := newTestEnvFull(t, &auth.User{Role: auth.RoleGuest}, "", logs)
+	env.hub.SetHeartbeatInterval(40 * time.Millisecond)
+	env.hub.SetSnapshotMinInterval(0)
+
+	c := env.dial(t, &helloPayload{Role: RoleDisplay, InstanceID: "d1"})
+	c.recvEvent(EventSnapshot)
+
+	// 模拟恢复动作的中间状态：目标库被关掉（换文件前的一刻）。
+	if err := env.db.Close(); err != nil {
+		t.Fatalf("关闭赛事库: %v", err)
+	}
+
+	// 大屏想补数据（resync）：这条路径在恢复窗口里必然读不到库。
+	c.send(EventResync, struct{}{})
+	// 连接必须留着，心跳照常下发（被 1011 打回时 recvWithin 会直接 Fatal）。
+	if ev, _, ok := c.recvWithin(2 * time.Second); !ok || ev != EventHeartbeat {
+		t.Fatalf("恢复窗口里已连接的屏应保持在线并继续收心跳，得到 %q ok=%v", ev, ok)
+	}
+	// 恢复窗口里新连上的屏同理：首包拿不到也不能被踢。
+	fresh := env.dial(t, &helloPayload{Role: RoleDisplay, InstanceID: "d2"})
+	if ev, _, ok := fresh.recvWithin(2 * time.Second); !ok || ev != EventHeartbeat {
+		t.Fatalf("恢复窗口里新连接应保持并收到心跳，得到 %q ok=%v", ev, ok)
+	}
+
+	got := logs.String()
+	if strings.Contains(got, "level=ERROR") || strings.Contains(got, "level=WARN") {
+		t.Fatalf("恢复窗口里不该出现 WARN/ERROR 日志:\n%s", got)
+	}
+	if !strings.Contains(got, "库已关闭") {
+		t.Fatalf("恢复窗口应留下 Debug 级的降级记录（否则真出问题时无从查起）:\n%s", got)
+	}
+}

server/internal/realtime/instances.go

@@ -5,6 +5,7 @@ import (
 	"encoding/hex"
 	"sort"
 	"strconv"
+	"strings"
 	"time"
 )
 
@@ -111,7 +112,9 @@ func (h *Hub) releaseDisplayID(id string, c *client) {
 	st.slow = c.slow.Load()
 }
 
-// touchInstance 在收到客户端消息或下发心跳时刷新「最后心跳」。
+// touchInstance 在收到客户端消息或探测到 pong 时刷新「最后活跃」。
+// now 必须是**收到对端帧的时间**，不能是服务端自己想盖的章：这个字段既决定注册表
+// 里的「最后心跳」，也是离线实例清理的计时起点（见 pruneInstancesLocked）。
 func (h *Hub) touchInstance(c *client, now time.Time) {
 	c.mu.Lock()
 	id := c.instanceID
@@ -129,9 +132,32 @@ func (h *Hub) touchInstance(c *client, now time.Time) {
 	}
 }
 
+// syncInstance 只把连接的 ack / 慢标记同步到注册表，**不碰 lastHeartbeat**。
+// 心跳循环用它：服务端自己发过心跳不能算「对端还活着」的证据，
+// 否则一块拔了网线的屏会一直被刷成「刚刚活跃」。
+func (h *Hub) syncInstance(c *client) {
+	c.mu.Lock()
+	id := c.instanceID
+	c.mu.Unlock()
+	if id == "" {
+		return
+	}
+
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if st := h.instances[id]; st != nil {
+		st.ackVersion = c.ackVersion.Load()
+		st.slow = c.slow.Load()
+	}
+}
+
 // setInstancePage 记录服务端刚下发的目标页，让注册表里的「当前页」跟得上 goto 指令。
 // targets 为空表示广播（所有在线实例），否则只更新被点名的那几个实例——定向切页后
 // 每块屏的「当前页」必须各算各的。
+//
+// targets 在这里再 TrimSpace 一次是防御性的：调用方（SendCommandToInstances）已经
+// 归一化过，但只要有第二个调用方忘了，注册表里就会出现「id 带空格」这类永远匹配不上的
+// 死条目，而症状是「指令发出去了、界面上的当前页不变」——很难查。
 func (h *Hub) setInstancePage(page string, targets []string) {
 	if page == "" {
 		return
@@ -140,7 +166,9 @@ func (h *Hub) setInstancePage(page string, targets []string) {
 	if len(targets) > 0 {
 		picked = make(map[string]bool, len(targets))
 		for _, id := range targets {
-			picked[id] = true
+			if id = strings.TrimSpace(id); id != "" {
+				picked[id] = true
+			}
 		}
 	}
 
@@ -184,6 +212,11 @@ func (h *Hub) pruneInstancesLocked(now time.Time) {
 }
 
 // Instances 返回注册表快照，按 instanceId 排序，便于管理端稳定展示。
+//
+// online = 「还有连接挂着」。这里刻意不叠加 TTL 判断：只要连接还在，客户端就是那条
+// 连接上的证据——而连接本身已经被 livenessLoop 用 ping/pong 求证过（不回 pong 的连接
+// 会先被断开、引用计数归零）。反过来，若在这里按 lastHeartbeat 再判一次，
+// 一块正常但不发上行帧的大屏（数据没变时它只在收心跳）就会被误判成离线。
 func (h *Hub) Instances() []Instance {
 	h.mu.Lock()
 	defer h.mu.Unlock()

server/internal/realtime/protocol.go

@@ -23,12 +23,19 @@ const (
 )
 
 // 房间名。admin:<userId> 由 AdminRoom 生成，用于定向通知。
+//
+// admin:<userId> 目前没有生产推送方（只有测试用 BroadcastTo 往它发过消息）：
+// 保留它是因为 devdocs/05 §1 把「admin:<userId>（定向通知）」写成了协议的一部分，
+// 要删就得连着文档一起改，而文档不在本轮可改范围内——见审查清单 C36。
 const (
 	RoomDisplay = "display"
 	RoomAdmin   = "admin"
 )
 
 // AdminRoom 返回某个管理端用户的定向房间名。
+//
+// 只有带会话的管理端连接会加入这个房间（见 handleHello），身份来自会话而非客户端自报；
+// 「guest 不能进管理端房间」这条鉴权语义由测试钉住，删房间会一起删掉那条覆盖。
 func AdminRoom(userID int64) string { return fmt.Sprintf("admin:%d", userID) }
 
 // 连接角色。

server/internal/realtime/snapshot.go

@@ -215,7 +215,7 @@ func loadEvents(ctx context.Context, tx *sql.Tx, snap *Snapshot) error {
 }
 
 // loadStandings 复用 domain 的排名口径，且输入与 REST /api/standings 完全一致：
-// 排名输入只含启用单位，展示字段用全量单位表补齐；个人流水按系数折算、团体奖牌开关生效、
+// 排名输入只含启用单位，展示字段用全量单位表补齐；个人流水按系数折算、奖牌开关生效、
 // 只有配了计分通道的项目才产出名次，排序键取自规则包落库的 standings.tie_break。
 func loadStandings(ctx context.Context, tx *sql.Tx, snap *Snapshot, teams []domain.Team, values map[string]string) error {
 	ledger, err := loadLedger(ctx, tx)

server/internal/realtime/snapshot_test.go

@@ -300,7 +300,7 @@ func TestSnapshotStandingsAppliesIndividualWeight(t *testing.T) {
 	}
 }
 
-// 团体奖牌开关与 REST 一致：关闭后团体项目奖牌不计入单位奖牌榜。
+// 奖牌开关与 REST 一致：关闭后团体项目奖牌不计入单位奖牌榜。
 func TestSnapshotStandingsMedalSwitch(t *testing.T) {
 	env := newTestEnv(t)
 	db := env.db
@@ -327,7 +327,7 @@ func TestSnapshotStandingsMedalSwitch(t *testing.T) {
 		t.Fatalf("构建快照: %v", err)
 	}
 	if len(snap.Standings) != 1 || snap.Standings[0].Gold != 0 || snap.Standings[0].MedalTotal != 0 {
-		t.Fatalf("关闭团体奖牌后应清零: %+v", snap.Standings)
+		t.Fatalf("关闭奖牌开关后应清零: %+v", snap.Standings)
 	}
 }