diff --git a/docs/01-architecture.md b/docs/01-architecture.md index eccd3cf..5333956 100644 --- a/docs/01-architecture.md +++ b/docs/01-architecture.md @@ -57,38 +57,48 @@ Profeto/ ├── src/ │ ├── api/ -│ │ ├── app.py # FastAPI 工厂(lifespan 建表) +│ │ ├── app.py # FastAPI 工厂(lifespan 仅验证 DB 连接,不建表) +│ │ ├── deps.py # 依赖:管理接口鉴权(X-API-Key) │ │ ├── schemas.py # Pydantic v2 请求/响应 │ │ └── routes/ │ │ ├── matches.py # 联赛/比赛查询(游标分页) │ │ ├── predict.py # 预测 + 预测历史 -│ │ ├── ingest.py # 采集触发(自管 session) -│ │ └── eval.py # 赛后回填 + 准确率汇总 +│ │ ├── ingest.py # 采集触发(自管 session,需鉴权) +│ │ ├── eval.py # 赛后回填 + 准确率汇总 +│ │ └── backtest.py # 历史回测(需鉴权) │ ├── db/ │ │ ├── base.py # async engine + get_db/get_db_read -│ │ └── models.py # 6 张表 ORM +│ │ ├── models.py # 6 张表 ORM +│ │ ├── repositories.py # 仓储层 +│ │ └── unit_of_work.py # 事务边界 │ ├── data/ │ │ ├── bzzoiro.py # 赛果采集 + 幂等入库 │ │ ├── understat.py # xG 回填 │ │ ├── injuries.py # 伤停采集(带文件缓存) │ │ ├── normalize.py # NormalizedMatch 清洗契约 │ │ ├── team_names.py # 队名归一映射 +│ │ ├── sources.py # 数据源注册表 │ │ └── config.py # 联赛代码映射 │ ├── llm/ │ │ ├── provider.py # OpenAI-compatible 抽象(共享连接池/JSON 兜底解析) │ │ ├── context_builder.py # 数据切片(h2h/form/stats/home_away/injuries)+ 单 agent 拼接 │ │ ├── predict.py # 预测入口(mode 分派 + 缓存) │ │ ├── eval.py # 准确率统计 +│ │ ├── validation.py # LLM 输出严格校验(Pydantic) +│ │ ├── backtest.py # 回测执行 │ │ ├── agents/ │ │ │ ├── base.py # AgentSpec / AgentReport / run_agent │ │ │ └── orchestrator.py # 并行专家 → 终裁 → 存库 │ │ └── prompts/ │ │ ├── match_prediction_v1/v2.md # 单 agent 模板 │ │ └── agents/{h2h,form,stats,home_away,injuries,aggregator}_v1.md -│ └── core/config.py # pydantic-settings -├── alembic/versions/ # 0001 建表 + 0002 agent 字段 -├── frontend/src/pages/Matches.tsx # 单页(预测面板 + 专家报告折叠区) -├── tests/ # 33 项(核心 13 + agent 20) +│ └── core/ +│ ├── config.py # pydantic-settings +│ ├── http_client.py # 共享 httpx 客户端 +│ └── retry.py # 重试工具 +├── alembic/versions/ # 0001~0006(0001 建表 → 0006 漂移清理) +├── frontend/src/pages/Matches.tsx # 单页(预测面板 + 专家报告折叠区 + 游标分页) +├── tests/ # 核心 + agent 测试 ├── docker-compose.yml # api + postgres 两容器 └── docs/ # 本文档 ``` diff --git a/docs/07-development.md b/docs/07-development.md index 93994ef..c9701f3 100644 --- a/docs/07-development.md +++ b/docs/07-development.md @@ -35,27 +35,34 @@ Profeto/ ├── src/ # 后端源码 │ ├── api/ │ │ ├── routes/ # FastAPI 路由 -│ │ │ ├── leagues.py # 联赛/比赛查询 +│ │ │ ├── matches.py # 联赛/比赛查询 │ │ │ ├── predict.py # 预测入口 │ │ │ ├── ingest.py # 数据采集 -│ │ │ └── eval.py # 评估回填 +│ │ │ ├── eval.py # 评估回填 +│ │ │ └── backtest.py # 历史回测 +│ │ ├── deps.py # 依赖:管理接口鉴权(X-API-Key) │ │ ├── schemas.py # Pydantic 模型 │ │ └── app.py # FastAPI 工厂 │ ├── db/ │ │ ├── base.py # SQLAlchemy async engine + session -│ │ └── models.py # 6 张表 ORM +│ │ ├── models.py # 6 张表 ORM +│ │ ├── repositories.py # 仓储层(查询封装) +│ │ └── unit_of_work.py # 事务边界 │ ├── data/ │ │ ├── bzzoiro.py # bzzoiro 采集 + 入库 │ │ ├── understat.py # understat xG 回填 │ │ ├── injuries.py # 伤停采集 │ │ ├── normalize.py # 数据清洗契约 │ │ ├── team_names.py # 队名归一化映射 +│ │ ├── sources.py # 数据源注册表 │ │ └── config.py # 联赛映射常量 │ ├── llm/ │ │ ├── provider.py # LLM 提供商抽象(OpenAI-compatible) │ │ ├── context_builder.py # 数据切片 + 拼接 │ │ ├── predict.py # 预测入口(单/多模式分派) │ │ ├── eval.py # 评估统计 +│ │ ├── validation.py # LLM 输出严格校验 +│ │ ├── backtest.py # 回测执行 │ │ ├── agents/ │ │ │ ├── base.py # AgentSpec + run_agent │ │ │ └── orchestrator.py # 多 agent 编排 @@ -69,12 +76,18 @@ Profeto/ │ │ ├── h2h_v1.md │ │ └── aggregator_v1.md │ └── core/ -│ └── config.py # pydantic-settings 配置 +│ ├── config.py # pydantic-settings 配置 +│ ├── http_client.py # 共享 httpx 客户端 +│ └── retry.py # 重试工具 ├── frontend/ # React 单页前端 ├── alembic/ # 数据库迁移 │ └── versions/ │ ├── 0001_initial.py -│ └── 0002_agent_outputs.py +│ ├── 0002_agent_outputs.py +│ ├── 0003_injuries.py +│ ├── 0004_snapshot_and_constraints.py +│ ├── 0005_prediction_status_and_stats_provenance.py +│ └── 0006_schema_model_drift_cleanup.py ├── tests/ # 测试 │ ├── test_core.py # 核心逻辑测试 │ └── test_agents.py # 多 agent 测试 diff --git a/src/core/retry.py b/src/core/retry.py index bb3dd6b..564c93d 100644 --- a/src/core/retry.py +++ b/src/core/retry.py @@ -1,4 +1,11 @@ -"""重试工具:带指数退避的瞬态错误重试。""" +"""重试工具:带指数退避的瞬态错误重试。 + +NOTE(审查报告 P3):当前全项目**无调用点** —— bzzoiro 在 `_fetch_json_sync` +里自带了一套重试逻辑,understat/injuries 各自也有。这里保留是作为后续统一 +重试策略的落点,但请勿误以为它已在生效。 + +如果决定不引入统一重试,建议删除本文件以避免"看起来有重试、实际没有"的误判。 +""" from __future__ import annotations import asyncio diff --git a/tests/test_regressions.py b/tests/test_regressions.py new file mode 100644 index 0000000..755e85e --- /dev/null +++ b/tests/test_regressions.py @@ -0,0 +1,99 @@ +"""回归测试:锁定 P0 三项「静默失效」缺陷不再复发。 + +这些用例不依赖数据库 —— 它们用静态分析检查代码结构, +因为三个 P0 的本质都是「集成方式错误」,在 mock 掉 slice_fn / +provider 的单元测试里永远照不出来(这正是它们当初漏网的原因)。 + +- P0-1/P0-2: 查询 Match 的函数必须 eager-load 切片会访问的关系 +- P0-3: bzzoiro 写 source_event_id 时用的 raw 必须与 nm 配对 +""" +from __future__ import annotations + +import re +from pathlib import Path + +SRC = Path(__file__).resolve().parent.parent / "src" + +# 切片函数会读取的关系属性 → 查询时必须 eager-load +MATCH_RELATIONS = ("stats", "home_team", "away_team", "league") + + +def _read(rel: str) -> str: + return (SRC / rel).read_text(encoding="utf-8") + + +class TestEagerLoadCoverage: + """P0-1 / P0-2: 凡是 select(Match) 且后续访问关系的函数,必须有 eager-load。""" + + def test_context_builder_getters_eager_load(self): + """_get_form / _get_h2h / _get_home_away 必须预加载关系。 + + models.py 已声明 lazy="selectin" 兜底,但这里同时检查显式 + selectinload —— 显式声明是查询意图的固化,也被 P0 修复所依赖。 + """ + src = _read("llm/context_builder.py") + for fn in ("_get_form", "_get_h2h", "_get_home_away"): + # 截取函数体 + m = re.search(rf"async def {fn}\(.*?(?=\nasync def |\n# =|\Z)", src, re.S) + assert m, f"{fn} 未找到" + body = m.group(0) + assert "selectinload" in body, ( + f"{fn} 查询 Match 但未 eager-load 关系 —— " + "this would raise MissingGreenlet in async SQLAlchemy (P0-2)" + ) + + def test_backtest_candidates_eager_load(self): + """回测取历史比赛必须 eager-load(否则 session 关闭后访问关系必炸)。""" + src = _read("llm/backtest.py") + assert "selectinload" in src, "backtest 未 eager-load 关系 (P0-1)" + + def test_relationship_default_is_selectin(self): + """models.py 中 Match 的高频关系应声明 lazy='selectin' 作为兜底。""" + src = _read("db/models.py") + # 找到 Match 类定义段 + m = re.search(r"class Match\(Base\):.*?(?=\nclass )", src, re.S) + assert m, "Match 类未找到" + body = m.group(0) + for rel in MATCH_RELATIONS: + # 关系声明可能跨多行(stats/home_team/away_team 都是),因此按 + # 「从 `rel: Mapped` 到下一个 `xxx: Mapped` 之前」整段匹配。 + m_rel = re.search( + rf"^\s*{rel}: Mapped.*?(?=^\s*\w+: Mapped|\Z)", body, re.M | re.S + ) + assert m_rel, f"Match.{rel} 未找到" + assert 'lazy="selectin"' in m_rel.group(0), ( + f"Match.{rel} 未声明 lazy='selectin' —— 兜底缺失 (P0-2)" + ) + + +class TestBzzoiroLineage: + """P0-3: source_event_id 必须取配对的 raw,不能是循环残留变量。""" + + def test_normalized_matches_carries_raw(self): + src = _read("data/bzzoiro.py") + # 规范化结果必须与原始 event 成对保存 + assert "normalized_matches.append((nm, raw))" in src, ( + "normalized_matches 未携带 (nm, raw) 元组 —— raw 变量泄漏会回归 (P0-3)" + ) + # 内层消费循环必须解包成对变量 + assert re.search(r"for nm, raw in normalized_matches", src), ( + "消费循环未解包 (nm, raw) —— 血缘字段会取到错误 event (P0-3)" + ) + + def test_no_orphan_raw_use(self): + """source_event_id 所在行必须在解包循环内(用缩进 + 上下文粗判)。""" + src = _read("data/bzzoiro.py") + lines = src.splitlines() + # 找到 "for nm, raw in normalized_matches" 所在行号 + start = next( + (i for i, ln in enumerate(lines) if "for nm, raw in normalized_matches" in ln), + None, + ) + assert start is not None + # 该循环之后、下一个同/更低缩进的顶层语句之前的范围 + seg = "\n".join(lines[start:]) + uses = [ln for ln in seg.splitlines() if "source_event_id" in ln] + assert uses, "未找到 source_event_id 赋值" + assert all("raw.get(" in ln for ln in uses), ( + "source_event_id 未使用配对的 raw (P0-3)" + )