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/middleware/middleware.go

@@ -194,7 +194,17 @@ func CSRF(logger *slog.Logger, next http.Handler) http.Handler {
 		// 登录是 guest 请求，拿不到 CSRF Token；跨站表单仍能把受害者登进攻击者的账号，
 		// 因此对带 Origin/Referer 的登录请求单独做同源校验。
 		if r.Method == http.MethodPost && r.URL.Path == "/api/auth/login" && !sameOrigin(r) {
-			intercept(logger, w, r, http.StatusForbidden, "FORBIDDEN", "登录请求来源校验失败，请刷新页面重试", nil)
+			// 文案必须指向真因：这条拦截最常见的场景不是「浏览器缓存了旧页面」，
+			// 而是反向代理改写了 Host（浏览器带外部域名、服务端只看到回源地址），
+			// 照旧写「请刷新页面重试」会把现场引到永远试不好的方向。
+			// detail 带上实际比对的两个值：现场照着改一行反代配置就能好。
+			source := r.Header.Get("Origin")
+			if source == "" {
+				source = r.Header.Get("Referer")
+			}
+			intercept(logger, w, r, http.StatusForbidden, "FORBIDDEN",
+				"登录请求来源校验失败：本站 Origin 与服务端收到的 Host 不一致（反向代理通常改写 Host，需让它原样透传 Host 或透传 X-Forwarded-Host 并把代理加入可信代理）",
+				map[string]any{"source": source, "host": r.Host, "forwardedHost": r.Header.Get("X-Forwarded-Host")})
 			return
 		}
 		if User(r.Context()).Role == auth.RoleGuest {
@@ -207,7 +217,10 @@ func CSRF(logger *slog.Logger, next http.Handler) http.Handler {
 			cookie = c.Value
 		}
 		if !auth.ValidCSRF(r.Header.Get("X-CSRF-Token"), cookie) {
-			intercept(logger, w, r, http.StatusForbidden, "FORBIDDEN", "CSRF 校验失败，请刷新页面重试", nil)
+			// 「请刷新页面重试」是错的：页面加载走的是 /auth/me，而它此前不会补发丢失的 CSRF Cookie，
+			// 刷新一百次也还是 403。当前唯一有效的自愈路径是退出后重新登录（登录会重新下发两枚 Cookie）。
+			// 配套修复见 internal/httpapi/handlers_config.go 的 me：缺票时补发一枚新的。
+			intercept(logger, w, r, http.StatusForbidden, "FORBIDDEN", "CSRF 校验失败，请退出后重新登录", nil)
 			return
 		}
 		next.ServeHTTP(w, r)
@@ -216,6 +229,23 @@ func CSRF(logger *slog.Logger, next http.Handler) http.Handler {
 
 // sameOrigin 判断请求是否来自本站。浏览器跨站 POST 一定带 Origin（或 Referer），
 // 两个头都没有时（curl、非浏览器客户端）放行，避免误伤脚本调用。
+//
+// 反代改写 Host 的部署（nginx `proxy_set_header Host 127.0.0.1:19540;`）下，浏览器带的 Origin 是
+// 外部域名、r.Host 是回源地址，两者永远不相等 → 所有人登录 403。这里在直连对端命中可信代理时，
+// 额外采信 X-Forwarded-Host（代理透传的原 Host）。
+//
+// 为什么这不等于「把同源校验放水到任意 Origin」：
+//  1. Origin 由浏览器自动生成，跨站页面改不了它——攻击者页面发来的请求，Origin 仍是攻击者的域名；
+//  2. X-Forwarded-Host 同样只有代理或非浏览器客户端能设：跨站 fetch/XHR 带自定义头会触发预检，
+//     本服务不返回任何 Access-Control-* 头，预检必失败；HTML 表单压根设不了自定义头；
+//  3. 能自行编造任意请求头的客户端（curl / 脚本）本来就没有受害者的 Cookie，CSRF 对它不成立，
+//     给它放宽不改变任何安全结论；
+//  4. 还要求直连对端在可信代理白名单里（与 ClientIP 同口径），挡住「绕过代理直连、自己塞头」的路径；
+//  5. 采信的值仍必须与 Origin 相等，不是无条件放行——校验的本质（Origin 属于本站）没有变，
+//     只是「本站」由 r.Host 一个候选变成 r.Host 或代理声明的原 Host。
+//
+// 保守取舍：只做全等比较，不做「忽略端口」这类归一化。
+// nginx 的 $host 会去掉端口，部署在非默认端口时请用 `X-Forwarded-Host $http_host`。
 func sameOrigin(r *http.Request) bool {
 	raw := r.Header.Get("Origin")
 	if raw == "" {
@@ -228,7 +258,15 @@ func sameOrigin(r *http.Request) bool {
 	if err != nil || parsed.Host == "" {
 		return false
 	}
-	return strings.EqualFold(parsed.Host, r.Host)
+	if strings.EqualFold(parsed.Host, r.Host) {
+		return true
+	}
+	if !isTrustedProxy(net.ParseIP(remoteHost(r.RemoteAddr))) {
+		return false
+	}
+	// 多值时取第一个：代理链上离客户端最近的那一跳写的才是浏览器真正用过的 Host。
+	forwarded := strings.TrimSpace(strings.Split(r.Header.Get("X-Forwarded-Host"), ",")[0])
+	return forwarded != "" && strings.EqualFold(parsed.Host, forwarded)
 }
 
 // RateLimitWrite 对已登录用户的写操作限流。

server/internal/middleware/proxy_origin_test.go

@@ -0,0 +1,121 @@
+package middleware
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"git.yeij.top/AskaEth/Scoreboard/server/internal/auth"
+)
+
+// withTrustedProxy 临时配置可信代理；可信代理是包级全局变量，测试结束必须恢复原状。
+func withTrustedProxy(t *testing.T, entries ...string) {
+	t.Helper()
+	t.Cleanup(func() { _ = SetTrustedProxies(nil) })
+	if err := SetTrustedProxies(entries); err != nil {
+		t.Fatalf("配置可信代理: %v", err)
+	}
+}
+
+// 反代改写 Host 的部署里，浏览器带的 Origin 是外部域名、r.Host 是回源地址，
+// 直连对端命中可信代理时采信它透传的原 Host（X-Forwarded-Host）。
+func TestSameOriginAcceptsForwardedHostFromTrustedProxy(t *testing.T) {
+	withTrustedProxy(t, "10.0.0.0/8")
+
+	req := httptest.NewRequest(http.MethodPost, "/api/auth/login", nil)
+	req.RemoteAddr = "10.0.0.7:51234" // 直连对端 = 可信代理
+	req.Host = "127.0.0.1:19540"      // 代理改写了 Host
+	req.Header.Set("Origin", "http://scoreboard.local")
+	req.Header.Set("X-Forwarded-Host", "scoreboard.local")
+	if !sameOrigin(req) {
+		t.Fatal("可信代理透传的原 Host 与 Origin 一致时应放行")
+	}
+
+	// 多值时只认第一个：代理链上离客户端最近的那一跳写的才是浏览器用过的 Host。
+	req.Header.Set("X-Forwarded-Host", "scoreboard.local, inner.local")
+	if !sameOrigin(req) {
+		t.Fatal("多值 X-Forwarded-Host 应取第一个比较")
+	}
+
+	// 放行的只是「代理透传的原 Host」，不是任意 Origin：跨站 Origin 仍然拦下。
+	req.Header.Set("Origin", "http://evil.example")
+	if sameOrigin(req) {
+		t.Fatal("跨站 Origin 必须被拒（同源校验没有被放水成任意 Origin）")
+	}
+
+	// 代理没透传原 Host 时，Host 与 Origin 不一致依旧拦下——
+	// 这正是「代理只改了 Host、既没透传 Host 也没透传 X-Forwarded-Host」的现场，
+	// 修法在代理一侧（proxy_set_header Host $host），服务端不猜。
+	req.Header.Set("Origin", "http://scoreboard.local")
+	req.Header.Set("X-Forwarded-Host", "")
+	if sameOrigin(req) {
+		t.Fatal("没有原 Host 可比时不能放行")
+	}
+}
+
+// 直连对端不在可信代理白名单时，X-Forwarded-Host 一律不采信——代理头是客户端可伪造的，
+// 与 ClientIP 同口径（只有可信代理的转发头才作数）。
+func TestSameOriginIgnoresForwardedHostFromUntrustedPeer(t *testing.T) {
+	req := httptest.NewRequest(http.MethodPost, "/api/auth/login", nil)
+	req.RemoteAddr = "203.0.113.9:5000" // 公网直连，不在白名单
+	req.Host = "127.0.0.1:19540"
+	req.Header.Set("Origin", "http://scoreboard.local")
+	req.Header.Set("X-Forwarded-Host", "scoreboard.local")
+	if sameOrigin(req) {
+		t.Fatal("不可信对端塞进来的 X-Forwarded-Host 不能放行")
+	}
+
+	// 真·同源（Host 就等于 Origin）不受影响，照常放行。
+	req.Host = "scoreboard.local"
+	if !sameOrigin(req) {
+		t.Fatal("Host 与 Origin 一致时应放行")
+	}
+}
+
+// 登录来源校验的提示不能再指向「刷新页面」：真因多半是反代改写 Host，
+// 文案必须把现场引到代理配置上（错误方向的提示会让人反复刷新）。
+func TestLoginOriginFailureMessagePointsAtProxy(t *testing.T) {
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })
+	h := CSRF(nil, next)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/auth/login", nil)
+	req.Host = "127.0.0.1:19540"
+	req.Header.Set("Origin", "http://scoreboard.local")
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("Host 与 Origin 不一致应 403，得到 %d", rec.Code)
+	}
+	body := rec.Body.String()
+	if strings.Contains(body, "刷新页面") {
+		t.Fatalf("提示不该再指向「刷新页面」：%s", body)
+	}
+	if !strings.Contains(body, "Host") || !strings.Contains(body, "X-Forwarded-Host") {
+		t.Fatalf("提示应说明是 Host 与 Origin 不一致以及代理怎么改：%s", body)
+	}
+}
+
+// CSRF 校验失败时刷新页面补不回丢失的 Cookie，提示必须指向唯一有效的自愈路径：退出后重新登录。
+func TestCSRFFailureMessagePointsAtRelogin(t *testing.T) {
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })
+	h := CSRF(nil, next)
+
+	req := httptest.NewRequest(http.MethodPut, "/api/teams/1", nil)
+	req = req.WithContext(WithUser(req.Context(),
+		&auth.User{ID: 1, Username: "recorder", Role: auth.RoleRecorder}))
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("缺 CSRF 头的写请求应 403，得到 %d", rec.Code)
+	}
+	body := rec.Body.String()
+	if strings.Contains(body, "刷新页面") {
+		t.Fatalf("提示不该再指向「刷新页面」（刷新走的是 /auth/me，补不回 Cookie）：%s", body)
+	}
+	if !strings.Contains(body, "请退出后重新登录") {
+		t.Fatalf("提示应指向「退出后重新登录」：%s", body)
+	}
+}

