J
JONSPC18/ai-155-model
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

足球AI赛程跨赛季记录接口设计

问题背景

足球赛程的赛季边界与自然年并不对齐:主流联赛多为秋春制,一个赛季横跨两个公历年;部分联赛为春秋制,一年内完成一个赛季;杯赛与洲际赛事又在联赛赛季之上叠加自己的赛期。当接口把「当前赛季」作为隐含上下文,只提供 /matches?season= 这类单一赛季入口时,调用方在赛季切换窗口会拿到语义含糊的结果:既无法区分「该赛季赛程尚未生成」与「该赛季不存在」,也无法表达「最近三个赛季同轮次对比」「某队跨赛季主场胜率」这类区间问题。AI 赛程类应用(赛果预测、体能负荷建模、转播排期)恰好最依赖跨赛季的连续切片,因此接口需要把赛季建模为一等公民,而不是一个可选过滤参数。相关参考:https://hycitech.com/article/pc28-zai-31。

第二类问题来自记录身份的不稳定。同一场比赛在赛季内会因转播、天气、杯赛冲突而改期,若以开球时间或自增 ID 作为跨赛季主键,一次改期就会在历史数据里留下两条互不相连的记录,训练集也随之出现重复样本。同时赛季命名格式不统一(2024、2024-25、2024/2025、2024-2025)会让字符串排序和范围过滤失效,跨赛季按时间轴排序时容易出现错位。因此设计目标明确为三条:以业务唯一键保证幂等写入、以显式单调的赛季序号替代赛季字符串比较、以只读归档状态冻结历史赛季,使接口在赛季滚动期间仍可重复调用而不产生歧义数据。相关参考:https://jyppt.zuiqiangyingyu.net/article/pc28-zai-29。

实现方案

整体采用三层结构。第一层是采集与归一化:外部赛程源按源 ID 映射到内部稳定标识 competition_id、team_id,赛季字符串归一为 YYYY-YYYY 并同时写入单调递增的 season_seq;归一化后的记录以 (competition_id, season, match_no) 为业务唯一键进入写入通道。第二层是存储:season_match 表保存每场比赛的跨赛季记录与修订号,season 字典表保存赛季起止日期、season_seq、赛季状态(planned/active/archived),两张表通过 (competition_id, season) 关联。第三层是查询接口:PUT /v1/records 负责幂等写入,GET /v1/records 负责跨赛季区间读取,所有跨赛季范围条件都作用在 season_seq 上而不是赛季字符串上。赛季滚动流程为:滚动任务先落 season 字典行,再导入新赛季赛程,最后把上一赛季置为 archived,写入入口对归档赛季默认拒绝变更。相关参考:https://hycitech.com/article/pc28-zai-32。

实现细节集中在三处。其一是改期语义:kickoff_utc 一律以 UTC 存储,本地开球时间由展示层换算,改期只更新 kickoff_utc 并递增 revision,业务唯一键保持不变,因此历史修订可追溯而记录不重复;调用方可带上次读到的 revision 做乐观并发控制,不一致时接口返回 409 而不是静默覆盖。其二是状态处理:比赛状态按 scheduled → live → finished 迁移,取消与腰斩进入 cancelled/abandoned 并保留行,聚合时按状态过滤而不是物理删除,避免历史赛季统计漏算。其三是异常与边界:赛季格式不合法返回 422;同键但 competition_id 与已有记录冲突返回 409;对已归档赛季的无条件写入返回 409 并在错误体中标记只读;分页使用 (season_seq, kickoff_utc, match_no) 复合游标而非 offset,避免新写入导致深分页漂移;对缺少比分的历史场次,聚合结果返回 partial: true 标记,不把缺失值当 0 计入。相关参考:https://jyppt.zuiqiangyingyu.net/article/shu-ju-ke。

代码示例

# app/main.py
# 必要依赖:Python 3.10+、fastapi、uvicorn、sqlalchemy>=2.0、pydantic>=2.0
# 生产环境另需 PostgreSQL 驱动 psycopg;本地联调可使用内置 sqlite
# 安装:python3 -m pip install fastapi uvicorn "sqlalchemy>=2.0" "pydantic>=2.0"
# 数据源地址统一由环境变量 BASE_DSN 注入,代码中不硬编码任何地址
# 首次启动需执行 Base.metadata.create_all(engine) 建表
import os
from datetime import datetime
from typing import Iterator

