Scoreboard/server/internal/domain/scoring.go

package domain

import (
	"fmt"
	"math"
	"sort"
)

// rankEpsilon 用于判定「成绩相同」。计时/测距保留两位小数，1e-9 足够区分。
const rankEpsilon = 1e-9

// ScoreOptions 控制引擎的可选行为；零值即本次运动会的口径。
type ScoreOptions struct {
	// IncludeDrafts 为 true 时草稿成绩也参与计分；默认只算已发布（草稿不上屏也不计分）。
	IncludeDrafts bool
}

// EventScoreInput 是一次小项（某组别）计分的全部输入，引擎只读不改。
type EventScoreInput struct {
	Event        Event
	Category     EventCategory
	Channels     []ScoreChannel
	Profiles     map[int64]ScoringProfile
	Entries      []Entry
	Results      []Result
	RecordBonus  *RecordBonusConfig
	RecordBreaks []RecordBreak
	// TeamRanks 是按单位录入的团体名次，只有 scope=team + basis=manual 的通道读它。
	// 与「团体报名项（athlete_id=0）的 results.rank」共同构成团体名次的全部来源。
	TeamRanks []TeamManualRank
	Options   ScoreOptions
}

// EventScore 是一次小项计分的结果。
type EventScore struct {
	Ledger []LedgerEntry
	Ranked []RankedResult
}

// RankedResult 记录「某条报名项在某通道下拿到的名次与原始积分」。
// Points 尚未乘个人→单位系数，因此可直接用于奖牌判定与分项成绩表。
// Shares 是该名次的归属单位；当前只有「整体归主单位」一种口径（联队未实现），
// 保留份额结构是因为导出 / 实时快照等消费方按份额遍历。
type RankedResult struct {
	EntryID     int64
	ResultID    int64
	EventID     int64
	CategoryID  int64
	ChannelID   int64
	Scope       Scope
	Basis       Basis
	AthleteID   int64
	AthleteName string
	TeamID      int64
	Shares      []TeamShare
	Rank        int
	Points      float64
	ResultValue *float64
	Status      ResultStatus
	// SubjectKey 是这条名次的主体标识：名次按 (通道, 组别, 主体) 唯一，
	// 取值 'e:<entryId>' / 'a:<athleteId>' / 't:<teamId>'，三者都是 0 时退化为 'ch:<channelId>'。
	// 聚合与团体手工名次没有单条报名项，靠它才能唯一落库。
	SubjectKey string
	// 下面三个开关随名次一起携带，榜单侧（standings.go）不必回查库就能算出奖牌：
	// 小项是否结算奖牌、通道是否发牌、个人奖牌是否并入单位奖牌榜。
	AwardMedals       bool
	CountToMedals     bool
	CountToTeamMedals bool
}

// ScoreEvent 按项目的计分通道逐条计算名次与积分，输出流水与名次明细。
// 计分与排名解耦：项目 scored=false 或没有通道时照样产出名次（Points=0），只是不写流水。
// 没有通道时按小项自身的录入方式（result_mode）推导排名口径，见 rankOnlyChannel。
func ScoreEvent(in EventScoreInput) (EventScore, error) {
	// 引擎不读取 pointsOverride，静默忽略等于「设置成功但毫无效果」；
	// 显式报错把问题暴露在计分环节，写入侧另有 400 拦截，两道都不放行。
	for _, r := range in.Results {
		if r.PointsOverride != nil {
			return EventScore{}, fmt.Errorf("%w: 成绩 %d（报名项 %d）", ErrPointsOverrideUnsupported, r.ID, r.EntryID)
		}
	}
	var out EventScore
	rankOnly := len(in.Channels) == 0
	// 只排名不计分：scored=false 或没有计分通道时都不产出任何流水（含破纪录加分）。
	scoreEnabled := in.Event.Scored && !rankOnly

	channels := sortedChannels(in.Channels)
	if rankOnly {
		channels = []ScoreChannel{rankOnlyChannel(in)}
	}

	for _, ch := range channels {
		// 不计分时不需要积分表：既不查模板，也不可能算出非零分。
		profile := ScoringProfile{}
		if scoreEnabled {
			p, ok := in.Profiles[ch.ProfileID]
			if !ok {
				return EventScore{}, fmt.Errorf("%w: 通道 %d 引用模板 %d", ErrProfileNotFound, ch.ID, ch.ProfileID)
			}
			profile = p
		}
		ranked, err := scoreChannel(in, ch, profile)
		if err != nil {
			return EventScore{}, err
		}
		if !scoreEnabled {
			for i := range ranked {
				ranked[i].Points = 0
			}
		}
		out.Ranked = append(out.Ranked, ranked...)
		if scoreEnabled {
			out.Ledger = append(out.Ledger, ledgerFromRanked(in, ch, ranked)...)
		}
	}

	if !scoreEnabled {
		return out, nil
	}
	bonus, err := recordBonusLedger(in)
	if err != nil {
		return EventScore{}, err
	}
	out.Ledger = append(out.Ledger, bonus...)
	return out, nil
}

