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

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. 调试示例
 

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=...

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/<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 与后端同时配置
 
 ## 九、常见问题
 

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 文档中心 - 技术与市场的桥梁_