from fastapi import Depends, FastAPI, HTTPException, Query
from pydantic import BaseModel, Field
from sqlalchemy import DateTime, Integer, String, UniqueConstraint, create_engine, select
from sqlalchemy.orm import DeclarativeBase, Mapped, Session, mapped_column, sessionmaker

BASE_DSN = os.environ.get("BASE_DSN")
if not BASE_DSN:
    raise RuntimeError("环境变量 BASE_DSN 未配置")

engine = create_engine(BASE_DSN, future=True)
SessionLocal = sessionmaker(bind=engine, future=True)


class Base(DeclarativeBase):
    pass


class SeasonMatch(Base):
    """跨赛季单场记录;业务唯一键为 (competition_id, season, match_no)。"""

    __tablename__ = "season_match"
    __table_args__ = (
        UniqueConstraint("competition_id", "season", "match_no", name="uq_match_key"),
    )

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    competition_id: Mapped[str] = mapped_column(String(32), index=True)
    season: Mapped[str] = mapped_column(String(16), index=True)   # 形如 2024-2025
    season_seq: Mapped[int] = mapped_column(Integer, index=True)  # 连续赛季序号
    match_no: Mapped[int] = mapped_column(Integer)
    home_team_id: Mapped[str] = mapped_column(String(32))
    away_team_id: Mapped[str] = mapped_column(String(32))
    kickoff_utc: Mapped[datetime] = mapped_column(DateTime(timezone=True))
    status: Mapped[str] = mapped_column(String(16), default="scheduled")
    revision: Mapped[int] = mapped_column(Integer, default=1)


class MatchIn(BaseModel):
    competition_id: str = Field(min_length=1, max_length=32)
    season: str = Field(pattern=r"^\d{4}-\d{4}$")
    season_seq: int = Field(ge=0)
    match_no: int = Field(ge=1)
    home_team_id: str
    away_team_id: str
    kickoff_utc: datetime
    status: str = "scheduled"


app = FastAPI(title="football-schedule-cross-season")


def get_session() -> Iterator[Session]:
    with SessionLocal() as session:
        yield session


@app.put("/v1/records", response_model=MatchIn)
def upsert_record(payload: MatchIn, session: Session = Depends(get_session)) -> MatchIn:
    """幂等写入:同一业务键重复提交只更新并递增 revision,不新增行。"""
    stmt = select(SeasonMatch).where(
        SeasonMatch.competition_id == payload.competition_id,
        SeasonMatch.season == payload.season,
        SeasonMatch.match_no == payload.match_no,
    )
    row = session.execute(stmt).scalar_one_or_none()
    if row is None:
        session.add(SeasonMatch(**payload.model_dump(), revision=1))
    else:
        for key, value in payload.model_dump().items():
            setattr(row, key, value)
        row.revision += 1
    session.commit()
    return payload


@app.get("/v1/records")
def list_records(
    competition_id: str,
    from_seq: int = Query(ge=0),
    to_seq: int = Query(ge=0),
    limit: int = Query(default=100, ge=1, le=500),
    session: Session = Depends(get_session),
) -> dict:
    """跨赛季查询:范围条件走 season_seq,避免赛季字符串字典序错位。"""
    if from_seq > to_seq:
        raise HTTPException(status_code=422, detail="from_seq 不能大于 to_seq")
    stmt = (
        select(SeasonMatch)
        .where(
            SeasonMatch.competition_id == competition_id,
            SeasonMatch.season_seq >= from_seq,
            SeasonMatch.season_seq <= to_seq,
        )
        .order_by(SeasonMatch.season_seq, SeasonMatch.kickoff_utc, SeasonMatch.match_no)
        .limit(limit)
    )
    rows = session.execute(stmt).scalars().all()
    return {
        "count": len(rows),
        "items": [
            {
                "season": r.season,
                "season_seq": r.season_seq,
                "match_no": r.match_no,
                "kickoff_utc": r.kickoff_utc.isoformat(),
                "status": r.status,
                "revision": r.revision,
            }
            for r in rows
        ],
    }

