降雨量分析与预警系统 — 使用说明

本系统基于和风天气（QWeather）API，提供降雨预测查看、历史趋势分析、后台自动监测与预警推送功能。

1. 系统概览

系统由两部分组成：

• 前端页面（本目录下的静态 HTML）：提供降雨预测图表、历史分析和系统设置。前端直接从浏览器调用和风天气 API 获取天气数据。
• 后台监测服务（server/ 目录）：Node.js 服务，每 60 秒自动运行一次，持续监测一个固定目标地点，根据降雨风险信号和官方暴雨预警通过 WxPusher 推送通知。

前后端通过 /monitor-health 接口衔接——前端首页读取后台的监测状态、风险信号和通知历史并展示在仪表板上。

2. 各页面说明

2.1 首页 — 降雨预测（index.html）

降雨预测模块：

• 点击 「2小时降雨量」「24小时雨量」「3天雨量」「1周雨量」 切换不同时间窗口的预测图表。
• 图表下方显示累计降雨量、峰值、滚动累计量等指标。
• 如果累计值达到预警阈值，图表右上角会显示对应级别的预警标签（轻度/中度/重度/严重）。
• 使用 「选择位置」 按钮可以临时切换查看地点（不影响后台监测目标）。

系统运行摘要：显示最近 7 天预报准确度、最近状态变更和最近通知。

监测面板（4 个可拖拽模块）：

• 监测概览：监测目标地点、坐标、当前状态、API 调用预算、数据来源。
• 风险信号：各时间窗口（2h/24h/72h/168h）的降雨风险等级和指标。
• 官方预警：当前生效的官方暴雨预警及覆盖状态；已解除/过期的预警可展开查看。
• 通知记录：最近推送的通知列表，显示时间、级别、来源和摘要。

历史降雨模块（页面下方的折叠区域）：查询和风历史天气 API，查看最近 3/7/10 天的历史降雨数据。

2.2 监测记录（monitor-log.html）

通知频率与数据来源（顶部总览面板）：

• 显示监测目标、坐标、当前状态、数据来源、API 调用预算。
• 通知统计：通知总数、日均通知数、平均通知间隔、按级别分布。
• 通知规则（开关、免打扰时间、橙色/红色突破免打扰）已在系统设置页统一管理。

状态变更时间线：

• 按时间倒序展示颜色预警进入、升级、降级、解除事件（NONE → YELLOW → ORANGE → RED）。
• 支持按事件类型和颜色筛选。
• 点击事件可展开查看触发详情和来源。

状态分布饼图：可视化各状态占比。

通知记录：表格形式展示所有推送通知，支持按级别筛选和 CSV 导出。

2.3 地点管理（locations.html）

• 在地图上点击选择位置，输入名称后保存。
• 已保存的地点可以在首页的「选择位置」下拉框中使用。
• 支持删除已保存的地点。

2.4 系统设置（settings.html）

颜色阈值：黄色 / 橙色 / 红色分别配置累计量门槛与峰值雨强门槛，每个信号可独立开关，同时命中取最高颜色；另显示每个信号的触发统计（次数 / 最近时间）。

通知设置：

• WxPusher 微信推送总开关与免打扰时间：黄色通知遵守免打扰，橙色 / 红色可突破。
• 测试推送：验证 WxPusher 通道，总开关关闭时不可用。
• 浏览器内声音提醒与桌面通知：仅浏览器本地生效，不影响后台推送。

显示偏好：降雨量单位（mm / cm）与图表分级（轻度 / 中度 / 重度 / 严重），只影响页面图表展示，不影响后台评估与通知。

首页布局：控制首页各模块的显示与密度。

后台监测目标：从保存地点中选择后台监测地点；切换目标会立即对新地点抓取评估，当前目标不能被删除。

服务状态：只读展示后台监测服务当前的预警颜色、数据质量、最近完整评估时间与监测目标。

3. 后台监测逻辑

后台服务（server/monitor.js）是一个定时调度器，启动后立即执行一轮抓取，之后固定每 15 分钟运行一次 tick()，获取监测目标的 2 小时分钟级预报和 24 小时逐时预报。

3.1 本地预警颜色

系统只使用四种预警颜色：NONE（无预警）/ YELLOW（黄色）/ ORANGE（橙色）/ RED（红色）。颜色由「本地降雨预测」和「官方暴雨预警」两类信号共同决定，两者互相独立：

颜色	评估窗口	触发条件
NONE	—	没有本地信号或官方预警达到任何颜色阈值
YELLOW	未来 6 小时	累计量 ≥ 50 mm 或峰值 ≥ 10 mm/h
ORANGE	未来 3 小时	累计量 ≥ 50 mm 或峰值 ≥ 20 mm/h
RED	未来 3 小时	累计量 ≥ 100 mm 或峰值 ≥ 45 mm/h

3.2 数据合并与评估

系统把 2 小时分钟级预报和 24 小时逐时预报按小时桶合并：2 小时数据优先覆盖重叠小时，24 小时数据补齐其余小时。合并结果用于计算未来 3h / 6h 窗口的累计量和峰值雨强。

