全国过敏指数实时监测

它要解决的问题

花粉季里，开发者常被问到「北京今天花粉情况如何」「哪些城市过敏风险高」。这类需求通常意味着要自己找天气 API、处理限速与缓存、再写一套可视化，流程割裂。

本技能把这几步打包：从华风爱科官方 API 拉取实时过敏指数（UPI），汇总全国 66 个主要城市，输出为交互式热力地图或结构化 JSON。

它如何工作

核心数据来自中国天气网官方 API（openapi.weathercn.com，过敏指数 ID:127），备用源为敏舒科技（allercast.cn）的 UPI 花粉浓度数据。脚本的关键环节：

• 首次全量拉取，后续秒级响应：第一次拉取全部城市数据，当日缓存，同一天再次查询直接复用，1 秒内出结果。
• 智能限速：内置请求频率 ≤4 次/秒，避免触发 API 429 错误。
• 自动降级：网络请求失败时切换到模拟演示数据，保证可视化流程不中断。

使用方式由命令行参数驱动：

1. --source weathercn --city 北京 查询单城市过敏指数；
2. 不带城市参数时生成全国过敏指数地图（默认行为）；
3. --format json 导出全部城市的结构化数据；
4. --list-cities 查看支持的城市列表。

生成的 HTML 是基于 ECharts 散点地图的独立静态文件，按 5 级过敏指数（绿色到红色）做颜色深浅标注，支持鼠标悬停弹窗、统计面板与图例说明，浏览器直接打开即可，无需后端服务。

适用边界与注意点

• 仅覆盖 66 个中国主要城市，超出列表的城市不支持。
• API Key 需预先配置，否则会走备用数据源或模拟数据。
• 数据有当日时效性，跨天比较时不要复用当日缓存。
• 地图为静态快照而非实时页面，查看最新数据需重新运行脚本。