// rankOnlyChannel 在没有计分通道时，按小项自身的录入方式推导排名口径：
// manual 直接录名次，其余按成绩自动排名；名次记给个人，团体/对抗项目记给单位。
// 「个人+团体」的双计靠两条通道表达，这条退化路径只排个人榜，故不入单位分支。
func rankOnlyChannel(in EventScoreInput) ScoreChannel {
	basis := BasisResult
	if in.Event.ResultMode == ResultModeManual {
		basis = BasisManual
	}
	scope := ScopeAthlete
	if in.Event.EventType == EventTypeTeam || in.Event.EventType == EventTypeMatch {
		scope = ScopeTeam
	}
	return ScoreChannel{EventID: in.Event.ID, Scope: scope, Basis: basis}
}

// sortedChannels 固定通道处理顺序，保证同一份输入每次产出同样的流水顺序。
func sortedChannels(channels []ScoreChannel) []ScoreChannel {
	out := append([]ScoreChannel(nil), channels...)
	sort.SliceStable(out, func(i, j int) bool {
		if out[i].SortOrder != out[j].SortOrder {
			return out[i].SortOrder < out[j].SortOrder
		}
		return out[i].ID < out[j].ID
	})
	return out
}

func scoreChannel(in EventScoreInput, ch ScoreChannel, profile ScoringProfile) ([]RankedResult, error) {
	switch ch.Basis {
	case BasisResult:
		return scoreByResult(in, ch, profile)
	case BasisManual:
		return scoreByManual(in, ch, profile)
	case BasisAggregate:
		return scoreByAggregate(in, ch, profile)
	default:
		return nil, fmt.Errorf("%w: %q", ErrUnknownBasis, ch.Basis)
	}
}

// candidate 是排名过程的中间态：一条可参与排名的报名项 + 它的比较值。
type candidate struct {
	entry   Entry
	result  Result
	subject int64   // 聚合通道的排名主体（单位或运动员）
	value   float64 // 排序用比较值
	rankIn  int     // manual 通道录入的名次
}

// entryMatches 判断报名项是否属于本次计分的小项与组别。
func entryMatches(in EventScoreInput, e Entry) bool {
	if in.Event.ID != 0 && e.EventID != 0 && e.EventID != in.Event.ID {
		return false
	}
	if in.Category.ID != 0 && e.CategoryID != in.Category.ID {
		return false
	}
	return true
}

// collectCandidates 过滤出本通道真正参与排名的报名项：
// 只取已发布、状态正常、且带有本通道所需数据的成绩。聚合通道不用本函数，见 scoreByAggregate。
// scope=team + basis=manual 的候选来源与其它通道不同（P0 的修法），转给 collectTeamManualCandidates。
func collectCandidates(in EventScoreInput, ch ScoreChannel) ([]candidate, error) {
	if ch.Basis == BasisResult && in.Event.Compare == CompareNone {
		return nil, ErrCompareRequired
	}
	if ch.Basis == BasisManual && ch.Scope == ScopeTeam {
		return collectTeamManualCandidates(in, ch), nil
	}

	byEntry := make(map[int64]Result, len(in.Results))
	for _, r := range in.Results {
		byEntry[r.EntryID] = r
	}

	out := make([]candidate, 0, len(in.Entries))
	for _, e := range in.Entries {
		if !entryMatches(in, e) {
			continue
		}
		if !e.Status.rankable() {
			continue
		}
		r, ok := byEntry[e.ID]
		if !ok {
			continue
		}
		if r.State == ResultStateDraft && !in.Options.IncludeDrafts {
			continue
		}
		if !r.Status.rankable() {
			continue
		}

		c := candidate{entry: e, result: r}
		switch ch.Basis {
		case BasisManual:
			if r.Rank <= 0 {
				continue
			}
			c.rankIn = r.Rank
		default: // result 按成绩值排序
			if r.ResultValue == nil {
				continue
			}
			c.value = *r.ResultValue
		}
		out = append(out, c)
	}
	return out, nil
}

