fix: 审查修复波次（P0x4 + P1x30+）

- domain/rules: 计分与排名解耦、破纪录按组别、tieBreak 生效、调整分不丢、移除 aggregate 假能力 - realtime: 新建 internal/dto，快照三项契约对齐，/ws 只认会话身份 - httpapi: 流水幂等、standings 整表载荷、广播接线、强制改密、XFF 防伪造、records 写入、审计、赛事包内容、发布前备份、result.points、实例列表 - web: FormData 上传、YAML 解析、快照归一化、大屏解析层、bootstrap 降级、访客判定、主题切换 - console: 优雅关闭握手、中文化、免验证改管理员账号、选屏与日志轮转修复 - docs: 用户文档三份 + README - 主代理: 破纪录加分接线（levels 未加载导致恒 0）
2026-09-09 21:06:40 +08:00
1 parent 8dae63ee70
commit 7f9701c465
@@ -0,0 +1,228 @@
+/**
+ * 规则包归一化。
+ *
+ * `GET /api/rules/export` 返回裸 YAML（服务端 rules.Marshal），这里把解析出的
+ * unknown 收敛成 shared 的 RulePack 契约：补齐缺省值、丢弃未知字段。
+ * 校验口径与服务端 rules.Canonical 对齐，避免前端拿到的规则包和实际生效规则不一致。
+ */
+
+import {
+  asRecord,
+  emptyToNull,
+  firstBool,
+  firstNumber,
+  firstNumberOrNull,
+  firstString,
+  isRecord,
+} from './internal'
+import type {
+  ChannelBasis,
+  ChannelScope,
+  ChannelTemplate,
+  EventOverride,
+  EventType,
+  RecordBonusLevel,
+  RecordBonusMode,
+  ResultType,
+  RuleChannel,
+  RulePack,
+  RulePackManualAdjustment,
+  RulePackMeta,
+  RulePackRecordBonus,
+  RulePackStandings,
+  RuleProfile,
+  ScoringProfileRule,
+  TieBreakKey,
+  TieMode,
+} from './types'
+
+const TIE_BREAK_KEYS: readonly TieBreakKey[] = [
+  'points',
+  'gold',
+  'silver',
+  'bronze',
+  'teamCode',
+  'name',
+]
+const DEFAULT_TIE_BREAK: TieBreakKey[] = ['points', 'gold', 'silver', 'bronze', 'teamCode']
+const TIE_MODES: readonly TieMode[] = ['skip', 'average', 'higher']
+const RECORD_BONUS_MODES: readonly RecordBonusMode[] = ['max', 'sum']
+const SCOPES: readonly ChannelScope[] = ['athlete', 'team']
+const BASES: readonly ChannelBasis[] = ['result', 'manual', 'aggregate']
+const EVENT_TYPES: readonly EventType[] = ['individual', 'team', 'match']
+const RESULT_TYPES: readonly ResultType[] = ['time', 'distance', 'count', 'score', 'none']
+
+export function normalizeRulePack(raw: unknown): RulePack | null {
+  if (!isRecord(raw)) return null
+  if (firstString(raw.format) !== 'scoreboard-rules') return null
+  if (firstNumber(0, raw.formatVersion) !== 1) return null
+  return {
+    format: 'scoreboard-rules',
+    formatVersion: 1,
+    meta: normalizeMeta(raw.meta),
+    standings: normalizeStandings(raw.standings),
+    profiles: normalizeProfiles(raw.profiles),
+    recordBonus: normalizeRecordBonus(raw.recordBonus),
+    manualAdjustment: normalizeManualAdjustment(raw.manualAdjustment),
+    channelTemplates: normalizeTemplates(raw.channelTemplates),
+    eventOverrides: normalizeOverrides(raw.eventOverrides),
+  }
+}
+
+function oneOf<T extends string>(value: unknown, allowed: readonly T[], fallback: T): T {
+  return typeof value === 'string' && (allowed as readonly string[]).includes(value)
+    ? (value as T)
+    : fallback
+}
+
+function optionalOneOf<T extends string>(value: unknown, allowed: readonly T[]): T | undefined {
+  return typeof value === 'string' && (allowed as readonly string[]).includes(value)
+    ? (value as T)
+    : undefined
+}
+
+function normalizeMeta(raw: unknown): RulePackMeta {
+  const rec = asRecord(raw)
+  return {
+    code: firstString(rec.code) ?? '',
+    name: firstString(rec.name) ?? '',
+    version: firstString(rec.version) ?? '',
+    updatedAt: firstString(rec.updatedAt) ?? '',
+    author: emptyToNull(firstString(rec.author)),
+    note: emptyToNull(firstString(rec.note)),
+  }
+}
+
+function normalizeStandings(raw: unknown): RulePackStandings {
+  const rec = asRecord(raw)
+  const tieBreakRaw = rec.tieBreak
+  const tieBreak = Array.isArray(tieBreakRaw)
+    ? tieBreakRaw.filter(
+        (item): item is TieBreakKey =>
+          typeof item === 'string' && (TIE_BREAK_KEYS as readonly string[]).includes(item),
+      )
+    : []
+  return {
+    individualToTeamWeight: firstNumber(1, rec.individualToTeamWeight),
+    tieBreak: tieBreak.length > 0 ? tieBreak : [...DEFAULT_TIE_BREAK],
+    medalCountsTeamEvents: firstBool(true, rec.medalCountsTeamEvents),
+    showIndividualBoard: firstBool(true, rec.showIndividualBoard),
+    showIndividualMedals: firstBool(true, rec.showIndividualMedals),
+  }
+}
+
+function normalizeProfiles(raw: unknown): RuleProfile[] {
+  if (!Array.isArray(raw)) return []
+  const out: RuleProfile[] = []
+  for (const item of raw) {
+    const rec = asRecord(item)
+    const code = firstString(rec.code)
+    if (code === null || code === '') continue
+    out.push({
+      code,
+      name: firstString(rec.name) ?? code,
+      awardRanks: firstNumber(0, rec.awardRanks),
+      lastPlaceZero: firstBool(false, rec.lastPlaceZero),
+      tieMode: oneOf(rec.tieMode, TIE_MODES, 'skip'),
+      recordBonusMode: optionalOneOf(rec.recordBonusMode, RECORD_BONUS_MODES),
+      rules: normalizeScoringRules(rec.rules),
+    })
+  }
+  return out
+}
+
+function normalizeScoringRules(raw: unknown): ScoringProfileRule[] {
+  if (!Array.isArray(raw)) return []
+  const out: ScoringProfileRule[] = []
+  for (const item of raw) {
+    const rec = asRecord(item)
+    const rank = firstNumberOrNull(rec.rank)
+    const points = firstNumberOrNull(rec.points)
+    if (rank === null || points === null) continue
+    out.push({ rank, points })
+  }
+  return out
+}
+
+function normalizeRecordBonus(raw: unknown): RulePackRecordBonus {
+  const rec = asRecord(raw)
+  return {
+    enabled: firstBool(false, rec.enabled),
+    mode: oneOf(rec.mode, RECORD_BONUS_MODES, 'max'),
+    levels: normalizeLevels(rec.levels),
+  }
+}
+
+function normalizeLevels(raw: unknown): RecordBonusLevel[] {
+  if (!Array.isArray(raw)) return []
+  const out: RecordBonusLevel[] = []
+  for (const item of raw) {
+    const rec = asRecord(item)
+    const code = firstString(rec.code)
+    if (code === null || code === '') continue
+    out.push({ code, name: firstString(rec.name) ?? code, points: firstNumber(0, rec.points) })
+  }
+  return out
+}
+
+function normalizeManualAdjustment(raw: unknown): RulePackManualAdjustment {
+  const rec = asRecord(raw)
+  return {
+    enabled: firstBool(false, rec.enabled),
+    reasonRequired: firstBool(true, rec.reasonRequired),
+  }
+}
+
+function normalizeTemplates(raw: unknown): ChannelTemplate[] {
+  if (!Array.isArray(raw)) return []
+  return raw.map((item) => {
+    const rec = asRecord(item)
+    const match = asRecord(rec.match)
+    return {
+      match: {
+        eventType: optionalOneOf(match.eventType, EVENT_TYPES),
+        resultType: optionalOneOf(match.resultType, RESULT_TYPES),
+        sportCode: firstString(match.sportCode) ?? undefined,
+      },
+      channels: normalizeChannels(rec.channels),
+    }
+  })
+}
+
+function normalizeOverrides(raw: unknown): EventOverride[] {
+  if (!Array.isArray(raw)) return []
+  const out: EventOverride[] = []
+  for (const item of raw) {
+    const rec = asRecord(item)
+    const eventCode = firstString(rec.eventCode)
+    if (eventCode === null || eventCode === '') continue
+    const override: EventOverride = { eventCode }
+    const name = firstString(rec.name)
+    if (name !== null) override.name = name
+    if (typeof rec.scored === 'boolean') override.scored = rec.scored
+    const multiplier = firstNumberOrNull(rec.multiplier)
+    if (multiplier !== null) override.multiplier = multiplier
+    if (Array.isArray(rec.channels)) override.channels = normalizeChannels(rec.channels)
+    out.push(override)
+  }
+  return out
+}
+
+function normalizeChannels(raw: unknown): RuleChannel[] {
+  if (!Array.isArray(raw)) return []
+  const out: RuleChannel[] = []
+  for (const item of raw) {
+    const rec = asRecord(item)
+    const profile = firstString(rec.profile)
+    if (profile === null || profile === '') continue
+    const channel: RuleChannel = {
+      scope: oneOf(rec.scope, SCOPES, 'athlete'),
+      basis: oneOf(rec.basis, BASES, 'result'),
+      profile,
+    }
+    const aggregate = firstString(rec.aggregate)
+    if (aggregate !== null && aggregate !== '') channel.aggregate = aggregate
+    out.push(channel)
+  }
+  return out
+}