From fe6477b09cc1c60a0620fae538bc5ce25b719cc2 Mon Sep 17 00:00:00 2001 From: "2569718930@qq.com" <2569718930@qq.com> Date: Sat, 18 Apr 2026 14:40:29 +0800 Subject: [PATCH] Use existing loading state for sparse detail --- CHANGELOG.md | 11 +++ README.md | 41 ++++++------ README_ZH.md | 28 +++++--- VERSION | 2 +- docs/API_ZH.md | 67 +++++++++++++++++-- docs/COMMERCIALIZATION.md | 13 ++-- docs/EMOS_LGBM_SYSTEM_ZH.md | 17 ++++- docs/LGBM_DAILY_HIGH_ZH.md | 17 ++++- docs/MODEL_STACK_AND_DEB_ZH.md | 30 ++++++++- docs/MONITORING_ZH.md | 37 +++++++++- docs/PROBABILITY_SNAPSHOT_ARCHIVE_ZH.md | 15 ++++- docs/deep-research-report.md | 22 +++--- frontend/README.md | 15 +++-- frontend/components/dashboard/DetailPanel.tsx | 8 +-- .../components/dashboard/PanelSections.tsx | 5 +- frontend/content/docs/docs.ts | 64 +++++++++++++----- frontend/package-lock.json | 4 +- frontend/package.json | 2 +- 18 files changed, 308 insertions(+), 90 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ca9638ea..b4e1b639 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog +## 1.5.4 - 2026-04-18 + +- 今日日内分析升级为专业气象判断台：主判断、置信度、基准/上修/下修路径、下一观测点、证据链、失效条件和确认条件前置展示 +- 日内分析弹窗新增显式 `today/future` 模式，修复点击“今日日内分析”偶发进入未来日期分析布局的问题 +- 日内分析在 full detail / market scan 同步完成前锁住旧内容，避免刷新期间短暂展示错误城市、错误日期或旧缓存数据 +- 右侧详情面板识别稀疏 detail / 单日 forecast 中间态，并显示同步占位卡，避免用户把未补齐数据误认为完整结果 +- 概率区改为“校准模型概率”：有 LGBM 时展示 LGBM 校准概率；模型共识与市场价格降级为辅助参考 +- 模型层补齐 DWD ICON、ECMWF AIFS、ECCC GEM/GDPS/RDPS/HRDPS 等开放模型说明，并明确 AIFS 不称作“AI 预报” +- 新增 / 补齐 Manila、Karachi、Masroor Air Base 等城市说明；机场市场以 METAR / 机场主站为结算锚点，Wunderground 仅作为历史页面或参考入口 +- 历史对账、模型栈、LGBM、监控、前端 README 与网页 `/docs` 文档同步更新到当前产品口径 + ## 1.5.3 - 2026-04-10 - 东京新增 `JMA AMeDAS` 羽田 10 分钟官方增强层，只取温度并作为机场周边官方参考 diff --git a/README.md b/README.md index d0bdee45..c73efa25 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Production weather-intelligence stack for temperature settlement markets. Official dashboard: [polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/) 中文说明: [README_ZH.md](README_ZH.md) -Public docs center: `/docs/intro` on the main site (bilingual product documentation, including intraday signals, TAF, settlement sources, history, and extension). +Public docs center: `/docs/intro` on the main site (bilingual product documentation, including intraday analysis, calibrated probability, model stack, TAF, settlement sources, history, and extension). ## Product Screenshots @@ -17,7 +17,7 @@ Public docs center: `/docs/intro` on the main site (bilingual product documentat ![PolyWeather Ankara analysis](docs/images/demo_ankara.png) -## Product Status (2026-04-10) +## Product Status (2026-04-18) - Subscription live: `Pro Monthly 5 USDC`. - Points redemption live: `500 points = 1 USDC`, max `3 USDC` off. @@ -27,7 +27,9 @@ Public docs center: `/docs/intro` on the main site (bilingual product documentat - Lightweight observability live: `/healthz`, `/api/system/status`, `/metrics`. - Runtime state, cache, and core offline training/backfill flows now use SQLite as the primary path; legacy JSON/JSONL files remain only for migration, export, and explicit fallback input. - EMOS/CRPS pipeline is integrated in `shadow` mode with rollout gating. -- Intraday structural signal is now peak-window aware and bilingual (`zh-CN` / `en-US`). +- Intraday analysis is now positioned as a professional meteorology read: headline, confidence, base/upside/downside paths, next observation point, evidence chain, failure modes, and confirmation rules. +- Intraday modal now blocks stale cached detail during refresh, so users do not briefly trade off old city/date data before full detail arrives. +- Calibrated model probability is now the primary probability panel. `LGBM` is shown as a calibrated probability engine when available; model consensus and market prices are secondary references. - Non-Hong Kong airport cities now ingest `TAF` and parse `FM / TEMPO / BECMG / PROB30/40`. - Temperature chart now overlays `TAF Timing` markers near the expected peak window. - Trade cue now combines upper-air structure, `TAF`, market crowding, and `edge_percent`. @@ -51,13 +53,13 @@ See: [AGPL-3.0 & Commercial Boundary](docs/OPEN_CORE_POLICY.md) ## Core Capabilities -- Aggregates observations and forecasts for 45 monitored cities. +- Aggregates observations and forecasts for 52 monitored cities. - Uses DEB (Dynamic Error Balancing) to blend multi-model highs. -- Generates settlement-oriented probability buckets (`mu` + bucket distribution). +- Generates settlement-oriented calibrated probability buckets (`mu` + bucket distribution), with `LGBM` metadata surfaced when the calibrated engine is active. - Maps weather view to Polymarket quotes for mispricing scan. - Reuses one analysis core across web dashboard and Telegram bot. - Adds payment audit trails, replay tooling, and incident visibility in ops. -- Adds peak-window-oriented intraday structure cards for surface + upper-air analysis. +- Adds peak-window-oriented intraday analysis with meteorology headline, path buckets, evidence chain, invalidation rules, and confirmation rules. - Adds airport-side `TAF` timing overlays and airport suppression/disruption interpretation for non-Hong Kong airport cities. - Adds official nearby-network enhancement layers for China, Japan, Korea, Hong Kong, Taiwan, and Turkey without replacing airport settlement anchors. - Adds optional dashboard prewarm worker so hot cities can be refreshed before user clicks. @@ -87,12 +89,12 @@ flowchart LR API --> PREWARM["Dashboard Prewarm API / Worker"] ``` -## Monitored Cities (45) +## Monitored Cities (52) -- Europe / Middle East: Ankara, Istanbul, Moscow, London, Paris, Munich, Milan, Warsaw, Madrid, Tel Aviv, Amsterdam, Helsinki -- APAC: Seoul, Busan, Hong Kong, Lau Fau Shan, Taipei, Shanghai, Beijing, Wuhan, Chengdu, Chongqing, Shenzhen, Singapore, Tokyo, Kuala Lumpur, Jakarta, Wellington -- Americas: Toronto, New York, Los Angeles, San Francisco, Denver, Austin, Houston, Chicago, Dallas, Miami, Atlanta, Seattle, Mexico City, Buenos Aires, Sao Paulo, Panama City -- South Asia: Lucknow +- Europe / Middle East / Africa: Ankara, Istanbul, Moscow, London, Paris, Munich, Milan, Warsaw, Madrid, Tel Aviv, Amsterdam, Helsinki, Lagos, Cape Town, Jeddah +- APAC: Seoul, Busan, Hong Kong, Lau Fau Shan, Taipei, Shanghai, Beijing, Wuhan, Chengdu, Chongqing, Shenzhen, Guangzhou, Singapore, Tokyo, Kuala Lumpur, Jakarta, Manila, Wellington +- Americas: Toronto, New York, Los Angeles, San Francisco, Aurora, Austin, Houston, Chicago, Dallas, Miami, Atlanta, Seattle, Mexico City, Buenos Aires, Sao Paulo, Panama City +- South Asia: Lucknow, Karachi, Masroor Air Base ## Quick Start @@ -112,14 +114,12 @@ npm run dev ## Recent Highlights -- Taipei settlement is aligned to `Wunderground RCSS` with whole-degree Celsius resolution logic. -- Shenzhen settlement is aligned to `Wunderground ZGSZ`. +- Airport-linked contracts use the METAR / airport primary observing site as the settlement anchor. Wunderground pages are reference/history pages, not stations. +- Taipei and Shenzhen retain their explicitly configured station history pages for reconciliation, but the docs avoid describing Wunderground itself as a physical station. - Hong Kong keeps `HKO` official readings in dashboard and history, without falling back to airport METAR lines. -- Intraday analysis now separates: - - `Surface Structure` - - `Upper-Air Structure` - - `Trade cue` +- Intraday analysis now separates meteorology conclusion, evidence chain, invalidation rules, confirmation rules, calibrated probability, and market reference. - `TAF` is used as an airport-side confirmation layer, not as the main temperature model. +- `LGBM` can power the calibrated probability panel; model vote counts remain an explanatory consensus line, not the final probability. - Browser extension remains a lightweight monitoring + basic-bias product, while the site holds the full analysis experience. ## Runtime Data (Recommended on VPS) @@ -196,6 +196,8 @@ docker compose logs -f polyweather | egrep "polymarket wallet activity watcher s - Chinese overview: [README_ZH.md](README_ZH.md) - Chinese API guide: [docs/API_ZH.md](docs/API_ZH.md) - TAF signal guide (ZH): [docs/TAF_SIGNAL_ZH.md](docs/TAF_SIGNAL_ZH.md) +- Model stack & DEB (ZH): [docs/MODEL_STACK_AND_DEB_ZH.md](docs/MODEL_STACK_AND_DEB_ZH.md) +- EMOS + LGBM system (ZH): [docs/EMOS_LGBM_SYSTEM_ZH.md](docs/EMOS_LGBM_SYSTEM_ZH.md) - Commercialization: [docs/COMMERCIALIZATION.md](docs/COMMERCIALIZATION.md) - AGPL-3.0 policy: [docs/OPEN_CORE_POLICY.md](docs/OPEN_CORE_POLICY.md) - Supabase setup (ZH): [docs/SUPABASE_SETUP_ZH.md](docs/SUPABASE_SETUP_ZH.md) @@ -208,6 +210,7 @@ docker compose logs -f polyweather | egrep "polymarket wallet activity watcher s - Payment audit: [docs/payments/PAYMENT_AUDIT_ZH.md](docs/payments/PAYMENT_AUDIT_ZH.md) - Payment V2 upgrade: [docs/payments/PAYMENT_UPGRADE_V2_ZH.md](docs/payments/PAYMENT_UPGRADE_V2_ZH.md) - Ops admin guide: [docs/OPS_ADMIN_ZH.md](docs/OPS_ADMIN_ZH.md) +- Monitoring guide (ZH): [docs/MONITORING_ZH.md](docs/MONITORING_ZH.md) - Deep research report: [docs/deep-research-report.md](docs/deep-research-report.md) - Frontend report: [FRONTEND_REDESIGN_REPORT.md](FRONTEND_REDESIGN_REPORT.md) - Release process: [RELEASE.md](RELEASE.md) @@ -215,5 +218,5 @@ docker compose logs -f polyweather | egrep "polymarket wallet activity watcher s ## Version -- Version: `v1.5.3` -- Last Updated: `2026-04-10` +- Version: `v1.5.4` +- Last Updated: `2026-04-18` diff --git a/README_ZH.md b/README_ZH.md index b7a583f5..7286e61b 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -14,7 +14,7 @@ ![PolyWeather Ankara 分析页](docs/images/demo_ankara.png) -## 当前产品状态（2026-04-10） +## 当前产品状态（2026-04-18） - 已上线订阅制：`Pro 月付 5 USDC`。 - 已上线积分抵扣：`500 积分 = 1 USDC`，最多抵扣 `3 USDC`。 @@ -36,6 +36,9 @@ - 东京现已接入羽田 `JMA AMeDAS` 10 分钟温度作为官方增强层。 - 已支持 Dashboard 定向预热 worker / cron 路径，运行态在 `/api/system/status` 与 `/ops` 可见。 - `/ops` 现已展示缓存桶数量、summary cache hit/miss 与 prewarm heartbeat。 +- 今日日内分析已改为“专业气象判断台”：顶部先给气象主判断、置信度、基准/上修/下修路径、下一观测点，再展示证据链、失效条件、确认条件和模型层。 +- 日内分析弹窗在 full detail / market detail 同步完成前会锁住旧内容并显示刷新状态，避免用户短暂看到上一轮缓存数据后误判。 +- 概率区已改为“校准模型概率”，有 LGBM 时展示 LGBM 校准概率；模型共识和市场价格只作为辅助参考。 - 今日日内结构解读已支持可选 `Groq` 改写层，失败时自动回退规则文案。 - 前端部署文档已补充 Vercel 节流建议，包括 analytics 关闭、eager fetch 开关与扫描流量防火墙规则。 @@ -51,13 +54,13 @@ ## 核心能力 -- 聚合 45 个监控城市的实测与预报数据。 +- 聚合 52 个监控城市的实测与预报数据。 - DEB（Dynamic Error Balancing）融合多模型最高温。 -- 输出结算导向概率分布（`mu` + 温度桶）。 +- 输出结算导向校准概率分布（`mu` + 温度桶），并在 LGBM 生效时展示校准引擎元数据。 - 将模型观点映射到 Polymarket 行情，做错价扫描。 - Web 仪表盘与 Telegram Bot 复用同一分析内核。 - 支付链路具备事件重放、SQLite 审计事件与 RPC 容灾能力。 -- 官方增强层支持按国家 provider 统一接入，但不替代机场主站或明确官方结算站。 +- 官方增强层支持按国家 provider 统一接入，但不替代机场主站、METAR 或明确官方结算站。 - 支持后台预热热点城市，降低用户点击城市后的冷启动成本。 ## 参考架构 @@ -86,12 +89,12 @@ flowchart LR ANA --> STATE["SQLite runtime state
legacy files only for migration/export fallback"] ``` -## 监控城市（45） +## 监控城市（52） -- 欧洲/中东：Ankara、Istanbul、Moscow、London、Paris、Munich、Milan、Warsaw、Madrid、Tel Aviv、Amsterdam、Helsinki -- 亚太：Seoul、Busan、Hong Kong、Lau Fau Shan、Taipei、Shanghai、Beijing、Wuhan、Chengdu、Chongqing、Shenzhen、Singapore、Tokyo、Kuala Lumpur、Jakarta、Wellington -- 美洲：Toronto、New York、Los Angeles、San Francisco、Denver、Austin、Houston、Chicago、Dallas、Miami、Atlanta、Seattle、Mexico City、Buenos Aires、Sao Paulo、Panama City -- 南亚：Lucknow +- 欧洲/中东/非洲：Ankara、Istanbul、Moscow、London、Paris、Munich、Milan、Warsaw、Madrid、Tel Aviv、Amsterdam、Helsinki、Lagos、Cape Town、Jeddah +- 亚太：Seoul、Busan、Hong Kong、Lau Fau Shan、Taipei、Shanghai、Beijing、Wuhan、Chengdu、Chongqing、Shenzhen、Guangzhou、Singapore、Tokyo、Kuala Lumpur、Jakarta、Manila、Wellington +- 美洲：Toronto、New York、Los Angeles、San Francisco、Aurora、Austin、Houston、Chicago、Dallas、Miami、Atlanta、Seattle、Mexico City、Buenos Aires、Sao Paulo、Panama City +- 南亚：Lucknow、Karachi、Masroor Air Base ## 快速启动 @@ -221,6 +224,9 @@ docker compose logs -f polyweather | egrep "polymarket wallet activity watcher s - 支付 V2 升级方案：[docs/payments/PAYMENT_UPGRADE_V2_ZH.md](docs/payments/PAYMENT_UPGRADE_V2_ZH.md) - 运营后台说明：[docs/OPS_ADMIN_ZH.md](docs/OPS_ADMIN_ZH.md) - 外部监控说明：[docs/MONITORING_ZH.md](docs/MONITORING_ZH.md) +- 模型栈与 DEB：[docs/MODEL_STACK_AND_DEB_ZH.md](docs/MODEL_STACK_AND_DEB_ZH.md) +- LightGBM 日最高温模型：[docs/LGBM_DAILY_HIGH_ZH.md](docs/LGBM_DAILY_HIGH_ZH.md) +- EMOS + LGBM 系统：[docs/EMOS_LGBM_SYSTEM_ZH.md](docs/EMOS_LGBM_SYSTEM_ZH.md) - 深度评估报告：[docs/deep-research-report.md](docs/deep-research-report.md) - 前端报告：[FRONTEND_REDESIGN_REPORT.md](FRONTEND_REDESIGN_REPORT.md) - 发布流程：[RELEASE.md](RELEASE.md) @@ -228,5 +234,5 @@ docker compose logs -f polyweather | egrep "polymarket wallet activity watcher s ## 当前版本 -- 版本：`v1.5.3` -- 文档最后更新：`2026-04-10` +- 版本：`v1.5.4` +- 文档最后更新：`2026-04-18` diff --git a/VERSION b/VERSION index 8af85beb..94fe62c2 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.5.3 +1.5.4 diff --git a/docs/API_ZH.md b/docs/API_ZH.md index 7d3a09c1..e9297cb2 100644 --- a/docs/API_ZH.md +++ b/docs/API_ZH.md @@ -1,6 +1,6 @@ -# PolyWeather API 文档（v1.5.1） +# PolyWeather API 文档（v1.5.4） -最后更新：`2026-03-24` +最后更新：`2026-04-18` 本文档描述当前对外可用 API 口径（`web/app.py` + `web/routes.py` + `frontend/app/api/*`）。 @@ -48,6 +48,13 @@ flowchart LR - `market_scan.anchor_model / anchor_high / anchor_settlement` - `market_scan.yes_buy / no_buy` - `market_scan.primary_market.tradable` +- `probabilities.engine / calibration_mode / calibration_version` +- `probabilities.raw_mu / raw_sigma / calibrated_mu / calibrated_sigma` +- `probabilities.shadow_distribution` +- `intraday_meteorology.headline / confidence` +- `intraday_meteorology.base_case_bucket / upside_bucket / downside_bucket` +- `intraday_meteorology.next_observation_time` +- `intraday_meteorology.invalidation_rules / confirmation_rules / signal_contributions` - `peak.first_h / peak.last_h / peak.status` - `vertical_profile_signal.heating_setup / suppression_risk / trigger_risk / mixing_strength` - `taf.signal.peak_window / suppression_level / disruption_level / markers` @@ -56,7 +63,50 @@ flowchart LR `/api/city/{name}/detail` 现在会返回一组更偏交易场景的结构字段： -#### 1. `peak` +#### 1. `intraday_meteorology` + +今日日内分析的专业气象判断层。该字段只做派生，不改变路由和缓存策略。 + +重点字段： + +- `headline`：今日主判断，例如“峰值仍有上修空间 / 峰值受云雨压制” +- `confidence`：`low | medium | high` +- `base_case_bucket`：基准温度档位 +- `upside_bucket`：上修路径档位 +- `downside_bucket`：下修路径档位 +- `next_observation_time`：下一次应重点看的本地时间 +- `invalidation_rules`：2-4 条失效条件 +- `confirmation_rules`：1-3 条确认条件 +- `signal_contributions`：气象因子列表，含 `label`、`direction`、`strength`、`summary` + +前端如果该字段暂缺，会降级使用现有 `paceView`、`boundaryRiskView`、`upperAirCue`、`probabilitySummary` 等字段。 + +#### 2. `probabilities` + +概率层现在按“校准模型概率”对外解释，而不是直接把模型票数或市场价格当成概率。 + +新增 / 重点字段： + +- `engine`：概率引擎名称，例如 `lgbm_calibrated`、`emos`、`legacy` +- `calibration_mode`：校准运行模式 +- `calibration_version`：校准产物版本 +- `raw_mu` / `raw_sigma`：原始分布参数 +- `calibrated_mu` / `calibrated_sigma`：校准后分布参数 +- `shadow_distribution`：shadow / 对照分布，供回归与灰度验证 + +当前前端会优先展示 LGBM / EMOS 等校准概率；模型共识与市场价格只作为辅助参考，不再作为主结论。 + +#### 3. `detail_depth` + +`detail_depth` 用于区分轻量 detail 与完整 detail。前端如果发现： + +- `detail_depth != "full"` +- 或 `forecast.daily` 只有当天一张卡 +- 或模型层只剩单模型 + +会触发强刷完整 detail，并在 UI 上显示同步状态 / 占位卡，避免用户把中间态误判成完整分析。 + +#### 4. `peak` - `first_h`：预计峰值窗口起始小时 - `last_h`：预计峰值窗口结束小时 @@ -64,7 +114,7 @@ flowchart LR 这组字段用于让日内结构信号围绕真实峰值窗口分析，而不是固定只看下午。 -#### 2. `vertical_profile_signal` +#### 5. `vertical_profile_signal` 重点字段： @@ -86,7 +136,7 @@ flowchart LR 这组字段对应前端“高空结构信号 / Upper-Air Structure”卡片。 -#### 3. `taf.signal` +#### 6. `taf.signal` 仅对**非香港机场城市**启用。当前已支持解析： @@ -109,6 +159,12 @@ flowchart LR `markers` 会被前端温度走势图拿来做 `TAF 时段 / TAF Timing` 标记。 +#### 7. 结算锚点口径 + +- 多数机场市场以 `METAR` / 机场主站实况为结算锚点。 +- `Wunderground` 是历史页面或参考入口，不应在产品文案里被描述成“站”。 +- `MGM / NMC / JMA / KMA / HKO / CWA` 等官方站网属于增强层或明确官方站点层；只有合约规则明确指定时，才作为最终结算站点。 + ## 4. 鉴权与账户接口 | 接口 | 方法 | 用途 | @@ -196,6 +252,7 @@ flowchart LR - `summary?force_refresh=true`：`Cache-Control: no-store` - 详情接口与支付接口：`no-store` - `METAR` / `TAF` / settlement current 由后端各自维护短 TTL 缓存 +- 前端打开今日日内分析时，如果 full detail 或 market scan 正在同步，会先显示刷新锁，不展示可交互的旧内容 ## 9. 调试示例 diff --git a/docs/COMMERCIALIZATION.md b/docs/COMMERCIALIZATION.md index 9857f1ca..7795372c 100644 --- a/docs/COMMERCIALIZATION.md +++ b/docs/COMMERCIALIZATION.md @@ -1,6 +1,6 @@ # 商业化说明（Production） -最后更新：`2026-03-14` +最后更新：`2026-04-18` ## 1. 定位 @@ -8,9 +8,10 @@ PolyWeather 是面向温度结算场景的气象决策层，不是通用天气 核心价值： -- 观测优先（METAR/MGM） -- 结算导向（DEB + 概率桶） -- 市场映射（行情对照 + 错价雷达） +- 观测优先（METAR / 机场主站 / 明确官方站点；MGM、NMC、JMA、KMA 等作为增强层） +- 结算导向（DEB + 校准概率桶） +- 气象判断优先（证据链、失效条件、下一观测点） +- 市场映射（行情对照 + 错价雷达），但不把交易建议放在第一层产品承诺 ## 2. 当前收费能力状态 @@ -30,6 +31,8 @@ PolyWeather 是面向温度结算场景的气象决策层，不是通用天气 - 登录用户：账户中心、钱包绑定、积分同步。 - Pro 用户： - 今日日内深度分析（含高温时段） + - 专业气象结论条、证据链、失效条件、确认条件 + - LGBM / EMOS 等校准概率层 - 历史对账 + 未来日期分析 - 全平台智能气象推送 @@ -57,6 +60,8 @@ PolyWeather 是面向温度结算场景的气象决策层，不是通用天气 3. 审计能力：支付日志、订阅变更、异常重试可追溯。 4. 通知策略：支付成功私发、群内通知降噪。 5. 安全边界：敏感配置不进仓库。 +6. 数据口径：机场市场按 METAR / 机场主站解释；Wunderground 只可描述为历史页面或参考入口，不描述成“站”。 +7. 加载口径：日内分析和右侧详情在 full detail 未补齐前必须显示同步状态，不能把旧缓存伪装成完整付费内容。 ## 7. 后续路线 diff --git a/docs/EMOS_LGBM_SYSTEM_ZH.md b/docs/EMOS_LGBM_SYSTEM_ZH.md index 66fc0c03..aa05af8a 100644 --- a/docs/EMOS_LGBM_SYSTEM_ZH.md +++ b/docs/EMOS_LGBM_SYSTEM_ZH.md @@ -1,5 +1,7 @@ # EMOS + LGBM 系统说明（中文） +最后更新：`2026-04-18` + 本文档用于完整说明 PolyWeather 当前的两条统计/机器学习链路： - `EMOS`：概率后处理与校准链路 @@ -309,7 +311,14 @@ LGBM 训练样本会优先从： - `Taipei` - `Shenzhen` -这两个城市已经切到了市场指定的 `Wunderground` 结算口径。 +这两个城市配置了 `Wunderground` 历史页面作为历史观测取数入口。 + +这里要注意产品文案口径： + +- `Wunderground` 不是物理观测站 +- 它只是历史页面 / 数据入口 +- 机场类市场仍应以 METAR / 机场主站作为结算锚点 +- 明确官方站点市场才以规则指定的官方站点作为最终结算锚点 之前的问题是： @@ -334,7 +343,7 @@ LGBM 训练样本会优先从： 5. 写入永久真值表 6. 记录来源与审计信息 -这一步对 `Taipei/Shenzhen` 尤其关键，因为它们不是 NOAA/HKO 口径。 +这一步对 `Taipei/Shenzhen` 尤其关键，因为它们的历史页面取数和普通 METAR bootstrap 不同。 --- @@ -358,9 +367,12 @@ LGBM 训练样本会优先从： - 辅助预测源 - 研究/观测链路 +- 校准概率层的一个可用引擎输入 不适合替代 `DEB` 主路径。 +前端展示上，`LGBM 校准概率` 代表概率层已使用 LGBM 上下文生成桶分布；它不是把模型四舍五入票数直接当成概率。模型共识仍只是解释层，市场价格也只作为参考层。 + --- ## 9. 当前最新状态 @@ -650,4 +662,3 @@ EMOS 更依赖： - [LGBM_DAILY_HIGH_ZH.md](/E:/web/PolyWeather/docs/LGBM_DAILY_HIGH_ZH.md) - [PROBABILITY_SNAPSHOT_ARCHIVE_ZH.md](/E:/web/PolyWeather/docs/PROBABILITY_SNAPSHOT_ARCHIVE_ZH.md) - [deep-research-report.md](/E:/web/PolyWeather/docs/deep-research-report.md) - diff --git a/docs/LGBM_DAILY_HIGH_ZH.md b/docs/LGBM_DAILY_HIGH_ZH.md index dd68b4cc..9a9c8dc7 100644 --- a/docs/LGBM_DAILY_HIGH_ZH.md +++ b/docs/LGBM_DAILY_HIGH_ZH.md @@ -1,5 +1,7 @@ # LightGBM 日最高温模型（中文） +最后更新：`2026-04-18` + ## 1. 目标 这套 `LightGBM` 模型是给 PolyWeather 增加一个轻量级的统计学习预测源。 @@ -22,9 +24,11 @@ - `D1-D3` - 小时级曲线 -- 概率分布 +- 原始独立概率分布 - 独立结算源 +注意：前端出现的“LGBM 校准概率”不是把 LGBM 模型票数直接当成概率，而是概率层基于 LGBM / DEB / 观测上下文输出的校准分布。模型共识只保留为解释性参考。 + ## 2. 适用场景 这条链路是为低资源 VPS 准备的。 @@ -214,6 +218,17 @@ - `LGBM` 需要吃到 `deb_prediction` 特征 - 但最终 `DEB` 又要把 `LGBM` 当成一个新的输入模型 +## 8.1 前端概率展示口径 + +当前网页的概率区按以下顺序解释： + +1. 如果后端 `probabilities.engine` 表示 LGBM 校准概率可用，则标题显示为 `LGBM 校准概率`。 +2. 如果 LGBM 不可用，但 EMOS / legacy 概率可用，则显示为 `校准模型概率`。 +3. 模型舍入票数只保留为“模型共识参考”，用于说明哪些模型四舍五入后落在同一温度档，不作为最终命中概率。 +4. 市场价格只保留为“市场参考”，不和校准概率混成同一结论。 + +这能避免用户把 `4/8 模型支持 82°F` 误读成 `82°F 有 50% 概率`。模型共识是解释层，概率引擎才是结论层。 + ## 9. 环境变量 示例配置见： diff --git a/docs/MODEL_STACK_AND_DEB_ZH.md b/docs/MODEL_STACK_AND_DEB_ZH.md index 073d18f2..13d96647 100644 --- a/docs/MODEL_STACK_AND_DEB_ZH.md +++ b/docs/MODEL_STACK_AND_DEB_ZH.md @@ -2,6 +2,8 @@ 本文档记录 PolyWeather 当前开放模型接入、区域覆盖差异，以及 DEB 在新增模型后的计权规则。 +最后更新：`2026-04-18` + ## 1. 接入方式 当前多模型层通过 Open-Meteo model API 接入开放 NWP / AIFS 等预报模型，不直接下载原始 GRIB。 @@ -33,7 +35,7 @@ Web API 会把这部分元数据挂到： | 显示名 | Open-Meteo key | 来源 | 层级 | 说明 | | --- | --- | --- | --- | --- | | ECMWF | `ecmwf_ifs025` | ECMWF | global | IFS 全球传统数值模式 | -| ECMWF AIFS | `ecmwf_aifs025_single` | ECMWF | aifs_global | ECMWF AIFS 模型 | +| ECMWF AIFS | `ecmwf_aifs025_single` | ECMWF | aifs_global | ECMWF AIFS 模型；产品文案保留 AIFS 名称，避免和外部泛神经天气模型混淆 | | GFS | `gfs_seamless` | NOAA | global | NOAA 全球参考 | | ICON | `icon_seamless` | DWD | global | DWD ICON 全球基准 | | ICON-EU | `icon_eu` | DWD | regional_europe | 欧洲区域高分辨率 | @@ -196,6 +198,32 @@ raw current_forecasts 区域模型不覆盖时不显示空模型。 +### 6.1 “来源 Open-Meteo”是什么意思 + +前端中的 `来源 - Open-Meteo` 表示本次多模型数据通过 Open-Meteo model API 归一化接入。 + +它不表示： + +- Open-Meteo 是单一数值模型 +- Open-Meteo 生成了所有预报 +- ECMWF / DWD / ECCC / NOAA / JMA 的机构来源被替换 + +所以模型行仍会分别展示： + +- 机构：例如 ECMWF、DWD、ECCC、NOAA、JMA +- 接入接口：例如 Open-Meteo +- 模型 key：例如 `ecmwf_ifs025`、`icon_d2`、`gem_hrdps_continental` + +### 6.2 模型区间、校准概率、市场参考的关系 + +当前前端把三层拆开展示： + +- `模型区间与分歧`：解释不同模型当前给出的最高温范围和分歧，不直接等于命中概率。 +- `校准模型概率`：由概率引擎输出温度桶概率；有 LGBM 时展示 LGBM 校准概率，缺失时降级到 EMOS / legacy 概率。 +- `市场参考`：只展示市场价格和错价背景，不再作为主判断，也不默认输出 BUY YES / BUY NO。 + +模型票数只用于解释“哪些模型支持某个档位”，不等于最终概率。最终概率应优先读取 `probabilities.engine` 对应的校准分布。 + ## 7. 测试覆盖 相关测试： diff --git a/docs/MONITORING_ZH.md b/docs/MONITORING_ZH.md index 95152fad..80407777 100644 --- a/docs/MONITORING_ZH.md +++ b/docs/MONITORING_ZH.md @@ -1,6 +1,6 @@ # 外部监控与告警说明 -最后更新：`2026-04-10` +最后更新：`2026-04-18` ## 1. 目标 @@ -131,13 +131,45 @@ python scripts/check_ops_health.py --base-url http://127.0.0.1:8000 - `total_requests` - `cache_hits / cache_misses` - `hit_rate / miss_rate` +- 前端数据完整性状态： + - 城市详情是否仍处于 `detail_depth != full` + - 多日预报是否只返回当天单卡 + - 日内分析 full detail / market scan 是否仍在同步 + - 右侧详情面板是否正在用同步占位卡提示用户 这意味着： - 外部监控负责“服务活没活、错误有没有暴增” - `/ops` 和 `/api/system/status` 负责“预热有没有真的跑、缓存有没有真的被打热” +- 前端同步状态负责“用户现在看到的是完整分析，还是仍在补齐中的中间态” -## 9. 备注 +## 9. 前端中间态巡检 + +近期重点避免两类误判： + +1. 打开今日日内分析时，先看到上一轮城市 / 日期的旧内容，几秒后才刷新成正确结果。 +2. 右侧详情面板只到达当天单张多日卡，用户误以为未来预报缺失。 + +当前前端已做这些保护： + +- `today/future` 弹窗模式显式分离，今天按钮不会再偶发进入未来日期分析布局。 +- 今日日内分析同步期间显示刷新锁，旧内容降权、禁止交互。 +- 详情面板发现稀疏 detail 或单日 forecast 时显示补齐提示和同步占位卡。 + +手动验收建议： + +```bash +cd frontend +npm run build +``` + +然后在桌面和移动宽度分别检查： + +- 切换城市后立即打开“今日日内分析”，旧城市数据不应可交互。 +- 多日预报未补齐时，应看到同步提示，而不是只有一张“今天”卡。 +- full detail 到达后，占位卡自动消失。 + +## 10. 备注 这套监控现在已经具备： @@ -153,3 +185,4 @@ python scripts/check_ops_health.py --base-url http://127.0.0.1:8000 - 数据库体积趋势 - 更细粒度支付指标 - 按城市/来源拆分的业务 SLA +- 按城市拆分的前端补齐耗时与 stale-detail 告警 diff --git a/docs/PROBABILITY_SNAPSHOT_ARCHIVE_ZH.md b/docs/PROBABILITY_SNAPSHOT_ARCHIVE_ZH.md index 00471ed5..d314884f 100644 --- a/docs/PROBABILITY_SNAPSHOT_ARCHIVE_ZH.md +++ b/docs/PROBABILITY_SNAPSHOT_ARCHIVE_ZH.md @@ -1,5 +1,7 @@ # 概率训练样本归档说明（中文） +最后更新：`2026-04-18` + ## 1. 目的 这份文档说明两件事： @@ -27,6 +29,12 @@ - `max_so_far` - `peak_status` - `prob_snapshot` +- `probability_engine` +- `calibration_mode` +- `calibration_version` +- `raw_mu / raw_sigma` +- `calibrated_mu / calibrated_sigma` +- `shadow_distribution` - 当天最终 `actual_high` - 当天最终 `settlement bucket` @@ -167,7 +175,10 @@ ], "probability_engine": "legacy", "probability_mode": "emos_shadow", - "calibration_version": "emos-20260320130245" + "calibration_mode": "emos_shadow", + "calibration_version": "emos-20260320130245", + "calibrated_mu": 15.4, + "calibrated_sigma": 1.1 } ``` @@ -176,6 +187,8 @@ - `actual_high` - `settlement_bucket` +当前前端把这类快照解释为“校准模型概率”。如果 `probability_engine` 为 LGBM 相关值，则显示为 LGBM 校准概率；模型舍入票数和市场价格只用于解释，不直接作为最终概率。 + ## 7. 现阶段你可以执行的命令 ### 7.1 回填历史天气 CSV diff --git a/docs/deep-research-report.md b/docs/deep-research-report.md index 128df526..40e19cec 100644 --- a/docs/deep-research-report.md +++ b/docs/deep-research-report.md @@ -5,13 +5,13 @@ PolyWeather（仓库：`yangyuan-zhen/PolyWeather`）定位为**面向温度类结算预测市场（如 Polymarket 的温度结算合约）**的“生产级气象情报系统”，核心在于把多源天气观测/预报转化为**结算导向的概率桶（μ + bucket distribution）**，并进一步映射到市场报价完成**错价扫描**；同时提供 Web 仪表盘与 Telegram Bot 两套交互入口，并包含 Polygon 链上 USDC/USDC.e 支付、自动补单与订阅/积分体系。项目 README 现明确仓库代码采用 `AGPL-3.0-only`，同时将品牌、商标、生产私有数据与运营阈值保留在代码许可证之外。 从工程实现看，截至 `2026-04-03`，项目已经完成一轮更明确的工程化收口：多源天气采集仍保持现有业务能力，同时已完成采集层与 Web API 大文件拆分、CI 质量门禁、配置分级（`.env.example` / `.env.secrets.example` / 中文部署文档）、EMOS/CRPS 校准链路、运行态状态与缓存迁移到 SQLite 主路径，以及最小外部监控链路（`/healthz`、`/api/system/status`、`/metrics` + Prometheus + Alertmanager + Grafana + Telegram relay）。除此之外，项目还补上了**历史真值治理**：`daily_records` 继续只保留近 14 天运行态缓存，但新增了永久真值表、真值 revision 审计表和长期训练特征表，并开始把监督真值与训练特征从“短期缓存”正式拆到“长期可追溯存储”。 这意味着报告里最初最突出的“工程地基缺失”问题，已经有一部分被关闭：`src/data_collection/weather_sources.py` 与 `web/app.py` 不再是原来的超大单文件；GitHub Actions 已覆盖 Python、前端和 Docker build；配置与密钥治理已成体系；运行态状态不再只能依赖 JSON/JSONL 文件；EMOS 也不再只是概念，而是进入了可训练、可评估、可 shadow、可门禁判断的阶段；更重要的是，监督真值与训练特征不再只能附着在 14 天运行态缓存上。 -但项目仍处在“从可用走向稳态”的中段，而不是终局。当前真正的高优先级问题已进一步收敛：**EMOS 仍未达到生产切换标准**，当前门禁结论明确为 `hold`，阻塞原因是 shadow bucket brier 明显退化，同时历史长期特征仍处在“刚开始积累”的阶段。SQLite 迁移方面，运行态主读切换和核心离线训练/回填链路已经完成验收：在移除 `data/*.json` / `data/*.jsonl` 后，训练、评估、shadow report 与关键 backfill 脚本仍可仅依赖运行时数据库正常执行；当前保留的 legacy 文件路径主要用于迁移、导出、校验和显式回退输入。历史真值治理方面，新增的永久真值表、revision 审计表与长期训练特征表已经落地，`Taipei` / `Shenzhen` 的 `Wunderground` 历史回填也已接通，因此当前缺口已从“历史真值是否会继续丢失”转为“历史特征是否能持续增长并支撑 EMOS/LGBM 评估”。可观测性方面，最小外部监控链路已经补齐：Prometheus 抓取、Alertmanager 规则、Grafana 面板、Telegram 告警 relay 与巡检脚本均已落地；当前剩余缺口已从“有没有外部监控”转为“监控覆盖深度是否足够”，例如节点级资源、数据库体积趋势、支付细粒度指标、按城市/来源拆分的业务 SLA。支付链路方面，链下审计与容灾已明显增强：事件重放、SQLite 审计事件、RPC 多节点容灾、合约静态检查、`/ops` 支付异常单都已补齐；当前剩余风险主要集中在**链上合约本身仍是最小实现**，尚未升级到 SafeERC20、Pausable、链上套餐绑定等更强防护版本。 +但项目仍处在“从可用走向稳态”的中段，而不是终局。当前真正的高优先级问题已进一步收敛：**EMOS 仍未达到生产切换标准**，当前门禁结论明确为 `hold`，阻塞原因是 shadow bucket brier 明显退化，同时历史长期特征仍处在“刚开始积累”的阶段。SQLite 迁移方面，运行态主读切换和核心离线训练/回填链路已经完成验收：在移除 `data/*.json` / `data/*.jsonl` 后，训练、评估、shadow report 与关键 backfill 脚本仍可仅依赖运行时数据库正常执行；当前保留的 legacy 文件路径主要用于迁移、导出、校验和显式回退输入。历史真值治理方面，新增的永久真值表、revision 审计表与长期训练特征表已经落地，`Taipei` / `Shenzhen` 的历史页面回填也已接通，因此当前缺口已从“历史真值是否会继续丢失”转为“历史特征是否能持续增长并支撑 EMOS/LGBM 评估”。可观测性方面，最小外部监控链路已经补齐：Prometheus 抓取、Alertmanager 规则、Grafana 面板、Telegram 告警 relay 与巡检脚本均已落地；当前剩余缺口已从“有没有外部监控”转为“监控覆盖深度是否足够”，例如节点级资源、数据库体积趋势、支付细粒度指标、按城市/来源拆分的业务 SLA。支付链路方面，链下审计与容灾已明显增强：事件重放、SQLite 审计事件、RPC 多节点容灾、合约静态检查、`/ops` 支付异常单都已补齐；当前剩余风险主要集中在**链上合约本身仍是最小实现**，尚未升级到 SafeERC20、Pausable、链上套餐绑定等更强防护版本。 因此，当前阶段最正确的策略已经不是继续做“大范围基础重构”，而是围绕**EMOS 上线门禁稳定化、长期训练特征持续积累、监控覆盖深挖、支付合约防护升级**这四条线持续收口。短中期内更高 ROI 的方向依然不是引入新的大模型，而是把现有“采集→后处理→市场映射→支付/订阅”的链路做成**状态一致、指标可见、发布可控、回退明确**的生产平台。 ## 项目概览 PolyWeather 的目标与范围在 README/README_ZH 中定义得较清楚：为温度结算市场提供气象情报（多源采集→融合→概率→对照市场报价），并提供“官方看板（Vercel 前端）+ VPS 后端 + Telegram Bot”。 项目主功能可归纳为四层： -**天气层（数据源/采集）**：聚合 39 个城市的实测与预报；支持 AviationWeather METAR（机场观测）、土耳其 MGM 站网、Open-Meteo（含多模型与集合预报）、美国 NWS（仅美国城市）、以及部分城市使用官方结算源（香港 HKO、台北 RCSS/Wunderground、深圳 ZGSZ/Wunderground）等。 +**天气层（数据源/采集）**：聚合 52 个城市的实测与预报；支持 AviationWeather METAR（机场观测）、土耳其 MGM 站网、Open-Meteo（含多模型与集合预报）、美国 NWS（仅美国城市）、以及部分城市使用明确官方站点或历史页面入口（香港 HKO、台湾/深圳相关历史页面等）等。机场类市场仍以 METAR / 机场主站为结算锚点，Wunderground 不描述为物理观测站。 **分析层（DEB/趋势/概率/结算口径）**： DEB（Dynamic Error Balancing）基于过去 N 天模型误差（MAE）倒数加权，输出融合预报；运行态仍维护近 14 天 `daily_records` 缓存做当前对账，但长期监督真值与训练特征已经迁到 SQLite 永久表中，并支持基于 WU（Weather Underground 口径）四舍五入的结算命中评估。 趋势/概率引擎在 `trend_engine.py` 中实现：综合“集合预报区间→σ/μ→高温窗口→死盘判定→温度桶概率分布→边界提示”等，用于 bot 展示与 web 结构化数据输出。 @@ -146,12 +146,12 @@ Web/Telegram 请求 → FastAPI 调用采集器抓取/复用缓存 → 分析引 **可复现性已从“缺模板”进入“模板与生产对齐”的阶段**：`.env.example`、`.env.secrets.example`、中文配置文档、前端部署文档、运行时配置校验器都已存在；当前风险主要在于线上历史 `.env` 与新模板并存、旧变量命名残留、以及密钥轮换与分层是否真正落实。 **CI 已建立，但组织级质量门禁未必完全收口**：CI 现已覆盖 Python、前端与 Docker build。当前问题不再是“缺 CI”，而是是否把这些 status check 绑定到 `main` 保护策略，以及是否逐步引入更严格的 pre-merge 审查。 **运行态状态/缓存与核心离线链路的 SQLite 收口已完成**：`daily_records`、`telegram_alert_state`、`probability_training_snapshots`、`open_meteo` 缓存已经支持并在生产中主读 SQLite，迁移/校验脚本可用；进一步地，在临时移除 `data/*.json` / `data/*.jsonl` 后，训练集导出、概率拟合、评估报告、shadow report 和关键 backfill 脚本已验证仍可运行。当前 legacy 文件路径主要是显式回退入口，而不再是默认主输入。 -**历史真值治理已从设计缺陷修复到可追溯运行**：`daily_records` 继续作为近 14 天运行态缓存，但已经不再承担长期监督真值职责；项目新增了永久真值表、真值 revision 审计表和长期训练特征表，并为 `Taipei` / `Shenzhen` 补上了 `Wunderground` 历史回填链路。当前风险已不再是“监督真值会不会继续被 14 天裁剪吞掉”，而是“历史长期特征能否持续积累到足够支撑 EMOS/LGBM 重新评估”。 +**历史真值治理已从设计缺陷修复到可追溯运行**：`daily_records` 继续作为近 14 天运行态缓存，但已经不再承担长期监督真值职责；项目新增了永久真值表、真值 revision 审计表和长期训练特征表，并为 `Taipei` / `Shenzhen` 补上了历史页面回填链路。当前风险已不再是“监督真值会不会继续被 14 天裁剪吞掉”，而是“历史长期特征能否持续积累到足够支撑 EMOS/LGBM 重新评估”。 **第三方服务合规与稳定性风险**： 项目强依赖外部 API（Open-Meteo、AviationWeather、NWS、HKO、CWA、Polymarket、Supabase）。其中 AviationWeather Data API 有明确速率限制；Polymarket 官方说明 Gamma/Data/CLOB 三套 API 分属不同域，CLOB 交易端点需鉴权且策略可能变化；Supabase 明确强调 `service_role`/secret keys 绝不可暴露。若缺乏集中治理（重试/退避/熔断/降级/配额监控/密钥轮换），稳定性与合规不可控。 **可观测性最小闭环已完成，但监控深度仍待加强**：项目现在已有 `/healthz`、`/api/system/status`、`/metrics`，并已补齐 Prometheus 抓取、Alertmanager 规则、Grafana 面板、Telegram relay 与巡检脚本。与此同时，`/ops` 已经逐步演进为后台管理台而不只是状态页：除支付、会员、用户与 EMOS 门禁外，还新增了训练数据治理卡片、城市覆盖矩阵，以及 `/ops/truth-history` 这种可直接查询 `actual_high / settlement_source / station_code / truth_version / updated_by / updated_at` 的真值表浏览页。当前缺口不再是“有没有外部监控”，而是节点级资源、数据库体积趋势、更细粒度支付指标、按城市/来源拆分的业务 SLA，以及是否需要进一步补 `truth revision` 明细页、趋势图和运营日报。 **EMOS 已完成工程接入，但未完成生产发布**：EMOS/CRPS 校准、shadow 观测、rollout report、上线门禁都已实现；当前真实门禁结果为 `hold`，阻塞原因是 shadow bucket brier 明显退化。因此概率引擎标准化并非未做，而是“工程完成、发布未通过”。 -**许可证/商业使用的潜在冲突点**：仓库自身现为 `AGPL-3.0-only`，但如果未来尝试引入外部 AI 预报模型，仍需单独核验第三方代码与权重的商用条件：GraphCast 仓库代码 Apache-2.0，但权重使用 CC BY-NC-SA 4.0（非商业），Pangu-Weather 权重同样 BY-NC-SA 且明确禁止商业用途；不加区分地把这些模型用于付费产品会留下法律风险。 +**许可证/商业使用的潜在冲突点**：仓库自身现为 `AGPL-3.0-only`，但如果未来尝试引入外部神经天气模型，仍需单独核验第三方代码与权重的商用条件：GraphCast 仓库代码 Apache-2.0，但权重使用 CC BY-NC-SA 4.0（非商业），Pangu-Weather 权重同样 BY-NC-SA 且明确禁止商业用途；不加区分地把这些模型用于付费产品会留下法律风险。 ## 对标分析 为满足“至少 3 个相似开源项目或近期论文”对标，本报告选择三类代表： @@ -162,7 +162,7 @@ Web/Telegram 请求 → FastAPI 调用采集器抓取/复用缓存 → 分析引 | 项目/论文 | 解决的问题 | 输出形态 | 性能/效果（公开描述） | 易用性与依赖 | 许可证要点 | | --------------------------------------------------------- | ---------------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -| **PolyWeather**（本仓库） | 温度结算市场气象情报：多源→概率桶→错价扫描→订阅/支付 | 生产级应用（Web+Bot+API+支付） | 以工程能力为主；内置 DEB、概率桶、死盘判定、市场扫描；当前覆盖 39 城市，并已补齐真值治理与后台运维视图。 | 主要依赖外部 API；Docker Compose 一键启动。 | 仓库 `AGPL-3.0-only`；品牌、生产私有数据与运营规则不随代码许可证授权。 | +| **PolyWeather**（本仓库） | 温度结算市场气象情报：多源→校准概率桶→错价扫描→订阅/支付 | 生产级应用（Web+Bot+API+支付） | 以工程能力为主；内置 DEB、LGBM/EMOS 校准概率、死盘判定、市场扫描；当前覆盖 52 城市，并已补齐真值治理与后台运维视图。 | 主要依赖外部 API；Docker Compose 一键启动。 | 仓库 `AGPL-3.0-only`；品牌、生产私有数据与运营规则不随代码许可证授权。 | | **GraphCast**（google-deepmind/graphcast） | 10 天全球中期预报（ML 替代/增强 NWP） | 模型代码+权重+notebooks | 论文与介绍提到在大量指标上优于主流确定性系统；仓库提供预训练权重与示例数据入口，并提示 ERA5/HRES 数据条款需另行遵守。 | 完整训练需 ERA5 等；更适合科研/平台级推理，不是产品级 BFF。 | 代码 Apache-2.0；权重 CC BY-NC-SA 4.0（商业限制）。 | | **FourCastNet**（NVlabs/FourCastNet） | 高分辨率 data-driven 全球预报（AFNO/ViT） | 模型训练/推理代码+数据/权重链接 | README 描述：0.25° 分辨率、周尺度推理非常快，并可做大规模集合；适合平台型预报。 | 训练/数据依赖大（ERA5 子集 TB 级）；工程集成成本高。 | BSD 3-Clause（代码）。 | | **Pangu-Weather**（198808xc/Pangu-Weather + Nature 论文） | 3D Transformer 架构的中期全球预报 | ONNX 推理代码+预训练模型 | Nature 论文称在 reanalysis 上对比 IFS 有更强确定性预报表现，并强调速度优势；仓库提供 ONNX 推理与 lite 版训练说明。 | 模型文件大（多份 ~GB 级），训练资源需求高；更适合科研推理或内部平台。 | 权重 BY-NC-SA 4.0、明确禁止商业用途。 | @@ -170,19 +170,19 @@ Web/Telegram 请求 → FastAPI 调用采集器抓取/复用缓存 → 分析引 | **Polymarket/py-clob-client** | Polymarket CLOB 读写 SDK | Python SDK | 官方 SDK，支持 read-only 与交易接口；协议与端点在官方文档中给出。 | 易用，适合增强 PolyWeather 市场层。 | MIT。 | | **aiopolymarket** | Polymarket APIs 的 async 客户端 | Python async 客户端 | 强调类型安全（Pydantic）、自动分页、重试与 backoff，适合高并发与健壮性诉求。 | 适合替换/补强当前同步 requests 与自定义缓存。 | 以仓库许可为准（此处建议上线前核验）。 | -**对标结论**：PolyWeather 与这类“全球 AI 预报模型”不在同一层级：PolyWeather 是“面向结算市场的产品化情报系统”，其价值核心是**将预测转成可交易/可结算的决策信息**。短中期内更高 ROI 的方向不是“自训大模型”，而是把现有“采集+后处理+市场映射”的链路做成**可复现、可观测、可评测、可扩展**的工程平台；在许可合规前提下，再评估引入外部模型推理作为额外信号源。 +**对标结论**：PolyWeather 与这类“全球神经天气模型”不在同一层级：PolyWeather 是“面向结算市场的产品化情报系统”，其价值核心是**将预测转成可交易/可结算的决策信息**。短中期内更高 ROI 的方向不是“自训大模型”，而是把现有“采集+后处理+市场映射”的链路做成**可复现、可观测、可评测、可扩展**的工程平台；在许可合规前提下，再评估引入外部模型推理作为额外信号源。 ## 优先级改进建议 下表按截至 `2026-04-03` 的真实状态重排优先级。已完成项不再继续列为“待做”，只保留当前仍需推进的事项。 | 优先级 | 改进项 | 预估工作量 | 主要收益 | 主要风险 | 可执行步骤（建议顺序） | | ------ | --------------------------------------------------------------------------------------------------------------------------------- | -------------------: | ------------------------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 高 | **稳定 EMOS shadow 并收紧上线门禁** | 1–2 周 | 让概率引擎升级具备明确发布条件，避免拍脑袋切换 | 当前 shadow bucket brier 退化明显，存在误上线风险 | 1) 持续积累 snapshot 样本 → 2) 定期重训与生成 `evaluation_report` / `shadow_report` / `rollout_report` → 3) 重点压 `bucket_brier` 退化 → 4) 只有门禁从 `hold` 进入 `observe/promote` 后才考虑上线 | -| 高 | **持续积累长期训练特征，验证 SQLite 真值治理后的样本增长** | 1–2 周 | 让 EMOS/LGBM 的重训真正建立在长期可信样本上，而不是继续被短期特征缺口卡住 | 当前真值已长期化，但历史长期特征仍偏少，EMOS/LGBM 样本增长会滞后 | 1) 持续写入 `training_feature_records_store` → 2) 每日检查 `/ops` 训练数据与 `/ops/truth-history` → 3) 定期对 `Taipei` / `Shenzhen` 的 Wunderground 回填做抽查 → 4) 观察样本是否自然增长后再重训 | +| 高 | **持续积累长期训练特征，验证 SQLite 真值治理后的样本增长** | 1–2 周 | 让 EMOS/LGBM 的重训真正建立在长期可信样本上，而不是继续被短期特征缺口卡住 | 当前真值已长期化，但历史长期特征仍偏少，EMOS/LGBM 样本增长会滞后 | 1) 持续写入 `training_feature_records_store` → 2) 每日检查 `/ops` 训练数据与 `/ops/truth-history` → 3) 定期对 `Taipei` / `Shenzhen` 的历史页面回填做抽查 → 4) 观察样本是否自然增长后再重训 | | 中 | **把最小外部监控继续补深**：从“可告警”提升到“可运营” | 3–7 天 | 不再只知道服务坏没坏，还能看资源趋势、来源 SLA 和支付波动 | 指标过多会带来维护噪音 | 1) 增加节点 CPU/内存/磁盘 → 2) 增加 SQLite/支付体积与事件趋势 → 3) 把 HTTP/来源指标细分到城市/来源维度 → 4) 增加日报或异常摘要 | | 中 | **市场层升级为 async + 类型安全**：引入 `aiopolymarket` 或在现有层加重试/backoff/连接池 | 4–7 天 | 行情层更稳，减少短时网络抖动；更易扩展更多市场/分页 | 依赖升级带来的行为差异 | 1) 把 requests.Session 替换为 aiohttp/httpx → 2) 在 Gamma/CLOB 调用侧实现指数退避 → 3) 引入 typed models，减少解析失败 | | 中 | **支付合约从“最小可用”升级到“更强合约防护”** | 1–2 周 | 在已完成的链下审计与容灾之上，进一步收紧链上授权边界 | 合约升级需要重新部署、迁移配置并再次验证 | 1) 维持现有事件重放、SQLite 审计、多 RPC fallback → 2) 升级合约到 SafeERC20 + Pausable → 3) 评估链上 plan/amount/token 绑定或 EIP-712 签名校验 → 4) 迁移后更新 PolygonScan 验证与支付审计文档 | | 中 | **将 CI 与分支保护/发布流程真正绑定** | 1–3 天 | 让现有 CI 从“存在”变成“强制门禁” | 历史分支/热修流程可能受影响 | 1) GitHub `main` 开启 required checks → 2) 把 release/tag 流程绑定 CI → 3) 明确热修例外流程 | -| 低 | **引入外部 AI 预报模型作为附加信号**（GraphCast/FourCastNet/Pangu-Weather 等） | 2–6 周（取决于范围） | 可能提升极端/中期预测能力与差异化 | **商业许可限制**（多为 CC BY-NC-SA/禁止商业）与算力成本 | 1) 先做合规评审（权重许可/数据条款）→ 2) 仅在研究/非商业环境评估 → 3) 若要商用，优先选择可商用权重或自研/购买授权 | +| 低 | **引入外部神经天气模型作为附加信号**（GraphCast/FourCastNet/Pangu-Weather 等） | 2–6 周（取决于范围） | 可能提升极端/中期预测能力与差异化 | **商业许可限制**（多为 CC BY-NC-SA/禁止商业）与算力成本 | 1) 先做合规评审（权重许可/数据条款）→ 2) 仅在研究/非商业环境评估 → 3) 若要商用，优先选择可商用权重或自研/购买授权 | ### 文档、测试与贡献流程的具体补强建议（落到仓库层面） @@ -198,7 +198,7 @@ PolyWeather 的评测应围绕“结算场景”而非传统数值天气预报 **数据集**（建议从现有生产数据演进） 1）`truth_records_store + training_feature_records_store` 的长期样本：当前长期评测主源应优先来自永久真值表与长期训练特征表；legacy 的 `daily_records.json` 与 `settlement_history.json` 更适合作为迁移恢复与对照来源，而不是长期主输入。 -2）观测“真值”统一口径：对 METAR 城市用 AviationWeather Data API；对香港按 HKO、对台北/深圳按 `Wunderground RCSS/ZGSZ` 等结算源作为真值，和项目当前逻辑一致。 +2）观测“真值”统一口径：对 METAR 城市用 AviationWeather Data API；对香港等明确官方站点按合约指定站点；对需要历史页面取数的城市使用对应历史页面入口。Wunderground 只描述为历史页面 / 数据入口，不描述为物理观测站。 **指标** 1）确定性误差：MAE、RMSE（按城市、按季节、按风险等级分组）； 2）结算命中率：`WU_round(pred) == WU_round(actual)`（项目已有统计口径）； @@ -214,7 +214,7 @@ PolyWeather 的评测应围绕“结算场景”而非传统数值天气预报 - 若历史样本足够，DEB 应在“系统性偏差明显”的城市提升 MAE； - EMOS 类方法通常能在概率校准（可靠性与 CRPS）上更稳定，尤其当 ensemble 信息可用（项目已接入 Open-Meteo ensemble/p10/p90）。 -**算力**：以上评测全部可在 CPU 上完成；数据量按“39 城市 × 180 天”级别，pandas/duckdb 即可。若引入更复杂拟合（如分层贝叶斯/分位数回归），也通常不需要 GPU。 +**算力**：以上评测全部可在 CPU 上完成；数据量按“52 城市 × 180 天”级别，pandas/duckdb 即可。若引入更复杂拟合（如分层贝叶斯/分位数回归），也通常不需要 GPU。 ### 错价信号与市场有效性基准 **数据集** @@ -247,7 +247,7 @@ PolyWeather 的评测应围绕“结算场景”而非传统数值天气预报 **外部 API 速率限制/格式变更**：AviationWeather 明确 rate limit 与建议使用 cache 文件；Open-Meteo 也可能在不同端点策略上变化。缓解：统一“请求预算”与退避/熔断；关键响应做 schema 校验与回放测试；对高频数据优先拉取官方 cache/批量接口（若可用）。 **密钥泄露与权限滥用**：Supabase 明确强调 `service_role` 属高权限密钥，绝不可出现在前端或公开环境。缓解：密钥分级、CI secret scan、运行时最小权限、日志脱敏。 **支付链路最终一致性与链上不确定性**：链上事件索引延迟、RPC 不稳定、交易确认数不足都会导致误判。当前项目已经补齐“事件监听 + 确认补单”双路径、事件重放脚本、SQLite 审计事件与多 RPC fallback；现阶段的主要剩余风险不再是“没有防护”，而是链上合约仍为最小实现，owner 为单地址管理，且没有 pause 开关与 SafeERC20。 -**引入外部 AI 预报模型的商业合规风险**：GraphCast/Pangu-Weather 的权重许可均带非商业限制（CC BY-NC-SA/BY-NC-SA）；若 PolyWeather 是付费产品，必须先做法务与授权评审。缓解：只在研究环境评估；商用优先选择可商用权重/购买授权/自研。 +**引入外部神经天气模型的商业合规风险**：GraphCast/Pangu-Weather 的权重许可均带非商业限制（CC BY-NC-SA/BY-NC-SA）；若 PolyWeather 是付费产品，必须先做法务与授权评审。缓解：只在研究环境评估；商用优先选择可商用权重/购买授权/自研。 **代码公开与生产私有资产边界导致的“公开仓库与生产行为不一致”**：README 明确品牌、商标、生产私有数据与运营阈值不在代码许可证授权范围内。缓解：把“公开核心”的可复现与评测做扎实（接口/数据 schema/测试/评测），私有策略只作为可插拔 policy layer 接入。 ## 参考链接 diff --git a/frontend/README.md b/frontend/README.md index a313bbbd..23ea837f 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -22,13 +22,14 @@ PolyWeather Pro 的生产前端工程。 ## 当前前端能力 - 主站 Dashboard 支持地图、城市详情、今日日内分析、历史准确率对账和账户中心 -- `/docs` 已提供公开双语产品文档中心，解释日内结构信号、TAF、结算来源和历史对账 +- `/docs` 已提供公开双语产品文档中心，解释日内分析、校准概率、模型栈、TAF、结算来源和历史对账 - 今日日内分析支持： - `锚点状态` - `当前节奏` - - `当前命中胜率` + - `校准模型概率` - `模型区间与分歧` - - `今日日内结构信号` + - `专业气象结论条` + - `气象证据链 / 失效条件 / 确认条件` - 非香港机场城市的 `TAF` 时段提示与走势图联动 - 历史对账支持： - `DEB / 最佳单模型 / 实测最高温` 对比 @@ -36,6 +37,9 @@ PolyWeather Pro 的生产前端工程。 - `/ops` 已支持桌面表格 + 手机端卡片化视图 - 点击城市图标后会显示地图顶部同步提醒与详情面板内同步徽标，避免用户误判为卡住 - 城市详情会自动识别“单模型 / 单日”的稀疏缓存并主动刷新，避免误把残缺 detail 当作完整结果 +- 右侧详情面板在多日预报仍未补齐时会显示同步占位卡，不再把“只有今天一张卡”的中间态伪装成完整数据 +- 日内分析弹窗在 full detail / market scan 同步时会锁住旧内容并显示刷新状态，避免用户短暂看到旧城市或旧日期的数据 +- 概率区优先展示 LGBM / EMOS 等校准模型概率，模型共识和市场价格只作为辅助说明 - `/ops` 现已展示 prewarm worker 运行态、缓存桶状态与 summary cache hit/miss ## 本地开发 @@ -181,7 +185,8 @@ Ops： - `cities` / `summary` / `history`：`ETag + Cache-Control` - `summary?force_refresh=true`：`no-store` - 支付相关路由：`no-store` -- 当 detail 缓存只返回单模型或单日 forecast 时，前端会自动强刷完整 detail +- 当 detail 缓存只返回单模型或单日 forecast 时，前端会自动强刷完整 detail，并在补齐前显示同步提示 / 占位卡 +- 今日日内分析打开时如果正在切换城市、日期或 detail 深度，弹窗会阻断旧内容点击并显示刷新锁 ## Vercel 节流建议 @@ -196,4 +201,4 @@ Ops： 详见根目录策略文档：`docs/OPEN_CORE_POLICY.md` -最后更新：`2026-04-10` +最后更新：`2026-04-18` diff --git a/frontend/components/dashboard/DetailPanel.tsx b/frontend/components/dashboard/DetailPanel.tsx index 9c35b20f..8a7acd93 100644 --- a/frontend/components/dashboard/DetailPanel.tsx +++ b/frontend/components/dashboard/DetailPanel.tsx @@ -190,12 +190,12 @@ export function DetailPanel() { const heroSettlementLabel = detail?.current?.settlement_source_label || basicSettlementLabel; const heroAirportLabel = detail?.risk?.airport || basicAirportLabel; - const isDetailCompleting = Boolean( + const isSparsePanelDetail = Boolean( detail && (detail.detail_depth !== "full" || (detail.forecast?.daily?.length ?? 0) <= 1), ); - const isPanelSyncing = store.loadingState.cityDetail || isDetailCompleting; + const isPanelSyncing = store.loadingState.cityDetail; const blurActiveElement = () => { if (typeof document === "undefined") return; @@ -320,10 +320,10 @@ export function DetailPanel() {