server/internal/middleware/recover_test.go

@@ -0,0 +1,145 @@
+package middleware
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"git.yeij.top/AskaEth/Scoreboard/server/internal/logging"
+)
+
+// panicOnce 第一次请求 panic，之后正常应答：这样一条链既能验「panic 被兜住」，
+// 又能验「兜住之后同一条链照常服务」（panic 没有被吞成静默死循环、也没有把进程带走）。
+func panicOnce(secret string) http.Handler {
+	var hits int
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		hits++
+		if hits == 1 {
+			panic(secret)
+		}
+		w.Header().Set("Content-Type", "application/json; charset=utf-8")
+		_, _ = w.Write([]byte(`{"ok":true}`))
+	})
+}
+
+// internalErrorBody 是 500 响应的形状：与 httpapi 的统一错误体同构
+// （writeError 与 httpapi.writeAPIError 是两份实现，形状必须对得上，前端只按一种解）。
+type internalErrorBody struct {
+	OK    bool `json:"ok"`
+	Error struct {
+		Code    string          `json:"code"`
+		Message string          `json:"message"`
+		Detail  json.RawMessage `json:"detail"`
+	} `json:"error"`
+}
+
+// 全仓此前没有任何「让 handler panic」的用例：Recover 写错状态码、写成 200、
+// 把 panic 原文（含栈、含内部数据）回给客户端，都没有东西会红。
+func TestRecoverReturnsInternalErrorAndKeepsServing(t *testing.T) {
+	const secret = "重算名次时下标越界：athleteID=8848"
+	chain := RequestID(Recover(slog.New(slog.NewTextHandler(io.Discard, nil)))(panicOnce(secret)))
+
+	rec := httptest.NewRecorder()
+	chain.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/standings", nil))
+
+	if rec.Code != http.StatusInternalServerError {
+		t.Fatalf("panic 应回 500，得到 %d（body %s）", rec.Code, rec.Body.String())
+	}
+	if ct := rec.Header().Get("Content-Type"); ct != "application/json; charset=utf-8" {
+		t.Fatalf("500 的 Content-Type 应为 application/json; charset=utf-8，得到 %q", ct)
+	}
+	// 响应体必须是一份完整、可解析的统一错误体：半截 JSON 会让前端把它当网络错误。
+	var body internalErrorBody
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("500 响应体应为完整 JSON: %v\n%s", err, rec.Body.String())
+	}
+	if body.OK {
+		t.Fatalf("500 不该是 ok:true，得到 %s", rec.Body.String())
+	}
+	if body.Error.Code != "INTERNAL" || body.Error.Message != "服务端异常" {
+		t.Fatalf("500 形状应为 code=INTERNAL / message=服务端异常，得到 %+v", body.Error)
+	}
+	if body.Error.Detail != nil {
+		t.Fatalf("panic 不该回 detail（内部细节不外泄），得到 %s", body.Error.Detail)
+	}
+	// panic 原文与栈一律不回客户端：里面常有 id、SQL、路径。
+	for _, leak := range []string{secret, "recover_test.go", "goroutine "} {
+		if strings.Contains(rec.Body.String(), leak) {
+			t.Fatalf("500 响应体泄露了 %q：%s", leak, rec.Body.String())
+		}
+	}
+
+	// 同一条链的下一个请求照常：panic 只结束这一个请求。
+	rec2 := httptest.NewRecorder()
+	chain.ServeHTTP(rec2, httptest.NewRequest(http.MethodGet, "/api/standings", nil))
+	if rec2.Code != http.StatusOK || !strings.Contains(rec2.Body.String(), `"ok":true`) {
+		t.Fatalf("panic 之后同一条链应照常服务，得到 %d %s", rec2.Code, rec2.Body.String())
+	}
+}
+
+// 日志侧：handler panic 是排查类事件，必须落 interceptions/（不是 operations/），
+// 且要带 panic 值、路径、request_id 与真实栈——只写一句「服务端异常」等于什么都没留。
+func TestRecoverLogsPanicToInterceptions(t *testing.T) {
+	const secret = "重算名次时下标越界：athleteID=8848"
+	dir := t.TempDir()
+	console := &bytes.Buffer{}
+	handler, closer := logging.New(logging.Options{
+		Dir: dir, Level: slog.LevelInfo, Console: console, MaxSizeMB: 20, KeepFiles: 10,
+	})
+	t.Cleanup(func() { _ = closer.Close() })
+
+	chain := RequestID(Recover(slog.New(handler))(panicOnce(secret)))
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/recompute", nil)
+	chain.ServeHTTP(rec, req)
+
+	inter := readLogFile(t, dir, logging.DirInterceptions)
+	for _, want := range []string{
+		`"level":"ERROR"`,
+		"请求处理 panic",
+		secret,
+		`"path":"/api/recompute"`,
+		`"requestId":"`, // 请求 id 必须能对上现场那次请求
+		`"stack":"`,
+		"recover_test.go", // 栈是这次 panic 的真实栈，不是一句占位文案
+	} {
+		if !strings.Contains(inter, want) {
+			t.Fatalf("interceptions 日志应含 %q，得到：\n%s", want, inter)
+		}
+	}
+	// request_id 不能是空串：空串等于没有追踪键。
+	if strings.Contains(inter, `"requestId":""`) {
+		t.Fatalf("panic 日志的 requestId 不该为空：\n%s", inter)
+	}
+
+	// 拦截类不落 operations/：两类日志混在一起时，「有没有被拦过」就查不出来了。
+	if ops := readLogFile(t, dir, logging.DirOperations); strings.Contains(ops, "请求处理 panic") {
+		t.Fatalf("panic 日志不该落 operations/，得到：\n%s", ops)
+	}
+	// 控制台仍要能看到（现场直接跑二进制时只有控制台）。
+	if !strings.Contains(console.String(), "请求处理 panic") {
+		t.Fatalf("控制台应看到 panic 日志，得到：\n%s", console.String())
+	}
+}
+
+// readLogFile 读某类日志今天的文件内容；文件不存在返回空串。
+func readLogFile(t *testing.T, dir, category string) string {
+	t.Helper()
+	path := filepath.Join(dir, category, category+"-"+time.Now().Format("20060102")+".log")
+	raw, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return ""
+	}
+	if err != nil {
+		t.Fatalf("读日志 %s: %v", path, err)
+	}
+	return string(raw)
+}