feat(entry): 团体报名「队员身份」—— 一条报名挂多个运动员,标识用号码布;版本 dev_0.5.6

## 需求(主人原话)
> 「双打我给他定义的是团队赛事,团队赛事不应该本来就是可以配置多个人的吗」
> 「把队员身份证留住,**应该是服务于整个团体报名**」

**现状问题**:界面(`EntryPicker`)**本来就能勾多个运动员**,但提交时只把姓名拼成文字
(`entrySelection.ts` 的 `input.athletes.map(a => a.name)` 存进 `entries.member_names TEXT`)→ **身份全丢**
→ 系统不知道队里坐着谁 → **所有团体/对抗项目都给不出个人分、个人奖牌,上不了个人积分榜**。

## 口径
- **运动员的唯一标识是号码布**(主人明确更正,不是证件号)。
- **每个队员各拿一份完整的个人分** —— 是「**复制**」不是「拆」(与联队 `splitSharePoints` 正好相反)。
- **个人奖牌每人各一枚**;**单位总分与单位奖牌不受影响**(由通道开关 `count_to_team` / `count_to_team_medals` 控制)。

## 一、数据
- 迁移 `0026_entry_athletes.sql`:新表 `entry_athletes(entry_id, athlete_id, sort_order)`,PK `(entry_id, athlete_id)`,两个外键都 `ON DELETE CASCADE`。
  `entries` **一个字节没动**(`member_names` 保留为显示用名单;多队唯一键 `(category_id,team_id,squad) WHERE athlete_id IS NULL` 未触碰)。
- **老数据回填(尽力而为)**:拿 `member_names` 去 `athletes` 匹配 —— **号码布优先**,其次「姓名 + 单位」且同单位同名唯一;**匹配不上留空**,不硬猜。

## 二、引擎
- `RankedResult.MemberCopy`(报名项那份 `false`、队员副本 `true`);**只在 `scope=athlete` 通道展开**(`scope=team` 与 `basis=aggregate` 不展开)。
- **单位维度不重复计算的三道锁**(本单最大的坑):
  1. 队员副本流水 `count_to_team` **恒为 false** —— 单位总分那条 SQL 第一句就跳过它,而个人榜不看这个开关;
  2. 单位奖牌仍按**报名项**去重、且报名项那份**排在最前**;
  3. 队员副本**照抄 `TeamID` 与 `Shares`**(不换单位、不另造份额 —— 联队报名尤其危险)。
  反面也测了:个人奖牌若按报名项去重会**一枚都发不出来**(被 `AthleteID=0` 那份吃掉),故改为按「报名项 + 运动员」去重。

## 三、写 / 读
- `PUT /api/entries/{id}/athletes`(recorder+、CSRF):body `{"athletes":[{"athleteId":12}],"requestId":"..."}`,**只认 athleteId**;空数组=清空;
  改完当场重算推榜。400:athleteId 缺/不存在、同一人两次、>30 人、个人报名不能挂队员。
- 读:`entryDTO.athletes: [{athleteId, name, bib}]`(**始终是数组**);`memberNames` 原样保留,**两者可并存**(没档案的人只能留文字)。

## 四、导入
- 报名表「队员名单」列现在**按号码布认人**(命中即关联,同时保留文字);⚠️ **姓名完全不做匹配**(同名会认错,而认错的分已经上了榜);匹配不上**不报错、只当文字**。
- 边界逐条有 notice/报错:跨单位号码布**照关联 + notice**(号码布是唯一标识);同格重号只关联一次 + notice;**个人行**写了号码布只留文字 + notice;**认出 >30 人整行拦下**;成功时一条汇总 notice。
- **更新路必须重算**:老表先导入、成绩已发布,之后补上号码布重传 —— 不在更新路重算就会出现「名单里有队员、榜上没有他」(删掉该条件即红)。

## 五、界面与显示
- 补报名勾的人**真正提交**(导入成功后追加 `PUT /athletes`,**只发需要变的**:勾了人的单位、以及原来有队员这次一个没勾的(发 `[]`);一个都没勾且原来也没队员的一律不发);**队员写失败单独提示**(报名本身已加入,不冒充「加入报名失败」)。
- **改队员**:录入页「运动员/队」那格的**「队员」小按钮**(只有纯团体行才有),弹窗勾选式名单;**与「成员单位与份额」是两个独立写请求**(份额管「分给哪些单位」、队员管「这条报名里有哪几个人」)。
- 显示统一写法 **`姓名(号码布)`**(导出件;大屏只写姓名与 ` / ` 分隔 —— 号码布太长会把整屏字号压下去);**没有队员关联的老数据一个字不变**;
  ⚠️ **一条报名仍只占一行**(有护栏测试钉着);`squad`(队)与 `athletes`(队员)**正交**。

## 验证
- 全量自检两轮**全绿、`EXIT=0`**:服务端 14 包 / 前端 **921 例** 0 fail / Console 68 例 0 fail。
- 各块先红后绿并留原始输出;**老数据零变化**有 golden 对拍(引擎层 / 接口层 / 导出层逐行 dump)。

## 文档
`docs/报名名单导入规范.md`(队员列语义升级,列数仍是 13)、`docs/使用手册.md`(新增 4.13 团体报名的队员)、
`docs/升级说明.md`(新增 `dev_0.5.6` 一节)。

