# PolyWeather Pro

面向温度结算市场的生产级气象情报系统。

官方看板：[polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/)

## 产品截图

### 全球看板

![PolyWeather 全球地图看板](docs/images/demo_map.png)

### 城市分析（Ankara）

![PolyWeather Ankara 分析页](docs/images/demo_ankara.png)

## 这个项目在做什么

- 聚合监控城市的实测与预报数据。
- 用 DEB（Dynamic Error Balancing）做动态融合预测。
- 计算结算导向的温度概率分布（`μ` + 温度桶）。
- 将模型概率与 Polymarket 只读市场数据对齐，输出错价/风险信号。
- Web 仪表盘与 Telegram 机器人共用同一套核心逻辑。

## 概览图

```mermaid
flowchart TD
    A["PolyWeather Pro"]

    subgraph DL["数据层"]
        DL1["METAR (Aviation Weather / METAR)"]
        DL2["MGM (土耳其 MGM)"]
        DL3["安卡拉主站 (17130 Center)"]
        DL4["Open-Meteo"]
        DL5["weather.gov (美国城市)"]
        DL6["Polymarket (P0 只读)"]
    end

    subgraph AL["分析层"]
        AL1["DEB (动态误差平衡)"]
        AL2["概率引擎 (mu + 桶分布)"]
        AL3["趋势引擎"]
        AL4["城市风险档案"]
        AL5["错价雷达"]
    end

    subgraph DEL["交付层"]
        DEL1["FastAPI"]
        DEL2["Next.js 仪表盘"]
        DEL3["Telegram Bot"]
        DEL4["预警推送"]
    end

    subgraph OL["运维层"]
        OL1["Docker Compose (VPS)"]
        OL2["Vercel (前端)"]
        OL3["缓存 + force_refresh"]
        OL4["Speed Insights"]
    end

    A --> DL
    A --> AL
    A --> DEL
    A --> OL
```

## 系统架构

```mermaid
graph TD
    User[Web / Telegram 用户] --> FE[Vercel Next.js 前端]
    User --> Bot[VPS Telegram Bot]
    FE --> API[FastAPI 服务]
    Bot --> API

    API --> WX[Weather Collector]
    WX --> METAR[METAR / Aviation Weather]
    WX --> MGM[MGM API / 周边站]
    WX --> OM[Open-Meteo]
    WX --> NWS[weather.gov]

    API --> DEB[DEB + 趋势 + 概率引擎]
    API --> PM[Polymarket 只读层]
    PM --> Gamma[Gamma API]
    PM --> CLOB[CLOB / py-clob-client]
```

## 当前数据源口径

| 领域           | 当前口径                          |
| :------------- | :-------------------------------- |
| 主观测源       | Aviation Weather / METAR          |
| Ankara 增强    | MGM + 周边站，领先站固定 `17130`  |
| 预报基线       | Open-Meteo                        |
| 美国官方语义层 | weather.gov                       |
| 市场层         | Polymarket P0 只读发现 + 报价     |
| 已移除         | Meteoblue（代码与文档已全部移除） |

## 最近更新（2026-03-12）

- 完整移除 Meteoblue API 及全部引用。
- 前端 BFF 增加 `ETag + Cache-Control`：
  - `/api/cities`
  - `/api/city/{name}/summary`（`force_refresh=true` 仍保持 `no-store`）
  - `/api/history/{name}`
- 前端状态持久化优化：
  - 记住上次选中城市（`localStorage`）
  - 记住侧边栏风险分组折叠状态（`localStorage`）
  - 详情命中缓存时做后台 revision 检查，静默更新陈旧数据
- 错价雷达安全加固：
  - 市场 `closed` / 不活跃 / 不接受下单 / 超过 `endDate` 时跳过推送
  - `market_scan.primary_market` 透传可交易状态字段
- AI 决策时段约束：
  - 上下文显式注入峰值窗口状态（`before` / `in_window` / `past`）
  - 峰值窗口前禁止“已锁定/已确认底线”结论
- 修复市场“最热温度桶”重复温度刷屏问题（后端按温度去重 + 前端兜底去重）。
- 修复详情面板可访问性告警（`aria-hidden` 焦点冲突），改为 `inert + blur`。
- 集成 Vercel Speed Insights（`frontend/app/layout.tsx`）。

## 目录说明

- 前端：`frontend/`（Next.js App Router）
- 后端：`web/app.py` 与 `src/`
- 机器人：`bot_listener.py` + `src/analysis/*`
- 文档：`docs/`

## 快速启动

### 后端 + 机器人（VPS / Docker）

```bash
docker compose up -d --build
```

### 前端本地运行

```bash
cd frontend
npm install
npm run dev
```

### 前端构建校验

```bash
cd frontend
npm run build
```

## 运维验收

### 验证前端缓存头（`ETag` / `304` / `force_refresh=no-store`）

```bash
./scripts/validate_frontend_cache.sh "https://polyweather-pro.vercel.app"
```

### 观察错价雷达推送决策日志

```bash
docker compose logs -f polyweather | egrep "market not tradable|trade alert pushed|mispricing cap"
```

## Telegram 命令

| 命令           | 用途         |
| :------------- | :----------- |
| `/city <name>` | 城市实时分析 |
| `/deb <name>`  | DEB 历史对账 |
| `/top`         | 用户排行榜   |
| `/help`        | 帮助说明     |

## 文档索引

- API 文档（中文）：`docs/API_ZH.md`
- 商业化路线：`docs/COMMERCIALIZATION.md`
- 技术债（英文）：`docs/TECH_DEBT.md`
- 技术债（中文）：`docs/TECH_DEBT_ZH.md`
- 英文总览：`README.md`

## 当前状态

- 版本：`v1.3`
- 最后更新：`2026-03-12`
- 状态：稳定运行（Web + Bot + 市场只读层）