feat: fully migrate frontend to a React component-driven architecture and expand project documentation.
This commit is contained in:
2569718930@qq.com
+52
-44
@@ -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
|
||||
|
||||
---
|
||||
|
||||
|
||||
+21
-20
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
+13
-13
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user