From 243bf6c33b814ee420ee719ea246aaa17cb91687 Mon Sep 17 00:00:00 2001 From: "2569718930@qq.com" <2569718930@qq.com> Date: Mon, 9 Mar 2026 10:53:23 +0800 Subject: [PATCH] feat: fully migrate frontend to a React component-driven architecture and expand project documentation. --- README.md | 75 +++++++++++++++--------------- README_ZH.md | 73 ++++++++++++++--------------- docs/API_ZH.md | 96 +++++++++++++++++++++------------------ docs/COMMERCIALIZATION.md | 41 +++++++++-------- docs/TECH_DEBT.md | 26 +++++------ frontend/README.md | 30 ++++++------ 6 files changed, 178 insertions(+), 163 deletions(-) diff --git a/README.md b/README.md index 384f506d..08244429 100644 --- a/README.md +++ b/README.md @@ -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 -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 -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**. -- **Backend API**: A **FastAPI** service running on a VPS, providing low-latency data access. -- **Bot & Alert Heartbeat**: A **Telegram Bot** running on a VPS, executing minute-level global scans and push notifications. +- **Frontend**: A **Next.js** dashboard on **Vercel** with React component rendering. +- **Backend API**: A **FastAPI** service on VPS for low-latency weather aggregation and analysis. +- **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/) @@ -27,13 +27,13 @@ This project utilizes a production-grade decoupled architecture for high availab

PolyWeather Demo - Ankara Live Analysis
- 📊 Deep Query View: DEB Blended Forecast + Settlement Probability + Groq AI Expert Advice + 📊 Deep Query View: DEB blended forecast + settlement probability + AI analysis context

PolyWeather Web Map
- 🗺️ Omni-Dashboard: Real-time global heatmaps + array-style data visualization + 🗺️ Omni-Dashboard: global station markers + nearby station context + right-side city intelligence panel

