wehub-resource-sync天气（Weather）- 和风天气 API 调研与接口对照
本目录用于记录“天气”App 需要用到的和风天气（QWeather）接口、字段与请求示例，方便后续实现 UI 与数据层。
安全提示：你提供的 API Key 属于敏感信息。为了避免泄露，建议在真实项目中使用环境变量（如
.env）或服务端代理，不要把 Key 写进代码并提交到 git。
##你当前的 Host / Key（用于本地调试）
-API Host：<YOUR_QWEATHER_HOST>
-API Key：<YOUR_QWEATHER_API_KEY>
-鉴权方式：API KEY（请求头 X-QW-Api-Key）
说明：和风建议使用 API Host（专属域名），公共域名从 2026 年起逐步停止服务。
##通用请求规则
###基础 URL
所有请求均为 HTTPS：
https://{API_HOST}/{path}
例如：
https://<YOUR_QWEATHER_HOST>/v7/weather/now?location=101010100
###鉴权（API KEY）
两种等价方式：
1)请求头（推荐，便于统一封装）
curl--compressed\
-H "X-QW-Api-Key: <YOUR_KEY>" \
"https://<YOUR_HOST>/v7/weather/now?location=101010100"
2)Query 参数
curl--compressed\
"https://<YOUR_HOST>/v7/weather/now?location=101010100&key=<YOUR_KEY>"
###location 参数（非常重要）
不同接口对 location 的要求不同：
-大多数 v7 天气接口支持：
-LocationID（如 101010100）
- 或
经度,纬度（如116.41,39.92）
-分钟级降水 GET /v7/minutely/5m：只支持 经度,纬度
-空气质量 v1：不用 location，而是用 路径参数 {latitude}/{longitude}
###常用可选参数
-lang：语言（如 zh）
-unit：单位（m 公制默认，i 英制）
##截图 UI 模块 → 接口对照表
###1) 顶部主卡（当前温度/体感/风/湿度/气压/能见度/天气文案）
-接口：实时天气
-Path：GET /v7/weather/now
-文档：https://dev.qweather.com/docs/api/weather/weather-now/
关键字段（示例）：
-now.temp：温度
-now.feelsLike：体感
-now.text / now.icon：天气文案/图标
-now.windDir / now.windScale / now.windSpeed：风向/风力/风速
-now.humidity：湿度
-now.pressure：气压
-now.vis：能见度
你已验证的请求示例（北京 101010100）：
curl--compressed\
-H "X-QW-Api-Key: <YOUR_QWEATHER_API_KEY>" \
"https://<YOUR_QWEATHER_HOST>/v7/weather/now?location=101010100"
对应返回（节选）：
-temp: "2"
-feelsLike: "-7"
-text: "多云"
-windDir: "北风", windScale: "3"
-humidity: "15"
-pressure: "1025"
-vis: "30"
###2) 未来 7 天（今天/明天/周六…，最高/最低、图标）
-接口：每日天气预报
-Path：GET /v7/weather/{days}，常用：7d / 15d
-文档：https://dev.qweather.com/docs/api/weather/weather-daily-forecast/
关键字段：
-daily[].fxDate：日期
-daily[].tempMax / daily[].tempMin：最高/最低温
-daily[].iconDay/textDay、daily[].iconNight/textNight：白天/夜间
-daily[].sunrise / daily[].sunset：日出日落（高纬可能为空）
示例：
curl--compressed\
-H "X-QW-Api-Key: <YOUR_QWEATHER_API_KEY>" \
"https://<YOUR_QWEATHER_HOST>/v7/weather/7d?location=101010100"
###3) 小时曲线（未来 24 小时：时间/温度/图标/风力等）
-接口：逐小时天气预报
-Path：GET /v7/weather/{hours}，常用：24h
-文档：https://dev.qweather.com/docs/api/weather/weather-hourly-forecast/
关键字段：
-hourly[].fxTime：预报时间
-hourly[].temp、hourly[].icon/text
-hourly[].windScale、hourly[].windDir
-hourly[].pop：降水概率（可能为空）
示例：
curl--compressed\
-H "X-QW-Api-Key: <YOUR_QWEATHER_API_KEY>" \
"https://<YOUR_QWEATHER_HOST>/v7/weather/24h?location=101010100"
###4) 分钟级降水（2 小时内无降雪/无降水，临近预报）
-接口：分钟级降水（未来 2 小时、每 5 分钟）
-Path：GET /v7/minutely/5m
-文档：https://dev.qweather.com/docs/api/minutely/minutely-precipitation/
注意：
-location 必须是 经度,纬度（例如 116.41,39.92），不能用 LocationID。
示例：
curl--compressed\
-H "X-QW-Api-Key: <YOUR_QWEATHER_API_KEY>" \
"https://<YOUR_QWEATHER_HOST>/v7/minutely/5m?location=116.41,39.92"
关键字段：
-summary：概括文案（如“2小时内无降雪/放心出行吧”）
-minutely[].precip、minutely[].type（rain/snow）
###5) 空气质量（例如 “空气优 25”）
-接口：实时空气质量（注意：这是 Air Quality API v1，不是 v7）
-Path：GET /airquality/v1/current/{latitude}/{longitude}
-文档：https://dev.qweather.com/docs/api/air-quality/air-current/
注意：
- 该接口使用 路径参数，不是
?location=... - 返回里
indexes[]可能同时包含本地 AQI 与 QAQI，两者展示口径需产品决定。
示例（北京大概坐标）：
curl--compressed\
-H "X-QW-Api-Key: <YOUR_QWEATHER_API_KEY>" \
"https://<YOUR_QWEATHER_HOST>/airquality/v1/current/39.90/116.40"
常用字段：
-indexes[].aqiDisplay：适合直接展示的 AQI 数值
-indexes[].category：优良中差等
-indexes[].primaryPollutant：首要污染物
###6) 灾害预警（例如 “大风蓝色预警” 卡片）
-接口：天气预警
-Path：GET /v7/warning/now
-文档：https://dev.qweather.com/en/docs/api/warning/weather-warning
示例：
curl--compressed\
-H "X-QW-Api-Key: <YOUR_QWEATHER_API_KEY>" \
"https://<YOUR_QWEATHER_HOST>/v7/warning/now?location=101010100"
常用字段：
-warning[].title：卡片标题
-warning[].severity / warning[].severityColor：严重等级/推荐颜色（用于“蓝/黄/橙/红”等视觉）
-warning[].text：详情描述
###7) 生活指数建议（穿衣/防晒/运动/洗车/带伞/感冒…）
-接口：天气指数预报
-Path：GET /v7/indices/{days}，常用：1d
-文档：https://dev.qweather.com/docs/api/indices/indices-forecast/
注意：
-type 必填，可用英文逗号一次取多个指数：type=3,5,9 等
- 每个指数的 ID/含义参考文档里的“天气指数信息”页
示例（先用少量 type 试通）：
curl--compressed\
-H "X-QW-Api-Key: <YOUR_QWEATHER_API_KEY>" \
"https://<YOUR_QWEATHER_HOST>/v7/indices/1d?location=101010100&type=1,2,3,5"
常用字段：
-daily[].name：指数名（穿衣/洗车/感冒…）
-daily[].category：等级文案（适宜/较不宜/很强…）
-daily[].text：详细建议（可用于详情页/tooltip）
##城市搜索（LocationID 获取）
如果需要“添加城市/搜索城市”，使用 GeoAPI：
-接口：城市搜索
-Path：GET /geo/v2/city/lookup?location=北京
-文档：https://dev.qweather.com/docs/api/geoapi/city-lookup/
示例：
curl--compressed\
-H "X-QW-Api-Key: <YOUR_QWEATHER_API_KEY>" \
"https://<YOUR_QWEATHER_HOST>/geo/v2/city/lookup?location=北京&range=cn&number=10"
取 location[].id 作为后续 v7 天气接口的 location。
##后续实现建议（仅记录）
-数据聚合：前端页面通常需要并发请求 now + 24h + 7d + indices + warning，再按 UI 模块组装。
-经纬度管理：分钟级降水与空气质量都需要经纬度，建议在“城市搜索”结果里缓存 lat/lon。
-缓存：短时间内重复打开页面可缓存（如 5-10 分钟），减少计费与延迟。