docs: 全套文档与代码对齐(P1-1,数据源收敛 bzzoiro 后的存量漂移清理)

- 数据源:全部文档统一为 bzzoiro 唯一来源,删除 understat/api-football 作为现行数据源的表述(仅保留历史注记);.env.example/docs/06 移除失效的 API_FOOTBALL_KEY - 多 Agent:injuries 阵容完整性 → standings 联赛排名 (README/01/04 的专家表、数据流图、no_data 示例、agent_weights、 prompt 清单全部对齐 form/stats/home_away/standings/h2h) - 数据库:6 张表 → 12 张表,补 standings/app_settings/schedules 与 4 张治理表说明(标注 raw_events/data_quality_checks/data_lineage 为预留未启用,ingest_failures 已启用),predictions 补 agent_weights 列 - API 文档(03):新增鉴权模型三档表;context/standings/leagues 公开端点补全;predictions/eval/backtest 标注需管理员;ingest/bzzoiro 补 task/limit/season 参数契约,删除 understat/injuries 端点小节 - 目录树(README/01/07):与真实 src/、frontend/src 结构一致 (core 7 文件、data 7 文件、移除不存在的 retry.py) - 采集命令(02/05):understat 回填 → task=stats/standings; 补管理员凭据提示;docs/08 文首标注历史/过时
2026-09-21 20:55:48 +08:00
parent a24017eb69
commit 80616cf459
10 changed files with 239 additions and 132 deletions
@@ -12,28 +12,30 @@
                       │ REST API
 ┌──────────────────────▼──────────────────────────────┐
 │  FastAPI                                            │
-│  ├── /api/v1/matches     比赛查询                   │
+│  ├── /api/v1/matches     比赛查询(公开只读)          │
 │  ├── /api/v1/predict     LLM 预测 (单/多 Agent)     │
