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

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 组件体系。