feat(import): 报名模板按「小项 × 组别」分工作表;号码布判重改认证件号;备份改原子落盘

三件事合成一次提交(其中两件都落在 handlers_config.go,无法按文件拆开):

一、分工作表报名模板(新增能力)
- 新增 GET /api/entries/template.xlsx:按当前赛事的「小项 × 组别」生成模板,
  一个小项组别一张工作表,工作表名 = <小项>@<组别>(31 字符上限、重名自动去重)。
- 导入解析器认工作表名还原小项 + 组别;若与表内列冲突则报错,不静默取其一。
- 小项名与组别名禁用 @,基础数据界面 / 规则包导入 / 服务端校验三处一并拦截。
- 单表 CSV/XLSX 导入路径不回归。

二、号码布判重(修误判)
- 旧逻辑依赖证件号本身,而证件号是可选字段 → 同一个人报多个项目会被整块拦下。
- 改为:号码布相同且证件号相同 → 判定为同一人报多项,放行;
  号码布相同且证件号都能填且不同 → 仍报错(真抢号);一方证件号为空 → 放行并给提示。
- 团体行的号码布一并纳入查重。

三、自动备份的关停与落盘(修数据安全隐患)
- export.Service 增加 Wait():StartAuto 的协程进 WaitGroup,关停时 join(10 秒上限,
  超时只记 WARN 不拖死关闭),不再在备份写到一半时退出。
- vacuumInto 改为先写 <最终名>.tmp-<随机> 再 rename,失败则删临时文件;
  Backup / SafetySnapshot / ExportProjectZip 三个调用方一并受益。
- 新增 isFinalBackupName,ListBackups / safetyCopies / KindOfBackupName 统一过滤中间文件,
  避免半截 .db 被列进备份列表、进而被「一键恢复」选中。

文档:docs/ 五份(使用手册 / 报名名单导入规范 / 升级说明 / 部署指南 / 上线检查清单)同步。
This commit is contained in:
AskaEth committed 2026-09-14 01:10:16 +08:00
1 parent b74768b7d5
commit 1b8a37ff8c
32 files changed
+3302 -233

No files matched your search

+74 -3
View File
@@ -2,6 +2,7 @@ package export
import (
"context"
"fmt"
"io"
"log/slog"
"os"
@@ -153,9 +154,19 @@ func TestStartAutoBacksUp(t *testing.T) {
seedEvent(t, db)
dir := t.TempDir()
const interval = 10 * time.Millisecond
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
NewService(nil, db, dir, 20, testLogger()).StartAuto(ctx, 10*time.Millisecond)
// 备份跑在后台协程里,而 t.TempDir 的清理是把目录整个删掉:测试一返回它就删,
// 协程此刻可能刚提交下一轮备份、正往目录里写新文件,RemoveAll 于是报
// 「unlinkat .../002: directory not empty」(本用例历史上就是这样偶发红的)。
// 清理按后进先出执行,这条比 t.TempDir 的清理注册得晚、所以先跑:
// 先取消 ctx 等协程真正停稳,t.TempDir 再去删就不会撞上还没落完的写。
t.Cleanup(func() {
cancel()
waitAutoBackupIdle(t, dir, interval)
})
NewService(nil, db, dir, 20, testLogger()).StartAuto(ctx, interval)
deadline := time.Now().Add(10 * time.Second)
for {
@@ -172,10 +183,70 @@ func TestStartAutoBacksUp(t *testing.T) {
if time.Now().After(deadline) {
t.Fatal("10 秒内未生成定时备份")
}
time.Sleep(10 * time.Millisecond)
time.Sleep(interval)
}
}
// waitAutoBackupIdle 等自动备份的后台协程停稳后再返回(供测试在删目录前调用)。
//
// Service.Wait 才是正式入口(StartAuto 起的协程都会被它 join,含已经在飞的那一轮备份);
// 这里仍然从目录上观察「还在不在写」,因为这一条不依赖 Service 内部实现,
// 能把「Wait 返回了但目录还在变」这种回归直接照出来。协程的退出本身是确定的——
// 每轮 select 都先看 ctx.Done,ctx 一取消就返回,最多再走完一轮已经在飞的备份——
// 所以「连续若干个 tick 目录都没有新文件落盘」就足以判定它已经停了。
func waitAutoBackupIdle(t *testing.T, dir string, interval time.Duration) {
t.Helper()
// 20 个 tick 的安静窗口:远大于单轮备份(这份小库几毫秒)与调度抖动,
// 又短到不至于让用例等出可感知的慢。
const quietTicks = 20
quiet := quietTicks * interval
const patience = 5 * time.Second
deadline := time.Now().Add(patience)
last := backupDirState(t, dir)
quietSince := time.Now()
for {
time.Sleep(interval)
if cur := backupDirState(t, dir); cur != last {
last, quietSince = cur, time.Now()
}
if time.Since(quietSince) >= quiet {
return
}
if time.Now().After(deadline) {
// 非 Fatal:这里用 t.Errorf 是为了不打断后面的清理(Fatal 会跳过 t.TempDir 的清理,
// 反而把残留目录留在 TMPDIR 里),用例仍然会红。
t.Errorf("自动备份协程在 %s 内都没停稳,目录 %s 仍在变化", patience, dir)
return
}
}
}
// backupDirState 给备份目录拍一张快照,用来判断「还有没有新备份在落盘」。
// 快照带上文件名、大小与修改时间:同一秒内的第 2、3 份备份只是文件名多了序号,
// 靠修改时间也能把它们与前一份区分开。
func backupDirState(t *testing.T, dir string) string {
t.Helper()
entries, err := os.ReadDir(dir)
if err != nil {
if os.IsNotExist(err) {
return ""
}
t.Fatalf("读取备份目录 %s: %v", dir, err)
}
var b strings.Builder
for _, e := range entries {
info, err := e.Info()
if err != nil {
continue
}
fmt.Fprintf(&b, "%s|%d|%d;", e.Name(), info.Size(), info.ModTime().UnixNano())
}
return b.String()
}
// 超过保留份数时删除最旧的备份。
func TestServiceRunPrunesOldBackups(t *testing.T) {
db := openEventDB(t)