2569718930@qq.com
250 lines
5.5 KiB
Markdown
250 lines
5.5 KiB
Markdown
# PolyWeather API 文档（v1.3）
|
||
|
||
本文档描述当前后端真实可用接口（`web/app.py`）。
|
||
前端一般通过 Next.js BFF 路由代理访问这些接口。
|
||
|
||
---
|
||
|
||
## 1. 基础信息
|
||
|
||
- 本地地址：`http://127.0.0.1:8000`
|
||
- 生产地址：`http://<vps-ip>:8000` 或你绑定的 HTTPS 域名
|
||
- 返回格式：`application/json`
|
||
- 缓存策略：
|
||
- 后端分析缓存：默认 5 分钟（Ankara 特殊口径 60 秒）
|
||
- 前端详情缓存：5 分钟 + revision 检查
|
||
- 手动刷新：`force_refresh=true` 强制绕过缓存
|
||
|
||
---
|
||
|
||
## 2. API 思维导图
|
||
|
||
```mermaid
|
||
mindmap
|
||
root((PolyWeather API))
|
||
城市列表
|
||
GET /api/cities
|
||
城市主数据
|
||
GET /api/city/{name}
|
||
GET /api/city/{name}/summary
|
||
GET /api/city/{name}/detail
|
||
历史数据
|
||
GET /api/history/{name}
|
||
关键对象
|
||
current
|
||
forecast
|
||
probabilities(mu + distribution)
|
||
multi_model / multi_model_daily
|
||
market_scan(P0 只读)
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 接口总览
|
||
|
||
| 接口 | 方法 | 用途 |
|
||
| :-- | :-- | :-- |
|
||
| `/api/cities` | GET | 城市清单与地图基础信息 |
|
||
| `/api/city/{name}` | GET | 城市主分析数据（侧栏/今日分析主来源） |
|
||
| `/api/city/{name}/summary` | GET | 轻量摘要（首屏预热/低开销更新） |
|
||
| `/api/city/{name}/detail` | GET | 聚合详情 + Polymarket P0 只读市场层 |
|
||
| `/api/history/{name}` | GET | 历史对账数据 |
|
||
|
||
---
|
||
|
||
## 4. 关键接口详解
|
||
|
||
### 4.1 `GET /api/cities`
|
||
|
||
返回监控城市列表（地图 Marker 与侧边栏基础数据）。
|
||
|
||
示例：
|
||
|
||
```json
|
||
{
|
||
"cities": [
|
||
{
|
||
"name": "ankara",
|
||
"display_name": "Ankara",
|
||
"lat": 39.9334,
|
||
"lon": 32.8597,
|
||
"risk_level": "medium",
|
||
"risk_emoji": "🟠",
|
||
"airport": "Esenboğa",
|
||
"icao": "LTAC",
|
||
"temp_unit": "celsius",
|
||
"is_major": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 4.2 `GET /api/city/{name}`
|
||
|
||
主数据接口，前端详情面板和今日分析最常用。
|
||
|
||
可选参数：
|
||
|
||
- `force_refresh=true|false`
|
||
|
||
核心字段：
|
||
|
||
- `name`, `display_name`, `local_date`, `local_time`, `temp_symbol`
|
||
- `risk`
|
||
- `current`
|
||
- `forecast`
|
||
- `mgm`, `mgm_nearby`
|
||
- `multi_model`, `multi_model_daily`
|
||
- `deb`
|
||
- `ensemble`
|
||
- `probabilities`（`mu` + `distribution`）
|
||
- `trend`, `peak`
|
||
- `hourly`, `hourly_next_48h`
|
||
- `source_forecasts`（当前只保留 `weather_gov`）
|
||
- `market_scan`
|
||
- `updated_at`
|
||
|
||
说明：
|
||
|
||
- `current.raw_metar` 是原始 METAR 报文。
|
||
- Ankara 专项增强使用 MGM 站网，领先站固定 `17130`。
|
||
- Meteoblue 已彻底移除，不再出现在接口字段中。
|
||
|
||
### 4.3 `GET /api/city/{name}/summary`
|
||
|
||
轻量温度摘要，用于地图首屏预热和低成本刷新。
|
||
|
||
典型字段：
|
||
|
||
- `name`, `display_name`, `icao`
|
||
- `local_time`, `temp_symbol`
|
||
- `current.temp`, `current.obs_time`
|
||
- `deb.prediction`
|
||
- `risk.level`, `risk.warning`
|
||
- `updated_at`
|
||
|
||
### 4.4 `GET /api/city/{name}/detail`
|
||
|
||
聚合视图接口，包含天气分析和市场只读层。
|
||
|
||
可选参数：
|
||
|
||
- `force_refresh=true|false`
|
||
- `market_slug=<slug>`（调试/定向市场匹配）
|
||
|
||
关键结构：
|
||
|
||
- `overview`
|
||
- `official`
|
||
- `timeseries`
|
||
- `models`
|
||
- `probabilities`
|
||
- `market_scan`
|
||
- `risk`
|
||
- `ai_analysis`
|
||
|
||
`market_scan`（P0 只读）重点字段：
|
||
|
||
- `primary_market`, `selected_condition_id`, `selected_slug`
|
||
- `yes_token`, `no_token`
|
||
- `yes_buy`, `yes_sell`, `no_buy`, `no_sell`
|
||
- `market_price`, `model_probability`, `edge_percent`
|
||
- `temperature_bucket`
|
||
- `top_buckets`（前端展示前会再去重）
|
||
- `signal_label`（`BUY YES` / `BUY NO` / `MONITOR`）
|
||
- `websocket.asset_ids`, `websocket.condition_ids`（订阅标识，不涉及下单）
|
||
|
||
注意：
|
||
|
||
- 后端已做温度桶去重与方向优先（优先与主市场同方向的 `or higher`/`or lower` 桶）。
|
||
- 前端还有二次去重兜底，避免重复温度桶刷屏。
|
||
|
||
### 4.5 `GET /api/history/{name}`
|
||
|
||
历史对账数据来源。
|
||
|
||
示例：
|
||
|
||
```json
|
||
{
|
||
"history": [
|
||
{
|
||
"date": "2026-03-07",
|
||
"actual": 7.0,
|
||
"deb": 6.5,
|
||
"mu": 7.2,
|
||
"mgm": 8.0
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 请求链路（以 `/api/city/{name}` 为例）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant FE as Frontend
|
||
participant API as FastAPI
|
||
participant WX as Weather Collector
|
||
participant PM as Polymarket RO Layer
|
||
|
||
FE->>API: GET /api/city/{name}?force_refresh=...
|
||
API->>WX: fetch_all_sources(city)
|
||
WX-->>API: METAR / MGM / Open-Meteo / weather.gov / Multi-model
|
||
API->>API: DEB + trend + probability
|
||
API->>PM: build_market_scan(...)
|
||
PM-->>API: market_scan (read-only)
|
||
API-->>FE: merged city payload
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 数据口径
|
||
|
||
### 6.1 主观测
|
||
|
||
- Aviation Weather / METAR 是全局主观测源。
|
||
- Ankara：结算主站仍是 `LTAC`，领先信号强化使用 MGM（`17130`）。
|
||
|
||
### 6.2 预测源
|
||
|
||
- Open-Meteo
|
||
- weather.gov（美国城市）
|
||
- 多模型：ECMWF / GFS / ICON / GEM / JMA
|
||
|
||
### 6.3 概率口径
|
||
|
||
- `mu`：动态分布中心，不是固定结算值。
|
||
- `distribution`：按温度桶输出概率分布，面向结算决策而非通用天气展示。
|
||
|
||
---
|
||
|
||
## 7. 常见问题
|
||
|
||
### 7.1 接口 500
|
||
|
||
- 先检查容器是否启动：`docker compose ps`
|
||
- 查看日志：`docker compose logs -f polyweather_web`
|
||
|
||
### 7.2 METAR 看起来“延迟”
|
||
|
||
优先核对：
|
||
|
||
- `current.obs_time`
|
||
- `current.report_time`
|
||
- `current.receipt_time`
|
||
|
||
通常是上游发布节奏，不一定是本地轮询问题。
|
||
|
||
### 7.3 前端仍显示旧内容
|
||
|
||
- 确认 Vercel 已部署最新构建
|
||
- 浏览器强刷（`Ctrl+F5`）
|
||
- 检查是否命中前端 5 分钟 TTL
|
||
|
||
---
|
||
|
||
最后更新：`2026-03-11`
|