• 峰值雨强：合并小时桶中的最大单小时预测值，为近似口径，页面和通知会标注。
• 完整评估：2h 数据至少连续覆盖约 2 小时，24h 数据至少连续覆盖 6 小时；更新时间过期视为不可用。
• 阈值可配置：各颜色的累计量与峰值门槛及信号开关在 系统设置 中统一管理。

3.3 官方暴雨预警

系统通过服务端专用凭证查询和风实时预警接口 weatheralert/v1/current，与本地预测互相独立：

• 命中判定：只把暴雨类型代码（1003/2502）、仍在有效期内且确认覆盖目标地点的官方预警视为命中。
• 级别：官方预警有自己的颜色等级（黄色/橙色/红色），与本地预测颜色分开保存、分开展示。
• 二次推送：一次查询命中多条时按官方颜色取最高色合并为一条推送，同时保留完整列表。
• 解除：预警消失、过期或不再覆盖目标时，发送一次解除通知。

3.4 通知规则

通知通过 WxPusher 推送到绑定的设备，文案统一使用颜色口径并区分本地颜色预警与官方暴雨预警：

• 事件键：每个通知事件有唯一键（本地颜色：color:{location}:{seq}，官方：official:{location}:{warningKey}）。
• 去重：同一事件同一颜色转换不重复通知。
• 升级/降级通知：颜色进入、升级、降级或解除（如黄→橙→红）都会通知。
• 免打扰：黄色通知遵守免打扰时间，橙色与红色通知可突破。
• 失败重试：发送失败按同一事件重试，每次尝试、失败、抑制和成功都记录。

3.5 数据质量与保留

系统跟踪每个数据源（本地天气预测、官方预警）的质量状态：

状态	含义
available	数据正常可用
unavailable-retained	查询失败，但仍在保留期内，沿用上次有效数据
unknown	超过保留期，数据可靠性未知

保留时间取决于当前预警颜色：NONE 6 小时、YELLOW/ORANGE 12 小时、RED 2 小时。数据不可用时系统保留仍可能有效的颜色状态，超过保留期后标记为 UNKNOWN。

4. 预警阈值说明

后台预警颜色阈值默认值（可在系统设置页统一管理）：

颜色	窗口	累计量	峰值雨强
黄色 YELLOW	未来 6 小时	50 mm	10 mm/h
橙色 ORANGE	未来 3 小时	50 mm	20 mm/h
红色 RED	未来 3 小时	100 mm	45 mm/h

5. 部署与配置

环境变量（.env）

变量	说明	示例
PORT	后台服务端口	8787
QWEATHER_API_KEY	和风天气 API Key	your_key
WEATHER_LOCATION	监测目标经纬度	114.049081,22.701914
WEATHER_LOCATION_NAME	监测目标名称	龙华区观湖街道
WXPUSHER_APP_TOKEN	WxPusher 应用 Token	your_token
WXPUSHER_UID	WxPusher 用户 UID	UID_xxx
MONTHLY_API_BUDGET	每月 API 调用上限	50000

启动与管理

• npm start — 启动后台服务
• npm test — 运行自动化测试
• npm run typecheck — JavaScript 语法检查

生产环境推荐使用 systemd 管理服务，并通过 nginx 反向代理将 /monitor-health 转发到后台端口。

6. 常见问题

Q: 首页监测面板显示「后台监测服务未运行」？

A: 后台服务未启动，或 nginx 未配置 /monitor-health 代理。前端通过该接口读取后台状态，未配置时会显示此提示。静态页面本身仍可正常使用。

Q: 预警通知没有收到？

A: 检查以下几点：

• 后台服务是否正常运行（systemctl status rain-monitor）。
• .env 中 WxPusher 配置是否正确。
• 系统设置页的「通知设置」中的总开关和免打扰时间是否合理配置。
• 通知只在预警进入或升级时发送一次，同色不重复提醒（这是设计行为，不是故障）。

Q: 前端预警标签和后台通知不一致？

A: 后台通知使用颜色口径（黄色/橙色/红色），由系统设置页中的全局颜色阈值统一管理。通知按事件触发（进入/升级）而非按周期重复发送，即使风险持续也可能不会每次都通知。前端图表的轻/中/重/严重分级只用于页面展示，不影响后台评估与通知。

Q: API 调用预算用完了怎么办？

A: 系统会在达到预算的 90% 时停止查询（预留 10% 安全余量）。可在 .env 中调大 MONTHLY_API_BUDGET，或在下个月自动重置。

Q: 如何修改监测目标地点？

A: 在系统设置页的「后台监测目标」中从已保存地点选择目标，或修改 .env 中的 WEATHER_LOCATION 和 WEATHER_LOCATION_NAME 后重启后台服务。前端页面的「选择位置」功能只影响查看，不改变后台监测目标。

Q: 页面上的「地点管理」和后台监测目标有什么区别？

A: 「地点管理」保存的地点既可用于前端查看降雨预测，也可以在系统设置页中选为后台监测目标。后台服务只监测一个目标地点。