--- @@ -41,18 +41,19 @@ This project utilizes a production-grade decoupled architecture for high availab ## 🚀 Core Features - **📡 Full-Spectrum Collection** - - **Major Models**: Real-time sync for ECMWF, GFS, ICON, GEM, JMA, and Open-Meteo daily/hourly guidance. - - **Observed Data**: Aviation Weather / METAR as the primary observation source, plus official Turkish MGM station-level data for Ankara. - - **City Specialization**: Integrated `17130` (`Ankara (Bölge/Center)`) as the key Ankara lead station, without replacing LTAC settlement observation. + - **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 Turkish MGM coverage for Ankara. + - **City Specialization**: `17130` (`Ankara (Bölge/Center)`) remains the Ankara lead station without replacing LTAC settlement observation. - **⚖️ 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** - - **Momentum Spike**: Captures rapid temperature changes within 30 minutes. - - **Forecast Breakthrough**: Fires when observations exceed all model predictions plus a safety margin. - - **Advection Monitoring**: Simulates warm/cold advection based on lead stations and wind currents. -- **🛡️ 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. + - **Momentum Spike**: Captures rapid short-window temperature slope changes. + - **Forecast Breakthrough**: Fires when observations break model envelopes plus margin. + - **Advection Monitoring**: Tracks warm/cold advection using lead-station behavior and wind direction. --- @@ -73,14 +74,15 @@ This project utilizes a production-grade decoupled architecture for high availab - **Ankara enhancement**: - Settlement observation: `LTAC / Esenboğa` - 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**: - - Current production logic uses Aviation Weather METAR clusters - - U.S. cities may later receive Mesonet augmentation, but METAR remains the base layer -- **Historical benchmarking rules**: - - Web dashboard: rolling last 15 settled days - - Telegram `/deb`: rolling last 7 settled days - - The current in-progress day is excluded from win rate and MAE + - Production currently uses Aviation Weather METAR clusters + - U.S. cities may later receive Mesonet augmentation while METAR stays baseline +- **Frontend request optimization**: + - Initial map temperatures preload via `/api/city/{name}/summary` + - City detail cache TTL = 5 minutes, revision probe avoids unnecessary refetch + - 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 graph TD subgraph "Client / Terminals" - Web[Next.js Web App] + Web[Next.js React Web App] TG[Telegram Client] end subgraph "Edge Deployment (Vercel)" - Web -.-> |Auth| Supa[(Supabase Auth/DB)] - Web --> |API| Fast[FastAPI API] + Web --> |BFF Routes| Fast[FastAPI API] end subgraph "Core Hub (VPS)" Fast --- |Shared Logic| Worker[Alert Engine / Worker] Bot[Telegram Bot] --- |Shared Logic| Worker - Worker --> |Cache/Sub| Supa end subgraph "External Sources" @@ -122,7 +122,7 @@ graph TD ### 1. Backend / Bot (VPS) ```bash -# Pull Source +# Pull source git pull # Environment @@ -134,7 +134,7 @@ docker-compose up -d --build ### 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] -> **Commercialization**: This project currently offers **Web Dashboard ($5/mo)** and **Telegram Signal Channel ($1/mo)** subscriptions. -> Point-earning via group participation is active and points can be redeemed for access. +> **Commercialization**: Current plans keep **Web Dashboard ($5/mo)** and **Telegram Signal Channel ($1/mo)** as the core entry offers. +> User entitlement and payment automation are tracked in `docs/COMMERCIALIZATION.md`. > [!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 -**🚀 Status**: v1.0 Stable - Professional Quant UI Locked +**🚀 Status**: v1.1 Stable - React Dashboard Runtime in Production > [!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. diff --git a/README_ZH.md b/README_ZH.md index df8e3264..2ee7e92c 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -1,4 +1,4 @@ -# 🌡️ PolyWeather Pro +# 🌡️ PolyWeather Pro > **专业级博弈情报系统** —— 专注边缘气象数据采集、DEB 智能融合与实时决策预警。 @@ -6,17 +6,17 @@ ## 💎 项目愿景 -PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报系统。我们不只是提供天气预报，而是通过聚合全球顶级气象源、应用自研的 **DEB (Dynamic Error Balancing)** 算法，并在关键时间节点提供**具有博弈预测价值**的异动预警。 +PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报系统。我们不只提供天气预报，而是通过聚合全球气象源、应用自研 **DEB (Dynamic Error Balancing)** 算法，并在关键时间节点输出**可执行的异动信号**。 --- ## 🏗️ 生产架构 -本项目采用生产级解耦架构，确保高可用与实时性： +本项目采用生产级解耦架构，确保高可用与迭代效率： -- **前端**：部署在 **Vercel** 上的 **Next.js** 交互式仪表盘。 -- **后端 API**：运行在 VPS 上的 **FastAPI**，提供低延迟数据服务。 -- **机器人与预警心跳**：运行在 VPS 上的 **Telegram Bot**，执行每分钟级的全球扫描与推送。 +- **前端**：部署在 **Vercel** 上的 **Next.js + React 组件化仪表盘**。 +- **后端 API**：运行在 VPS 上的 **FastAPI**，负责多源聚合与分析计算。 +- **机器人与预警心跳**：运行在 VPS 上的 **Telegram Bot**，执行分钟级扫描与推送。 🔗 **官方访问地址**：[polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/) @@ -27,13 +27,13 @@ PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报

PolyWeather 效果展示 - 安卡拉实时分析
- 📊 深度查询效果：DEB 融合预测 + 结算概率 + Groq AI 专家建议 + 📊 深度查询效果：DEB 融合预测 + 结算概率 + AI 分析上下文

PolyWeather Web Map
- 🗺️ 全景仪表盘：全球站点实时热力场 + 阵列式数据展示 + 🗺️ 全景仪表盘：全球站点标记 + 周边站点联动 + 右侧城市详情卡片