执行方式:先导出 BASE_DSN(本地可用 sqlite:///./fixture.db,生产为 PostgreSQL 连接串),按需调用 Base.metadata.create_all(engine) 建表,再用 uvicorn app.main:app --reload 启动服务;随后对 /v1/records 以同一 (competition_id, season, match_no) 提交两次请求,第二次改动 kickoff_utc,最后用 /v1/records?competition_id=...&from_seq=..&to_seq=.. 读取区间。预期结果:两次写入后表中该业务键只有一行,响应中 revision 由 1 变为 2,kickoff_utc 为第二次提交值;区间查询按 season_seq 升序返回覆盖各赛季的记录,count 与实际行数一致,from_seq 大于 to_seq 时返回 422。以上为设计预期,示例代码待验证,不作为已运行通过的测试记录。相关参考:https://hycitech.com/article/pc28-zai-28。

代码与正文的对应关系需要逐项自查:示例只从 BASE_DSN 读取数据源地址,没有第二个地址常量;写入路径用的三个字段与表的唯一约束 uq_match_key 完全一致,MatchIn 的字段集合也与 SeasonMatch 的列一一对应,否则 SeasonMatch(**payload.model_dump()) 会抛参数错误;season 的正则只接受 YYYY-YYYY,单年份或斜杠写法必须在归一化层先转换。另有一处已知限制:DateTime(timezone=True) 在 SQLite 下不保留时区偏移,本地联调读回的 kickoff_utc 可能缺少时区标记,生产应使用 PostgreSQL 的 timestamptz,否则跨时区换算会被错误本地时间污染;season_seq 也必须由 season 字典表统一分配,若调用方自行填写冲突值,同一 season 会出现两个序号,跨赛季排序随即失效。若后续把 limit 改为游标分页,order_by 中的三个字段必须同时进入游标键,否则同一秒开球的两场比赛在翻页时可能重复或遗漏。相关参考:https://jyppt.zuiqiangyingyu.net/article/pc28-zai-28。

验证方法

幂等性与修订验证:以相同 competition_id、season、match_no 连续提交两次不同 kickoff_utc 的请求,然后比对行数统计 select count(*) 与 count(distinct competition_id || season || match_no),两者应相等,说明未产生重复记录;同时读取响应或直接查表确认 revision 单调递增,且旧的开球时间不再出现在结果中。若要验证并发行为,可在两个会话中携带同一 revision 提交,预期只有一个成功、另一个收到 409 冲突,从而确认写入不是最后写入覆盖。相关参考:https://hycitech.com/article/pc28-zai-34。

跨赛季边界验证:准备三个连续赛季(season_seq 分别为 3、4、5)的样本记录,分别检查区间包含性(from_seq=3,to_seq=5 返回三条)、闭区间两端(from_seq=4,to_seq=4 只返回中间赛季)、非法区间(from_seq=5,to_seq=3 返回 422),以及空区间(赛季存在但无赛程时返回 count=0 而非 404,使调用方能区分「无数据」与「资源不存在」)。另需验证排序稳定性:同一 season_seq 内结果应严格按 kickoff_utc、match_no 升序,重复请求两次结果顺序一致;对归档赛季发起写入应返回只读类错误而非静默成功。以上步骤为验证方案描述,本次未实际执行。相关参考:https://jyppt.zuiqiangyingyu.net/article/pc28-zai-15。

局限性

赛季序号依赖人工维护的字典表,只能保证同一 competition_id 内部单调,无法用一个全局序号表达不同足协赛制的重叠赛季(秋春制与春秋制并行时,同一自然年可能对应两个不同联赛的不同序号),跨联赛对齐需要额外的赛期映射。球队侧的历史连续性同样没有覆盖:升降级、改名、合并、梯队递补都会改变 team_id 的语义,当前方案未引入别名表,因此跨赛季「同一支球队」的聚合只能由调用方自行维护映射来完成。相关参考:https://hycitech.com/article/pc28-zai-29。

记录归属与统计口径的边界也未被接口吸收:赛事扩军导致 match_no 重排时,同一轮次编号在不同赛季可能指向不同的对阵结构;赛季腰斩、比赛判负、结果改判等情况需要人工裁定后重写记录,接口只做幂等覆盖,除 revision 外并不提供差异审计视图。此外,示例仅给出单机 SQLite 联调路径与 PostgreSQL 的部署建议,未进行并发压测、索引调优或任何性能测量,因此不具备可引用的吞吐与延迟结论;聚合指标(场均进球、胜率、负荷指数)的公式刻意留在调用方,接口只提供赛季切片与状态标记,以免口径变更导致历史数据不可比。相关参考:https://jyppt.zuiqiangyingyu.net/article/pc28-zai-16。