错误与兼容规范

本文使用“必须”表示契约要求，“建议”表示接入建议。规则面向本站快照及文档发布；外部服务不受本站契约约束。

数据与时间

1. 发布数据必须满足 JSON Schema 和业务约束，不可把类型错误、缺失字段或非法日期当作成功。
2. 对象不接受未知字段；null 表示明确未知，不能替换成 0、空字符串或当前时间。
3. 时间戳必须是带时区的 RFC 3339 / ISO date-time。贡献日历的日期使用 YYYY-MM-DD，日期不能带时间。
4. Git 提交者时间、快照生成时间和 OJ 评测时间必须分别表达。本站没有 OJ 提交记录字段。
5. problemUrl 可以指向比赛页或平台首页。不得将推导 URL 宣称为已验证的原题链接。

错误处理

情况	客户端处理
200 且符合契约	接受快照，显示 generatedAt
200 但 JSON 解析或校验失败	判为无效数据，不覆盖已验证缓存
304	使用已有缓存；无缓存则重新发起完整请求
404	检查完整 API 地址和发布状态；响应可能是 HTML
403 / 429 或限流提示	读取服务给出的限流与重试信息，停止密集请求
网络超时 / 5xx	有上限地重试，保留旧数据并说明更新失败

本站静态托管没有统一的 {code,message} 错误体，不能对所有错误响应无条件调用 response.json()。建议每次请求设置超时，对暂时性失败采用带抖动的退避并限制次数，不对固定的路径错误无限重试。

网站的快照和在线 JSON 请求均有 6 秒超时；题目与最近提交独立更新。源码读取仍使用 5 秒主请求和各 7 秒的回退请求。失败时标明正在显示部署快照，不宣称“实时同步”。

兼容与变更

当前 API 集合契约为 2.0.0，版本维护在 OpenAPI info.version，构建元数据自动读取该版本。响应暂无版本字段。新增或删除字段、修改字段类型、可空性、枚举或语义时，必须同步更新 schema、参考文档、校验和版本说明；不能仅修改展示文字。

2.0.0 将基地址迁移为 https://codeflare.lucius7.dev，并将 repository.owner、repository.name 的固定值更新为 xw7qwq、codeflare，源码与提交链接同步指向新仓库。端点路径 /data/site-data.json 和 /data/recent-commits.json 及其字段结构不变，但旧 Schema 的仓库固定值校验会拒绝新快照，因此按不兼容变更升级主版本。接入方应同时更新基地址、Schema 与缓存中的旧快照，不能假定旧域名会重定向。

历史 1.1.0 新增独立最近提交端点，site-data.json 沿用 1.0.0 的字段结构。历史快照的时间和源码清单中的提交基线不会因仓库迁移而改写为新的历史记录。

由于 additionalProperties: false，增加字段也会被旧严格校验器拒绝，应按不兼容变更处理并先提供迁移方案。修正文档笔误但不改变契约可使用补丁版本。未经实施的版本化 URL 或写接口只能写为未来方案，不可列为现有接口。

校验命令

在 docs/project-guide 的仓库根目录：

npm --prefix site ci
npm --prefix site run check:api
npm --prefix site run build

检查器校验 OpenAPI 文档、自包含的 JSON Schema 和当前 origin/gh-pages 中真实快照，并执行坏数据拒绝检查。构建从 schema 生成模型表，校验站内链接，再产出可部署文件。网络部署验证另行获取线上响应，以免把本地构建成功当成已经上线。

契约检查不证明全部原题链接可用、源码正确或题库完整。旧版路径漏收修复及完整性核对方法见题库维护。