PolyWeather/README_ZH.md

PolyWeather Pro

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

官方看板：polyweather-pro.vercel.app

产品截图

全球看板

城市分析（Ankara）

这个项目在做什么

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

概览图

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

系统架构

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）

docker compose up -d --build

前端本地运行

cd frontend
npm install
npm run dev

前端构建校验

cd frontend
npm run build

运维验收

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

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

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

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 + 市场只读层）