-│  ├── /api/v1/ingest/*    数据采集                   │
-│  ├── /api/v1/eval/*      评估回填                   │
-│  └── /api/v1/backtest    回测                       │
+│  ├── /api/v1/ingest/*    数据采集(需管理员)          │
+│  ├── /api/v1/eval/*      评估回填(需管理员)          │
+│  └── /api/v1/backtest    回测(需管理员)              │
 └──────────┬─────────────────────────────┬────────────┘
           │                             │
 ┌──────────▼──────────┐    ┌─────────────▼────────────┐
 │  PostgreSQL         │    │  LLM (OpenAI-compatible)  │
-│  6 张表             │    │  OpenAI / Deepseek /      │
+│  12 张表            │    │  OpenAI / Deepseek /      │
 │  leagues/teams/     │    │  Ollama / 任意网关        │
 │  matches/match_     │    └──────────────────────────┘
-│  stats/predictions/ │
-│  injuries           │
+│  stats/standings/   │
+│  predictions/       │
+│  app_settings/      │
+│  schedules +        │
+│  raw_events 等 4 张 │
+│  数据治理表          │
 └─────────────────────┘
           ▲
           │ 采集
 ┌──────────┴─────────────────────────────────────────┐
 │  数据源 (DataSource 协议 + 注册表)                   │
-│  ├── bzzoiro    比分 / 统计 / xG                    │
-│  ├── understat  xG 回填                             │
-│  └── injuries   伤停数据 (api-football)             │
+│  └── bzzoiro    比分 / 赛程 / 统计 / 积分榜          │
 └────────────────────────────────────────────────────┘
 ```

@@ -55,7 +57,7 @@ API Route → Application Service → Repository → UnitOfWork → DB
 比赛数据 → 切片 ─┬─→ A 近期状态专家 ─┐
                 ├─→ B 攻防数据专家 ─┤
                 ├─→ C 主客因素专家 ─┼─→ 终裁专家 ─→ 最终预测
-                 ├─→ D 阵容完整专家 ─┤
+                 ├─→ D 联赛排名专家 ─┤
                 └─→ E 历史交锋专家 ─┘
 ```

@@ -66,8 +68,7 @@ API Route → Application Service → Repository → UnitOfWork → DB

 ### 数据正确性保障

- **Cutoff 机制**: 回测时只使用 `cutoff_at` 之前已采集的数据
- **Injury 防泄漏**: 伤停查询强制 `retrieved_at <= cutoff`
+- **Cutoff 机制**: 回测时只使用 `cutoff_at` 之前已采集的数据(近况/交锋/统计/积分榜切片统一生效)
 - **LLM 输出校验**: Pydantic 严格校验 + 语义一致性检查
 - **数据库约束**: CHECK 约束作为最后一道防线

@@ -141,20 +142,29 @@ cd frontend && npm install && npm run dev

 ## API 概览

+**公开只读**(无需登录;`predict` 带内存限流):
+
 | 方法 | 路径 | 说明 |
 |---|---|---|
-| GET | `/api/v1/matches` | 比赛查询(筛选/分页) |
-| GET | `/api/v1/leagues` | 联赛列表 |
-| POST | `/api/v1/predict` | LLM 预测 (`mode=single`/`multi`) |
-| GET | `/api/v1/predictions` | 预测历史 |
-| POST | `/api/v1/ingest/bzzoiro` | 采集比分/统计 |
-| POST | `/api/v1/ingest/understat` | 回填 xG |
-| POST | `/api/v1/ingest/injuries` | 采集伤停 |
+| GET | `/api/v1/leagues` | 联赛列表(仅 id/code/name/country) |
+| GET | `/api/v1/matches` | 比赛查询(筛选/游标分页) |
+| GET | `/api/v1/matches/{id}` | 比赛详情(含统计与最近预测) |
+| GET | `/api/v1/matches/{id}/context` | 比赛上下文(双方近况 + 历史交锋) |
+| GET | `/api/v1/standings` | 联赛积分榜 |
+| POST | `/api/v1/predict` | LLM 预测 (`mode=single`/`multi`/`baseline`) |
+| GET | `/health`、`/health/ready` | 存活 / 就绪检查(含 DB) |
+
+**需管理员**(Cookie 会话或 `X-API-Key`):
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/api/v1/ingest/bzzoiro` | 采集赛果/赛程/统计/积分榜 |
+| GET | `/api/v1/predictions` | 预测历史(列表) |
+| GET | `/api/v1/predictions/{id}` | 单条预测详情 |
 | POST | `/api/v1/eval/settle` | 回填实际结果 |
 | GET | `/api/v1/eval/summary` | 准确率汇总 |
 | POST | `/api/v1/backtest` | 历史回测 |
-| GET | `/health` | 存活检查 |
-| GET | `/health/ready` | 就绪检查(含 DB) |
+| `/api/v1/admin/**` | 配置/采集状态/日志/定时任务/死信等 | 管理后台(router 级鉴权) |

 ## 项目结构

@@ -163,36 +173,46 @@ Profeto/
 ├── src/
 │   ├── api/                    # FastAPI 路由层
 │   │   ├── app.py              # 应用工厂 + lifespan
+│   │   ├── deps.py             # 依赖注入:鉴权 / 限流
 │   │   ├── schemas.py          # Pydantic 请求/响应模型
 │   │   └── routes/
-│   │       ├── matches.py      # 比赛查询
-│   │       ├── predict.py      # 预测入口
-│   │       ├── ingest.py       # 数据采集
-│   │       ├── eval.py         # 评估回填
-│   │       └── backtest.py     # 回测
+│   │       ├── matches.py      # 比赛查询(公开只读)
+│   │       ├── predict.py      # 预测入口 + 预测历史
+│   │       ├── ingest.py       # 数据采集(需管理员)
+│   │       ├── eval.py         # 评估回填(需管理员)
+│   │       ├── backtest.py     # 回测(需管理员)
+│   │       ├── auth.py         # 登录/登出/改密
+│   │       ├── admin_settings.py  # /admin/** 配置/日志/数据质量(router 级鉴权)
+│   │       └── schedules.py    # 定时任务 + 死信重试(router 级鉴权)
 │   ├── core/                   # 基础设施
 │   │   ├── config.py           # pydantic-settings 配置
+│   │   ├── crypto.py           # 加密/哈希
 │   │   ├── http_client.py      # 共享 httpx 客户端
-│   │   └── retry.py            # 重试工具(指数退避)
+│   │   ├── log_buffer.py       # 内存日志缓冲(admin 日志页)
+│   │   ├── runtime_config.py   # DB 配置覆盖(.env → app_settings)
+│   │   ├── scheduler.py        # 进程内 cron 调度器
+│   │   └── security_check.py   # 启动安全校验
 │   ├── data/                   # 数据层
 │   │   ├── sources.py          # DataSource 协议 + 注册表
+│   │   ├── bzzoiro.py          # bzzoiro 数据源(events/standings/stats)
 │   │   ├── normalize.py        # 数据规范化契约
-│   │   ├── bzzoiro.py          # bzzoiro 数据源
-│   │   ├── understat.py        # understat xG 数据源
-│   │   ├── injuries.py         # 伤停数据
 │   │   ├── config.py           # 联赛映射常量
-│   │   └── team_names.py       # 队名归一化
+│   │   ├── key_ring.py         # API Key 轮换环(429 冷却)
+│   │   ├── team_names.py       # 队名归一化
+│   │   └── team_names_zh.py    # 队名中文映射
 │   ├── db/                     # 数据库
 │   │   ├── base.py             # SQLAlchemy async engine
-│   │   ├── models.py           # ORM 模型 (6 表)
+│   │   ├── models.py           # ORM 模型 (12 表)
 │   │   ├── unit_of_work.py     # UnitOfWork 事务封装
 │   │   └── repositories.py     # Repository 数据访问
 │   └── llm/                    # LLM 预测核心
-│       ├── predict.py          # 预测服务 (缓存 + 单/多模式)
+│       ├── predict.py          # 预测服务 (缓存 + 单/多/基线模式)
 │       ├── context_builder.py  # 数据切片 + 上下文拼接
+│       ├── baseline.py         # 基线预测(均值模型)
 │       ├── eval.py             # 评估统计
 │       ├── backtest.py         # 回测框架
 │       ├── provider.py         # 多提供商 LLM 抽象
+│       ├── utils.py            # LLM 工具函数
 │       ├── validation.py       # LLM 输出校验
 │       ├── agents/
 │       │   ├── base.py         # Agent 基础设施 + 解析
@@ -200,6 +220,11 @@ Profeto/
 │       └── prompts/            # Prompt 模板
 ├── alembic/                    # 数据库迁移
 ├── frontend/                   # React 前端
+│   └── src/
+│       ├── pages/              # 公开站(赛程 Matches + 积分榜 Standings)
+│       ├── admin/              # 管理后台(布局/页面/数据访问层 dal.ts)
+│       ├── components/         # 共享组件
+│       └── lib/http.ts         # 唯一 HTTP 实现(带凭据/超时/错误处理)
 ├── docs/                       # 详细文档
 ├── tests/                      # 单元测试
 ├── docker-compose.yml
@@ -234,7 +259,6 @@ Profeto/
 | `LLM_SPECIALIST_MODEL` | 专家模型 (空=回落 LLM_MODEL) | |
 | `LLM_AGGREGATOR_MODEL` | 终裁模型 (空=回落 LLM_MODEL) | |
 | `BZZOIRO_KEY` | bzzoiro API Key | *(必填)* |
-| `API_FOOTBALL_KEY` | api-football Key (伤停) | |
 | `CORS_ORIGINS` | 允许的跨域来源 | `http://localhost:5173` |

 ## 测试