From a5eff0031c30cf8a438cfcb9381cb98abe41de66 Mon Sep 17 00:00:00 2001 From: "2569718930@qq.com" <2569718930@qq.com> Date: Fri, 10 Apr 2026 08:04:25 +0800 Subject: [PATCH] Update docs for v1.5.3 release --- CHANGELOG.md | 15 ++++++++ README.md | 47 ++++++++++++++++++------ README_ZH.md | 52 +++++++++++++++++++++------ VERSION | 2 +- docs/CONFIGURATION_ZH.md | 66 +++++++++++++++++++++++++++++++++- docs/FRONTEND_DEPLOYMENT_ZH.md | 46 +++++++++++++++++++++++- docs/MONITORING_ZH.md | 36 +++++++++++++++++-- docs/OPS_ADMIN_ZH.md | 29 ++++++++++++++- frontend/README.md | 29 ++++++++++++--- frontend/content/docs/docs.ts | 16 ++++----- 10 files changed, 298 insertions(+), 40 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e6b309a..ca9638ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog +## 1.5.3 - 2026-04-10 + +- 东京新增 `JMA AMeDAS` 羽田 10 分钟官方增强层，只取温度并作为机场周边官方参考 +- 韩国官方增强层补齐 `KMA` 接入链，与 `METAR` 锚点保持分离 +- 城市点击交互恢复地图 `flyTo` 放大动画，并补回明确的 loading 提示 +- 城市点击后新增地图顶部同步提醒与详情面板内同步徽标，降低“看起来像卡住”的误判 +- 城市 detail 现在会识别“单模型 / 单日”的稀疏缓存并自动强刷，修复“模型只剩 DEB / 多日预报只剩今天”这类残缺展示 +- 前端多日预报在窄面板下改为可横向滚动，并对稀疏日序列给出刷新提示 +- `/ops` 与 `/api/system/status` 新增 prewarm worker 运行态、heartbeat、summary/detail/market 统计，以及缓存桶状态与 summary cache hit/miss +- 新增 Dashboard 定向预热脚本、后台 worker 和 docker service，支持热点城市 summary/detail/market 预热 +- 共享天气采集 HTTP 层进一步统一到 `httpx` helper，并补齐短重试与错误分类 +- 今日日内分析改造成更交易化的工作台结构：`锚点状态 / 当前节奏 / 当前命中胜率 / 模型区间与分歧 / 今日日内结构信号` +- 今日日内结构解读新增可选 `Groq` 改写层，失败时自动回退到规则文案 +- 文档统一更新到 `v1.5.3`，补充预热 worker、Groq、Vercel 节流与官方增强站网说明 + ## 1.5.1 - 2026-03-23 - `/ops` 页面增加管理员守卫，前后端双层限制管理员访问 diff --git a/README.md b/README.md index d3949111..d0bdee45 100644 --- a/README.md +++ b/README.md @@ -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-03-24) +## Product Status (2026-04-10) - Subscription live: `Pro Monthly 5 USDC`. - Points redemption live: `500 points = 1 USDC`, max `3 USDC` off. @@ -32,6 +32,12 @@ Public docs center: `/docs/intro` on the main site (bilingual product documentat - 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. +- Official nearby-network layer now covers `MGM` (Turkey), `CMA/NMC` (Mainland China), `JMA AMeDAS` (Japan), `KMA` (Korea), `HKO` (Hong Kong), and `CWA` (Taiwan). +- Tokyo now ingests Haneda `JMA AMeDAS` 10-minute temperature as the official enhancement layer. +- Dashboard prewarm is now supported through a dedicated worker / cron path, with runtime status exposed in `/api/system/status` and `/ops`. +- `/ops` now exposes cache bucket counts, summary cache hit / miss rate, and prewarm runtime heartbeat. +- Intraday commentary can optionally use `Groq` as a bilingual rewrite layer, while rule-based commentary remains the fallback. +- Vercel frontend guidance now includes cost controls for analytics, eager fetches, and edge-side scanner blocking. ## License & Commercial Boundary @@ -45,7 +51,7 @@ See: [AGPL-3.0 & Commercial Boundary](docs/OPEN_CORE_POLICY.md) ## Core Capabilities -- Aggregates observations and forecasts for 30 monitored cities. +- Aggregates observations and forecasts for 45 monitored cities. - Uses DEB (Dynamic Error Balancing) to blend multi-model highs. - Generates settlement-oriented probability buckets (`mu` + bucket distribution). - Maps weather view to Polymarket quotes for mispricing scan. @@ -53,6 +59,8 @@ See: [AGPL-3.0 & Commercial Boundary](docs/OPEN_CORE_POLICY.md) - 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. +- 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. ## Reference Architecture @@ -68,20 +76,23 @@ flowchart LR WX --> TAF["Aviation Weather (TAF)"] WX --> MGM["MGM (Turkey station network)"] WX --> OM["Open-Meteo"] - WX --> HKO["HKO / NOAA / Official settlement sources"] + WX --> JMA["JMA AMeDAS (Japan)"] + WX --> KMA["KMA (Korea)"] + WX --> HKO["HKO / CWA / NOAA / Official settlement sources"] API --> ANA["DEB + Trend + Probability + Market Scan"] ANA --> PAY["Payment State (Intent + Event + Confirm Loop)"] ANA --> PM["Polymarket Read-only Layer"] + ANA --> LLM["Optional Groq Commentary Rewrite"] + API --> PREWARM["Dashboard Prewarm API / Worker"] ``` -## Monitored Cities (30) +## Monitored Cities (45) -- Europe / Middle East: Ankara, London, Paris, Munich, Tel Aviv, Milan, Warsaw, Madrid -- APAC: Seoul, Hong Kong, Taipei, Shanghai, Singapore, Tokyo, Wellington -- Americas: Toronto, New York, Chicago, Dallas, Miami, Atlanta, Seattle, Buenos Aires, Sao Paulo +- 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 -- China extension: Chengdu, Chongqing, Shenzhen, Beijing, Wuhan ## Quick Start @@ -95,7 +106,7 @@ docker compose up -d --build ```bash cd frontend -npm install +npm ci npm run dev ``` @@ -131,6 +142,20 @@ curl http://127.0.0.1:8000/api/system/status curl http://127.0.0.1:8000/metrics ``` +### Dashboard prewarm worker + +```bash +docker compose --profile workers up -d polyweather_prewarm +curl http://127.0.0.1:8000/api/system/status +``` + +Check: + +- `prewarm.thread_alive` +- `prewarm.runtime.cycle_count` +- `cache.analysis.hit_rate` +- `cache.open_meteo_forecast_entries` + ### Frontend cache headers ```bash @@ -190,5 +215,5 @@ docker compose logs -f polyweather | egrep "polymarket wallet activity watcher s ## Version -- Version: `v1.5.1` -- Last Updated: `2026-03-24` +- Version: `v1.5.3` +- Last Updated: `2026-04-10` diff --git a/README_ZH.md b/README_ZH.md index 8d8159d3..b7a583f5 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -14,7 +14,7 @@ ![PolyWeather Ankara 分析页](docs/images/demo_ankara.png) -## 当前产品状态（2026-03-21） +## 当前产品状态（2026-04-10） - 已上线订阅制：`Pro 月付 5 USDC`。 - 已上线积分抵扣：`500 积分 = 1 USDC`，最多抵扣 `3 USDC`。 @@ -26,6 +26,18 @@ - 已补最小外部监控栈：Prometheus + Alertmanager + Grafana + Telegram 告警 relay。 - 运行态状态、缓存与核心离线训练/回填链路已完成 SQLite 主路径收口；legacy JSON/JSONL 仅保留给迁移、导出与显式回退输入。 - 已接入 EMOS/CRPS 校准链路，但当前仍保持 `emos_shadow`。 +- 官方增强站网已统一接入： + - `MGM`（土耳其） + - `CMA/NMC`（中国内地） + - `JMA AMeDAS`（日本） + - `KMA`（韩国） + - `HKO`（香港） + - `CWA`（台湾） +- 东京现已接入羽田 `JMA AMeDAS` 10 分钟温度作为官方增强层。 +- 已支持 Dashboard 定向预热 worker / cron 路径，运行态在 `/api/system/status` 与 `/ops` 可见。 +- `/ops` 现已展示缓存桶数量、summary cache hit/miss 与 prewarm heartbeat。 +- 今日日内结构解读已支持可选 `Groq` 改写层，失败时自动回退规则文案。 +- 前端部署文档已补充 Vercel 节流建议，包括 analytics 关闭、eager fetch 开关与扫描流量防火墙规则。 ## 许可证与商用边界（重要） @@ -39,12 +51,14 @@ ## 核心能力 -- 聚合 30 个监控城市的实测与预报数据。 +- 聚合 45 个监控城市的实测与预报数据。 - DEB（Dynamic Error Balancing）融合多模型最高温。 - 输出结算导向概率分布（`mu` + 温度桶）。 - 将模型观点映射到 Polymarket 行情，做错价扫描。 - Web 仪表盘与 Telegram Bot 复用同一分析内核。 - 支付链路具备事件重放、SQLite 审计事件与 RPC 容灾能力。 +- 官方增强层支持按国家 provider 统一接入，但不替代机场主站或明确官方结算站。 +- 支持后台预热热点城市，降低用户点击城市后的冷启动成本。 ## 参考架构 @@ -58,22 +72,26 @@ flowchart LR API --> WX["Weather Collector"] WX --> METAR["Aviation Weather（METAR）"] WX --> MGM["MGM（土耳其站网）"] + WX --> JMA["JMA AMeDAS（日本）"] + WX --> KMA["KMA（韩国）"] WX --> OM["Open-Meteo"] + WX --> HKO["HKO / CWA / NOAA 等官方结算源"] API --> ANA["DEB + 趋势 + 概率 + 市场扫描"] ANA --> PAY["支付状态（Intent + Event + Confirm Loop）"] ANA --> PM["Polymarket 只读层"] API --> OBS["healthz / system status / metrics"] + API --> PREWARM["Dashboard 预热接口 / Worker"] + ANA --> LLM["可选 Groq 文案改写层"] ANA --> STATE["SQLite runtime state
legacy files only for migration/export fallback"] ``` -## 监控城市（30） +## 监控城市（45） -- 欧洲/中东：Ankara、London、Paris、Munich、Tel Aviv、Milan、Warsaw、Madrid -- 亚太：Seoul、Hong Kong、Taipei、Shanghai、Singapore、Tokyo、Wellington -- 美洲：Toronto、New York、Chicago、Dallas、Miami、Atlanta、Seattle、Buenos Aires、Sao Paulo +- 欧洲/中东：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 -- 中国扩展：Chengdu、Chongqing、Shenzhen、Beijing、Wuhan ## 快速启动 @@ -87,7 +105,7 @@ docker compose up -d --build ```bash cd frontend -npm install +npm ci npm run dev ``` @@ -111,6 +129,20 @@ curl http://127.0.0.1:8000/api/system/status curl http://127.0.0.1:8000/metrics ``` +### Dashboard 预热 Worker + +```bash +docker compose --profile workers up -d polyweather_prewarm +curl http://127.0.0.1:8000/api/system/status +``` + +重点关注： + +- `prewarm.thread_alive` +- `prewarm.runtime.cycle_count` +- `prewarm.runtime.last_summary_ok` +- `cache.analysis.hit_rate` + ### 前端缓存头 ```bash @@ -196,5 +228,5 @@ docker compose logs -f polyweather | egrep "polymarket wallet activity watcher s ## 当前版本 -- 版本：`v1.5.1` -- 文档最后更新：`2026-03-21` +- 版本：`v1.5.3` +- 文档最后更新：`2026-04-10` diff --git a/VERSION b/VERSION index 26ca5946..8af85beb 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.5.1 +1.5.3 diff --git a/docs/CONFIGURATION_ZH.md b/docs/CONFIGURATION_ZH.md index c2f8436f..3132761f 100644 --- a/docs/CONFIGURATION_ZH.md +++ b/docs/CONFIGURATION_ZH.md @@ -110,6 +110,8 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级 - `TELEGRAM_ALERT_PUSH_ENABLED` - `TELEGRAM_MARKET_FOCUS_DIGEST_ENABLED` - `POLYMARKET_WALLET_ACTIVITY_ENABLED`（已退役，建议保持 `false`） +- `POLYWEATHER_DASHBOARD_PREWARM_ENABLED` +- `POLYWEATHER_GROQ_COMMENTARY_ENABLED` ### 4.3 L3：运行调优项 @@ -129,6 +131,15 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级 - `TELEGRAM_MARKET_FOCUS_DIGEST_TOP_N` - `POLYWEATHER_PAYMENT_RPC_URLS` - `TAF_CACHE_TTL_SEC` +- `POLYWEATHER_PREWARM_INTERVAL_SEC` +- `POLYWEATHER_PREWARM_JITTER_SEC` +- `POLYWEATHER_PREWARM_CITIES` +- `POLYWEATHER_PREWARM_INCLUDE_DETAIL` +- `POLYWEATHER_PREWARM_INCLUDE_MARKET` +- `POLYWEATHER_PREWARM_FORCE_REFRESH` +- `POLYWEATHER_GROQ_COMMENTARY_MODEL` +- `POLYWEATHER_GROQ_COMMENTARY_TIMEOUT_SEC` +- `POLYWEATHER_GROQ_COMMENTARY_CACHE_TTL_SEC` 策略： @@ -148,6 +159,7 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级 - `METEOBLUE_API_KEY` - `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` - `POLYMARKET_SECRET_KEY` +- `GROQ_API_KEY` ## 5. 推荐部署矩阵 @@ -173,6 +185,9 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级 - `POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN` - `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` - `NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL` +- `NEXT_PUBLIC_POLYWEATHER_APP_ANALYTICS` +- `NEXT_PUBLIC_POLYWEATHER_WEB_VITALS` +- `NEXT_PUBLIC_POLYWEATHER_EAGER_CITY_SUMMARIES` 说明： @@ -203,6 +218,9 @@ NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key POLYWEATHER_AUTH_ENABLED=true POLYWEATHER_AUTH_REQUIRED=true +NEXT_PUBLIC_POLYWEATHER_APP_ANALYTICS=false +NEXT_PUBLIC_POLYWEATHER_WEB_VITALS=false +NEXT_PUBLIC_POLYWEATHER_EAGER_CITY_SUMMARIES=false ``` ### 6.2 后端最小变量 @@ -234,6 +252,16 @@ TELEGRAM_MARKET_FOCUS_DIGEST_ENABLED=true TELEGRAM_MARKET_FOCUS_DIGEST_INTERVAL_SEC=1800 TELEGRAM_MARKET_FOCUS_DIGEST_TOP_N=5 POLYMARKET_WALLET_ACTIVITY_ENABLED=false +POLYWEATHER_DASHBOARD_PREWARM_ENABLED=true +POLYWEATHER_PREWARM_INTERVAL_SEC=300 +POLYWEATHER_PREWARM_JITTER_SEC=20 +POLYWEATHER_PREWARM_INCLUDE_DETAIL=true +POLYWEATHER_PREWARM_INCLUDE_MARKET=true +POLYWEATHER_BACKEND_URL=http://polyweather_web:8000 +POLYWEATHER_GROQ_COMMENTARY_ENABLED=false +POLYWEATHER_GROQ_COMMENTARY_MODEL=openai/gpt-oss-20b +POLYWEATHER_GROQ_COMMENTARY_TIMEOUT_SEC=8 +POLYWEATHER_GROQ_COMMENTARY_CACHE_TTL_SEC=1800 ``` 说明： @@ -247,8 +275,44 @@ POLYMARKET_WALLET_ACTIVITY_ENABLED=false - 机器人市场监控当前以 `关注清单` 为主，按固定间隔主动推送。 - `TELEGRAM_MARKET_FOCUS_DIGEST_INTERVAL_SEC` 表示主动推送间隔，默认 `1800` 秒（30 分钟）。 - `POLYMARKET_WALLET_ACTIVITY_ENABLED` 已退役，保留为 `false` 即可，不建议再启用钱包异动监听。 +- `POLYWEATHER_DASHBOARD_PREWARM_ENABLED=true` 时，建议同时启用独立 worker 或 bot 内嵌预热线程。 +- `POLYWEATHER_BACKEND_URL` 仅在独立 `polyweather_prewarm` worker 容器中使用，建议设为 `http://polyweather_web:8000`，不要写 `127.0.0.1`。 +- `POLYWEATHER_GROQ_COMMENTARY_ENABLED=false` 表示默认仍走规则文案；只有在确实配置了 `GROQ_API_KEY` 时才建议开启。 -### 6.3 机器人市场监控建议配置 +### 6.3 Dashboard 预热 worker 推荐变量 + +```env +POLYWEATHER_DASHBOARD_PREWARM_ENABLED=true +POLYWEATHER_PREWARM_INTERVAL_SEC=300 +POLYWEATHER_PREWARM_JITTER_SEC=20 +POLYWEATHER_PREWARM_CITIES=ankara,istanbul,shanghai,beijing,shenzhen,wuhan,chengdu,chongqing,hong kong,taipei,london,paris,new york,los angeles +POLYWEATHER_PREWARM_INCLUDE_DETAIL=true +POLYWEATHER_PREWARM_INCLUDE_MARKET=true +POLYWEATHER_PREWARM_FORCE_REFRESH=false +POLYWEATHER_BACKEND_URL=http://polyweather_web:8000 +``` + +说明： + +- 这组变量用于后台定向预热热点城市，避免用户点击城市时才冷启动拉 detail。 +- 如果使用独立 `polyweather_prewarm` 容器，`POLYWEATHER_BACKEND_URL` 必须指向容器网络中的 `polyweather_web`。 + +### 6.4 Groq 解读增强层 + +```env +POLYWEATHER_GROQ_COMMENTARY_ENABLED=true +GROQ_API_KEY=... +POLYWEATHER_GROQ_COMMENTARY_MODEL=openai/gpt-oss-20b +POLYWEATHER_GROQ_COMMENTARY_TIMEOUT_SEC=8 +POLYWEATHER_GROQ_COMMENTARY_CACHE_TTL_SEC=1800 +``` + +说明： + +- 这层只负责把结构化信号改写成短摘要，不替代真实模型、机场锚点和结算逻辑。 +- Groq 调用失败时，系统会自动回退到规则文案。 + +### 6.5 机器人市场监控建议配置 这套配置用于替代旧的钱包异动监听，围绕市场本身做两类推送： diff --git a/docs/FRONTEND_DEPLOYMENT_ZH.md b/docs/FRONTEND_DEPLOYMENT_ZH.md index 7db05f0f..5cb819c4 100644 --- a/docs/FRONTEND_DEPLOYMENT_ZH.md +++ b/docs/FRONTEND_DEPLOYMENT_ZH.md @@ -23,7 +23,7 @@ - Framework Preset: `Next.js` - Root Directory: `frontend` - Build Command: `npm run build` -- Install Command: `npm install` +- Install Command: `npm ci` 如果仓库已经连接过 Vercel，通常只需要确认 `Root Directory` 仍然是 `frontend`。 @@ -98,6 +98,20 @@ NEXT_PUBLIC_TELEGRAM_BOT_URL=https://t.me/WeatherQuant_bot 只影响按钮跳转，不影响核心页面加载。 +### 6. 前端观测与预热开关（推荐默认关闭） + +```env +NEXT_PUBLIC_POLYWEATHER_APP_ANALYTICS=false +NEXT_PUBLIC_POLYWEATHER_WEB_VITALS=false +NEXT_PUBLIC_POLYWEATHER_EAGER_CITY_SUMMARIES=false +``` + +说明： + +- `NEXT_PUBLIC_POLYWEATHER_APP_ANALYTICS=false`：关闭前端自建埋点。 +- `NEXT_PUBLIC_POLYWEATHER_WEB_VITALS=false`：关闭前端 Web Vitals 上报。 +- `NEXT_PUBLIC_POLYWEATHER_EAGER_CITY_SUMMARIES=false`：关闭首页全量城市 summary 预热，避免白白消耗 Vercel function / edge 成本。 + ## 五、支付配置与旧部署治理 支付区现在有一层额外防护： @@ -209,3 +223,33 @@ NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID ``` 这是钱包连接的必需项。 + +## 十、Vercel 成本与节流建议 + +### 1. 建议先关闭的项目级能力 + +- `Web Analytics` +- `Speed Insights` + +它们对排查前端体验有价值，但在 Hobby / 低预算阶段会额外消耗数据点和边缘资源。 + +### 2. 建议加的 Firewall 自定义规则 + +如果你的 Next.js 项目根本不提供 WordPress / PHP 路径，建议在 Vercel Firewall 里先 `Log` 再 `Deny` 这条规则： + +```regex +(^/(wp-admin|wp-includes|wp-content|wp-login|wordpress|xmlrpc\.php))|\.php($|\?) +``` + +目的： + +- 在边缘层提前拦截 WordPress / PHP 扫描流量 +- 避免无效请求继续触发 middleware 与 route handler + +### 3. 建议的上线前检查 + +除了功能本身，额外确认： + +1. `Web Analytics` 和 `Speed Insights` 是否真的关闭 +2. `NEXT_PUBLIC_POLYWEATHER_APP_ANALYTICS` / `NEXT_PUBLIC_POLYWEATHER_WEB_VITALS` / `NEXT_PUBLIC_POLYWEATHER_EAGER_CITY_SUMMARIES` 是否保持关闭 +3. Firewall 自定义规则是否已从 `Log` 切到 `Deny` diff --git a/docs/MONITORING_ZH.md b/docs/MONITORING_ZH.md index 6548c66a..95152fad 100644 --- a/docs/MONITORING_ZH.md +++ b/docs/MONITORING_ZH.md @@ -1,6 +1,6 @@ # 外部监控与告警说明 -最后更新：`2026-04-01` +最后更新：`2026-04-10` ## 1. 目标 @@ -105,7 +105,39 @@ python scripts/check_ops_health.py --base-url http://127.0.0.1:8000 任何一项失败都会非零退出，适合挂到 crontab 或 systemd timer。 -## 8. 备注 +## 8. 当前内置运行态观测 + +除了 Prometheus / Grafana 这套外部监控，当前后端还内置了更贴业务的只读运行态： + +- `/api/system/status` +- `/ops` + +目前已覆盖： + +- `prewarm` worker 是否启用、线程 / heartbeat 是否活着 +- 最近一轮 prewarm 的： + - `cycle_count` + - `success_count / failure_count` + - `last_started_at / last_finished_at` + - `last_summary_ok / last_detail_ok / last_market_ok` +- 缓存桶条目数： + - `api_cache` + - `metar` + - `taf` + - `nmc` + - `settlement` + - `open_meteo forecast / ensemble / multi-model` +- `summary` 分析缓存命中率： + - `total_requests` + - `cache_hits / cache_misses` + - `hit_rate / miss_rate` + +这意味着： + +- 外部监控负责“服务活没活、错误有没有暴增” +- `/ops` 和 `/api/system/status` 负责“预热有没有真的跑、缓存有没有真的被打热” + +## 9. 备注 这套监控现在已经具备： diff --git a/docs/OPS_ADMIN_ZH.md b/docs/OPS_ADMIN_ZH.md index 727b955e..c17e58ae 100644 --- a/docs/OPS_ADMIN_ZH.md +++ b/docs/OPS_ADMIN_ZH.md @@ -1,6 +1,6 @@ # Ops 运营后台说明 -最后更新：`2026-04-01` +最后更新：`2026-04-10` ## 1. 入口 @@ -25,6 +25,8 @@ POLYWEATHER_OPS_ADMIN_EMAILS=yhrsc30@gmail.com - 系统健康 - SQLite / rollout / metrics 摘要 - 支付运行态 +- prewarm worker 运行态 +- 缓存桶状态与 summary cache hit/miss - 当前会员 - 周榜 - 支付异常单 @@ -99,6 +101,31 @@ python scripts/reconcile_subscription_by_email.py --email ## 7. 备注 +### 7.1 当前 prewarm / 缓存观测项 + +`/ops` 里的系统状态卡目前已额外展示： + +- `prewarm` 是否启用 +- `thread_alive` / `heartbeat_age_sec` +- 最近一轮： + - `cycle_count` + - `success_count / failure_count` + - `last_started_at / last_finished_at` + - `last_summary_ok / last_detail_ok / last_market_ok` +- 缓存桶数量： + - `api_cache` + - `metar` + - `taf` + - `nmc` + - `settlement` + - `open_meteo forecast / ensemble / multi-model` +- `summary` 层缓存命中率： + - `total_requests` + - `cache_hits / cache_misses` + - `hit_rate / miss_rate` + +### 7.2 当前用途边界 + `/ops` 是运营后台最小版，不是完整 Admin 平台。当前目标是： - 让会员、积分、支付事故、系统状态可查 diff --git a/frontend/README.md b/frontend/README.md index b2088731..a313bbbd 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -24,21 +24,26 @@ PolyWeather Pro 的生产前端工程。 - 主站 Dashboard 支持地图、城市详情、今日日内分析、历史准确率对账和账户中心 - `/docs` 已提供公开双语产品文档中心，解释日内结构信号、TAF、结算来源和历史对账 - 今日日内分析支持： - - 峰值窗口感知的近地面结构信号 - - 高空结构信号 - - 交易动作卡 + - `锚点状态` + - `当前节奏` + - `当前命中胜率` + - `模型区间与分歧` + - `今日日内结构信号` - 非香港机场城市的 `TAF` 时段提示与走势图联动 - 历史对账支持： - `DEB / 最佳单模型 / 实测最高温` 对比 - 峰值前 12 小时 `DEB` 参考（近似） - `/ops` 已支持桌面表格 + 手机端卡片化视图 +- 点击城市图标后会显示地图顶部同步提醒与详情面板内同步徽标，避免用户误判为卡住 +- 城市详情会自动识别“单模型 / 单日”的稀疏缓存并主动刷新，避免误把残缺 detail 当作完整结果 +- `/ops` 现已展示 prewarm worker 运行态、缓存桶状态与 summary cache hit/miss ## 本地开发 ```bash cd frontend cp .env.example .env.local -npm install +npm ci npm run dev ``` @@ -86,6 +91,11 @@ POLYWEATHER_OPS_ADMIN_EMAILS=yhrsc30@gmail.com # 社群入口 NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/ NEXT_PUBLIC_TELEGRAM_BOT_URL=https://t.me/WeatherQuant_bot + +# 推荐默认关闭的前端观测 / 预热开关 +NEXT_PUBLIC_POLYWEATHER_APP_ANALYTICS=false +NEXT_PUBLIC_POLYWEATHER_WEB_VITALS=false +NEXT_PUBLIC_POLYWEATHER_EAGER_CITY_SUMMARIES=false ``` 更完整的 Vercel 配置说明见： @@ -136,6 +146,8 @@ Ops： - 系统状态 - SQLite / rollout / 支付运行态 +- prewarm worker 运行态 +- 缓存桶状态与 summary cache hit/miss - 用户查询 - 当前会员 - 本周积分榜 @@ -169,6 +181,13 @@ Ops： - `cities` / `summary` / `history`：`ETag + Cache-Control` - `summary?force_refresh=true`：`no-store` - 支付相关路由：`no-store` +- 当 detail 缓存只返回单模型或单日 forecast 时，前端会自动强刷完整 detail + +## Vercel 节流建议 + +- 生产环境建议关闭 `Web Analytics` 和 `Speed Insights` +- 建议把自建 `app analytics / web vitals / eager city summaries` 默认保持关闭 +- 如果你部署在 Vercel，可在 Firewall 中加一条 `WordPress / php scanner` 拦截规则，避免无效扫描白白触发 middleware ## AGPL 与商用边界说明 @@ -177,4 +196,4 @@ Ops： 详见根目录策略文档：`docs/OPEN_CORE_POLICY.md` -最后更新：`2026-03-24` +最后更新：`2026-04-10` diff --git a/frontend/content/docs/docs.ts b/frontend/content/docs/docs.ts index 30ce15bb..0cd4c778 100644 --- a/frontend/content/docs/docs.ts +++ b/frontend/content/docs/docs.ts @@ -41,7 +41,7 @@ export const DOCS_PAGES: DocsPage[] = [ content: { "zh-CN": { title: "简介", - description: "PolyWeather 文档中心解释核心产品概念、结算口径和日内结构信号，帮助用户把天气分析转成可执行判断。", + description: "PolyWeather 文档中心解释核心产品概念、结算口径和日内结构信号，帮助用户把机场锚点、官方增强层和模型判断转成可执行判断。", sections: [ { id: "what-is-polyweather", @@ -55,21 +55,21 @@ export const DOCS_PAGES: DocsPage[] = [ id: "core-modules", title: "你会在页面上看到什么", blocks: [ - { type: "bullets", items: ["今日日内分析：围绕今日峰值窗口，解释近地面信号、高空结构和机场 TAF。", "多模型预报：展示 DEB 与多模型最高温预测，帮助判断市场当前最热桶是否合理。", "历史对账：查看近 15 天已结算样本、DEB MAE 与最佳单模型表现。", "站点结构：明确区分结算站点、机场主站和官方增强站网。"] }, + { type: "bullets", items: ["锚点状态：先确认当前机场主站实测、日内已见高点和结算时钟。", "当前节奏：把“此刻应到温度”和“机场实测”放在一张卡里，判断今天跑得快还是慢。", "当前命中胜率 / 模型区间与分歧：快速看最可能命中的温度桶，以及多模型当前分歧。", "今日日内结构信号：用近地面结构、高空结构、机场 TAF 和官方增强层解释今天还会不会继续冲高。", "历史对账：查看近 15 天已结算样本、DEB MAE 与最佳单模型表现。"] }, ], }, { id: "how-to-read", title: "如何快速读懂主站", blocks: [ - { type: "steps", items: ["先看今日气温预测图，确认当前实测、DEB 预测和峰值窗口。", "再看今日日内结构信号，判断现在是偏支持继续升温、偏压制，还是先观察。", "最后看市场对照与概率分布，判断市场是否已经把天气结构计入价格。"] }, + { type: "steps", items: ["先看锚点状态和今日气温预测图，确认当前机场实测、DEB 预测和峰值窗口。", "再看当前节奏，判断今天是偏热、偏冷，还是基本按预期在走。", "接着看今日日内结构信号，确认边界风险、机场 vs 周边站，以及 TAF 有没有压温扰动。", "最后看当前命中胜率与模型区间，判断最热桶是不是已经被市场充分计价。"] }, ], }, ], }, "en-US": { title: "Introduction", - description: "The PolyWeather docs explain the product's core concepts, settlement logic, and intraday structural signals so users can turn weather context into actionable decisions.", + description: "The PolyWeather docs explain the product's core concepts, settlement logic, and intraday structural signals so users can turn airport anchors, official nearby networks, and model context into actionable decisions.", sections: [ { id: "what-is-polyweather", @@ -83,14 +83,14 @@ export const DOCS_PAGES: DocsPage[] = [ id: "core-modules", title: "What you see on the site", blocks: [ - { type: "bullets", items: ["Intraday analysis: peak-window focused reading of surface structure, upper-air structure, and airport TAF.", "Multi-model forecast: DEB versus major model highs, useful for checking whether the hottest market bucket is justified.", "History reconciliation: settled-sample MAE and hit-rate over the last 15 days.", "Station structure: a clear split between the settlement station, airport primary observation, and official nearby network."] }, + { type: "bullets", items: ["Anchor status: current airport-primary observation, day-high-so-far, and the settlement clock.", "Current pace: compares where the airport should be by now versus the actual observation.", "Current hit odds / model spread: the likeliest bucket now and how far the model family is split.", "Intraday structural signal: surface structure, upper-air structure, airport TAF, and official nearby-network context around the peak window.", "History reconciliation: settled-sample MAE and hit-rate over the last 15 days."] }, ], }, { id: "how-to-read", title: "How to read the dashboard quickly", blocks: [ - { type: "steps", items: ["Start with the intraday temperature chart to anchor current observations, DEB, and the expected peak window.", "Read the structural signal next to see whether the setup still supports further warming, leans suppressive, or remains mixed.", "Then compare that weather structure against market buckets and settlement probabilities."] }, + { type: "steps", items: ["Start with anchor status and the intraday chart to anchor current observations, DEB, and the expected peak window.", "Read the current pace card to see whether the airport is running hot, cold, or roughly on schedule.", "Use the structural signal to check boundary risk, airport versus nearby stations, and whether TAF introduces suppression risk.", "Then compare that weather structure against hit odds and the model spread."] }, ], }, ], @@ -242,7 +242,7 @@ export const DOCS_PAGES: DocsPage[] = [ id: "city-rules", title: "当前主要口径", blocks: [ - { type: "bullets", items: ["多数机场市场：按机场 METAR 或机场主站实况结算。", "土耳其机场市场：机场主站仍以 METAR 为锚点，同时保留 Turkish MGM 作为领先结构参考。", "中国内地机场市场：机场主站仍以 METAR 为锚点，NMC 当前实况作为官方增强层，不直接替代机场结算站。", "香港 / 流浮山 / 台湾等明确官方站点市场：按规则指定的官方结算站点结算，不能拿机场 TAF 或城区体感替代。"] }, + { type: "bullets", items: ["多数机场市场：按机场 METAR 或机场主站实况结算。", "土耳其机场市场：机场主站仍以 METAR 为锚点，同时保留 Turkish MGM 作为领先结构参考。", "中国内地机场市场：机场主站仍以 METAR 为锚点，NMC 当前实况作为官方增强层，不直接替代机场结算站。", "日本 / 韩国机场市场：机场主站仍以 METAR 为锚点，同时可接入 JMA / KMA 官方增强层做领先结构参考。", "香港 / 流浮山 / 台湾等明确官方站点市场：按规则指定的官方结算站点结算，不能拿机场 TAF 或城区体感替代。"] }, ], }, { @@ -269,7 +269,7 @@ export const DOCS_PAGES: DocsPage[] = [ id: "city-rules", title: "Current primary rules", blocks: [ - { type: "bullets", items: ["Most airport-linked markets settle on airport METAR or the airport primary observing site.", "Turkish airport markets keep METAR as the airport anchor, with Turkish MGM retained as a leading-structure reference.", "Mainland China airport markets keep METAR as the airport anchor, while NMC current observations act as an official enhancement layer rather than a direct replacement anchor.", "Markets with explicitly designated official sites, such as Hong Kong, Lau Fau Shan, and Taiwan station-driven contracts, should be anchored to those official settlement stations rather than generic airport logic."] }, + { type: "bullets", items: ["Most airport-linked markets settle on airport METAR or the airport primary observing site.", "Turkish airport markets keep METAR as the airport anchor, with Turkish MGM retained as a leading-structure reference.", "Mainland China airport markets keep METAR as the airport anchor, while NMC current observations act as an official enhancement layer rather than a direct replacement anchor.", "Japanese and Korean airport markets can keep METAR as the anchor while using JMA / KMA nearby-network observations as an official enhancement layer.", "Markets with explicitly designated official sites, such as Hong Kong, Lau Fau Shan, and Taiwan station-driven contracts, should be anchored to those official settlement stations rather than generic airport logic."] }, ], }, {