# 03 · API 参考

Base URL: `http://localhost:8000` · 交互式文档: `/docs`(Swagger)与 `/redoc`

所有数据端点返回 JSON。错误统一为 `{"detail": "<message>"}` + 对应 HTTP 状态码。

---

## 数据查询

### `GET /api/v1/leagues`

列出已入库联赛。

```json
[{"id": 1, "code": "E0", "name": "Premier League", "country": "England"}]
```

### `GET /api/v1/matches`

比赛列表,游标分页。

| 参数 | 说明 |
|---|---|
| `league` | 联赛代码,如 `E0` / `SP1` / `D1` / `I1` / `F1` |
| `status` | `scheduled` / `finished`(不传 = 全部) |
| `date` | `YYYY-MM-DD`,当天比赛 |
| `cursor` | 上一页返回的 `next_cursor` |
| `limit` | 1–100,默认 50 |

响应(倒序,含双方中文名与 xG):

```json
{
  "items": [
    {"id": 42, "league_code": "E0", "season": "2026-2027",
     "home_team": "Arsenal", "away_team": "Manchester United",
     "home_team_zh": null, "away_team_zh": null,
     "match_date": "2026-09-15T19:00:00Z", "match_status": "scheduled",
     "home_goals": null, "away_goals": null,
     "match_stage": "第 5 轮", "home_xg": null, "away_xg": null}
  ],
  "next_cursor": "2026-09-15T19:00:00+00:00|41",
  "has_more": true
}
```

### `GET /api/v1/matches/{id}`

单场比赛详情,字段同上。

---

## 预测

### `POST /api/v1/predict`

对一场比赛做 LLM 预测。**核心端点。**

请求:

```json
{
  "match_id": 42,
  "mode": "multi",
  "model": "gpt-4o",
  "prompt_version": "v1"
}
```

| 字段 | 默认 | 说明 |
|---|---|---|
| `match_id` | 必填 | 比赛 ID |
| `mode` | `multi` | `multi` = 5 专家 + 终裁;`single` = 单次调用 |
| `model` | 配置值 | 覆盖本次模型(single 模式下生效) |
| `prompt_version` | `v1` | prompt 版本(multi 模式即 agent prompt 版本) |

响应(multi 模式):

```json
{
  "prediction_id": 7,
  "provider": "openai",
  "model": "gpt-4o",
  "prompt_version": "multi_v1",
  "mode": "multi",
  "pred_home_goals": 2.1,
  "pred_away_goals": 1.0,
  "pred_1x2": "1",
  "subjective_confidence": 0.68,
  "reasoning": "综合 xg 报告的进球期望 2.1-1.0 与 form 报告的三连胜势头……",
  "agent_outputs": [
    {"agent": "h2h", "status": "ok", "data_sufficiency": "medium",
     "analysis": "近 5 次交锋主队 3 胜……", "home_edge": 0.4,
     "subjective_confidence": 0.7, "key_evidence": ["近5次交锋主队3胜", "主场交锋3连胜"],
     "exp_home_goals": null, "exp_away_goals": null, "probable_score": null,
     "model": "gpt-4o-mini", "latency_ms": 2100,
     "prompt_tokens": 380, "completion_tokens": 120},
    {"agent": "injuries", "status": "no_data", "data_sufficiency": "none",
     "analysis": "该维度无数据,跳过分析。", "home_edge": null, "subjective_confidence": null,
     "key_evidence": [], "exp_home_goals": null, "exp_away_goals": null,
     "probable_score": null, "model": "", "latency_ms": null,
     "prompt_tokens": null, "completion_tokens": null}
  ],
  "agent_weights": {"form": 0.9, "stats": 0.8, "home_away": 0.7, "injuries": 0.0, "h2h": 0.8},
  "context": "[5 份报告的 JSON 串]",
  "latency_ms": 9800
}
```

`agent.status` 取值:`ok` / `no_data`(维度无数据,已跳过 LLM)/ `error`(调用失败,fail-open 不阻断)/ `parse_error`。

错误:404 比赛不存在;502 LLM 调用失败(终裁失败时整体失败,专家失败不会)。

### `GET /api/v1/predictions?match_id=&limit=`

预测历史(倒序),含 `settled` 与实际比分回填状态。

### `GET /api/v1/predictions/{id}`

单条预测详情(含完整 `agent_outputs`)。

---

## 数据采集

### `POST /api/v1/ingest/bzzoiro`

从 bzzoiro 采集赛果/赛程并入库(幂等,重复跑安全)。

```json
{"leagues": ["E0", "SP1"], "date_from": "2025-08-01", "date_to": "2026-09-08", "status": "finished"}
```

- `status` 还可传 `scheduled` 拉未来赛程
- 响应含每联赛 `inserted`/`updated`/`errors` 统计

### `POST /api/v1/ingest/understat`

回填 xG(只补空字段,不创建比赛):

```json
{"league": "E0", "season": 2025}
```

`season=2025` 表示 2025-2026 赛季。仅支持五大联赛。

### `POST /api/v1/ingest/injuries`

采集伤停(需 `API_FOOTBALL_KEY`,当前只返回计数,尚未接入 context):

```json
{"date": "2026-09-10"}
```

---

## 评估

### `POST /api/v1/eval/settle`

赛后回填实际比分:

```json
{"prediction_id": 7, "home_goals": 2, "away_goals": 1}
```

### `GET /api/v1/eval/summary`

按 `provider × model` 聚合已结算预测:

```json
{"summary": [
  {"provider": "openai", "model": "gpt-4o", "total": 12,
   "accuracy_1x2": 58.3, "avg_score_rmse": 1.21, "avg_subjective_confidence": 0.65}
]}
```

> 提示:multi 模式存的 `model` 是终裁模型、`prompt_version` 是 `multi_v1`,
> 因此 summary 里天然可对比 multi vs single、以及不同 prompt 版本的效果。

---

## 基础

| 端点 | 说明 |
|---|---|
| `GET /health` | 存活检查 |
| `GET /docs` | Swagger UI |