#天气功能

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

#温度显示与颜色映射

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

#离散模式（建议）

当 use_gradient 设为 false 时，采用离散颜色映射。系统从配置的温度端点列表中查找第一个满足 当前温度 < 端点温度 的端点，使用该端点的颜色。

#渐变模式

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

#默认温度端点

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

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

#天气状况文字

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

#极端天气预警联动横幅

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

#预警模式

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

• 详细模式：横幅显示完整的预警信息，包含预警类型、级别和详细描述。

  • 比如：瑞安市气象台2026年07月17日16时03分继续发布大风黄色预警信号：目前我市东山北龙岛已出现9级大风，预计今天下午到后天我市沿海海面（北麂乡、东山街道沿海）仍将有7-9级大风。希各有关方面做好防风加固，涉海部门和沿海地区加强防范。

• 简略模式：横幅优先显示简略预警标题，适合仅需快速了解预警类型的场景。

  • 比如：瑞安市气象台发布大风黄色预警

#横幅替代行为

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

• 存在预警数据：横幅内容替换为预警文字，跑马灯正常滚动。
• 不存在预警数据：横幅显示普通文字（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 次调用量的限制。

#请求流程

服务端处理天气请求的流程为：城市查询获取城市 ID → 实时天气查询 → 天气预警查询。城市查询结果缓存在内存中。客户端请求天气时带有重试逻辑，最多重试 5 次，每次间隔 5 秒。

#托盘菜单天气控制

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