gavindiaz/PolyWeather
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: fully migrate frontend to a React component-driven architecture and expand project documentation.

Browse Source
This commit is contained in:
2569718930@qq.com
2026-03-09 10:53:23 +08:00
parent 283a935f24
commit 243bf6c33b
6 changed files with 178 additions and 163 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+38 -37
View File
@@ -1,22 +1,22 @@
# 🌡️ PolyWeather Pro # 🌡️ PolyWeather Pro
> **Professional Weather Intelligence System** —— Specialized in edge data collection, DEB smart blending, and real-time decision alerts. > **Professional Weather Intelligence System** — Specialized in edge data collection, DEB smart blending, and real-time decision alerts.
--- ---
## 💎 Project Vision ## 💎 Project Vision
PolyWeather is a specialized intelligence system built for **Polymarket** high-stakes participants. We don't just provide weather forecasts; we aggregate data from top-tier global meteorological sources, apply our proprietary **DEB (Dynamic Error Balancing)** algorithm, and deliver **market-shifting alerts** at critical decision nodes. PolyWeather is a specialized intelligence system built for **Polymarket** high-stakes participants. We aggregate top-tier meteorological sources, apply proprietary **DEB (Dynamic Error Balancing)** logic, and surface **actionable shift signals** at critical decision windows.
--- ---
## 🏗️ Production Architecture ## 🏗️ Production Architecture
This project utilizes a production-grade decoupled architecture for high availability: This project uses a decoupled production setup for reliability and iteration speed:
- **Frontend**: A **Next.js** interactive dashboard deployed on **Vercel**. - **Frontend**: A **Next.js** dashboard on **Vercel** with React component rendering.
- **Backend API**: A **FastAPI** service running on a VPS, providing low-latency data access. - **Backend API**: A **FastAPI** service on VPS for low-latency weather aggregation and analysis.
- **Bot & Alert Heartbeat**: A **Telegram Bot** running on a VPS, executing minute-level global scans and push notifications. - **Bot & Alert Heartbeat**: A **Telegram Bot** on VPS for minute-level scanning and push alerts.
🔗 **Official Visit**: [polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/) 🔗 **Official Visit**: [polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/)
@@ -27,13 +27,13 @@ This project utilizes a production-grade decoupled architecture for high availab
<p align="center"> <p align="center">
<img src="docs/images/demo_ankara.png" alt="PolyWeather Demo - Ankara Live Analysis" width="450"> <img src="docs/images/demo_ankara.png" alt="PolyWeather Demo - Ankara Live Analysis" width="450">
<br> <br>
<em>📊 <b>Deep Query View</b>: DEB Blended Forecast + Settlement Probability + Groq AI Expert Advice</em> <em>📊 <b>Deep Query View</b>: DEB blended forecast + settlement probability + AI analysis context</em>
</p> </p>
<p align="center"> <p align="center">
<img src="./docs/images/demo_map.png" alt="PolyWeather Web Map" width="850"> <img src="./docs/images/demo_map.png" alt="PolyWeather Web Map" width="850">
<br> <br>
<em>🗺️ <b>Omni-Dashboard</b>: Real-time global heatmaps + array-style data visualization</em> <em>🗺️ <b>Omni-Dashboard</b>: global station markers + nearby station context + right-side city intelligence panel</em>
</p> </p>
--- ---
@@ -41,18 +41,19 @@ This project utilizes a production-grade decoupled architecture for high availab
## 🚀 Core Features ## 🚀 Core Features
- **📡 Full-Spectrum Collection** - **📡 Full-Spectrum Collection**
- **Major Models**: Real-time sync for ECMWF, GFS, ICON, GEM, JMA, and Open-Meteo daily/hourly guidance. - **Major Models**: ECMWF, GFS, ICON, GEM, JMA, Open-Meteo, and city-level daily/hourly guidance.
- **Observed Data**: Aviation Weather / METAR as the primary observation source, plus official Turkish MGM station-level data for Ankara. - **Observed Data**: Aviation Weather / METAR as the primary observation source, plus Turkish MGM coverage for Ankara.
- **City Specialization**: Integrated `17130` (`Ankara (Bölge/Center)`) as the key Ankara lead station, without replacing LTAC settlement observation. - **City Specialization**: `17130` (`Ankara (Bölge/Center)`) remains the Ankara lead station without replacing LTAC settlement observation.
- **⚖️ DEB Smart Blending** - **⚖️ DEB Smart Blending**
- Dynamic weighting of forecasts based on recent historical performance and city-specific reliability. - Dynamic weighting based on city-level performance and current model spread.
- **🧩 React Dashboard Runtime**
- Typed store + typed API client + Leaflet/Chart.js lifecycle wrappers.
- City click workflow: map focus + right panel open + nearby stations render.
- Today analysis workflow: open modal + freeze map motion.
- **🔔 Alert Engine** - **🔔 Alert Engine**
- **Momentum Spike**: Captures rapid temperature changes within 30 minutes. - **Momentum Spike**: Captures rapid short-window temperature slope changes.
- **Forecast Breakthrough**: Fires when observations exceed all model predictions plus a safety margin. - **Forecast Breakthrough**: Fires when observations break model envelopes plus margin.
- **Advection Monitoring**: Simulates warm/cold advection based on lead stations and wind currents. - **Advection Monitoring**: Tracks warm/cold advection using lead-station behavior and wind direction.
- **🛡️ Smart Suppression**
- **Peak Protection**: Automatically switches to snapshot mode when the daily high has likely passed.
- **Cooldown Management**: Global and city-level cooldowns to prevent notification fatigue.
--- ---
@@ -73,14 +74,15 @@ This project utilizes a production-grade decoupled architecture for high availab
- **Ankara enhancement**: - **Ankara enhancement**:
- Settlement observation: `LTAC / Esenboğa` - Settlement observation: `LTAC / Esenboğa`
- Official lead station: `Ankara (Bölge/Center)` / `17130` - Official lead station: `Ankara (Bölge/Center)` / `17130`
- Nearby station layer: Turkish MGM station network - Nearby station layer: Turkish MGM network (Ankara-specific preferred station ordering)
- **Other cities nearby layer**: - **Other cities nearby layer**:
- Current production logic uses Aviation Weather METAR clusters - Production currently uses Aviation Weather METAR clusters
- U.S. cities may later receive Mesonet augmentation, but METAR remains the base layer - U.S. cities may later receive Mesonet augmentation while METAR stays baseline
- **Historical benchmarking rules**: - **Frontend request optimization**:
- Web dashboard: rolling last 15 settled days - Initial map temperatures preload via `/api/city/{name}/summary`
- Telegram `/deb`: rolling last 7 settled days - City detail cache TTL = 5 minutes, revision probe avoids unnecessary refetch
- The current in-progress day is excluded from win rate and MAE - Map movements, panel toggles, and modal open/close do not trigger redundant requests
- Manual refresh always bypasses cache (`force_refresh=true`)
--- ---
@@ -89,19 +91,17 @@ This project utilizes a production-grade decoupled architecture for high availab
```mermaid ```mermaid
graph TD graph TD
subgraph "Client / Terminals" subgraph "Client / Terminals"
Web[Next.js Web App] Web[Next.js React Web App]
TG[Telegram Client] TG[Telegram Client]
end end
subgraph "Edge Deployment (Vercel)" subgraph "Edge Deployment (Vercel)"
Web -.-> |Auth| Supa[(Supabase Auth/DB)] Web --> |BFF Routes| Fast[FastAPI API]
Web --> |API| Fast[FastAPI API]
end end
subgraph "Core Hub (VPS)" subgraph "Core Hub (VPS)"
Fast --- |Shared Logic| Worker[Alert Engine / Worker] Fast --- |Shared Logic| Worker[Alert Engine / Worker]
Bot[Telegram Bot] --- |Shared Logic| Worker Bot[Telegram Bot] --- |Shared Logic| Worker
Worker --> |Cache/Sub| Supa
end end
subgraph "External Sources" subgraph "External Sources"
@@ -122,7 +122,7 @@ graph TD
### 1. Backend / Bot (VPS) ### 1. Backend / Bot (VPS)
```bash ```bash
# Pull Source # Pull source
git pull git pull
# Environment # Environment
@@ -134,7 +134,7 @@ docker-compose up -d --build
### 2. Frontend (Vercel) ### 2. Frontend (Vercel)
Associate the `frontend` directory as the project root on Vercel for automatic CI/CD. Set `frontend` as the Vercel root directory for automatic CI/CD.
--- ---
@@ -150,18 +150,19 @@ Associate the `frontend` directory as the project root on Vercel for automatic C
--- ---
> [!NOTE] > [!NOTE]
> **Commercialization**: This project currently offers **Web Dashboard ($5/mo)** and **Telegram Signal Channel ($1/mo)** subscriptions. > **Commercialization**: Current plans keep **Web Dashboard ($5/mo)** and **Telegram Signal Channel ($1/mo)** as the core entry offers.
> Point-earning via group participation is active and points can be redeemed for access. > User entitlement and payment automation are tracked in `docs/COMMERCIALIZATION.md`.
> [!NOTE] > [!NOTE]
> **Frontend Model**: The production website still uses the legacy high-density dashboard shell under `frontend/public/legacy/index.html`, embedded through the Next.js app shell. > **Frontend Model**: Production rendering is now fully handled by React components under `frontend/components/dashboard` and hooks under `frontend/hooks`.
> Legacy static files are retained for reference, but no longer act as the main runtime path.
--- ---
--- ---
**📅 Last Updated**: 2026-03-09 **📅 Last Updated**: 2026-03-09
**🚀 Status**: v1.0 Stable - Professional Quant UI Locked **🚀 Status**: v1.1 Stable - React Dashboard Runtime in Production
> [!TIP] > [!TIP]
> **Production Note**: The current dashboard utilizes the high-density "Professional Quant" UI (v1.0-legacy) which integrates real-time METAR/MGM data, DEB ensemble blending, and multi-model probability distribution in a single high-performance view. > **Production Note**: The UI layout and visual contract remain unchanged while data flow, map lifecycle, and modal interaction are now managed by typed React modules.
README_ZH.md
+37 -36
View File
@@ -1,4 +1,4 @@
# 🌡️ PolyWeather Pro # 🌡️ PolyWeather Pro
> **专业级博弈情报系统** —— 专注边缘气象数据采集、DEB 智能融合与实时决策预警。 > **专业级博弈情报系统** —— 专注边缘气象数据采集、DEB 智能融合与实时决策预警。
@@ -6,17 +6,17 @@
## 💎 项目愿景 ## 💎 项目愿景
PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报系统。我们不只是提供天气预报，而是通过聚合全球顶级气象源、应用自研的 **DEB (Dynamic Error Balancing)** 算法，并在关键时间节点提供**具有博弈预测价值**的异动预警。 PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报系统。我们不只提供天气预报，而是通过聚合全球气象源、应用自研 **DEB (Dynamic Error Balancing)** 算法，并在关键时间节点输出**可执行的异动信号**。
--- ---
## 🏗️ 生产架构 ## 🏗️ 生产架构
本项目采用生产级解耦架构，确保高可用与实时性： 本项目采用生产级解耦架构，确保高可用与迭代效率：
- **前端**：部署在 **Vercel** 上的 **Next.js** 交互式仪表盘。 - **前端**：部署在 **Vercel** 上的 **Next.js + React 组件化仪表盘**。
- **后端 API**：运行在 VPS 上的 **FastAPI**，提供低延迟数据服务。 - **后端 API**：运行在 VPS 上的 **FastAPI**，负责多源聚合与分析计算。
- **机器人与预警心跳**：运行在 VPS 上的 **Telegram Bot**，执行每分钟级的全球扫描与推送。 - **机器人与预警心跳**：运行在 VPS 上的 **Telegram Bot**，执行分钟级扫描与推送。
🔗 **官方访问地址**：[polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/) 🔗 **官方访问地址**：[polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/)
@@ -27,13 +27,13 @@ PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报
<p align="center"> <p align="center">
<img src="docs/images/demo_ankara.png" alt="PolyWeather 效果展示 - 安卡拉实时分析" width="450"> <img src="docs/images/demo_ankara.png" alt="PolyWeather 效果展示 - 安卡拉实时分析" width="450">
<br> <br>
<em>📊 <b>深度查询效果</b>：DEB 融合预测 + 结算概率 + Groq AI 专家建议</em> <em>📊 <b>深度查询效果</b>：DEB 融合预测 + 结算概率 + AI 分析上下文</em>
</p> </p>
<p align="center"> <p align="center">
<img src="./docs/images/demo_map.png" alt="PolyWeather Web Map" width="850"> <img src="./docs/images/demo_map.png" alt="PolyWeather Web Map" width="850">
<br> <br>
<em>🗺️ <b>全景仪表盘</b>：全球站点实时热力场 + 阵列式数据展示</em> <em>🗺️ <b>全景仪表盘</b>：全球站点标记 + 周边站点联动 + 右侧城市详情卡片</em>
</p> </p>
--- ---
@@ -41,18 +41,19 @@ PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报
## 🚀 核心功能 ## 🚀 核心功能
- **📡 多源全量采集** - **📡 多源全量采集**
- **主流模型**：ECMWF、GFS、ICON、GEM、JMA、Open-Meteo 的日/小时温度指导。 - **主流模型**：ECMWF、GFS、ICON、GEM、JMA、Open-Meteo 的日/小时指导。
- **实测数据**：Aviation Weather / METAR 作为主观测源，安卡拉叠加土耳其 MGM 官方站点实测。 - **实测数据**：Aviation Weather / METAR 为主观测源，安卡拉叠加 Turkish MGM 官方网络。
- **城市特化**：安卡拉特别接入 `17130`（`Ankara (Bölge/Center)`）作为领先站，不替代 LTAC 结算主站。 - **城市特化**：安卡拉保留 `17130`（`Ankara (Bölge/Center)`）领先站逻辑，不替代 LTAC 结算主站。
- **⚖️ DEB 智能融合** - **⚖️ DEB 智能融合**
- 基于近期历史表现和城市级可靠性，动态调整各模型权重。 - 基于城市历史表现与当前模型分歧动态调整权重。
- **🔔 异动预警系统 (Alert Engine)** - **🧩 React 仪表盘运行时**
- **动量突变**：捕捉 30 分钟内的急剧温变。 - 类型化 Store + 类型化 Data Client + Leaflet/Chart.js 生命周期封装。
- **预测突破**：当实测击穿所有预报上限时触发告警。 - 点击城市：地图聚焦 + 右侧卡片打开 + 周边站点展示。
- **平流监测**：基于周边前导站的风向流场模拟，预测冷/暖平流的到达。 - 点击“今日日内分析”：打开模态框并冻结地图动画。
- **🛡️ 智能压制逻辑** - **🔔 异动预警系统**
- **峰值保护**：当日高温峰值大概率已过时，自动转为静默/快照模式，拒绝骚扰。 - **动量突变**：捕捉短窗口温度斜率变化。
- **冷却管理**：同一信号路径支持全局与城市级双重 CD。 - **预测突破**：实测突破模型包络与安全边际时触发。
- **平流监测**：结合前导站和风向识别冷暖平流。
--- ---
@@ -73,14 +74,15 @@ PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报
- **安卡拉增强逻辑**： - **安卡拉增强逻辑**：
- 结算主观测：`LTAC / Esenboğa` - 结算主观测：`LTAC / Esenboğa`
- 官方领先站：`Ankara (Bölge/Center)` / `17130` - 官方领先站：`Ankara (Bölge/Center)` / `17130`
- 周边站层：土耳其 MGM 周边站网络 - 周边站层：土耳其 MGM 网络（含安卡拉优先站筛选）
- **其他城市周边站层**： - **其他城市周边站层**：
- 生产环境当前使用 Aviation Weather METAR cluster - 当前生产环境使用 Aviation Weather METAR cluster
- 美国城市后续可追加 Mesonet，但 METAR 仍是基础层 - 美国城市后续可叠加 Mesonet，但 METAR 仍为基础层
- **历史对账口径**： - **前端请求优化口径**：
- 网页端：滚动近 15 个已结算自然日 - 首屏先走 `/api/city/{name}/summary` 预热地图温度
- Telegram `/deb`：滚动近 7 个已结算自然日 - 城市详情 5 分钟 TTL，revision 不变则跳过重拉
- 当天未结算样本不参与胜率与 MAE 统计 - 地图联动、侧卡开关、modal 开关不会重复请求
- 手动刷新强制绕过缓存（`force_refresh=true`）
--- ---
@@ -89,19 +91,17 @@ PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报
```mermaid ```mermaid
graph TD graph TD
subgraph "客户端 / 终端" subgraph "客户端 / 终端"
Web[Next.js 网页端] Web[Next.js React 网页端]
TG[Telegram 客户端] TG[Telegram 客户端]
end end
subgraph "云端部署 (Vercel)" subgraph "云端部署 (Vercel)"
Web -.-> |Auth| Supa[(Supabase Auth/DB)] Web --> |BFF 路由| Fast[FastAPI API]
Web --> |API| Fast[FastAPI API]
end end
subgraph "核心引擎 (VPS)" subgraph "核心引擎 (VPS)"
Fast --- |Shared Logic| Worker[Alert Engine / Worker] Fast --- |Shared Logic| Worker[Alert Engine / Worker]
Bot[Telegram Bot] --- |Shared Logic| Worker Bot[Telegram Bot] --- |Shared Logic| Worker
Worker --> |Cache/Sub| Supa
end end
subgraph "外部数据源" subgraph "外部数据源"
@@ -134,7 +134,7 @@ docker-compose up -d --build
### 2. 前端 (Vercel) ### 2. 前端 (Vercel)
直接关联本项目 `frontend` 目录作为根目录即可，享受自动 CI/CD。 关联本项目 `frontend` 目录作为根目录，启用自动 CI/CD。
--- ---
@@ -150,18 +150,19 @@ docker-compose up -d --build
--- ---
> [!NOTE] > [!NOTE]
> **商业化提示**：本项目目前提供 **Web 仪表盘 ($5/月)** 与 **Telegram 信号频道 ($1/月)** 订阅服务。 > **商业化提示**：当前仍以 **Web 仪表盘 ($5/月)** 与 **Telegram 信号频道 ($1/月)** 为核心入口套餐。
> 发言获取积分逻辑已上线，活跃用户可兑换相应权限。 > 自动化支付与订阅鉴权规划见 `docs/COMMERCIALIZATION.md`。
> [!NOTE] > [!NOTE]
> **前端现状**：生产环境网页仍使用 `frontend/public/legacy/index.html` 的高密度 legacy dashboard，由 Next.js 外壳嵌入并在 Vercel 上部署。 > **前端现状**：生产环境页面已由 `frontend/components/dashboard` 与 `frontend/hooks` 完整接管渲染。
> legacy 静态文件仅保留为历史参考，不再作为主运行入口。
--- ---
--- ---
**📅 最后更新**：2026-03-09 **📅 最后更新**：2026-03-09
**🚀 状态**：v1.0 稳定版 - 专业量化 UI 已锁定 **🚀 状态**：v1.1 稳定版 - React 运行时已上线
> [!TIP] > [!TIP]
> **生产提示**：当前仪表盘采用高密度“专业量化版” UI (v1.0-legacy)，深度集成了 METAR/MGM 实测数据、DEB 智能融合预报及多模型概率分布，提供最高性能的数据交互体验。 > **生产提示**：在不改变既有 UI 布局与视觉层级的前提下，数据流、地图联动和模态行为已迁移到类型化 React 组件体系。
docs/API_ZH.md
+52 -44
View File
@@ -1,6 +1,6 @@
# PolyWeather API 接口文档 (v1.1) # PolyWeather API 接口文档 (v1.2)
本文档说明当前 PolyWeather 后端实际提供的 HTTP API。后端由 `web/app.py` 提供，前端网页通过 Next.js BFF 代理访问这些接口。 本文档说明当前 PolyWeather 后端实际提供的 HTTP API。后端由 `web/app.py` 提供，前端通过 Next.js BFF 路由代理访问这些接口。
--- ---
@@ -10,11 +10,9 @@
- **生产 Base URL**: `http://<your-vps-ip>:8000` 或绑定后的 HTTPS API 域名 - **生产 Base URL**: `http://<your-vps-ip>:8000` 或绑定后的 HTTPS API 域名
- **响应格式**: JSON - **响应格式**: JSON
- **缓存策略**: - **缓存策略**:
- `/api/cities`: 5 分钟 - 后端 `web/app.py` 内部分析缓存：默认 5 分钟（Ankara 为 60 秒）
- `/api/city/{name}`: 30 秒 - 前端城市详情缓存：5 分钟 TTL + revision 校验
- `/api/history/{name}`: 15 分钟 - 前端手动刷新：强制 `force_refresh=true` 跳过缓存
- `/api/city/{name}/summary`: 30 秒
- `/api/city/{name}/detail`: 30 秒
--- ---
@@ -24,7 +22,7 @@
- **URL**: `/api/cities` - **URL**: `/api/cities`
- **Method**: `GET` - **Method**: `GET`
- **用途**: 返回首页左侧监控城市与世界地图 marker 的基础元数据。 - **用途**: 返回首页左侧监控城市与地图 marker 的基础元数据。
**响应示例** **响应示例**
@@ -37,7 +35,7 @@
"lat": 40.1281, "lat": 40.1281,
"lon": 32.9951, "lon": 32.9951,
"risk_level": "medium", "risk_level": "medium",
"risk_emoji": "🟡", "risk_emoji": "🟠",
"airport": "Esenboğa", "airport": "Esenboğa",
"icao": "LTAC", "icao": "LTAC",
"temp_unit": "celsius", "temp_unit": "celsius",
@@ -54,7 +52,7 @@
- **参数**: - **参数**:
- `name`: 城市名或别名，如 `ankara`、`new-york` - `name`: 城市名或别名，如 `ankara`、`new-york`
- `force_refresh` (可选): `true` 时跳过缓存 - `force_refresh` (可选): `true` 时跳过缓存
- **用途**: 首页右侧详情面板与地图数据的主接口。 - **用途**: 右侧详情卡片、今日分析 modal、图表和周边站点的主数据接口。
**当前核心字段** **当前核心字段**
@@ -76,21 +74,23 @@
- `metar_recent_obs` - `metar_recent_obs`
- `hourly` - `hourly`
- `hourly_next_48h` - `hourly_next_48h`
- `source_forecasts`
- `multi_model_daily`
- `updated_at` - `updated_at`
**说明** **说明**
- `current.raw_metar` 现在直接透出 Aviation Weather API 返回的原始 METAR 报文。 - `current.raw_metar` 为 Aviation Weather 返回的原始报文字段。
- `mgm` 只对 Ankara 这类确实有 Turkish MGM 覆盖的城市有值。 - `mgm` 仅在具备官方 MGM 覆盖的城市（如 Ankara）有效。
- `mgm_nearby` 当前是一个复用字段： - `mgm_nearby` 为统一周边站点字段：
- Ankara: Turkish MGM 周边站 - Ankara：MGM 官方周边站
- 多数其他城市: AviationWeather METAR cluster - 其他多数城市：METAR cluster
### 2.3 获取历史对账数据 ### 2.3 获取历史对账数据
- **URL**: `/api/history/{name}` - **URL**: `/api/history/{name}`
- **Method**: `GET` - **Method**: `GET`
- **用途**: 历史准确率对账弹窗与机器人 `/deb` 命令的数据基础。 - **用途**: 历史对账弹窗与 `/deb` 指令的历史样本来源。
**响应示例** **响应示例**
@@ -110,14 +110,14 @@
**说明** **说明**
- 网页端历史对账只统计 **近 15 天已结算样本** - 网页端历史图默认展示近期样本，但统计口径只使用已结算日期。
- 当天未结算样本可以画在图里，但不计入胜率与 MAE - 当天未结算样本可用于可视化趋势，不计入胜率与 MAE。
### 2.4 获取城市摘要 ### 2.4 获取城市摘要
- **URL**: `/api/city/{name}/summary` - **URL**: `/api/city/{name}/summary`
- **Method**: `GET` - **Method**: `GET`
- **用途**: 轻量摘要接口，适合未来做 hover 预取或低开销列表更新。 - **用途**: 轻量级温度摘要接口，用于首屏地图温度预热与低开销列表更新。
**字段** **字段**
@@ -127,6 +127,7 @@
- `local_time` - `local_time`
- `temp_symbol` - `temp_symbol`
- `current.temp` - `current.temp`
- `current.obs_time`
- `deb.prediction` - `deb.prediction`
- `risk.level` - `risk.level`
- `risk.warning` - `risk.warning`
@@ -136,7 +137,7 @@
- **URL**: `/api/city/{name}/detail` - **URL**: `/api/city/{name}/detail`
- **Method**: `GET` - **Method**: `GET`
- **用途**: 面向未来的单请求聚合详情接口，便于把 `city + summary + history + future analysis` 整合到一个载荷中。 - **用途**: 面向后续商业化聚合视图的单请求聚合接口。
**当前结构** **当前结构**
@@ -145,12 +146,14 @@
- `timeseries` - `timeseries`
- `models` - `models`
- `probabilities` - `probabilities`
- `future` - `market_scan`
- `risk`
- `ai_analysis`
**说明** **说明**
- 当前首页 legacy 布局还主要使用 `/api/city/{name}` 和 `/api/history/{name}` - 当前生产前端主链路仍以 `/api/city/{name}` + `/api/history/{name}` 为主。
- `/api/city/{name}/detail` 已用于后续更完整详情态的聚合设计 - `/api/city/{name}/detail` 已提供聚合结构，供后续产品层扩展接入。
--- ---
@@ -158,23 +161,23 @@
### 3.1 风险等级 ### 3.1 风险等级
- `low`: 低风险，模型与实测较一致 - `low`: 低风险，模型与实测整体较一致
- `medium`: 中风险，存在一定分歧或本地站点偏置 - `medium`: 中风险，存在一定分歧或站点偏置
- `high`: 高风险，模型冲突大或盘面博弈价值高 - `high`: 高风险，模型冲突较大或盘面波动价值高
### 3.2 DEB ### 3.2 DEB
`DEB` 是 PolyWeather 的动态融合预测层，不是简单平均值。它会结合： `DEB` 是 PolyWeather 的动态融合预测层，不是简单平均值。它会综合：
- 多模型预测值 - 多模型预测值
- 近期表现 - 近期表现
- 实况修正 - 城市级偏差特征
- 城市级偏置 - 实况修正上下文
### 3.3 μ ### 3.3 μ
`μ` 代表当前结算分布中心，是一个**动态期望值**，会随着模型、实况、趋势变化而变化。 `μ` 表示当前结算概率分布中心（动态期望值），会随模型分歧与实况变化而更新。
它不应直接与固定 forecast 用同一口径做静态历史对账。 它不应直接按固定 forecast 口径做静态历史对账。
--- ---
@@ -183,31 +186,35 @@
### 4.1 主观测源 ### 4.1 主观测源
- **Aviation Weather / METAR** - **Aviation Weather / METAR**
- 当前全球机场主观测源 - 全球机场主观测源
- 同时提供结构化字段与 `rawOb` - 同时提供结构化字段与原始 METAR 报文
### 4.2 Ankara 专属源 ### 4.2 Ankara 专属源
- **Turkish MGM** - **Turkish MGM**
- Ankara 主官方增强层 - Ankara 官方增强层
- 包括 `Ankara (Bölge/Center)` 与周边站点 - 含 `Ankara (Bölge/Center)` 与周边站点
### 4.3 预测源 ### 4.3 预测源
- **Open-Meteo** - **Open-Meteo**
- **weather.gov**（美国城市） - **weather.gov**（美国城市）
- **Meteoblue**（部分城市） - **Meteoblue**（部分城市）
- **多模型集合**: ECMWF / GFS / ICON / GEM / JMA - **多模型集成**: ECMWF / GFS / ICON / GEM / JMA
--- ---
## 5. 当前口径说明 ## 5. 当前口径说明
- 首页地图主 marker 显示 **当前温度** - 地图 marker 显示当前温度（首屏通过 `summary` 预热）。
- 右侧详情面板展示当前实测、DEB、结算概率、多模型、多日预报 - 点击城市后打开右侧详情卡片，保持当前布局与样式不变。
- 未来日期分析模态框： - “今日日内分析”在 modal 中展示：
- 显示温度走势、结算概率分布、多模型预报、未来 6-48 小时趋势、未来 0-2 小时临近判断 - 今日温度走势（含 METAR 实测点）
- 已移除独立“冷锋 / 暖锋判断”模块 - 结算概率分布
- 多模型预报
- 今日日内结构信号（规则引擎）
- AI 深度分析 + 0-2 小时临近判断
- modal 打开时地图停止动画；点击空白地图仅关闭右侧卡片，不重置视角。
--- ---
@@ -218,15 +225,16 @@
- 再看 `docker-compose logs -f polyweather_web` - 再看 `docker-compose logs -f polyweather_web`
- **METAR 看起来慢几分钟** - **METAR 看起来慢几分钟**
- 通常是官方链路入库/发布延迟，不一定是本地轮询慢 - 常见原因是上游发布延迟，不一定是本地轮询问题
- 请同时看： - 建议同时查看：
- `current.obs_time` - `current.obs_time`
- `current.report_time` - `current.report_time`
- `current.receipt_time` - `current.receipt_time`
- **网页显示旧内容** - **网页显示旧内容**
- 先确认 Vercel 已部署新版本 - 先确认 Vercel 已部署最新版本
- 再强刷浏览器缓存 - 再强刷浏览器缓存
- 如为详情数据，确认是否命中前端 5 分钟 TTL
--- ---
docs/COMMERCIALIZATION.md
+21 -20
View File
@@ -1,4 +1,4 @@
# 📈 Commercialization Roadmap # 📈 Commercialization Roadmap
> **Target**: Transforming PolyWeather for paid weather intelligence delivery. > **Target**: Transforming PolyWeather for paid weather intelligence delivery.
@@ -6,7 +6,7 @@
## 🎯 Product Focus ## 🎯 Product Focus
PolyWeather is positioned as a **premium intelligence service** for weather-based prediction markets (**Polymarket**). The value proposition lies in **Ankara-specialization**, **advanced advection forecasting**, and **DEB-weighted consensus**. PolyWeather is positioned as a **premium intelligence service** for weather-driven prediction markets (**Polymarket**). The core differentiators remain **Ankara specialization**, **advection-aware signal logic**, and **DEB-weighted consensus**.
--- ---
@@ -15,13 +15,13 @@ PolyWeather is positioned as a **premium intelligence service** for weather-base
| Tier | Price | Primary Value Proposition | | Tier | Price | Primary Value Proposition |
| :------------------- | :------------ | :------------------------------------------------------------ | | :------------------- | :------------ | :------------------------------------------------------------ |
| **Telegram Channel** | **$1 / mo** | High-fidelity proactive alerts, low noise. | | **Telegram Channel** | **$1 / mo** | High-fidelity proactive alerts, low noise. |
| **Web Dashboard** | **$5 / mo** | Comprehensive multi-model view + historical MAE benchmarking. | | **Web Dashboard** | **$5 / mo** | Full multi-model context + historical DEB benchmarking. |
| **VIP Bundle** | **$5.5 / mo** | Full access to all intelligence streams. | | **VIP Bundle** | **$5.5 / mo** | Unified access to dashboard + signal stream. |
### 🛠️ Payment Infrastructure ### 🛠️ Payment Infrastructure
- **Currency**: Polygon / USDC. - **Currency**: Polygon / USDC.
- **Method**: Initially manual activation; migrating to automatic deposit detection (Phase 2). - **Method**: Phase-1 manual activation; Phase-2 automatic deposit detection and entitlement sync.
--- ---
@@ -45,27 +45,28 @@ graph LR
### 📦 Phase 1: Manual Beta ### 📦 Phase 1: Manual Beta
- **Goal**: Stabilize current alert quality and build core user group. - **Goal**: Stabilize signal quality and convert initial paid users.
- **Actions**: - **Actions**:
- Manual subscription activation via Telegram DM. - Manual subscription activation via Telegram DM.
- Small, focused paid Telegram channel for signal tests. - Small paid Telegram channel for low-noise signal validation.
- Invitation-only Web Access (Vercel). - Invite-based Web access while entitlement layer is being finalized.
- Validate city-specific edge before scaling, with Ankara as the flagship strategy city. - Keep Ankara as flagship strategy city for product credibility.
### 🛠️ Phase 2: Automation (USDC) ### 🛠️ Phase 2: Automation (USDC)
- **Goal**: Reduce operational friction. - **Goal**: Reduce operational friction and improve payment reliability.
- **Actions**: - **Actions**:
- **On-chain monitoring**: Detect USDC deposits to unique addresses. - **On-chain monitoring**: Detect USDC deposits to dedicated addresses.
- **One-time Links**: Telegram bot automatically generates invite links with `member_limit=1`. - **One-time Links**: Bot-generated invite links with strict member limits.
- **JWT Auth**: Securing the Next.js frontend with subscriber-only tokens. - **JWT Auth**: Subscriber-only access control for the Next.js frontend.
### 🌐 Phase 3: Scaling & Analytics ### 🌐 Phase 3: Scaling & Analytics
- **Goal**: Retention and expansion. - **Goal**: Improve retention and expand B2C/B2B utility.
- **Actions**: - **Actions**:
- **Accuracy Leaderboard**: Monthly reports of DEB vs Market outcomes. - **Accuracy Leaderboard**: Monthly DEB vs settled-actual reports.
- **Self-Serve Portal**: User dashboard for billing and alert settings. - **Self-Serve Portal**: Billing, subscription status, and alert preferences.
- **Usage Telemetry**: Feature-level analytics for conversion optimization.
### 📡 API Expansion Priority ### 📡 API Expansion Priority
@@ -79,15 +80,15 @@ graph LR
- U.S. cities may later receive Mesonet enhancement without replacing METAR - U.S. cities may later receive Mesonet enhancement without replacing METAR
- **P2 Product Layer** - **P2 Product Layer**
- Stripe / Polygon-USDC automation - Stripe / Polygon-USDC automation
- Realtime sync and user entitlement system - Realtime entitlement sync and subscriber state management
--- ---
## 🚧 Critical Constraints ## 🚧 Critical Constraints
- **Weather-First**: We focus on the **physical variable changes** rather than exchange-side order book execution. - **Weather-First**: The product is built around physical weather shifts, not exchange-side execution tooling.
- **Quality > Quantity**: Alert fatigue will churn subscribers. We enforce a "True Probability Shift" rule for notifications. - **Quality > Quantity**: Alert fatigue directly harms retention; thresholds must favor actionable rarity.
- **Local Niche**: Ankara is our flagship differentiator. - **UI Stability**: Commercial rollout assumes layout consistency; visual contract stays fixed while internals evolve.
--- ---
docs/TECH_DEBT.md
+13 -13
View File
@@ -1,20 +1,20 @@
# 🛠️ Technical Debt & Engineering Backlog # 🛠️ Technical Debt & Engineering Backlog
> **Vision**: Moving from a research script to a production SaaS. > **Vision**: Moving from a research script to a production SaaS.
--- ---
## 🏛️ System Health: 75% ## 🏛️ System Health: 82%
```mermaid ```mermaid
pie title System Health & Tech Debt pie title System Health & Tech Debt
"Stable Engine" : 75 "Stable Engine" : 82
"Centralized Logic Debt" : 10 "Entitlement/Payments Debt" : 8
"Subscription DB Debt" : 10 "Test/Replay Debt" : 6
"Testing/Replay Debt" : 5 "Observability Debt" : 4
``` ```
The core engine is stable, but several infrastructure "shortcut" decisions remain. The core weather engine and React dashboard runtime are now stable, but product-layer infrastructure debt is still material.
### Current Stable Modules ### Current Stable Modules
@@ -22,7 +22,7 @@ The core engine is stable, but several infrastructure "shortcut" decisions remai
- [x] DEB Blending Algorithm - [x] DEB Blending Algorithm
- [x] Proactive Telegram Alert Engine - [x] Proactive Telegram Alert Engine
- [x] Vercel Dashboard Infrastructure - [x] Vercel Dashboard Infrastructure
- [x] Legacy dashboard running behind Next.js/Vercel - [x] React component-driven dashboard runtime (replacing legacy `public/static/app.js` rendering path)
--- ---
@@ -33,7 +33,7 @@ The core engine is stable, but several infrastructure "shortcut" decisions remai
| **Monolithic Bot** | `bot_listener.py` is hard to test and evolve. | Isolate UI interaction from business logic into `src/analysis`. | | **Monolithic Bot** | `bot_listener.py` is hard to test and evolve. | Isolate UI interaction from business logic into `src/analysis`. |
| **Subscription Store** | No persistent record of who has paid. | Migrate from in-memory user checks to **Supabase/PostgreSQL**. | | **Subscription Store** | No persistent record of who has paid. | Migrate from in-memory user checks to **Supabase/PostgreSQL**. |
| **Alert Transparency** | Operators cannot easily audit "why" an alert fired. | Add an `Evidence` metadata block to all internal alert payloads. | | **Alert Transparency** | Operators cannot easily audit "why" an alert fired. | Add an `Evidence` metadata block to all internal alert payloads. |
| **Encoding Drift** | Legacy frontend files have suffered mixed encodings.| Normalize all legacy static files to UTF-8 and stop editing them with incompatible encodings. | | **Entitlement Guard** | Dashboard routes are public by default. | Add JWT/session gating in Next.js middleware + backend checks. |
--- ---
@@ -44,7 +44,7 @@ The core engine is stable, but several infrastructure "shortcut" decisions remai
| **Hard-coded Thresholds** | Modification requires code changes (e.g., 5s CD). | Extract all business constants into a structured `config.yaml`. | | **Hard-coded Thresholds** | Modification requires code changes (e.g., 5s CD). | Extract all business constants into a structured `config.yaml`. |
| **Simulation Harness** | No way to "replay" a rainy day to test alert logic. | Build a `ReplayEngine` using `data/daily_records.json`. | | **Simulation Harness** | No way to "replay" a rainy day to test alert logic. | Build a `ReplayEngine` using `data/daily_records.json`. |
| **Backend Naming** | Artifacts of "market price" logic remain in naming. | Systematic refactor of variable names to reflect weather-intelligence focus. | | **Backend Naming** | Artifacts of "market price" logic remain in naming. | Systematic refactor of variable names to reflect weather-intelligence focus. |
| **Legacy Frontend Debt** | Large `public/static/app.js` mixes data, UI, charts, and modal logic. | Gradually extract panel, chart, and modal logic into typed modules without changing the current layout contract. | | **Chart Regression Tests**| UI relies on custom Chart.js lifecycles. | Add snapshot + interaction tests for chart datasets and legends. |
--- ---
@@ -60,9 +60,9 @@ The core engine is stable, but several infrastructure "shortcut" decisions remai
## 🗓️ Next Milestones ## 🗓️ Next Milestones
1. **DB Integration**: Connect Supabase to `src/database/db_manager.py`. 1. **DB Integration**: Connect Supabase to `src/database/db_manager.py`.
2. **Alert Transparency**: Append logic metrics (slope, lead delta) to push messages. 2. **Entitlement Layer**: Enforce paid-access middleware on dashboard and API proxy routes.
3. **Authentication**: Secure `/api/city` on Vercel with subscription keys. 3. **Alert Transparency**: Append logic metrics (slope, lead delta, advection factors) to push payloads.
4. **UTF-8 Cleanup**: Remove remaining mojibake from legacy static files and comments. 4. **Replay & QA**: Add deterministic replay tests for map/panel/modal interaction regressions.
--- ---
frontend/README.md
+17 -13
View File
@@ -1,4 +1,4 @@
# PolyWeather Frontend # PolyWeather Frontend
This directory is the only web frontend in production. This directory is the only web frontend in production.
@@ -8,21 +8,23 @@ Production URL:
## Stack ## Stack
- Next.js App Router - Next.js App Router
- React (component-driven dashboard)
- Tailwind CSS - Tailwind CSS
- Lucide React - Leaflet (map runtime)
- shadcn/ui base layer - Chart.js (charts with manual lifecycle wrapper)
- Legacy dashboard shell loaded from `public/legacy/index.html` - Typed store + typed data client
## Production Model ## Production Model
- Vercel serves the web UI - Vercel serves the web UI and BFF route handlers
- FastAPI on VPS serves API only - FastAPI on VPS serves weather APIs only
- The old FastAPI static website has been removed - The old FastAPI static website has been removed
- The production page shell is still the legacy dashboard embedded by `app/page.tsx` - The production page shell is React-driven (`components/dashboard/*`), with no runtime dependency on `public/static/app.js`
Current request flow: Current request flow:
- Browser -> Vercel frontend - Browser -> Vercel frontend
- Vercel route handlers -> FastAPI API - React store/client -> Next route handlers
- Next route handlers -> FastAPI API
## Local Development ## Local Development
@@ -51,12 +53,14 @@ Examples:
Thin BFF routes currently exposed by Next: Thin BFF routes currently exposed by Next:
- `GET /api/cities` - `GET /api/cities`
- `GET /api/city/[name]` - `GET /api/city/[name]`
- `GET /api/city/[name]/summary`
- `GET /api/history/[name]` - `GET /api/history/[name]`
Current frontend behavior: Current frontend behavior:
- `/` keeps the world overview layout - `/` keeps the world overview layout and initial city temperatures preload
- City clicks stay inside the same layout and load the right-side panel - Marker click: focus map + open right city card + render nearby stations
- Future forecast dates open a modal instead of mutating the base panel - Right-card "今日日内分析": opens modal and freezes map motion
- Blank-map click: closes right card only, without resetting camera
## Vercel Deployment ## Vercel Deployment
@@ -68,7 +72,7 @@ Current frontend behavior:
## Notes ## Notes
- Backend CORS must allow `https://polyweather-pro.vercel.app` - Backend CORS must allow `https://polyweather-pro.vercel.app`
- The page shell currently embeds the legacy dashboard HTML from `public/legacy/index.html` - City detail cache TTL is 5 minutes with revision probe; manual refresh bypasses cache
- If you change files under `public/static`, deploy to Vercel to make them live - UI layout and sizing remain aligned with the legacy visual contract after React migration
Last updated: 2026-03-09 Last updated: 2026-03-09