// collectTeamManualCandidates 是 scope=team + basis=manual 的候选来源，只有两处：
//  1. in.TeamRanks（按单位录入的团体名次）：没有对应的报名项，用合成 Entry{TeamID: id} 承载；
//  2. 兜底：团体报名项（athlete_id == 0）的 results.rank，纯团体项目（篮球等）沿用原录入流程。
//
// 同一单位两个来源都有时以 TeamRanks 为准；rank <= 0 的团体名次视为未填 / 清空，直接忽略。
// 个人报名项（athlete_id != 0）的名次是个人名次，绝不进团体通道——否则双通道项目
// 第 2 次发布时会把刚写回 results.rank 的个人名次当成团体名次再发一次分（P0）。
func collectTeamManualCandidates(in EventScoreInput, ch ScoreChannel) []candidate {
	type manualRank struct {
		teamID int64
		rank   int
	}
	overrides := make([]manualRank, 0, len(in.TeamRanks))
	overrideOf := make(map[int64]int, len(in.TeamRanks))
	for _, tr := range in.TeamRanks {
		if tr.TeamID == 0 || tr.Rank <= 0 {
			continue
		}
		if _, dup := overrideOf[tr.TeamID]; dup {
			continue
		}
		overrideOf[tr.TeamID] = tr.Rank
		overrides = append(overrides, manualRank{teamID: tr.TeamID, rank: tr.Rank})
	}

	byEntry := make(map[int64]Result, len(in.Results))
	for _, r := range in.Results {
		byEntry[r.EntryID] = r
	}

	out := make([]candidate, 0, len(in.Entries)+len(overrides))
	taken := make(map[int64]bool, len(overrides))
	for _, e := range in.Entries {
		if !entryMatches(in, e) || e.AthleteID != 0 || !e.Status.rankable() {
			continue
		}
		r, ok := byEntry[e.ID]
		if !ok {
			continue
		}
		if r.State == ResultStateDraft && !in.Options.IncludeDrafts {
			continue
		}
		if !r.Status.rankable() || r.Rank <= 0 {
			continue
		}
		rankIn := r.Rank
		if rank, ok := overrideOf[e.TeamID]; ok {
			rankIn = rank
		}
		taken[e.TeamID] = true
		out = append(out, candidate{entry: e, result: r, rankIn: rankIn})
	}
	for _, or := range overrides {
		if taken[or.teamID] {
			continue
		}
		// 合成报名项：ID=0 表示「不对应任何一条报名项」，团体名次的主体是单位。
		out = append(out, candidate{
			entry:  Entry{TeamID: or.teamID},
			rankIn: or.rank,
		})
	}
	return out
}

func scoreByResult(in EventScoreInput, ch ScoreChannel, profile ScoringProfile) ([]RankedResult, error) {
	cands, err := collectCandidates(in, ch)
	if err != nil {
		return nil, err
	}
	sortCandidatesByValue(cands, in.Event.Compare)
	return rankGroups(in, ch, profile, groupByValue(cands)), nil
}

func scoreByManual(in EventScoreInput, ch ScoreChannel, profile ScoringProfile) ([]RankedResult, error) {
	cands, err := collectCandidates(in, ch)
	if err != nil {
		return nil, err
	}
	sort.SliceStable(cands, func(i, j int) bool {
		if cands[i].rankIn != cands[j].rankIn {
			return cands[i].rankIn < cands[j].rankIn
		}
		return cands[i].entry.ID < cands[j].entry.ID
	})
	return rankGroups(in, ch, profile, groupByManualRank(cands)), nil
}

// tieGroup 是一组并列的参赛者；startRank 是它们共同展示的名次。
type tieGroup struct {
	startRank int
	members   []candidate
}

