feat: Integrate TAF data for non-Hong Kong airport cities, enhance intraday structural analysis, and add new Chinese documentation for API, configuration, and deployment.

2026-03-24 04:03:41 +08:00
parent 54acfc05aa
commit 1461d02488
8 changed files with 210 additions and 11 deletions
@@ -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
@@ -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`
@@ -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. 调试示例

@@ -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=...
@@ -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/<your_group>
@@ -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 与后端同时配置

 ## 九、常见问题

@@ -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 文档中心 - 技术与市场的桥梁_
@@ -9,11 +9,12 @@
  - 风险徽章
  - 城市档案（结算源 / 距离 / 观测更新时间 / 周边站点）
  - 今日日内走势（简版 Canvas）
-  - 多日预报
+  - 多日预报（`DEB` 优先）
+  - 基础判断卡（方向 / 置信度 / 原因）
 - 快捷按钮：
  - 今日日内分析
  - 历史对账
-  - 打开完整网站分析
+  - 打开网站查看更多
 - 自动识别城市：
  - 监听当前激活标签页 URL（例如 Polymarket `.../event/highest-temperature-in-ankara-...`）
  - 自动将侧边栏城市切换为 URL 对应城市
@@ -42,5 +43,7 @@

 ## 说明

- 当前版本是 MVP，重点是“导流回站”，未接入支付链路。
+- 当前版本仍是轻量 MVP，重点是“监控 + 基础判断 + 导流回站”，未接入支付链路。
 - 若你的 API 做了严格鉴权，请先在设置页填写 token 再使用。
+- 台北现在按 `NOAA RCTP` 结算参考展示。
+- 插件不会承载完整分析；完整结构判断、历史对账和更多信号仍以主站为准。
@@ -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/<your_group>
@@ -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`