数据模型

下载完整 JSON Schema。下列字段表在文档构建时直接从同一 schema 生成，避免手工维护两套定义。

SiteSnapshot

字段	类型	必填	说明
repository	Repository	是
generatedAt	string	是	快照生成时间，包含时区；不代表 legacy Rating 更新时间。 date-time
sourceRef	string	是	用于读取 Git 的 ref，不要求等于 repository.branch。
commitCount	integer	是	兼容字段：所选 Git ref 的提交数量；首页不展示。 最小值 0
contributions	object	是	兼容字段：首页不展示。稀疏日期字典；不存在的日期表示当天无记录。
problems	array<Problem>	是	题目条目；数组本身不保证按时间排序。
ratings	Ratings	是

Repository

字段	类型	必填	说明
owner	string	是	仓库所有者。 固定值 xw7qwq
name	string	是	仓库名。 固定值 codeflare
branch	string	是	源码链接和在线树使用的分支。 固定值 main

Problem

字段	类型	必填	说明
path	string	是	仓库内相对路径，保留大小写和 Unicode；必须唯一。
platform	string	是	来源平台，对应 path 第一段；不固定平台列表。
language	string	是	由源码扩展名识别的语言。 枚举：C++、C、Python、Java、Rust、Go、Kotlin
title	string	是	路径推导的显示名称，不保证是 OJ 原题标题。
problemUrl	string	是	原题、比赛或平台入口，并非必定为精确题目页。 uri；格式 ^https://
githubUrl	string	是	源码的 GitHub blob 地址。 uri；格式 ^https://github.com/
rawUrl	string	是	原始源码文本地址。 uri；格式 ^https://raw.githubusercontent.com/
submittedAt	string / null	是	快照中该路径的 Git 提交者时间；未知为 null，不是 OJ 评测时间。 date-time

Ratings

字段	类型	必填	说明
atcoder	AtCoderRating / null	是	AtCoder 数据；保留的历史兼容数据，不再主动刷新；未知或未提供时为 null。
codeforces	CodeforcesRating / null	是	Codeforces 数据；保留的历史兼容数据，不再主动刷新；未知或未提供时为 null。

AtCoderRating

字段	类型	必填	说明
rating	integer / null	是	最新有效 Rating；无 rated 记录时为 null。 最小值 0
maxRating	integer	是	有效历史场次最高值；无记录时为 0。 最小值 0
contests	integer	是	计入统计的 rated 场次数。 最小值 0

CodeforcesRating

字段	类型	必填	说明
rating	integer / null	是	当前 Rating；未提供时为 null。 最小值 0
maxRating	integer / null	是	最高 Rating，允许未知。 最小值 0
rank	string	是	平台返回的级别，缺失时使用 unrated；不限定枚举。

RecentCommitsSnapshot

字段	类型	必填	说明
repository	Repository	是
generatedAt	string	是	快照生成时间，不是仓库最近提交时间。 date-time
sourceRef	string	是	生成时读取的 Git ref；生产快照使用 main 或对应远端 ref。
commits	array<Commit>	是	最多六条提交；保留 Git / GitHub 返回顺序，包含合并提交。 最多 6 项

Commit

字段	类型	必填	说明
sha	string	是	完整的小写 Git SHA；列表中必须唯一。 格式 ^[0-9a-f]{40}$
subject	string	是	原始 commit message 第一行，允许为空；按纯文本展示。 格式 ^[^\r\n]*$
committedAt	string	是	提交者时间（%cI / commit.committer.date），不是作者日期或 OJ 提交时间。 date-time
url	string	是	该仓库对应完整 SHA 的 GitHub 提交详情地址。 uri；格式 ^https://github.com/xw7qwq/codeflare/commit/[0-9a-f]{40}$

业务约束

除结构校验外，发布检查要求：

• 每个 path 唯一，必须是安全的仓库相对路径，第一段与 platform 一致。

• 文件扩展名与 language 一致；githubUrl 和 rawUrl 与仓库配置及逐段编码后的路径一致。

• contributions 是真实日期到正整数的字典，计数合计必须等于 commitCount。

• 非空 Rating 使用非负整数；最高值不得低于当前值。此处是契约门禁，网页运行时没有完整执行这些检查。

• 最近提交最多六条，完整 SHA 唯一；URL 必须与仓库及 SHA 精确匹配。其顺序来自 Git 历史，不要求时间戳递减。

日历和 Rating 是保留的兼容数据，当前首页不展示，Rating 不再主动刷新；generatedAt 不表示 Rating 的更新时间。

允许 submittedAt 未知，允许平台 Rating 为 null。不要求响应预排序，不锁定题目数量，不要求 sourceRef 与链接分支相同，也不把 Git 时钟误差作为算法错误。