feat: 足球 LLM 预测服务初始提交

Profeto — 给 LLM 提供数据,让 LLM 预测足球比分。

核心模块:
- FastAPI 后端 + PostgreSQL (SQLAlchemy async)
- 多 Agent LLM 预测 (5 专家 + 终裁)
- 数据采集 (bzzoiro / understat / injuries)
- React 前端 (Vite + Tailwind)

包含:
- 数据源抽象 (DataSource 协议 + 注册表)
- Alembic 数据库迁移
- Prompt 模板 (单/多 Agent)
- 核心路径单元测试

docs/02-quickstart.md

@@ -0,0 +1,129 @@
+# 02 · 快速开始
+
+## 前置条件
+
+- Python 3.11+
+- Docker Desktop(跑 PostgreSQL)
+- 一个 OpenAI-compatible 的 LLM API Key(OpenAI / Deepseek / Ollama 等任一)
+- bzzoiro 数据源 Key(旧项目 MatchPro 的同一 Key)
+
+## 1. 安装
+
+```bash
+cd P:\Profeto
+pip install -e ".[dev]"
+```
+
+## 2. 配置环境变量
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env`,至少填这三项:
+
+```ini
+LLM_API_KEY=sk-xxx                # 必填
+LLM_BASE_URL=https://api.openai.com/v1   # 换成你的提供商
+LLM_MODEL=gpt-4o-mini             # 默认模型
+
+# 可选分档(推荐):
+LLM_SPECIALIST_MODEL=gpt-4o-mini  # 5 个专家用(便宜快)
+LLM_AGGREGATOR_MODEL=gpt-4o      # 终裁用(强)
+
+BZZOIRO_KEY=xxx                   # 数据采集用
+```
+
+## 3. 启动数据库 + 建表
+
+```bash
+docker compose up -d postgres
+alembic upgrade head
+```
+
+## 4. 启动服务
+
+```bash
+# 后端
+uvicorn src.api.app:app --reload
+
+# 前端(另开终端)
+cd frontend
+npm install
+npm run dev
+```
+
+- 前端界面: http://localhost:5173
+- API 文档(Swagger): http://localhost:8000/docs
+
+## 5. 首次跑通全流程
+
+### 采集历史数据(英超近两个月为例)
+
+```bash
+curl -X POST http://localhost:8000/api/v1/ingest/bzzoiro \
+  -H "Content-Type: application/json" \
+  -d '{"leagues":["E0"],"date_from":"2026-08-01","date_to":"2026-09-08"}'
+```
+
+数据量大时**直接拉整赛季**(约 380 场,含近几个赛季更好,近况/交锋/积分榜都需要历史):
+
+```bash
+curl -X POST http://localhost:8000/api/v1/ingest/bzzoiro \
+  -H "Content-Type: application/json" \
+  -d '{"leagues":["E0"],"date_from":"2025-08-01","date_to":"2026-09-08"}'
+```
+
+### 回填 xG(可选,让攻防数据 agent 有数据)
+
+```bash
+curl -X POST http://localhost:8000/api/v1/ingest/understat \
+  -H "Content-Type: application/json" \
+  -d '{"league":"E0","season":2025}'
+```
+
+### 查比赛
+
+浏览器打开 http://localhost:5173 ,选"英超 / 未开赛";
+或:
+
+```bash
+curl "http://localhost:8000/api/v1/matches?league=E0&status=scheduled"
+```
+
+### LLM 预测
+
+页面上点"LLM 预测",预测面板会展示最终结论 + 5 个专家 agent 的折叠报告(方向性评分/证据/分析);
+或:
+
+```bash
+curl -X POST http://localhost:8000/api/v1/predict \
+  -H "Content-Type: application/json" \
+  -d '{"match_id": 1}'
+```
+
+不传 `mode` 默认走多 agent;`"mode":"single"` 走单次调用旧路径(用于对比)。
+
+### 赛后评估
+
+比赛结束后,采集最新赛果(同一条 ingest 命令会自动把 scheduled 升级为 finished 并补比分),
+然后回填预测:
+
+```bash
+curl -X POST http://localhost:8000/api/v1/eval/settle \
+  -H "Content-Type: application/json" \
+  -d '{"prediction_id": 1, "home_goals": 2, "away_goals": 1}'
+
+# 汇总准确率(按 模型 × prompt 版本,含 multi/single 对比)
+curl http://localhost:8000/api/v1/eval/summary
+```
+
+## 常见问题
+
+| 问题 | 处理 |
+|---|---|
+| 连不上数据库 | `docker compose ps` 确认 postgres 健康;`.env` 的 `DATABASE_URL` 与 compose 一致 |
+| predict 返回 502 | 看 uvicorn 日志的 LLM error;确认 `LLM_BASE_URL`/`LLM_API_KEY`;`response_format` 不兼容的网关会报错(改用支持 json mode 的模型) |
+| 采集 0 场 | bzzoiro Key 失效或联赛代码写错;先 `GET /api/v1/leagues` 看库里有没有联赛 |
+| 专家报告全是 no_data | 历史数据不够 —— 近况需要每队近 5 场、积分榜需要本赛季已完赛比赛,多拉几周数据 |
+| xg agent 报无 xG 数据 | 先跑 understat 回填;注意 understat 只有五大联赛 |