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

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
 <p align="center">
   <img src="docs/images/demo_ankara.png" alt="PolyWeather Demo - Ankara Live Analysis" width="450">
   <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 align="center">
   <img src="./docs/images/demo_map.png" alt="PolyWeather Web Map" width="850">
   <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>
 
 ---
@@ -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.

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** 深度博弈者设计的实时情报
 <p align="center">
   <img src="docs/images/demo_ankara.png" alt="PolyWeather 效果展示 - 安卡拉实时分析" width="450">
   <br>
-  <em>📊 <b>深度查询效果</b>：DEB 融合预测 + 结算概率 + Groq AI 专家建议</em>
+  <em>📊 <b>深度查询效果</b>：DEB 融合预测 + 结算概率 + AI 分析上下文</em>
 </p>
 
 <p align="center">
   <img src="./docs/images/demo_map.png" alt="PolyWeather Web Map" width="850">
   <br>
-  <em>🗺️ <b>全景仪表盘</b>：全球站点实时热力场 + 阵列式数据展示</em>
+  <em>🗺️ <b>全景仪表盘</b>：全球站点标记 + 周边站点联动 + 右侧城市详情卡片</em>
 </p>
 
 ---
@@ -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 组件体系。

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://<your-vps-ip>: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
 
 ---
 

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.
 
 ---
 

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.
 
 ---
 

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