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

+46 -1
View File
@@ -2,6 +2,7 @@ package export
import (
"archive/zip"
"crypto/rand"
"crypto/sha256"
"database/sql"
"encoding/hex"
@@ -337,15 +338,59 @@ func SafeProjectName(name string) (string, error) {
return name, nil
}
// tmpMark 是「中间文件」在文件名里的标记:备份先写成 <最终名>.tmp-<随机>,成功后再改名。
// ListBackups / safetyCopies 靠它把这些文件挡在备份列表之外(见 isFinalBackupName)。
const tmpMark = ".tmp"
// vacuumInto 把 db 的快照写进 dst,并且**只以完整文件的形态出现在 dst 这个名字上**:
// 先写同目录的中间文件 <dst>.tmp-<随机>,VACUUM 成功后再改名过去。
//
// 不能直接写 dst。VACUUM INTO 是「先按最终名建出空文件,再往里灌页」:源库一旦被别的
// 进程/连接锁住(或有别的写入卡着),它会带着一个 0 字节的目标文件在那里等(实测),
// 进程此时退出(正常关闭 / 被 Console 杀掉 / 掉电)就在原地留下半截 .db。
// 备份目录里所有 .db 都会被 ListBackups 列出来、被「一键恢复」当作可恢复的文件选中,
// 而备份是最后一道防线——它自己不能是个坏文件。
//
// 中间文件与最终文件同目录,改名不跨文件系统;失败(含 VACUUM 中途失败)时中间文件会被删掉。
func vacuumInto(db *sql.DB, dst string) error {
tmp, err := vacuumTempPath(dst)
if err != nil {
return err
}
// VACUUM INTO 的目标是语句里的字面量,路径由本包自己生成,转义单引号即可。
stmt := "VACUUM INTO '" + strings.ReplaceAll(dst, "'", "''") + "'"
stmt := "VACUUM INTO '" + strings.ReplaceAll(tmp, "'", "''") + "'"
if _, err := db.Exec(stmt); err != nil {
// 半截的中间文件既不是备份,也不该在备份目录里攒着——删不掉不算新错误,
// 照原样回报 VACUUM 的失败(它才是操作员要看的原因)。
_ = os.Remove(tmp)
return fmt.Errorf("export: VACUUM INTO %s: %w", dst, err)
}
if err := os.Rename(tmp, dst); err != nil {
_ = os.Remove(tmp)
return fmt.Errorf("export: 提交备份文件 %s: %w", dst, err)
}
return nil
}
// vacuumTempPath 给一次 VACUUM INTO 挑一个中间文件名。
//
// 只挑名字、不建文件:VACUUM INTO 拒绝写已经存在的目标文件。随机串用来避开
// 「上一次异常退出留下的同名中间文件」与「并发的 CLI 备份(scoreboard backup)」。
func vacuumTempPath(dst string) (string, error) {
dir, base := filepath.Split(dst)
var buf [8]byte
if _, err := rand.Read(buf[:]); err != nil {
return "", fmt.Errorf("export: 生成备份中间文件名: %w", err)
}
p := filepath.Join(dir, base+tmpMark+"-"+hex.EncodeToString(buf[:]))
if _, err := os.Stat(p); err == nil {
return "", fmt.Errorf("export: 备份中间文件名 %s 已存在,请清理后重试", p)
} else if !os.IsNotExist(err) {
return "", fmt.Errorf("export: 检查备份中间文件 %s: %w", p, err)
}
return p, nil
}
func buildManifest(root string) ([]ProjectFile, error) {
var out []ProjectFile
err := filepath.WalkDir(root, func(p string, d fs.DirEntry, err error) error {