From 1461d0248836b6dccf16fe8772f9b6b0f3cd0fd6 Mon Sep 17 00:00:00 2001 From: "2569718930@qq.com" <2569718930@qq.com> Date: Tue, 24 Mar 2026 04:03:41 +0800 Subject: [PATCH] feat: Integrate TAF data for non-Hong Kong airport cities, enhance intraday structural analysis, and add new Chinese documentation for API, configuration, and deployment. --- CHANGELOG.md | 16 +++++++++ README.md | 24 +++++++++++-- docs/API_ZH.md | 64 +++++++++++++++++++++++++++++++++- docs/CONFIGURATION_ZH.md | 10 ++++-- docs/FRONTEND_DEPLOYMENT_ZH.md | 14 +++++++- docs/TAF_SIGNAL_ZH.md | 64 ++++++++++++++++++++++++++++++++++ extension/README.md | 9 +++-- frontend/README.md | 20 +++++++++-- 8 files changed, 210 insertions(+), 11 deletions(-) create mode 100644 docs/TAF_SIGNAL_ZH.md diff --git a/CHANGELOG.md b/CHANGELOG.md index cada395d..8e6b309a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,22 @@ - 台北主结算源切换到 `NOAA RCTP`，按最终质控后的最高整度摄氏值展示和说明 - 浏览器插件同步台北 `NOAA RCTP` 结算参考标签和说明 - `/ops` 手机端收口为卡片化视图，保留桌面表格 +- 账户中心补充本周积分显示，`weekly_points` 与周排行同屏展示 +- Dashboard 历史对账补充“峰值前 12 小时 DEB 参考（近似）”卡片 +- 历史图不再错误混入 `settlement_history` 实测，历史样本仅按可比较样本统计 +- 新增 `scripts/backfill_recent_daily_actuals_from_metar.py`，支持为缺失 `daily_records` 的 METAR 城市补最近 14 天 `actual_high` +- 历史接口对新接入的 METAR 城市增加自动 bootstrap，避免新增城市历史页整块空白 +- 香港历史/日内展示继续坚持 `HKO` 官方口径，不再 fallback 到 `VHHH METAR` 连续线 +- 香港 HKO 当天官方点位不再落单独 JSON，统一写入 runtime state +- 今日日内结构信号按城市本地时间与峰值窗口分析，不再只看固定下午时段 +- 新增高空结构信号：冲高环境、压温风险、午后扰动、冲高效率，并提供中英文说明 +- 新增交易动作卡：结合高空结构、市场拥挤度与 `edge_percent` 输出 `偏暖侧 / 偏谨慎 / 先观察` +- 非香港机场城市新增 `TAF` 接入，支持 `FM / TEMPO / BECMG / PROB30/40` 时间片解析 +- 温度走势图新增 `TAF 时段 / TAF Timing` 标记，并在 tooltip 中显示对应时段摘要 +- `TAF` 信号与 `market_signal / edge_percent` 联动进入交易动作，提示更贴近交易语境 +- `TAF` 展示词已改成普通用户可读版本：`基础时段 / 明确切换 / 临时波动 / 逐步转变` +- 日内结构总摘要补充“TAF 未新增压温不等于继续升温”的解释，避免误读 +- 浏览器插件多日预报改为 `DEB` 优先，基础判断卡补充方向、置信度与原因，并统一引流到主站首页 ## Unreleased diff --git a/README.md b/README.md index 407f03f7..5f080668 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Official dashboard: [polyweather-pro.vercel.app](https://polyweather-pro.vercel. ![PolyWeather Ankara analysis](docs/images/demo_ankara.png) -## Product Status (2026-03-21) +## Product Status (2026-03-24) - Subscription live: `Pro Monthly 5 USDC`. - Points redemption live: `500 points = 1 USDC`, max `3 USDC` off. @@ -24,6 +24,11 @@ Official dashboard: [polyweather-pro.vercel.app](https://polyweather-pro.vercel. - Lightweight observability live: `/healthz`, `/api/system/status`, `/metrics`. - Runtime state supports gradual SQLite migration (`file / dual / sqlite`). - 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`). +- 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`. +- Browser extension now uses `DEB` for multi-day forecast and stays positioned as a lightweight lead-in to the main site. ## Open-Core Boundary (Important) @@ -42,6 +47,8 @@ See: [Open-Core & Commercial Boundary](docs/OPEN_CORE_POLICY.md) - 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 airport-side `TAF` timing overlays and airport suppression/disruption interpretation for non-Hong Kong airport cities. ## Reference Architecture @@ -54,8 +61,10 @@ flowchart LR API --> WX["Weather Collector"] WX --> METAR["Aviation Weather (METAR)"] + WX --> TAF["Aviation Weather (TAF)"] WX --> MGM["MGM (Turkey station network)"] WX --> OM["Open-Meteo"] + WX --> HKO["HKO / NOAA / Official settlement sources"] API --> ANA["DEB + Trend + Probability + Market Scan"] ANA --> PAY["Payment State (Intent + Event + Confirm Loop)"] @@ -86,6 +95,17 @@ npm install npm run dev ``` +## Recent Highlights + +- Taipei settlement is aligned to `NOAA RCTP` and rounded whole-degree Celsius logic. +- 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` +- `TAF` is used as an airport-side confirmation layer, not as the main temperature model. +- Browser extension remains a lightweight monitoring + basic-bias product, while the site holds the full analysis experience. + ## Runtime Data (Recommended on VPS) Use external runtime storage to avoid SQLite/git conflicts: @@ -163,4 +183,4 @@ docker compose logs -f polyweather | egrep "polymarket wallet activity watcher s ## Version - Version: `v1.5.1` -- Last Updated: `2026-03-21` +- Last Updated: `2026-03-24` diff --git a/docs/API_ZH.md b/docs/API_ZH.md index e4780cc4..14b92326 100644 --- a/docs/API_ZH.md +++ b/docs/API_ZH.md @@ -1,6 +1,6 @@ # PolyWeather API 文档（v1.5.1） -最后更新：`2026-03-21` +最后更新：`2026-03-24` 本文档描述当前对外可用 API 口径（`web/app.py` + `web/routes.py` + `frontend/app/api/*`）。 @@ -44,9 +44,70 @@ flowchart LR - `market_scan.available` - `market_scan.signal_label` +- `market_scan.edge_percent` - `market_scan.anchor_model / anchor_high / anchor_settlement` - `market_scan.yes_buy / no_buy` - `market_scan.primary_market.tradable` +- `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` + +### `detail` 新增结构信号说明 + +`/api/city/{name}/detail` 现在会返回一组更偏交易场景的结构字段： + +#### 1. `peak` + +- `first_h`：预计峰值窗口起始小时 +- `last_h`：预计峰值窗口结束小时 +- `status`：`before_peak | near_peak | after_peak` + +这组字段用于让日内结构信号围绕真实峰值窗口分析，而不是固定只看下午。 + +#### 2. `vertical_profile_signal` + +重点字段： + +- `source` +- `window` +- `cape_max` +- `cin_min` +- `lifted_index_min` +- `boundary_layer_height_max` +- `shear_10m_180m_max` +- `suppression_risk` +- `trigger_risk` +- `mixing_strength` +- `shear_risk` +- `heating_setup` +- `heating_score` +- `summary_zh` +- `summary_en` + +这组字段对应前端“高空结构信号 / Upper-Air Structure”卡片。 + +#### 3. `taf.signal` + +仅对**非香港机场城市**启用。当前已支持解析： + +- `FM` +- `TEMPO` +- `BECMG` +- `PROB30` +- `PROB40` + +重点字段： + +- `peak_window` +- `segments` +- `markers` +- `suppression_level` +- `disruption_level` +- `wind_shift` +- `summary_zh` +- `summary_en` + +`markers` 会被前端温度走势图拿来做 `TAF 时段 / TAF Timing` 标记。 ## 4. 鉴权与账户接口 @@ -134,6 +195,7 @@ flowchart LR - `cities` / `summary` / `history`：BFF 支持 `ETag + 304` - `summary?force_refresh=true`：`Cache-Control: no-store` - 详情接口与支付接口：`no-store` +- `METAR` / `TAF` / settlement current 由后端各自维护短 TTL 缓存 ## 9. 调试示例 diff --git a/docs/CONFIGURATION_ZH.md b/docs/CONFIGURATION_ZH.md index 65fdd43d..5fd367e3 100644 --- a/docs/CONFIGURATION_ZH.md +++ b/docs/CONFIGURATION_ZH.md @@ -83,6 +83,7 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级 前端： - `POLYWEATHER_API_BASE_URL` +- `POLYWEATHER_OPS_ADMIN_EMAILS`（如果启用 `/ops` 页面级管理员守卫） 如果启用登录： @@ -119,6 +120,7 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级 - 各类 `*_COOLDOWN_SEC` - 各类 `*_INTERVAL_SEC` - `POLYWEATHER_PAYMENT_RPC_URLS` +- `TAF_CACHE_TTL_SEC` 策略： @@ -158,6 +160,7 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级 - `NEXT_PUBLIC_SUPABASE_ANON_KEY` - `POLYWEATHER_AUTH_ENABLED` - `POLYWEATHER_AUTH_REQUIRED` +- `POLYWEATHER_OPS_ADMIN_EMAILS` - `POLYWEATHER_DASHBOARD_ACCESS_TOKEN` - `POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN` - `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` @@ -165,8 +168,10 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级 说明： -- `/ops` 页面本身部署在 Vercel 前端下，但管理员写接口权限仍由后端 `POLYWEATHER_OPS_ADMIN_EMAILS` 控制。 -- 因此，Vercel 侧不需要配置管理员邮箱白名单；管理员判定发生在 VPS / FastAPI 后端。 +- `/ops` 现在是前后端双层限制： + - 前端页面入口读取 `POLYWEATHER_OPS_ADMIN_EMAILS` + - 后端写接口同样读取 `POLYWEATHER_OPS_ADMIN_EMAILS` +- 因此，Vercel 和 VPS / Docker 两侧都应配置相同的管理员邮箱白名单。 不要把后端专用密钥全搬进 Vercel。 @@ -205,6 +210,7 @@ GID=1000 POLYWEATHER_AUTH_ENABLED=true POLYWEATHER_AUTH_REQUIRED=false POLYWEATHER_OPS_ADMIN_EMAILS=yhrsc30@gmail.com +TAF_CACHE_TTL_SEC=900 SUPABASE_URL=https://your-project.supabase.co SUPABASE_ANON_KEY=... SUPABASE_SERVICE_ROLE_KEY=... diff --git a/docs/FRONTEND_DEPLOYMENT_ZH.md b/docs/FRONTEND_DEPLOYMENT_ZH.md index 79b08c41..7db05f0f 100644 --- a/docs/FRONTEND_DEPLOYMENT_ZH.md +++ b/docs/FRONTEND_DEPLOYMENT_ZH.md @@ -78,7 +78,18 @@ NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL=https://polygon-bor-rpc.publicnode.com 如果不启用钱包支付，可以留空。 -### 4. Telegram 入口 +### 4. `/ops` 管理员页面守卫 + +```env +POLYWEATHER_OPS_ADMIN_EMAILS=yhrsc30@gmail.com +``` + +说明： + +- `/ops` 现在不是只有后端接口限制，前端页面入口也会读取管理员邮箱白名单。 +- 因此前端部署到 Vercel 时，也应配置 `POLYWEATHER_OPS_ADMIN_EMAILS`。 + +### 5. Telegram 入口 ```env NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/ @@ -167,6 +178,7 @@ Vercel 部署前至少确认： 3. GitHub Actions 中 `frontend-quality` 已通过 4. 如果启用鉴权，Supabase redirect URL 已包含前端域名 5. `GET /api/payments/config` 返回的是当前最新地址，而不是旧收款合约 +6. 如果启用了 `/ops`，确认 `POLYWEATHER_OPS_ADMIN_EMAILS` 已在 Vercel 与后端同时配置 ## 九、常见问题 diff --git a/docs/TAF_SIGNAL_ZH.md b/docs/TAF_SIGNAL_ZH.md new file mode 100644 index 00000000..3c830e12 --- /dev/null +++ b/docs/TAF_SIGNAL_ZH.md @@ -0,0 +1,64 @@ +# PolyWeather TAF 信号实战指南：从报文解析到多维度联动 (TAF_SIGNAL_ZH) + +在 PolyWeather 系统中，TAF (机场终端预报) 不仅仅是原始文本的展示，它更是**后端分析引擎 (Analysis Engine)** 与 **前端可视化图表** 深度耦合的核心指标。本文档揭秘 TAF 在本项目中的底层逻辑及其在交易中的实战应用。 + +--- + +## 一、 系统架构层面的 TAF 联动 + +### 1. 后端解析引擎 (`web/analysis_service.py`) + +项目后端通过 `_build_taf_signal` 函数对原始 TAF 报文执行“特征工程”提取，生成两个核心指标： + +- **压温等级 (suppression_level)**：来源于对 `FEW/SCT/BKN/OVC` 云底高度和 `TSRA/RA/DZ`（降雨/雷暴）关键词的扫描。如果 TAF 在午后峰值窗口预告低云（<4000ft）或降雨，该指标会跳变至 `high`，直接削减预测高点的置信度。 +- **扰动等级 (disruption_level)**：主要由 `TEMPO`（临时波动）、`PROB30/40`（概率触发）和 `BECMG`（转变过程）贡献。数值越高，暗示预测的高温点越不稳定，可能受短时云团遮挡产生剧烈震荡。 + +### 2. 前端可视化呈现 (`FutureForecastModal.tsx`) + +在前端“今日/未来预报弹窗”中，TAF 信号通过以下方式呈现： + +- **图表标记 (TAF Markers)**：图表右侧的散点或高亮区域标识了 TAF 中的变天时点（如 `FM` 起点）。当鼠标悬停在时点上，会弹出具体的报文解码。 +- **AI 智库融合信号 (Combined Reading)**：在弹窗顶部的结论区，你会看到诸如“高空+TAF+市场读取倾向于...”的判断。这是系统将 **TAF 压温等级** 与 **Open-Meteo GFS 剖面数据** 交叉验证后的最终交易建议。 + +--- + +## 二、 TAF 关键词与交易动作 + +| TAF 关键词 | 项目解析逻辑 (Backend) | 典型交易动作 | +| :--------------- | :----------------------------------------- | :----------------------------------------------------------------------------- | +| **BASE (基准)** | 基准气象场，作为初始预测底色。 | 维持基础仓位，关注中性桶。 | +| **FM (From)** | `valid_match` 触发，标志趋势**强制更新**。 | 若 FM 预告冷切或风向改变，立即对冲高位 Yes 仓位。 | +| **TEMPO (临时)** | 贡献 `disruption_level: high`。 | **多头需谨慎**：即使主趋势在升温，TEMPO 降雨也可能导致 ASOS 实测值瞬间“哑火”。 | +| **PROB40** | 高权重扰动。 | 视同确定性信号，如果包含 `SHRA`（阵雨），则是做空当天“极热桶”的最佳理由。 | +| **BECMG (转变)** | 平滑过渡，通常用于修正结算末期的温度。 | 用于判断退场时点，若 17:00 后 BECMG 显著冷却，说明结算价已定格。 | + +--- + +## 三、 图表联动实战：如何看懂“联动”？ + +### 情况 A：TAF 压温与图表分叉 + +如果你在 **Daily Trend Graph (趋势图)** 上看到预测曲线直冲 35°C，但上方的 TAF 信号提示 `suppression_level: high`（高风险压温），这意味着： + +- 数值模型（Open-Meteo）认为太阳热量足。 +- **但 TAF 预报员认为云/雨会打断升温。** +- **结论**：此时不要在高位买入，大概率实际结算会低于模型预测。 + +### 情况 B：TEMPO 峰值重叠 + +当 TAF 的 `TEMPO` 窗口（如 `07/11`，即当地下午 15:00-19:00）内出现降水信号，且图表显示此时为气温最高点时： + +- 系统会生成“AI 预警：注意峰值被云雨压低”。 +- **交易建议**：这种情况下，买入“低一档”的温度桶往往比“最高的一档”更具性价比（EV 更高）。 + +--- + +## 四、 交易员必备：PolyWeather 报文解析口诀 + +> **看 FM 定趋势，看 TEMPO 抓波动。** +> **压温等级看 High，大单入场要收工。** +> **图表高亮即信号，峰值重叠莫冲动。** + +--- + +_PolyWeather 文档中心 - 技术与市场的桥梁_ diff --git a/extension/README.md b/extension/README.md index 017f77b2..8fd35c45 100644 --- a/extension/README.md +++ b/extension/README.md @@ -9,11 +9,12 @@ - 风险徽章 - 城市档案（结算源 / 距离 / 观测更新时间 / 周边站点） - 今日日内走势（简版 Canvas） - - 多日预报 + - 多日预报（`DEB` 优先） + - 基础判断卡（方向 / 置信度 / 原因） - 快捷按钮： - 今日日内分析 - 历史对账 - - 打开完整网站分析 + - 打开网站查看更多 - 自动识别城市： - 监听当前激活标签页 URL（例如 Polymarket `.../event/highest-temperature-in-ankara-...`） - 自动将侧边栏城市切换为 URL 对应城市 @@ -42,5 +43,7 @@ ## 说明 -- 当前版本是 MVP，重点是“导流回站”，未接入支付链路。 +- 当前版本仍是轻量 MVP，重点是“监控 + 基础判断 + 导流回站”，未接入支付链路。 - 若你的 API 做了严格鉴权，请先在设置页填写 token 再使用。 +- 台北现在按 `NOAA RCTP` 结算参考展示。 +- 插件不会承载完整分析；完整结构判断、历史对账和更多信号仍以主站为准。 diff --git a/frontend/README.md b/frontend/README.md index 38fed683..e9e2521f 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -19,6 +19,19 @@ PolyWeather Pro 的生产前端工程。 2. Next Route Handlers（`/api/*`）-> FastAPI 后端 3. FastAPI -> 分析服务 / 支付服务 +## 当前前端能力 + +- 主站 Dashboard 支持地图、城市详情、今日日内分析、历史准确率对账和账户中心 +- 今日日内分析支持： + - 峰值窗口感知的近地面结构信号 + - 高空结构信号 + - 交易动作卡 + - 非香港机场城市的 `TAF` 时段提示与走势图联动 +- 历史对账支持： + - `DEB / 最佳单模型 / 实测最高温` 对比 + - 峰值前 12 小时 `DEB` 参考（近似） +- `/ops` 已支持桌面表格 + 手机端卡片化视图 + ## 本地开发 ```bash @@ -67,6 +80,7 @@ POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN= NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID= NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL=https://polygon-bor-rpc.publicnode.com NEXT_PUBLIC_PAYMENT_ALLOWED_HOSTS=polyweather-pro.vercel.app +POLYWEATHER_OPS_ADMIN_EMAILS=yhrsc30@gmail.com # 社群入口 NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/ @@ -126,10 +140,12 @@ Ops： - 本周积分榜 - 手动补分 - 支付异常单筛选与标记已处理 +- 手机端卡片化视图 注意： -- `/ops` 页面是否可写，取决于后端 `POLYWEATHER_OPS_ADMIN_EMAILS` +- `/ops` 现在是前后端双层管理员限制 +- Vercel 前端和后端都应配置相同的 `POLYWEATHER_OPS_ADMIN_EMAILS` - 前端登录邮箱本身不会自动获得管理员权限 ## 支付安全补充 @@ -160,4 +176,4 @@ Ops： 详见根目录策略文档：`docs/OPEN_CORE_POLICY.md` -最后更新：`2026-03-21` +最后更新：`2026-03-24`