// groupByValue 按成绩值分组：值相同即并列，名次按「占位顺推」计算（skip 口径）。
func groupByValue(cands []candidate) []tieGroup {
	var groups []tieGroup
	pos := 1
	for i := 0; i < len(cands); {
		j := i + 1
		for j < len(cands) && nearlyEqual(cands[j].value, cands[i].value) {
			j++
		}
		groups = append(groups, tieGroup{startRank: pos, members: cands[i:j]})
		pos += j - i
		i = j
	}
	return groups
}

// groupByManualRank 按录入名次分组：录入名次就是展示名次，不做顺推改写。
func groupByManualRank(cands []candidate) []tieGroup {
	var groups []tieGroup
	for i := 0; i < len(cands); {
		j := i + 1
		for j < len(cands) && cands[j].rankIn == cands[i].rankIn {
			j++
		}
		groups = append(groups, tieGroup{startRank: cands[i].rankIn, members: cands[i:j]})
		i = j
	}
	return groups
}

// rankGroups 给每组分配积分并产出名次明细。
func rankGroups(in EventScoreInput, ch ScoreChannel, profile ScoringProfile, groups []tieGroup) []RankedResult {
	lastRank := 0
	for _, g := range groups {
		if r := g.startRank + len(g.members) - 1; r > lastRank {
			lastRank = r
		}
	}

	var out []RankedResult
	for _, g := range groups {
		pts := groupPoints(profile, g.startRank, len(g.members), lastRank, in.Event, in.Category)
		for _, c := range g.members {
			out = append(out, rankedResult(in, ch, c, g.startRank, pts))
		}
	}
	return out
}

// groupPoints 计算一组并列者拿到的分。
// 三种口径都先确定这组「占用了哪些名次」：startRank .. startRank+size-1。
func groupPoints(profile ScoringProfile, startRank, size, lastRank int, ev Event, cat EventCategory) float64 {
	if startRank <= 0 || size <= 0 {
		return 0
	}
	// lastPlaceZero 是对「最后一名」的覆盖；并列在末位的整组都按最后一名处理，
	// 否则同组出现 0 与 1 两种分数，违背「并列同分」的语义。
	if profile.LastPlaceZero && startRank <= lastRank && lastRank <= startRank+size-1 {
		return 0
	}

	switch profile.tieMode() {
	case TieAverage:
		var sum float64
		for r := startRank; r < startRank+size; r++ {
			p, _ := basePoints(profile, r, ev, cat)
			sum += p
		}
		return sum / float64(size)
	case TieHigher:
		best := 0.0
		for r := startRank; r < startRank+size; r++ {
			if p, ok := basePoints(profile, r, ev, cat); ok && p > best {
				best = p
			}
		}
		return best
	default: // TieSkip
		p, _ := basePoints(profile, startRank, ev, cat)
		return p
	}
}

// basePoints 查表得分并乘项目权重、组别权重；超出录取名次或表中无名次一律 0。
func basePoints(profile ScoringProfile, rank int, ev Event, cat EventCategory) (float64, bool) {
	if rank <= 0 {
		return 0, false
	}
	if profile.AwardRanks > 0 && rank > profile.AwardRanks {
		return 0, false
	}
	p, ok := profile.pointsAt(rank)
	if !ok {
		return 0, false
	}
	return p * ev.multiplier() * cat.multiplier(), true
}

func rankedResult(in EventScoreInput, ch ScoreChannel, c candidate, rank int, points float64) RankedResult {
	rr := RankedResult{
		EntryID:     c.entry.ID,
		ResultID:    c.result.ID,
		EventID:     in.Event.ID,
		CategoryID:  in.Category.ID,
		ChannelID:   ch.ID,
		Scope:       ch.Scope,
		Basis:       ch.Basis,
		AthleteID:   c.entry.AthleteID,
		AthleteName: c.entry.AthleteName,
		TeamID:      c.entry.primaryTeamID(),
		Shares:      wholeShare(c.entry.primaryTeamID()),
		Rank:        rank,
		Points:      points,
		Status:      c.result.Status,
	}
	rr.SubjectKey = subjectKeyOf(rr)
	rr.AwardMedals = in.Event.AwardMedals
	rr.CountToMedals = ch.CountsToMedals()
	rr.CountToTeamMedals = ch.CountsToTeamMedals()
	if c.result.ResultValue != nil {
		v := *c.result.ResultValue
		rr.ResultValue = &v
	}
	return rr
}