--- @@ -41,18 +41,19 @@ PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报 ## 🚀 核心功能 - **📡 多源全量采集** - - **主流模型**：ECMWF、GFS、ICON、GEM、JMA、Open-Meteo 的日/小时温度指导。 - - **实测数据**：Aviation Weather / METAR 作为主观测源，安卡拉叠加土耳其 MGM 官方站点实测。 - - **城市特化**：安卡拉特别接入 `17130`（`Ankara (Bölge/Center)`）作为领先站，不替代 LTAC 结算主站。 + - **主流模型**：ECMWF、GFS、ICON、GEM、JMA、Open-Meteo 的日/小时指导。 + - **实测数据**：Aviation Weather / METAR 为主观测源，安卡拉叠加 Turkish MGM 官方网络。 + - **城市特化**：安卡拉保留 `17130`（`Ankara (Bölge/Center)`）领先站逻辑，不替代 LTAC 结算主站。 - **⚖️ DEB 智能融合** - - 基于近期历史表现和城市级可靠性，动态调整各模型权重。 -- **🔔 异动预警系统 (Alert Engine)** - - **动量突变**：捕捉 30 分钟内的急剧温变。 - - **预测突破**：当实测击穿所有预报上限时触发告警。 - - **平流监测**：基于周边前导站的风向流场模拟，预测冷/暖平流的到达。 -- **🛡️ 智能压制逻辑** - - **峰值保护**：当日高温峰值大概率已过时，自动转为静默/快照模式，拒绝骚扰。 - - **冷却管理**：同一信号路径支持全局与城市级双重 CD。 + - 基于城市历史表现与当前模型分歧动态调整权重。 +- **🧩 React 仪表盘运行时** + - 类型化 Store + 类型化 Data Client + Leaflet/Chart.js 生命周期封装。 + - 点击城市：地图聚焦 + 右侧卡片打开 + 周边站点展示。 + - 点击“今日日内分析”：打开模态框并冻结地图动画。 +- **🔔 异动预警系统** + - **动量突变**：捕捉短窗口温度斜率变化。 + - **预测突破**：实测突破模型包络与安全边际时触发。 + - **平流监测**：结合前导站和风向识别冷暖平流。 --- @@ -73,14 +74,15 @@ PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报 - **安卡拉增强逻辑**： - 结算主观测：`LTAC / Esenboğa` - 官方领先站：`Ankara (Bölge/Center)` / `17130` - - 周边站层：土耳其 MGM 周边站网络 + - 周边站层：土耳其 MGM 网络（含安卡拉优先站筛选） - **其他城市周边站层**： - - 生产环境当前使用 Aviation Weather METAR cluster - - 美国城市后续可追加 Mesonet，但 METAR 仍是基础层 -- **历史对账口径**： - - 网页端：滚动近 15 个已结算自然日 - - Telegram `/deb`：滚动近 7 个已结算自然日 - - 当天未结算样本不参与胜率与 MAE 统计 + - 当前生产环境使用 Aviation Weather METAR cluster + - 美国城市后续可叠加 Mesonet，但 METAR 仍为基础层 +- **前端请求优化口径**： + - 首屏先走 `/api/city/{name}/summary` 预热地图温度 + - 城市详情 5 分钟 TTL，revision 不变则跳过重拉 + - 地图联动、侧卡开关、modal 开关不会重复请求 + - 手动刷新强制绕过缓存（`force_refresh=true`） --- @@ -89,19 +91,17 @@ PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报 ```mermaid graph TD subgraph "客户端 / 终端" - Web[Next.js 网页端] + Web[Next.js React 网页端] TG[Telegram 客户端] end subgraph "云端部署 (Vercel)" - Web -.-> |Auth| Supa[(Supabase Auth/DB)] - Web --> |API| Fast[FastAPI API] + Web --> |BFF 路由| Fast[FastAPI API] end subgraph "核心引擎 (VPS)" Fast --- |Shared Logic| Worker[Alert Engine / Worker] Bot[Telegram Bot] --- |Shared Logic| Worker - Worker --> |Cache/Sub| Supa end subgraph "外部数据源" @@ -134,7 +134,7 @@ docker-compose up -d --build ### 2. 前端 (Vercel) -直接关联本项目 `frontend` 目录作为根目录即可，享受自动 CI/CD。 +关联本项目 `frontend` 目录作为根目录，启用自动 CI/CD。 --- @@ -150,18 +150,19 @@ docker-compose up -d --build --- > [!NOTE] -> **商业化提示**：本项目目前提供 **Web 仪表盘 ($5/月)** 与 **Telegram 信号频道 ($1/月)** 订阅服务。 -> 发言获取积分逻辑已上线，活跃用户可兑换相应权限。 +> **商业化提示**：当前仍以 **Web 仪表盘 ($5/月)** 与 **Telegram 信号频道 ($1/月)** 为核心入口套餐。 +> 自动化支付与订阅鉴权规划见 `docs/COMMERCIALIZATION.md`。 > [!NOTE] -> **前端现状**：生产环境网页仍使用 `frontend/public/legacy/index.html` 的高密度 legacy dashboard，由 Next.js 外壳嵌入并在 Vercel 上部署。 +> **前端现状**：生产环境页面已由 `frontend/components/dashboard` 与 `frontend/hooks` 完整接管渲染。 +> legacy 静态文件仅保留为历史参考，不再作为主运行入口。 --- --- **📅 最后更新**：2026-03-09 -**🚀 状态**：v1.0 稳定版 - 专业量化 UI 已锁定 +**🚀 状态**：v1.1 稳定版 - React 运行时已上线 > [!TIP] -> **生产提示**：当前仪表盘采用高密度“专业量化版” UI (v1.0-legacy)，深度集成了 METAR/MGM 实测数据、DEB 智能融合预报及多模型概率分布，提供最高性能的数据交互体验。 +> **生产提示**：在不改变既有 UI 布局与视觉层级的前提下，数据流、地图联动和模态行为已迁移到类型化 React 组件体系。 diff --git a/docs/API_ZH.md b/docs/API_ZH.md index 32caec53..f0cbb0f9 100644 --- a/docs/API_ZH.md +++ b/docs/API_ZH.md @@ -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://: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 秒 + - 后端 `web/app.py` 内部分析缓存：默认 5 分钟（Ankara 为 60 秒） + - 前端城市详情缓存：5 分钟 TTL + revision 校验 + - 前端手动刷新：强制 `force_refresh=true` 跳过缓存 --- @@ -24,7 +22,7 @@ - **URL**: `/api/cities` - **Method**: `GET` -- **用途**: 返回首页左侧监控城市与世界地图 marker 的基础元数据。 +- **用途**: 返回首页左侧监控城市与地图 marker 的基础元数据。 **响应示例** @@ -37,7 +35,7 @@ "lat": 40.1281, "lon": 32.9951, "risk_level": "medium", - "risk_emoji": "🟡", + "risk_emoji": "🟠", "airport": "Esenboğa", "icao": "LTAC", "temp_unit": "celsius", @@ -54,7 +52,7 @@ - **参数**: - `name`: 城市名或别名，如 `ankara`、`new-york` - `force_refresh` (可选): `true` 时跳过缓存 -- **用途**: 首页右侧详情面板与地图数据的主接口。 +- **用途**: 右侧详情卡片、今日分析 modal、图表和周边站点的主数据接口。 **当前核心字段** @@ -76,21 +74,23 @@ - `metar_recent_obs` - `hourly` - `hourly_next_48h` +- `source_forecasts` +- `multi_model_daily` - `updated_at` **说明** -- `current.raw_metar` 现在直接透出 Aviation Weather API 返回的原始 METAR 报文。 -- `mgm` 只对 Ankara 这类确实有 Turkish MGM 覆盖的城市有值。 -- `mgm_nearby` 当前是一个复用字段： - - Ankara: Turkish MGM 周边站 - - 多数其他城市: AviationWeather METAR cluster +- `current.raw_metar` 为 Aviation Weather 返回的原始报文字段。 +- `mgm` 仅在具备官方 MGM 覆盖的城市（如 Ankara）有效。 +- `mgm_nearby` 为统一周边站点字段： + - Ankara：MGM 官方周边站 + - 其他多数城市：METAR cluster ### 2.3 获取历史对账数据 - **URL**: `/api/history/{name}` - **Method**: `GET` -- **用途**: 历史准确率对账弹窗与机器人 `/deb` 命令的数据基础。 +- **用途**: 历史对账弹窗与 `/deb` 指令的历史样本来源。 **响应示例** @@ -110,14 +110,14 @@ **说明** -- 网页端历史对账只统计 **近 15 天已结算样本** -- 当天未结算样本可以画在图里，但不计入胜率与 MAE +- 网页端历史图默认展示近期样本，但统计口径只使用已结算日期。 +- 当天未结算样本可用于可视化趋势，不计入胜率与 MAE。 ### 2.4 获取城市摘要 - **URL**: `/api/city/{name}/summary` - **Method**: `GET` -- **用途**: 轻量摘要接口，适合未来做 hover 预取或低开销列表更新。 +- **用途**: 轻量级温度摘要接口，用于首屏地图温度预热与低开销列表更新。 **字段** @@ -127,6 +127,7 @@ - `local_time` - `temp_symbol` - `current.temp` +- `current.obs_time` - `deb.prediction` - `risk.level` - `risk.warning` @@ -136,7 +137,7 @@ - **URL**: `/api/city/{name}/detail` - **Method**: `GET` -- **用途**: 面向未来的单请求聚合详情接口，便于把 `city + summary + history + future analysis` 整合到一个载荷中。 +- **用途**: 面向后续商业化聚合视图的单请求聚合接口。 **当前结构** @@ -145,12 +146,14 @@ - `timeseries` - `models` - `probabilities` -- `future` +- `market_scan` +- `risk` +- `ai_analysis` **说明** -- 当前首页 legacy 布局还主要使用 `/api/city/{name}` 和 `/api/history/{name}` -- `/api/city/{name}/detail` 已用于后续更完整详情态的聚合设计 +- 当前生产前端主链路仍以 `/api/city/{name}` + `/api/history/{name}` 为主。 +- `/api/city/{name}/detail` 已提供聚合结构，供后续产品层扩展接入。 --- @@ -158,23 +161,23 @@ ### 3.1 风险等级 -- `low`: 低风险，模型与实测较一致 -- `medium`: 中风险，存在一定分歧或本地站点偏置 -- `high`: 高风险，模型冲突大或盘面博弈价值高 +- `low`: 低风险，模型与实测整体较一致 +- `medium`: 中风险，存在一定分歧或站点偏置 +- `high`: 高风险，模型冲突较大或盘面波动价值高 ### 3.2 DEB -`DEB` 是 PolyWeather 的动态融合预测层，不是简单平均值。它会结合： +`DEB` 是 PolyWeather 的动态融合预测层，不是简单平均值。它会综合： - 多模型预测值 - 近期表现 -- 实况修正 -- 城市级偏置 +- 城市级偏差特征 +- 实况修正上下文 ### 3.3 μ -`μ` 代表当前结算分布中心，是一个**动态期望值**，会随着模型、实况、趋势变化而变化。 -它不应直接与固定 forecast 用同一口径做静态历史对账。 +`μ` 表示当前结算概率分布中心（动态期望值），会随模型分歧与实况变化而更新。 +它不应直接按固定 forecast 口径做静态历史对账。 --- @@ -183,31 +186,35 @@ ### 4.1 主观测源 - **Aviation Weather / METAR** - - 当前全球机场主观测源 - - 同时提供结构化字段与 `rawOb` + - 全球机场主观测源 + - 同时提供结构化字段与原始 METAR 报文 ### 4.2 Ankara 专属源 - **Turkish MGM** - - Ankara 主官方增强层 - - 包括 `Ankara (Bölge/Center)` 与周边站点 + - Ankara 官方增强层 + - 含 `Ankara (Bölge/Center)` 与周边站点 ### 4.3 预测源 - **Open-Meteo** - **weather.gov**（美国城市） - **Meteoblue**（部分城市） -- **多模型集合**: ECMWF / GFS / ICON / GEM / JMA +- **多模型集成**: ECMWF / GFS / ICON / GEM / JMA --- ## 5. 当前口径说明 -- 首页地图主 marker 显示 **当前温度** -- 右侧详情面板展示当前实测、DEB、结算概率、多模型、多日预报 -- 未来日期分析模态框： - - 显示温度走势、结算概率分布、多模型预报、未来 6-48 小时趋势、未来 0-2 小时临近判断 - - 已移除独立“冷锋 / 暖锋判断”模块 +- 地图 marker 显示当前温度（首屏通过 `summary` 预热）。 +- 点击城市后打开右侧详情卡片，保持当前布局与样式不变。 +- “今日日内分析”在 modal 中展示： + - 今日温度走势（含 METAR 实测点） + - 结算概率分布 + - 多模型预报 + - 今日日内结构信号（规则引擎） + - AI 深度分析 + 0-2 小时临近判断 +- modal 打开时地图停止动画；点击空白地图仅关闭右侧卡片，不重置视角。 --- @@ -218,15 +225,16 @@ - 再看 `docker-compose logs -f polyweather_web` - **METAR 看起来慢几分钟** - - 通常是官方链路入库/发布延迟，不一定是本地轮询慢 - - 请同时看： + - 常见原因是上游发布延迟，不一定是本地轮询问题 + - 建议同时查看： - `current.obs_time` - `current.report_time` - `current.receipt_time` - **网页显示旧内容** - - 先确认 Vercel 已部署新版本 + - 先确认 Vercel 已部署最新版本 - 再强刷浏览器缓存 + - 如为详情数据，确认是否命中前端 5 分钟 TTL --- diff --git a/docs/COMMERCIALIZATION.md b/docs/COMMERCIALIZATION.md index 9303c3d5..1f33c329 100644 --- a/docs/COMMERCIALIZATION.md +++ b/docs/COMMERCIALIZATION.md @@ -1,4 +1,4 @@ -# 📈 Commercialization Roadmap +# 📈 Commercialization Roadmap > **Target**: Transforming PolyWeather for paid weather intelligence delivery. @@ -6,7 +6,7 @@ ## 🎯 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 | | :------------------- | :------------ | :------------------------------------------------------------ | | **Telegram Channel** | **$1 / mo** | High-fidelity proactive alerts, low noise. | -| **Web Dashboard** | **$5 / mo** | Comprehensive multi-model view + historical MAE benchmarking. | -| **VIP Bundle** | **$5.5 / mo** | Full access to all intelligence streams. | +| **Web Dashboard** | **$5 / mo** | Full multi-model context + historical DEB benchmarking. | +| **VIP Bundle** | **$5.5 / mo** | Unified access to dashboard + signal stream. | ### 🛠️ Payment Infrastructure - **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 -- **Goal**: Stabilize current alert quality and build core user group. +- **Goal**: Stabilize signal quality and convert initial paid users. - **Actions**: - Manual subscription activation via Telegram DM. - - Small, focused paid Telegram channel for signal tests. - - Invitation-only Web Access (Vercel). - - Validate city-specific edge before scaling, with Ankara as the flagship strategy city. + - Small paid Telegram channel for low-noise signal validation. + - Invite-based Web access while entitlement layer is being finalized. + - Keep Ankara as flagship strategy city for product credibility. ### 🛠️ Phase 2: Automation (USDC) -- **Goal**: Reduce operational friction. +- **Goal**: Reduce operational friction and improve payment reliability. - **Actions**: - - **On-chain monitoring**: Detect USDC deposits to unique addresses. - - **One-time Links**: Telegram bot automatically generates invite links with `member_limit=1`. - - **JWT Auth**: Securing the Next.js frontend with subscriber-only tokens. + - **On-chain monitoring**: Detect USDC deposits to dedicated addresses. + - **One-time Links**: Bot-generated invite links with strict member limits. + - **JWT Auth**: Subscriber-only access control for the Next.js frontend. ### 🌐 Phase 3: Scaling & Analytics -- **Goal**: Retention and expansion. +- **Goal**: Improve retention and expand B2C/B2B utility. - **Actions**: - - **Accuracy Leaderboard**: Monthly reports of DEB vs Market outcomes. - - **Self-Serve Portal**: User dashboard for billing and alert settings. + - **Accuracy Leaderboard**: Monthly DEB vs settled-actual reports. + - **Self-Serve Portal**: Billing, subscription status, and alert preferences. + - **Usage Telemetry**: Feature-level analytics for conversion optimization. ### 📡 API Expansion Priority @@ -79,15 +80,15 @@ graph LR - U.S. cities may later receive Mesonet enhancement without replacing METAR - **P2 Product Layer** - Stripe / Polygon-USDC automation - - Realtime sync and user entitlement system + - Realtime entitlement sync and subscriber state management --- ## 🚧 Critical Constraints -- **Weather-First**: We focus on the **physical variable changes** rather than exchange-side order book execution. -- **Quality > Quantity**: Alert fatigue will churn subscribers. We enforce a "True Probability Shift" rule for notifications. -- **Local Niche**: Ankara is our flagship differentiator. +- **Weather-First**: The product is built around physical weather shifts, not exchange-side execution tooling. +- **Quality > Quantity**: Alert fatigue directly harms retention; thresholds must favor actionable rarity. +- **UI Stability**: Commercial rollout assumes layout consistency; visual contract stays fixed while internals evolve. --- diff --git a/docs/TECH_DEBT.md b/docs/TECH_DEBT.md index f8bf4b83..566c6888 100644 --- a/docs/TECH_DEBT.md +++ b/docs/TECH_DEBT.md @@ -1,20 +1,20 @@ -# 🛠️ Technical Debt & Engineering Backlog +# 🛠️ Technical Debt & Engineering Backlog > **Vision**: Moving from a research script to a production SaaS. --- -## 🏛️ System Health: 75% +## 🏛️ System Health: 82% ```mermaid pie title System Health & Tech Debt - "Stable Engine" : 75 - "Centralized Logic Debt" : 10 - "Subscription DB Debt" : 10 - "Testing/Replay Debt" : 5 + "Stable Engine" : 82 + "Entitlement/Payments Debt" : 8 + "Test/Replay Debt" : 6 + "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 @@ -22,7 +22,7 @@ The core engine is stable, but several infrastructure "shortcut" decisions remai - [x] DEB Blending Algorithm - [x] Proactive Telegram Alert Engine - [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`. | | **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. | -| **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`. | | **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. | -| **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 1. **DB Integration**: Connect Supabase to `src/database/db_manager.py`. -2. **Alert Transparency**: Append logic metrics (slope, lead delta) to push messages. -3. **Authentication**: Secure `/api/city` on Vercel with subscription keys. -4. **UTF-8 Cleanup**: Remove remaining mojibake from legacy static files and comments. +2. **Entitlement Layer**: Enforce paid-access middleware on dashboard and API proxy routes. +3. **Alert Transparency**: Append logic metrics (slope, lead delta, advection factors) to push payloads. +4. **Replay & QA**: Add deterministic replay tests for map/panel/modal interaction regressions. --- diff --git a/frontend/README.md b/frontend/README.md index 3c6e9028..4a990159 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,4 +1,4 @@ -# PolyWeather Frontend +# PolyWeather Frontend This directory is the only web frontend in production. @@ -8,21 +8,23 @@ Production URL: ## Stack - Next.js App Router +- React (component-driven dashboard) - Tailwind CSS -- Lucide React -- shadcn/ui base layer -- Legacy dashboard shell loaded from `public/legacy/index.html` +- Leaflet (map runtime) +- Chart.js (charts with manual lifecycle wrapper) +- Typed store + typed data client ## Production Model -- Vercel serves the web UI -- FastAPI on VPS serves API only +- Vercel serves the web UI and BFF route handlers +- FastAPI on VPS serves weather APIs only - 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: - Browser -> Vercel frontend -- Vercel route handlers -> FastAPI API +- React store/client -> Next route handlers +- Next route handlers -> FastAPI API ## Local Development @@ -51,12 +53,14 @@ Examples: Thin BFF routes currently exposed by Next: - `GET /api/cities` - `GET /api/city/[name]` +- `GET /api/city/[name]/summary` - `GET /api/history/[name]` Current frontend behavior: -- `/` keeps the world overview layout -- City clicks stay inside the same layout and load the right-side panel -- Future forecast dates open a modal instead of mutating the base panel +- `/` keeps the world overview layout and initial city temperatures preload +- Marker click: focus map + open right city card + render nearby stations +- Right-card "今日日内分析": opens modal and freezes map motion +- Blank-map click: closes right card only, without resetting camera ## Vercel Deployment @@ -68,7 +72,7 @@ Current frontend behavior: ## Notes - Backend CORS must allow `https://polyweather-pro.vercel.app` -- The page shell currently embeds the legacy dashboard HTML from `public/legacy/index.html` -- If you change files under `public/static`, deploy to Vercel to make them live +- City detail cache TTL is 5 minutes with revision probe; manual refresh bypasses cache +- UI layout and sizing remain aligned with the legacy visual contract after React migration Last updated: 2026-03-09