PolyWeather/docs/API_ZH.md

# PolyWeather API 接口文档 (v1.2)

本文档说明当前 PolyWeather 后端实际提供的 HTTP API。后端由 `web/app.py` 提供，前端通过 Next.js BFF 路由代理访问这些接口。

---

## 1. 基础信息

- **本地 Base URL**: `http://127.0.0.1:8000`
- **生产 Base URL**: `http://<your-vps-ip>:8000` 或绑定后的 HTTPS API 域名
- **响应格式**: JSON
- **缓存策略**:
  - 后端 `web/app.py` 内部分析缓存：默认 5 分钟（Ankara 为 60 秒）
  - 前端城市详情缓存：5 分钟 TTL + revision 校验
  - 前端手动刷新：强制 `force_refresh=true` 跳过缓存

---

## 2. 接口列表

### 2.1 获取监控城市列表

- **URL**: `/api/cities`
- **Method**: `GET`
- **用途**: 返回首页左侧监控城市与地图 marker 的基础元数据。

**响应示例**

```json
{
  "cities": [
    {
      "name": "ankara",
      "display_name": "Ankara",
      "lat": 40.1281,
      "lon": 32.9951,
      "risk_level": "medium",
      "risk_emoji": "🟠",
      "airport": "Esenboğa",
      "icao": "LTAC",
      "temp_unit": "celsius",
      "is_major": true
    }
  ]
}
```

### 2.2 获取城市实时分析

- **URL**: `/api/city/{name}`
- **Method**: `GET`
- **参数**:
  - `name`: 城市名或别名，如 `ankara`、`new-york`
  - `force_refresh` (可选): `true` 时跳过缓存
- **用途**: 右侧详情卡片、今日分析 modal、图表和周边站点的主数据接口。

**当前核心字段**

- `display_name`
- `local_time`
- `local_date`
- `temp_symbol`
- `risk`
- `current`
- `mgm`
- `mgm_nearby`
- `forecast`
- `multi_model`
- `deb`
- `ensemble`
- `probabilities`
- `trend`
- `metar_today_obs`
- `metar_recent_obs`
- `hourly`
- `hourly_next_48h`
- `source_forecasts`
- `multi_model_daily`
- `updated_at`

**说明**

- `current.raw_metar` 为 Aviation Weather 返回的原始报文字段。
- `mgm` 仅在具备官方 MGM 覆盖的城市（如 Ankara）有效。
- `mgm_nearby` 为统一周边站点字段：
  - Ankara：MGM 官方周边站
  - 其他多数城市：METAR cluster

### 2.3 获取历史对账数据

- **URL**: `/api/history/{name}`
- **Method**: `GET`
- **用途**: 历史对账弹窗与 `/deb` 指令的历史样本来源。

**响应示例**

```json
{
  "history": [
    {
      "date": "2026-03-07",
      "actual": 7.0,
      "deb": 6.5,
      "mu": 7.2,
      "mgm": 8.0
    }
  ]
}
```

**说明**

- 网页端历史图默认展示近期样本，但统计口径只使用已结算日期。
- 当天未结算样本可用于可视化趋势，不计入胜率与 MAE。

### 2.4 获取城市摘要

- **URL**: `/api/city/{name}/summary`
- **Method**: `GET`
- **用途**: 轻量级温度摘要接口，用于首屏地图温度预热与低开销列表更新。

**字段**

- `name`
- `display_name`
- `icao`
- `local_time`
- `temp_symbol`
- `current.temp`
- `current.obs_time`
- `deb.prediction`
- `risk.level`
- `risk.warning`
- `updated_at`

### 2.5 获取城市聚合详情

- **URL**: `/api/city/{name}/detail`
- **Method**: `GET`
- **用途**: 商业化聚合视图单请求接口（已接入 P0 只读价格层）。
- **可选参数**:
  - `force_refresh=true|false`
  - `market_slug=<slug>`（调试优先直查；传入后优先按 slug 精确定位市场，跳过自动发现）

**当前结构**

- `overview`
- `official`
- `timeseries`
- `models`
- `probabilities`
- `market_scan`
- `risk`
- `ai_analysis`

**说明**

- 当前生产前端主链路仍以 `/api/city/{name}` + `/api/history/{name}` 为主。
- `/api/city/{name}/detail` 当前已包含 Polymarket P0 只读字段：
  - `primary_market`
  - `selected_condition_id`
  - `yes_token` / `no_token`
  - `yes_buy` / `yes_sell` / `no_buy` / `no_sell` / `model_probability`
  - `market_price`（优先 midpoint）
  - `edge_percent`（`(model_probability - market_price) * 100`）
  - `temperature_bucket` / `top_buckets` （结算温度桶及市场概率）
  - `signal_label`（`BUY YES` / `BUY NO` / `MONITOR`）
  - `websocket.asset_ids` / `websocket.condition_ids`（仅用于订阅标识，P0 不下单）

---

## 3. 核心对象定义

### 3.1 风险等级

- `low`: 低风险，模型与实测整体较一致
- `medium`: 中风险，存在一定分歧或站点偏置
- `high`: 高风险，模型冲突较大或盘面波动价值高

### 3.2 DEB

`DEB` 是 PolyWeather 的动态融合预测层，不是简单平均值。它会综合：

- 多模型预测值
- 近期表现
- 城市级偏差特征
- 实况修正上下文

### 3.3 μ

`μ` 表示当前结算概率分布中心（动态期望值），会随模型分歧与实况变化而更新。  
它不应直接按固定 forecast 口径做静态历史对账。

---

## 4. 数据源与第三方 API

### 4.1 主观测源

- **Aviation Weather / METAR**
  - 全球机场主观测源
  - 同时提供结构化字段与原始 METAR 报文

### 4.2 Ankara 专属源

- **Turkish MGM**
  - Ankara 官方增强层
  - 含 `Ankara (Bölge/Center)` 与周边站点

### 4.3 预测源

- **Open-Meteo**
- **weather.gov**（美国城市）
- **Meteoblue**（部分城市）
- **多模型集成**: ECMWF / GFS / ICON / GEM / JMA

---

## 5. 当前口径说明

- 地图 marker 显示当前温度（首屏通过 `summary` 预热）。
- 点击城市后打开右侧详情卡片，保持当前布局与样式不变。
- “今日日内分析”在 modal 中展示：
  - 今日温度走势（含 METAR 实测点）
  - 结算概率分布
  - 多模型预报
  - 今日日内结构信号（规则引擎）
  - AI 深度分析 + 0-2 小时临近判断
- modal 打开时地图停止动画；点击空白地图仅关闭右侧卡片，不重置视角。

---

## 6. 常见问题

- **接口 500**
  - 先检查 `polyweather_web` 是否启动成功
  - 再看 `docker-compose logs -f polyweather_web`

- **METAR 看起来慢几分钟**
  - 常见原因是上游发布延迟，不一定是本地轮询问题
  - 建议同时查看：
    - `current.obs_time`
    - `current.report_time`
    - `current.receipt_time`

- **网页显示旧内容**
  - 先确认 Vercel 已部署最新版本
  - 再强刷浏览器缓存
  - 如为详情数据，确认是否命中前端 5 分钟 TTL

---

**最后更新**: 2026-03-10