// scoreByAggregate 实现 basis=aggregate：把同一主体（单位/运动员）在本组别的成绩取平均，
// 得到团体成绩后按项目的 compare 方向排名（并列沿用模板的 tieMode，默认顺延）。
// 平均值分母由项目的 avg_mode 决定：
//   - valid：分子 = 有效成绩之和，分母 = 有有效成绩的人数；一个人都没成绩就不参与排名、不得分；
//   - all：分子 = 有效成绩之和（没成绩的按 0），分母 = 该主体的报名人数。
//     没有报名项的主体不会成桶，自然不参与。
//
// 弃权 / 失格（status 非 registered）的报名项既不算参与也不算进分母，与「不占名次」的既有口径一致。
func scoreByAggregate(in EventScoreInput, ch ScoreChannel, profile ScoringProfile) ([]RankedResult, error) {
	if in.Event.Compare == CompareNone {
		return nil, ErrCompareRequired
	}

	byEntry := make(map[int64]Result, len(in.Results))
	for _, r := range in.Results {
		byEntry[r.EntryID] = r
	}

	type bucket struct {
		subject int64
		entry   Entry
		sum     float64 // 有效成绩之和
		valid   int     // 有有效成绩的人数（valid 口径的分母）
		roster  int     // 报名人数（all 口径的分母）
	}
	order := make([]int64, 0)
	buckets := make(map[int64]*bucket)
	for _, e := range in.Entries {
		if !entryMatches(in, e) || !e.Status.rankable() {
			continue
		}
		subject := e.TeamID
		if ch.Scope == ScopeAthlete {
			subject = e.AthleteID
		}
		if subject == 0 {
			continue
		}
		b, ok := buckets[subject]
		if !ok {
			b = &bucket{subject: subject, entry: e}
			buckets[subject] = b
			order = append(order, subject)
		}
		b.roster++
		r, found := byEntry[e.ID]
		if v, ok := validResultValue(r, found, in.Options); ok {
			b.sum += v
			b.valid++
		}
	}
	agg := make([]candidate, 0, len(order))
	for _, id := range order {
		b := buckets[id]
		var value float64
		if in.Event.avgMode() == AvgModeAll {
			// 分母 = 报名人数：没成绩的人按 0 计入，也就是只累加有效成绩之和。
			value = b.sum / float64(b.roster)
		} else {
			if b.valid == 0 {
				// 一个人都没有效成绩的单位不参与团体排名，也不得分。
				continue
			}
			value = b.sum / float64(b.valid)
		}
		c := candidate{entry: b.entry, subject: b.subject, value: value}
		c.entry.ID = 0 // 聚合结果不对应单条报名项
		agg = append(agg, c)
	}
	sortCandidatesByValue(agg, in.Event.Compare)

	groups := groupByValue(agg)
	lastRank := 0
	for _, g := range groups {
		if r := g.startRank + len(g.members) - 1; r > lastRank {
			lastRank = r
		}
	}

	var out []RankedResult
	for _, g := range groups {
		pts := groupPoints(profile, g.startRank, len(g.members), lastRank, in.Event, in.Category)
		for _, c := range g.members {
			rr := RankedResult{
				EventID:    in.Event.ID,
				CategoryID: in.Category.ID,
				ChannelID:  ch.ID,
				Scope:      ch.Scope,
				Basis:      ch.Basis,
				TeamID:     c.entry.primaryTeamID(),
				Rank:       g.startRank,
				Points:     pts,
			}
			if ch.Scope == ScopeTeam {
				rr.TeamID = c.subject
				rr.Shares = wholeShare(c.subject)
			} else {
				rr.AthleteID = c.subject
				rr.AthleteName = c.entry.AthleteName
				rr.Shares = wholeShare(c.entry.primaryTeamID())
			}
			rr.SubjectKey = subjectKeyOf(rr)
			rr.AwardMedals = in.Event.AwardMedals
			rr.CountToMedals = ch.CountsToMedals()
			rr.CountToTeamMedals = ch.CountsToTeamMedals()
			v := c.value
			rr.ResultValue = &v
			out = append(out, rr)
		}
	}
	return out, nil
}

