Files
Scoreboard/server/internal/httpapi/dto.go
T
AskaEth 99c91f99f7 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` 两张)。
2026-09-14 14:05:48 +08:00

411 lines
16 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package httpapi
// 本文件是 REST 的 JSON 契约(camelCase,与 web/src/shared/types.ts 一一对应)。
// 数据库列是 snake_case,转换集中放在 repo.go 的扫描函数里。
type teamDTO struct {
ID int64 `json:"id"`
Code string `json:"code"`
Name string `json:"name"`
ShortName *string `json:"shortName"`
LogoPath *string `json:"logoPath"`
Color *string `json:"color"`
SortOrder int `json:"sortOrder"`
Active bool `json:"active"`
// DeletedAt 非空表示「彻底删除」(对界面不可见),行仍在库里;停用是另一回事(active = false)。
DeletedAt *string `json:"deletedAt"`
}
type athleteDTO struct {
ID int64 `json:"id"`
Name string `json:"name"`
Gender *string `json:"gender"`
TeamID int64 `json:"teamId"`
EmployeeNo *string `json:"employeeNo"`
IDCard *string `json:"idCard"`
Bib *string `json:"bib"`
Age *int `json:"age"`
Active bool `json:"active"`
}
type sportDTO struct {
ID int64 `json:"id"`
Code string `json:"code"`
Name string `json:"name"`
ShortName *string `json:"shortName"`
DefaultProfileID *int64 `json:"defaultProfileId"`
SortOrder int `json:"sortOrder"`
Active bool `json:"active"`
}
type categoryDTO struct {
ID int64 `json:"id"`
EventID int64 `json:"eventId"`
Name string `json:"name"`
Multiplier float64 `json:"multiplier"`
Gender *string `json:"gender"`
AgeMin *int `json:"ageMin"`
AgeMax *int `json:"ageMax"`
SortOrder int `json:"sortOrder"`
}
type channelDTO struct {
ID int64 `json:"id"`
EventID int64 `json:"eventId"`
Scope string `json:"scope"`
Basis string `json:"basis"`
ProfileID int64 `json:"profileId"`
SortOrder int `json:"sortOrder"`
// AggregateMode 是 basis=aggregate 通道的汇总口径:avg 按成员平均 / sum 按成员总和。
// 请求体里缺省(空串)按 avg 处理,不带该字段的旧客户端保存通道时口径不变。
// 响应里只下发非缺省值(sum);缺省(avg)不下发,老数据的响应体因此一个字节都不变。
AggregateMode string `json:"aggregateMode,omitempty"`
// CountToTeam 决定该通道产出的流水是否计入单位总分;请求体里缺省(null)按 true 处理,
// 「个人+团体」项目的个人通道传 false。响应里始终是具体值。
CountToTeam *bool `json:"countToTeam"`
// CountToMedals 决定该通道产出的名次是否发奖牌;缺省(null)按 true 处理(与库中默认值一致)。
CountToMedals *bool `json:"countToMedals"`
// CountToTeamMedals 决定该通道的个人奖牌是否并入单位奖牌榜;缺省按 true 处理。
// 只对 scope=athlete 的通道有意义:scope=team 的名次本来就记在单位头上。
CountToTeamMedals *bool `json:"countToTeamMedals"`
}
type eventDTO struct {
ID int64 `json:"id"`
SportID int64 `json:"sportId"`
Code string `json:"code"`
Name string `json:"name"`
EventType string `json:"eventType"`
ResultMode string `json:"resultMode"`
ResultType string `json:"resultType"`
Compare string `json:"compare"`
RecordEligible bool `json:"recordEligible"`
Scored bool `json:"scored"`
Multiplier float64 `json:"multiplier"`
Status string `json:"status"`
ScheduledAt *string `json:"scheduledAt"`
Venue *string `json:"venue"`
SortOrder int `json:"sortOrder"`
Remark *string `json:"remark"`
AvgMode string `json:"avgMode"`
// AwardMedals 决定该小项是否结算奖牌;请求体缺省按 true 处理(与库中默认值一致)。
// 关闭后小项的名次不产生任何奖牌,积分不受影响。
AwardMedals bool `json:"awardMedals"`
Categories []categoryDTO `json:"categories,omitempty"`
Channels []channelDTO `json:"channels,omitempty"`
}
type profileRuleDTO struct {
Rank int `json:"rank"`
Points float64 `json:"points"`
}
type profileDTO struct {
ID int64 `json:"id"`
Code string `json:"code"`
Name string `json:"name"`
TieMode string `json:"tieMode"`
RecordBonusMode string `json:"recordBonusMode"`
AwardRanks int `json:"awardRanks"`
LastPlaceZero bool `json:"lastPlaceZero"`
Rules []profileRuleDTO `json:"rules"`
}
type entryDTO struct {
ID int64 `json:"id"`
EventID int64 `json:"eventId"`
CategoryID int64 `json:"categoryId"`
TeamID int64 `json:"teamId"`
// Squad 是「这个单位在本组别的第几支队」(自由文本:一队 / 二队 / 青年队)。
// 空串 = 不区分队伍:单队单位与升级前的老数据都是它,行为与升级前完全一致(见迁移 0025)。
// 只对纯团体报名(athleteId 为空)有意义:带运动员的报名按 (组别, 单位, 运动员) 唯一,
// 同一个人在同一组别不会因为 squad 而多报一次。
Squad string `json:"squad"`
AthleteID *int64 `json:"athleteId"`
MemberNames []string `json:"memberNames"`
// Athletes 是这条报名的**队员**(团队 / 对抗项目的成员运动员),读侧始终下发数组
// (空数组 = 只报单位,与升级前一致;不是 null,前端不必写两套渲染)。
// 它是人员关联(athleteId),memberNames 只是显示用的文字名单——两者可以同时存在:
// 老数据、以及「人没录档案只登记姓名」的报名就只有 memberNames。
Athletes []entryAthleteDTO `json:"athletes"`
Bib *string `json:"bib"`
Seed *string `json:"seed"`
// Heat 是录入 / 展示用的批次号,null 表示「未分批」;批次不参与算分。
Heat *int64 `json:"heat"`
Status string `json:"status"`
Remark *string `json:"remark"`
AthleteName *string `json:"athleteName,omitempty"`
TeamCode string `json:"teamCode,omitempty"`
TeamName string `json:"teamName,omitempty"`
ShortName *string `json:"shortName,omitempty"`
CategoryName string `json:"categoryName,omitempty"`
// TeamShares 是这条报名的归属份额(联队):读侧至少一条,第一条是主单位(= teamId)。
// 普通报名也下发一条独占份额,前端不必为「有没有联队」写两套渲染。
TeamShares []entryTeamShareDTO `json:"teamShares"`
}
// entryAthleteDTO 是报名上的一名**队员**(devdocs/20):团队 / 对抗项目的成员运动员。
//
// - athleteId:人员档案的 id,**唯一身份**(认人时以号码布为准,姓名会重名);
// - name / bib:展示字段(前端显示「姓名(号码布)」),写侧不需要带。
//
// 写侧(PUT /api/entries/{id}/athletes)只认 athleteId:把姓名 / 号码布认成人是导入与界面
// 的事(导入的「队员名单」列可以写号码布),服务端不在这里二次猜测。
type entryAthleteDTO struct {
AthleteID int64 `json:"athleteId"`
Name string `json:"name,omitempty"`
Bib *string `json:"bib,omitempty"`
}
// entryTeamShareDTO 是报名份额的一条(联队的一个成员单位)。
//
// - weight:积分份额,**相对权重**(缺省 1)。引擎按权重之和归一,所以 1+1 与 0.5+0.5 等价;
// 入库也就存原值,不做归一,避免 2:1 被写成 0.666…/0.333… 这种除不尽的数。
// - medal :这枚奖牌是否**整枚**记给该单位(缺省 true)。联队的金牌两个单位各记 1 枚,
// 与 weight 无关——奖牌榜数整数枚,不按积分权重拆。
// - teamCode / teamName 是读侧补的展示字段(前端拼「A+B联队」用),写侧不需要带。
type entryTeamShareDTO struct {
TeamID int64 `json:"teamId"`
Weight float64 `json:"weight"`
Medal *bool `json:"medal,omitempty"`
TeamCode string `json:"teamCode,omitempty"`
TeamName string `json:"teamName,omitempty"`
}
type entryWithResultDTO struct {
entryDTO
Result *resultDTO `json:"result"`
}
// entryHeatResultDTO 是批量设置批次的结果:本批条目当前统一的批次号(null = 未分批)。
type entryHeatResultDTO struct {
Updated int `json:"updated"`
Heat *int64 `json:"heat"`
EntryIDs []int64 `json:"entryIds"`
}
type resultDTO struct {
ID int64 `json:"id"`
EventID int64 `json:"eventId"`
EntryID int64 `json:"entryId"`
Rank *int `json:"rank"`
ResultText string `json:"resultText"`
ResultValue *float64 `json:"resultValue"`
Unit string `json:"unit"`
IsTie bool `json:"isTie"`
PointsOverride *float64 `json:"pointsOverride"`
Status string `json:"status"`
State string `json:"state"`
RecordedBy *int64 `json:"recordedBy"`
RecordedAt *string `json:"recordedAt"`
VerifiedBy *int64 `json:"verifiedBy"`
VerifiedAt *string `json:"verifiedAt"`
Note *string `json:"note"`
Points *float64 `json:"points,omitempty"`
}
type athleteStandingDTO struct {
Rank int `json:"rank"`
AthleteID int64 `json:"athleteId"`
AthleteName string `json:"athleteName"`
Gender *string `json:"gender"`
TeamID int64 `json:"teamId"`
TeamCode string `json:"teamCode"`
TeamName string `json:"teamName"`
ShortName *string `json:"shortName"`
LogoPath *string `json:"logoPath"`
TotalPoints float64 `json:"totalPoints"`
Gold int `json:"gold"`
Silver int `json:"silver"`
Bronze int `json:"bronze"`
}
type breakdownItemDTO struct {
LedgerID int64 `json:"ledgerId"`
SourceType string `json:"sourceType"`
EventID *int64 `json:"eventId"`
EventCode *string `json:"eventCode"`
EventName *string `json:"eventName"`
CategoryName *string `json:"categoryName"`
AthleteID *int64 `json:"athleteId"`
AthleteName *string `json:"athleteName"`
Rank *int `json:"rank"`
ResultText *string `json:"resultText"`
Points float64 `json:"points"`
CreatedAt string `json:"createdAt"`
// 修订痕迹(口径见 internal/revisions):这条成绩发布之后被改过几次、最后一次因为什么改、什么时候。
//
// 三个字段一起看:RevisionCount 为 nil 表示**追不出来**(没有版本基线),为 0 表示追出来了、
// 确实没改过;前端只在 > 0 时显示「已修订 ×N」角标。宁可为空也不误报。
// LastRevisionReason / LastRevisedBy 都可能为 nil:现场没写原因、操作人已删号时就是空的。
RevisionCount *int `json:"revisionCount"`
LastRevisionAt *string `json:"lastRevisionAt"`
LastRevisionReason *string `json:"lastRevisionReason"`
LastRevisedBy *string `json:"lastRevisedBy"`
}
type teamBreakdownDTO struct {
TeamID int64 `json:"teamId"`
TeamCode string `json:"teamCode"`
TeamName string `json:"teamName"`
TotalPoints float64 `json:"totalPoints"`
Items []breakdownItemDTO `json:"items"`
}
type adjustmentDTO struct {
ID int64 `json:"id"`
TeamID int64 `json:"teamId"`
Delta float64 `json:"delta"`
Category string `json:"category"`
Reason string `json:"reason"`
EventID *int64 `json:"eventId"`
Voided bool `json:"voided"`
CreatedBy *int64 `json:"createdBy"`
CreatedAt string `json:"createdAt"`
}
type recordEntryDTO struct {
ID int64 `json:"id"`
EventID int64 `json:"eventId"`
Level string `json:"level"`
ResultValue float64 `json:"resultValue"`
ResultText string `json:"resultText"`
HolderName *string `json:"holderName"`
HolderTeamID *int64 `json:"holderTeamId"`
AchievedAt *string `json:"achievedAt"`
IsCurrent bool `json:"isCurrent"`
Source string `json:"source"`
}
type recordBreakDTO struct {
ID int64 `json:"id"`
EventID int64 `json:"eventId"`
EntryID int64 `json:"entryId"`
Level string `json:"level"`
ResultValue float64 `json:"resultValue"`
ResultText string `json:"resultText"`
BonusPoints float64 `json:"bonusPoints"`
State string `json:"state"`
ApprovedBy *int64 `json:"approvedBy"`
ApprovedAt *string `json:"approvedAt"`
// Note 是驳回 / 作废这条登记时写下的理由(0021 新增的列);从未被驳回的登记(含
// 老库里的历史行)为 null——空理由与「没有理由」是两回事,所以这里用指针。
Note *string `json:"note"`
}
type auditLogDTO struct {
ID int64 `json:"id"`
UserID *int64 `json:"userId"`
Action string `json:"action"`
EntityType string `json:"entityType"`
EntityID *int64 `json:"entityId"`
BeforeJSON *string `json:"beforeJson"`
AfterJSON *string `json:"afterJson"`
IP *string `json:"ip"`
RequestID *string `json:"requestId"`
CreatedAt string `json:"createdAt"`
}
type currentUserDTO struct {
ID int64 `json:"id"`
Username string `json:"username"`
DisplayName string `json:"displayName"`
Role string `json:"role"`
LastLoginAt *string `json:"lastLoginAt"`
MustChangePassword bool `json:"mustChangePassword"`
// SessionExpiresAt 是当前会话的到期时间(RFC3339 UTC),供界面显示
// 「当前会话将于 … 过期」;未登录时为 null。
SessionExpiresAt *string `json:"sessionExpiresAt"`
}
type backupResultDTO struct {
Path string `json:"path"`
CreatedAt string `json:"createdAt"`
}
// GET/PUT /api/settings 的线上结构见 internal/dto.EventSettings(与 snapshot.settings 共用)。
// ---------- 用户管理 ----------
type userListItemDTO struct {
ID int64 `json:"id"`
Username string `json:"username"`
DisplayName string `json:"displayName"`
Role string `json:"role"`
Active bool `json:"active"`
MustChangePassword bool `json:"mustChangePassword"`
LastLoginAt *string `json:"lastLoginAt"`
}
// resetPasswordResultDTO 里的 password 是唯一一次明文,落库只存哈希。
type resetPasswordResultDTO struct {
ID int64 `json:"id"`
Username string `json:"username"`
Password string `json:"password"`
Generated bool `json:"generated"`
MustChangePassword bool `json:"mustChangePassword"`
}
// ---------- 变更历史 ----------
type revisionPageDTO struct {
Items []revisionListItemDTO `json:"items"`
Total int `json:"total"`
Limit int `json:"limit"`
Offset int `json:"offset"`
}
type revisionListItemDTO struct {
ID int64 `json:"id"`
ParentID *int64 `json:"parentId"`
EventID int64 `json:"eventId"`
EventName string `json:"eventName"`
Action string `json:"action"`
ActorID *int64 `json:"actorId"`
ActorName string `json:"actorName"`
Message *string `json:"message"`
CreatedAt string `json:"createdAt"`
ChangedCount int `json:"changedCount"`
}
type revisionDetailDTO struct {
revisionListItemDTO
Snapshot []resultDTO `json:"snapshot"`
Diff revisionDiffDTO `json:"diff"`
}
type revisionDiffDTO struct {
Results []revisionResultChangeDTO `json:"results"`
Teams []revisionTeamDeltaDTO `json:"teams"`
}
type revisionResultChangeDTO struct {
ResultID int64 `json:"resultId"`
EntryID int64 `json:"entryId"`
TeamID *int64 `json:"teamId"`
Change string `json:"change"`
Fields []string `json:"fields,omitempty"`
Before *resultDTO `json:"before"`
After *resultDTO `json:"after"`
}
type revisionTeamDeltaDTO struct {
TeamID int64 `json:"teamId"`
TeamCode string `json:"teamCode"`
TeamName string `json:"teamName"`
PointsBefore float64 `json:"pointsBefore"`
PointsAfter float64 `json:"pointsAfter"`
PointsDelta float64 `json:"pointsDelta"`
ChangedResults int `json:"changedResults"`
}
// ---------- domain → DTO ----------
func nilIfEmpty(s string) *string {
if s == "" {
return nil
}
return &s
}