足球比赛事件、阵容与统计：从目录确认到字段核对
先区分已核验接口与待确认字段，再建立实体关联、时间口径和数据校验规则，避免把业务假设写成产品能力。
开发足球比赛详情页时，事件、阵容和统计往往需要共同呈现。但页面能否正确展示，首先取决于字段含义是否清楚，而不是组件是否齐全。本指南先说明百查数据体育 API 已核验目录的边界，再给出独立于产品能力的一般工程核对方法。
一、先确认目录，不预设字段
当前已核验目录包含国家列表，以及联赛、赛季、阶段、球队、球员、教练、裁判、场馆的分页列表，并包含“比赛-即时比分”；这些接口均为 GET。以下摘录可用于确认接口入口，但目录名称不能代替响应结构说明。
| 接口名称 | 已核验地址 |
|---|---|
| 球队分页列表 | https://api.superscore.cn/football/base/teamPage |
| 球员分页列表 | https://api.superscore.cn/football/base/playerPage |
| 比赛-即时比分 | https://api.superscore.cn/football/change/live |
该目录未列出独立的比赛事件、阵容或技术统计接口，也未提供返回字段、枚举及更新规则。因此，不能据此认定即时比分接口包含上述数据，更不能推定字段名、单位或空值含义。正式映射前，应先取得并核验相应字段说明与响应样本。
二、按事件、阵容、统计建立核对表
以下属于一般工程建议，不代表百查数据已提供相应字段。建议在项目内维护映射表，记录来源字段、内部名称、类型、是否允许缺失、业务解释及说明版本；尚未确认的项目标记为“待核验”，不要用猜测补齐。
- 事件：核对比赛关联、事件类别、所属球队、涉及球员与时间表达；补时、撤销和更正如何表示，均需单独确认。
- 阵容：核对球队与球员关联，区分首发、替补、位置和换人信息；名单顺序不能直接解释为阵型位置。
- 统计：核对指标定义、数值类型、单位、统计时段和主客队归属；百分比是否带符号、缺失是否表示未知，不能自行约定为来源事实。
- 实体关联：确认标识的唯一性范围与关联规则，避免仅凭球队或球员名称匹配；同名、译名差异应进入人工复核流程。
跨模块比对也应有边界。例如，不能在事件完整性和计分规则尚未确认时，把可见事件数量直接当成最终比分；球员名单与统计参与者出现差异时，应先检查数据时点、统计范围和更正记录，而非立即覆盖其中一方。
三、把未知状态保留在校验结果里
下面仅演示本地归一化记录的基础校验，键名并非官方响应字段，也不是接口请求示例。实际使用时，应在字段映射得到确认后运行；校验失败的记录保留原值与原因，缺失值不要自动改成零。
# 本地模型示例，不代表官方字段
def validate_local(record):
issues = []
for key in ('match_ref', 'team_ref', 'data_kind'):
if record.get(key) is None:
issues.append(f'{key}: missing')
if record.get('data_kind') == 'stat':
value = record.get('value')
if value is None:
issues.append('value: unknown, keep null')
elif isinstance(value, bool) or not isinstance(value, (int, float)):
issues.append('value: review mapped type')
return issues
四、上线前留存可追溯依据
上线前，建议将字段说明版本、脱敏样本、映射配置和校验结果一起归档，并分别测试字段缺失、未知枚举、重复记录与数据更正。页面应明确区分“零”“未知”和“不适用”。字段核对的目标不是让数据看起来完整，而是让每一次展示都有可追溯的解释。