## 版本
`dev_0.5.5` → **`dev_0.5.6`**(含数据迁移 `0026`);安装器素材同步重生成(照例只动 `brand.bmp` 两张)。
This commit is contained in:
AskaEth committed 2026-09-14 14:05:48 +08:00
1 parent 7a3e4ad365
commit 99c91f99f7
57 files changed
+4903 -94

No files matched your search

+32 -5
View File
@@ -298,9 +298,12 @@ func medalKeyOf(rr RankedResult, index int) medalKey {
return k
}
// pickMedalChannels 先按奖牌入选判据过滤,再把按通道展开的名次明细去重成「每个主体一条」:
// pickMedalChannels 先按奖牌入选判据过滤,再把按通道展开的名次明细按 keyOf 去重成「每个主体一条」:
// 只保留优先级最高的通道名次(个人通道优先),否则双通道项目一条成绩会拿两枚奖牌。
func pickMedalChannels(ranked []RankedResult, excludeTeam bool) []RankedResult {
//
// 去重键由调用方给:**单位维度按报名项**(medalKeyOf,一条报名只记一枚牌),
// **个人维度按报名项 + 运动员**(athleteMedalKeyOf,团体报名的队员各记各的)。
func pickMedalChannels(ranked []RankedResult, excludeTeam bool, keyOf func(RankedResult, int) medalKey) []RankedResult {
best := make(map[medalKey]RankedResult, len(ranked))
order := make([]medalKey, 0, len(ranked))
for i, rr := range ranked {
@@ -310,7 +313,7 @@ func pickMedalChannels(ranked []RankedResult, excludeTeam bool) []RankedResult {
if excludeTeam && rr.Scope == ScopeTeam {
continue
}
k := medalKeyOf(rr, i)
k := keyOf(rr, i)
cur, ok := best[k]
if !ok {
best[k] = rr
@@ -328,10 +331,31 @@ func pickMedalChannels(ranked []RankedResult, excludeTeam bool) []RankedResult {
return out
}
// athleteMedalKeyOf 是个人维度的奖牌去重键:在单位维度的键上再带上运动员。
//
// 团体报名的队员各有一份个人副本,它们与报名项那一份共享 entry_id——只按报名项去重的话,
// 三份会并成一条(且胜出的是排在最前的报名项那份,AthleteID=0,个人维度根本不看它),
// 队员的个人奖牌会**一枚都发不出来**。带上运动员之后:同一报名项同一运动员仍旧只记一枚
// (多通道项目不会重复发牌),不同队员各记各的。
//
// 只对「有报名项」的名次加这一维:没有报名项的聚合名次本来就用主体区分(medalKeyOf 已处理),
// 老数据的名次构不成同一个键下的多条,行为逐字节不变。
func athleteMedalKeyOf(rr RankedResult, index int) medalKey {
k := medalKeyOf(rr, index)
if k.entryID != 0 && rr.AthleteID != 0 {
k.scope, k.subject = ScopeAthlete, rr.AthleteID
}
return k
}
// teamMedals 统计单位奖牌榜。按 Shares 逐份额记牌:每个份额各记**一枚整牌**,
// 联队拿到的金牌因此两个成员单位各记 1 枚(不是各 0.5 枚,口径见 TeamShare.Medal)。
// 份额里的 Medal 显式关掉时该单位不记这枚牌(积分份额 Weight 不参与奖牌计算)。
//
// 去重按**报名项**(medalKeyOf):一条报名在同一小项同一组别只记一枚牌,而团体报名的队员
// 个人副本与报名项那一份共享 entry_id,因此**不会把单位奖牌数放大成队员人数倍**
// ——这是本单最容易错的地方,由 TestTeamEntryMembersKeepTeamDimensionByteIdentical 钉住。
//
// 两层开关(devdocs 17 §4.5):
// - 粗粒度总闸 StandingsInput.ExcludeTeamEventMedals:为 true 时团体项目的奖牌一律不进单位榜;
// - 通道开关 count_to_team_medals:scope=athlete 的通道置 false 时,它的个人奖牌不进单位榜。
@@ -339,7 +363,7 @@ func pickMedalChannels(ranked []RankedResult, excludeTeam bool) []RankedResult {
// 两者是「与」的关系;scope=team 的奖牌本来就记在单位头上,不受通道开关影响。
func teamMedals(in StandingsInput) map[int64]medalTally {
out := make(map[int64]medalTally)
for _, rr := range pickMedalChannels(in.Ranked, in.ExcludeTeamEventMedals) {
for _, rr := range pickMedalChannels(in.Ranked, in.ExcludeTeamEventMedals, medalKeyOf) {
if rr.Scope != ScopeTeam && !rr.CountToTeamMedals {
continue
}
@@ -368,9 +392,12 @@ func teamMedals(in StandingsInput) map[int64]medalTally {
// athleteMedals 只统计个人项目(scope=athlete)的奖牌;
// 通道的 count_to_team_medals 与个人榜无关,只决定这枚奖牌算不算进单位榜。
//
// 去重按**报名项 + 运动员**(athleteMedalKeyOf):团体报名的每个队员各记一枚自己的奖牌
// (他们共享同一条报名项,只按报名项去重会把队员的奖牌并成一枚、甚至一枚都不发)。
func athleteMedals(in StandingsInput) map[int64]medalTally {
out := make(map[int64]medalTally)
for _, rr := range pickMedalChannels(in.Ranked, false) {
for _, rr := range pickMedalChannels(in.Ranked, false, athleteMedalKeyOf) {
if rr.Scope != ScopeAthlete || rr.AthleteID == 0 {
continue
}