#天气功能

AstraSchedule 客户端可实时显示当前温度、天气状况文字，并在极端天气时通过横幅发出预警。天气数据来源于和风天气 API，由服务端代理请求。

#温度显示与颜色映射

客户端在课表左上角显示实时温度（摄氏度），温度文字的颜色随数值变化，支持两种映射模式：

#离散模式

当 use_gradient 设为 false 时，采用离散颜色映射。系统从配置的温度端点列表中查找第一个满足 当前温度 < 端点温度 的端点，使用该端点的颜色。适用于希望温度分档明确（如"低于 20 度蓝色、低于 30 度绿色"）的场景。

#渐变模式

当 use_gradient 设为 true 时，采用非线性渐变插值。系统在两个相邻温度端点之间使用幂函数插值（指数 0.35）动态计算颜色，实现从蓝到绿、从绿到橙、从橙到红的平滑过渡。适用于追求视觉连续性的场景。

#默认温度端点

系统内置四个默认温度端点，可在管理端自由调整端点温度和对应颜色：

端点列表支持任意数量的自定义端点，管理端提供颜色选择器和温度输入框进行可视化配置。

#温度偏移校准

当客户端显示的温度与实际体感存在偏差时，可通过托盘菜单中的调试输入进行偏移校准。点击该菜单项后输入偏移数值（正数表示升高显示温度，负数表示降低），客户端会将 API 返回的原始温度加上偏移值后显示，并重新计算温度颜色。偏移值通过 electron-store 持久化保存。

#天气状况文字

温度数值旁边显示天气状况文字（如"晴""多云""小雨"等），来源于和风天气 API 的实时天气字段。当 API 返回空数据或请求失败时，显示问号（？）作为占位。

#极端天气预警联动横幅

当服务端返回极端天气预警数据时，客户端可将预警信息自动替换横幅通知内容。

#预警模式

系统支持两种预警显示模式，在管理端通过 weather_alert_brief 开关控制：

• 详细模式（weather_alert_brief 为 false）：横幅显示完整的预警信息（warn 字段），包含预警类型、级别和详细描述。
• 简略模式（weather_alert_brief 为 true）：横幅优先显示简略预警标题（brief_warn 字段），适合仅需快速了解预警类型的场景。

#横幅替代行为

是否用天气预警替换普通横幅由 weather_alert_override 开关控制。当此开关开启时：

• 存在预警数据：横幅内容替换为预警文字，跑马灯正常滚动。
• 不存在预警数据：横幅显示普通文字（banner_text 配置的值）。
• 横幅文字为空时，横幅自动隐藏。

预警数据包含时间戳以防止显示过期信息，客户端会根据最新数据的生成时间判断预警是否仍然有效。

#和风天气 API 认证

服务端支持两种和风天气 API 认证方式，在 config.toml 中配置：

#JWT 认证（推荐）

使用 EdDSA（Ed25519）算法生成 JWT Bearer Token。需要配置以下参数：

• KID：和风天气开发者控制台中的凭据 ID。
• ProjectID：和风天气项目 ID。
• PrivateKeyPEM：Ed25519 私钥的 PEM 格式文本。
• Expires：Token 过期时间（秒），默认 900 秒（15 分钟）。

JWT 方式日调用量无限额，推荐在正式环境中使用。

#API Key 认证

使用传统的 API Key 认证，在请求头中附加 X-QW-Api-Key。需要配置 Weather 字段为和风天气的 API Key。免费 API Key 有每日 1000 次调用量的限制。

#请求流程

服务端处理天气请求的流程为：城市查询（city lookup）获取城市 ID → 实时天气查询（weather now）→ 天气预警查询（weather warning）。城市查询结果会缓存在内存中以减少重复 API 调用。客户端请求天气时带有重试逻辑，最多重试 5 次，每次间隔 5 秒。

#托盘菜单天气控制

• 当前地区：点击后弹出输入框，输入所在地市名称（如"北京""上海"）。此设置通过 electron-store 持久化保存，客户端启动时自动使用。
• 刷新天气：手动触发天气数据刷新，立即向服务端请求最新的天气和预警数据，更新客户端显示。