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

本文档说明当前 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
- **缓存策略**:
  - `/api/cities`: 5 分钟
  - `/api/city/{name}`: 30 秒
  - `/api/history/{name}`: 15 分钟
  - `/api/city/{name}/summary`: 30 秒
  - `/api/city/{name}/detail`: 30 秒

---

## 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` 时跳过缓存
- **用途**: 首页右侧详情面板与地图数据的主接口。

**当前核心字段**

- `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`
- `updated_at`

**说明**

- `current.raw_metar` 现在直接透出 Aviation Weather API 返回的原始 METAR 报文。
- `mgm` 只对 Ankara 这类确实有 Turkish MGM 覆盖的城市有值。
- `mgm_nearby` 当前是一个复用字段：
  - Ankara: Turkish MGM 周边站
  - 多数其他城市: AviationWeather 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
    }
  ]
}
```

**说明**

- 网页端历史对账只统计 **近 15 天已结算样本**
- 当天未结算样本可以画在图里，但不计入胜率与 MAE

### 2.4 获取城市摘要

- **URL**: `/api/city/{name}/summary`
- **Method**: `GET`
- **用途**: 轻量摘要接口，适合未来做 hover 预取或低开销列表更新。

**字段**

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

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

- **URL**: `/api/city/{name}/detail`
- **Method**: `GET`
- **用途**: 面向未来的单请求聚合详情接口，便于把 `city + summary + history + future analysis` 整合到一个载荷中。

**当前结构**

- `overview`
- `official`
- `timeseries`
- `models`
- `probabilities`
- `future`

**说明**

- 当前首页 legacy 布局还主要使用 `/api/city/{name}` 和 `/api/history/{name}`
- `/api/city/{name}/detail` 已用于后续更完整详情态的聚合设计

---

## 3. 核心对象定义

### 3.1 风险等级

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

### 3.2 DEB

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

- 多模型预测值
- 近期表现
- 实况修正
- 城市级偏置

### 3.3 μ

`μ` 代表当前结算分布中心，是一个**动态期望值**，会随着模型、实况、趋势变化而变化。  
它不应直接与固定 forecast 用同一口径做静态历史对账。

---

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

### 4.1 主观测源

- **Aviation Weather / METAR**
  - 当前全球机场主观测源
  - 同时提供结构化字段与 `rawOb`

### 4.2 Ankara 专属源

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

### 4.3 预测源

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

---

## 5. 当前口径说明

- 首页地图主 marker 显示 **当前温度**
- 右侧详情面板展示当前实测、DEB、结算概率、多模型、多日预报
- 未来日期分析模态框：
  - 显示温度走势、结算概率分布、多模型预报、未来 6-48 小时趋势、未来 0-2 小时临近判断
  - 已移除独立“冷锋 / 暖锋判断”模块

---

## 6. 常见问题

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

- **METAR 看起来慢几分钟**
  - 通常是官方链路入库/发布延迟，不一定是本地轮询慢
  - 请同时看：
    - `current.obs_time`
    - `current.report_time`
    - `current.receipt_time`

- **网页显示旧内容**
  - 先确认 Vercel 已部署新版本
  - 再强刷浏览器缓存

---

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