DATA CONTRACT / FOR CONTRIBUTORS & AGENTS

成绩录入与固定页面规范

先确认赛季和数据状态，再填写数据。两种模板由同一份赛季配置生成。

1. 页面与入口

用途	固定页面	读写位置
赛季入口 / 正式结算	`/s{N}/`	赛季配置、正式快照、已审核投稿自动合并
临时成绩及快照目录	`/s{N}/live/`	最新有效临时批次与历史批次链接
单批历史快照	`/s{N}/snapshots/{YYYYMMDD-HHmm}/`	不可变快照；以北京时间批次标签生成路径
阵容证据	`/s{N}/lineups/`	独立记录阵容截图时间和对应总伤
用户提交 / 后台审核	每期榜单“提交 / 补录”与受保护管理后台	审核通过后应用统一身份与最高成绩规则

2. 新一期只填写数据

在 data/season-registry.json 添加赛季、Boss、属性、弱点、北京时间开放与结束时间、状态及快照文件列表。挑战开始使用 status: provisional，得到结算证据后改为 settled。新一期不需要复制或修改 HTML 模板。

临时数据保存在 data/raid-snapshots-{批次}.json；正式数据保存为 data/raid-snapshots-s{N}-final.json。每批包含独立 ID、区服、批次标签、真实截图时间、收录/审核时间、来源及行数据。

{
  "id": "s18:qq:2026-11-01T12:00:top50:v1",
  "season": 18,
  "server": "qq",
  "snapshotAt": "2026-11-01T12:00:00+08:00",
  "observation": {
    "kind": "provisional",
    "sampleType": "leaderboard",
    "observedAt": "2026-11-01T11:58:00+08:00",
    "observedUntil": "2026-11-01T12:00:00+08:00"
  },
  "rows": [{"rank": 1, "nickname": "示例玩家", "guild": "示例公会", "damage": 12345678901}]
}

上面仅为字段示意，不代表 S18 的实际日期、Boss 或成绩。正式快照使用 observation.kind: final，时间必须对应结束后的正式结算证据。完整 schema 与命令见仓库录入运行手册。

3. 档位与身份规则

伤害填写精确正整数，不把“亿”的四舍五入展示值写回源数据。
固定六档顺序为 3%、1%、0.5%、Top200、Top50、第一名。没有依据的数字留空。
个人截图的百分比是显示值。3.08% 只能登记为 3% 附近样本，不能改写为精确 3% 边界。
同区服的明确 UID 优先关联；昵称可以更新，历史成绩仍属于原 UID。没有可靠反证时，同服同名默认关联，换公会或缺少 UID 不拆档；明确不同 UID 和已知多账号分别保留。
早期入榜但结算未进前50的玩家继续保留，标为沿用赛中成绩；不沿用旧名次。
通过审核的新高分进入公开结果；待审核、驳回、撤回记录不生效。历史快照保留。
阵容截图与总伤分开核验，旧阵容的刀伤总和不得当作新总伤。

4. 固定更新链

录入源数据 → 校验快照/身份/档位 → 合并结算数据 → 生成固定 HTML、JSON 和 sitemap → 同一条生产构建发布。管理审核使用同一结算函数更新已有固定页面的纯文本响应。

Agent 应先读 SEASON_DATA_WORKFLOW.md。已有快照不可直接改写为新批次；修订需保留旧版来源。算法回测与真实结算分别储存，预测不能成为真实成绩。