func sortCandidatesByValue(cands []candidate, compare CompareMode) {
	sort.SliceStable(cands, func(i, j int) bool {
		if nearlyEqual(cands[i].value, cands[j].value) {
			return cands[i].entry.ID < cands[j].entry.ID
		}
		if compare == CompareDesc {
			return cands[i].value > cands[j].value
		}
		return cands[i].value < cands[j].value
	})
}

func nearlyEqual(a, b float64) bool {
	return math.Abs(a-b) <= rankEpsilon
}

// validResultValue 判断一条成绩是否算「有效成绩」：成绩存在、已发布（或允许草稿）、
// 状态正常，且有可比较的数值。聚合通道按 avg_mode 决定没成绩的人算不算进分母。
func validResultValue(r Result, found bool, opts ScoreOptions) (float64, bool) {
	if !found {
		return 0, false
	}
	if r.State == ResultStateDraft && !opts.IncludeDrafts {
		return 0, false
	}
	if !r.Status.rankable() || r.ResultValue == nil {
		return 0, false
	}
	return *r.ResultValue, true
}

// ledgerFromRanked 把名次明细转成积分流水：按通道 scope 决定记给个人还是单位；
// 0 分不产生流水，避免流水表被零分噪声撑大。
// 流水是否计入单位总分由通道的 countToTeam 决定（个人通道可以只记个人）。
//
// 团体手工名次与聚合名次没有对应的报名项与成绩（EntryID=0、ResultID=0），
// 仍要能落库：SourceType 与聚合流水一样是 result，sourceID 退化为通道 id，
// 由真实来源（通道 + 主体）唯一确定。写入侧按「EntryID=0 && ResultID=0 && source_type=result」
// 识别这类流水（httpapi 的 isAggregateLedger），按组别重算时会整项重算回填，条数不增不减。
func ledgerFromRanked(in EventScoreInput, ch ScoreChannel, ranked []RankedResult) []LedgerEntry {
	var out []LedgerEntry
	for _, rr := range ranked {
		if rr.Points == 0 {
			continue
		}
		athleteID := int64(0)
		if rr.Scope == ScopeAthlete {
			athleteID = rr.AthleteID
		}
		sourceID := rr.ResultID
		if sourceID == 0 {
			sourceID = rr.EntryID
		}
		if sourceID == 0 {
			sourceID = ch.ID
		}
		for _, s := range rr.Shares {
			pts := rr.Points * s.Weight
			if pts == 0 {
				continue
			}
			out = append(out, LedgerEntry{
				TeamID:      s.TeamID,
				AthleteID:   athleteID,
				EventID:     in.Event.ID,
				CategoryID:  in.Category.ID,
				EntryID:     rr.EntryID,
				ResultID:    rr.ResultID,
				ChannelID:   ch.ID,
				SourceType:  SourceResult,
				SourceID:    sourceID,
				Points:      pts,
				CountToTeam: ch.countToTeam(),
			})
		}
	}
	return out
}

// subjectKeyOf 计算一条名次明细的主体标识（channel_ranks.subject_key 同口径）：
// 有报名项就用报名项（个人名次按报名项去重才不会被并列拆开），否则按主体（个人 / 单位），
// 全为空时退化为通道 id，保证 (通道, 组别, 主体) 的唯一索引不会撞键。
func subjectKeyOf(rr RankedResult) string {
	switch {
	case rr.EntryID != 0:
		return fmt.Sprintf("e:%d", rr.EntryID)
	case rr.Scope == ScopeAthlete && rr.AthleteID != 0:
		return fmt.Sprintf("a:%d", rr.AthleteID)
	case rr.TeamID != 0:
		return fmt.Sprintf("t:%d", rr.TeamID)
	default:
		return fmt.Sprintf("ch:%d", rr.ChannelID)
	}
}

// wholeShare 构造「主单位独占 100%」的归属份额。联队拆分未实现，这里只产出这一种口径。
func wholeShare(teamID int64) []TeamShare {
	if teamID == 0 {
		return nil
	}
	return []TeamShare{{TeamID: teamID, Weight: 1}}
}