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/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() {